Protet

Docs / Getting started

Getting started

The fastest path to your first verdict is the free cloud tier and the GitHub Action — a signup and three lines in a workflow. On-prem, signed-bundle deployment is further down. Everything here is also shown as raw API calls if you'd rather script it.

1. Create a free account

Self-serve signup starts you on the cloud-hosted free tier (Otus) — no card required. Use the dashboard, or the API:

curl -X POST https://protet.io/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "a-strong-password", "name": "Your Company"}'

The verification email carries a token; posting it back activates your account and provisions your free-tier license:

curl -X POST https://protet.io/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "<from the email link>"}'

2. Watch your first build

GitHub Actions is the fastest way. Mint an ingest token from your dashboard, add it as a repository secret, and drop one step into any workflow. Protet watches every command the build runs and posts a malicious / benign verdict to the run and the pull request — your build steps don't change, and there's no agent to install.

- uses: protet/monitor@v1
  with:
    token: ${{ secrets.PROTET_TOKEN }}

# ↓ your existing build steps run unchanged — and watched
- run: npm ci && npm run build

That's the whole integration — the next push produces a verdict.

3. Or send events from any pipeline

Not on GitHub Actions? The cloud ingest endpoint is an open HTTP contract — anything that can make a request works (GitLab CI, Jenkins, Buildkite, your own collector). Trade your ingest token for a short-lived access token, then POST execve events:

POST https://protet.io/v1/ingest/refresh
Authorization: Bearer <your ingest token>

→ { "token": "<access token>", "expires_in": 3600 }
curl -X POST https://ingress.protet.io/v1/ingest \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"event_type": "exec", "binary": "/usr/local/bin/npm", "args": "install"}]}'

Verdicts are delivered to your dashboard in real time — nothing about your build sessions is stored server-side on the cloud tiers. See Integrations for the full event shape and the OCSF finding schema.

On-prem: pull a signed model bundle

On an on-prem tier (Bubo), the detection pipeline runs entirely inside your own infrastructure and can operate fully air-gapped. Here, verifying your email also mints a pull token — use it to fetch a signed bundle over a single, token-only URL:

curl -H "x-license-key: <your pull token>" https://protet.io/v1/bundle -o bundle.tar.gz

The first pull for a given model version returns 202 and schedules a build — retry after a few seconds until you get a 200 with the archive. Every later pull of the same version is an immediate cache hit.

The archive contains manifest.json, manifest.sig, and the detection model and its supporting files. Verify manifest.sig against Protet's public signing key before trusting the contents:

curl https://protet.io/v1/public-keys

Then point your on-prem pipeline at the bundle: MODEL_BUNDLE_URL=https://protet.io/v1/bundle, MODEL_BUNDLE_KEY=<your pull token>. See Architecture for what the pipeline does with it, and Integrations for wiring findings into your SIEM.

Architecture →