Docs / Install / GitHub Action

Install: GitHub Action

Add protet/monitor to a GitHub Actions job. It watches every process the job starts and is designed to report a verdict on the run and the pull request.

Prerequisites

• A verified Protet account (Quickstart) and an ingest token minted in the dashboard.
• A Linux runner with sudo. GitHub-hosted ubuntu-* runners work out of the box; the Action installs auditd itself.
• Repository admin rights to create a secret.

1. Store the token as a secret

In the repository, open Settings, Secrets and variables, Actions and add a repository secret named PROTET_TOKEN with the token from the dashboard. Or with the GitHub CLI:

gh secret set PROTET_TOKEN --repo OWNER/REPO

Paste the token when prompted. One token does both jobs: the Action sends events with it and reads the verdict back with it.

2. Add the step to a workflow

Put the Action right after checkout, before the steps you want watched. Commands that run before it are not captured. Save this as .github/workflows/build.yml:

name: build
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write   # lets the Action update its pull request comment

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: protet/monitor@v1
        with:
          token: ${{ secrets.PROTET_TOKEN }}
          fail-on-malicious: "false"

      # your existing build steps run unchanged, and are watched
      - run: npm ci && npm run build

Pull requests from forks do not receive repository secrets (a GitHub rule). On those runs the token is empty, and the Action logs a warning and turns monitoring off without failing the build.

Inputs

What you see

This is the designed behaviour. See the status note above for why it is not dependable today.

• Job summary, every run. A Protet Runtime Monitor section with the verdict, how many events were delivered. Every analysed run gets a verdict, benign or malicious.
• Pull request comment, malicious runs only. A single comment, updated in place on later runs. A clean run does not create a comment; if an earlier run left one and the build is now clean, that comment is updated to say so.
• Job log. At the end of the job the log prints the verdict between two rules, and a warning if any events could not be delivered or none were captured.
• Failing the job. Only when fail-on-malicious is "true" and the verdict is malicious.
• Monitoring never breaks your build. If the token is missing or capture cannot start, the Action warns and carries on.

The Action adds time at the end of a job: up to about 30 seconds to flush events, and up to about 90 seconds waiting for the verdict.

Plan limits

The free plan allows 500 build sessions per calendar month. Each monitored job counts as one session, and every analysed build returns a result, benign or malicious. Past the cap, new sessions are held back; a running job is never cut off. Retention: build activity is held for at most 24 hours and never archived; each build's result is kept for up to 6 hours so the Action can read it back, then deleted. Check live numbers with GET /v1/usage (API reference).

Runner support

• Supported: Linux with sudo and auditd, including GitHub-hosted ubuntu-*.
• Not supported yet: macOS and Windows runners, and locked-down self-hosted Linux runners without auditd. There the step warns and does nothing.
• What is collected: the commands the job runs, as seen by auditd (execve). Source code, build artifacts and build output do not leave the runner.

Problems? Troubleshooting: the GitHub Action.