Docs / GitHub Action

GitHub Actions supply-chain security

protet/monitor is a GitHub Action that records every command a CI job runs and checks the job for supply-chain attack behaviour: a dependency that downloads and runs a script, reads credentials or adds persistence while your build installs it.

What the Action does

• It installs auditd on the runner and records every process the job starts (execve), from the Action's step to the end of the job.
• It sends those commands to Protet with your token, and at the end of the job reads the verdict back.
• It reports the verdict in the job summary and, for a malicious build, in a pull request comment. It can fail the job if you ask it to.
• Monitoring never breaks your build: if the token is missing or capture cannot start, the Action logs a warning and the job carries on.

What Protet flags, and what a finding contains, is on How it works. Packages Protet has confirmed as malicious are listed on Protet Intel.

Setup

1. Get a token

Create a free account and mint an ingest token in the dashboard. The quickstart shows both steps, with commands.

2. Store it as a repository secret

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

gh secret set PROTET_TOKEN --repo OWNER/REPO

3. Add the step

Put the Action right after checkout, before the steps you want watched. Commands that run before it are not recorded.

permissions:
  contents: read
  pull-requests: write   # for the pull request comment

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: protet/monitor@v1
        with:
          token: ${{ secrets.PROTET_TOKEN }}
      - run: npm ci && npm run build

Every input, a complete workflow file and runner support are in the GitHub Action reference. Pull requests from forks do not receive repository secrets; on those runs the Action turns monitoring off with a warning.

Outputs

This is the designed behaviour; see the status note above.

• Job summary, every run: a Protet Runtime Monitor section with the verdict, the number of events delivered. Every analysed run gets a verdict, benign or malicious.
• Pull request comment, malicious runs only: one comment, updated in place on later runs. If a later run is clean, the existing comment is updated to say so.
• Job log: the verdict at the end of the job, and a warning if events could not be delivered or none were captured.
• Failing the job: only with fail-on-malicious: "true" and a malicious verdict. The default is "false".

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

What is collected

The commands the job runs, as auditd sees them: each executable and its arguments. Source code, build artifacts and build output do not leave the runner. Linux runners with sudo are supported, including GitHub-hosted ubuntu-*; macOS and Windows runners are not supported yet. How long the data is kept is on the security page.

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. See Pricing.