Skip to content
These docs describe staging.zkao.io and the @zksecurity/zkao-cli@next release. For production, see docs.zkao.io.

GitHub Action

View .md

The zksecurity/zkao-action action scans the commit a workflow runs on. By default it starts the scan and returns. It can also wait, write the findings to the job summary, and fail the job on severe findings.

The action needs no checkout. zkao reads the commit from GitHub itself.

  1. Add the repository to a zkao project. A scan needs at least one project member with GitHub access to the repository.

  2. Create a project API token with the read and scans:launch scopes. See Authentication.

  3. In the GitHub repository settings, store the token as the secret ZKAO_API_TOKEN. Store the project id as the variable ZKAO_PROJECT_ID.

  4. Keep credits on the organization. A scan reserves its budget at launch. See Credits.

name: zkao
on:
push:
branches: [main]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: zksecurity/zkao-action@v1
with:
token: ${{ secrets.ZKAO_API_TOKEN }}
project: ${{ vars.ZKAO_PROJECT_ID }}

This launches a Flash scan of the change in each push and moves on. The results are on zkao when the scan finishes.

scan: flash audits only the change a pull request makes, with one focused analysis led by a flagship model. It is cheap and fast. scan: max runs every technique on the change, on flagship models. In gate mode, the job fails when open findings reach fail-on.

name: zkao
on:
pull_request:
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: zksecurity/zkao-action@v1
with:
token: ${{ secrets.ZKAO_API_TOKEN }}
project: ${{ vars.ZKAO_PROJECT_ID }}
scan: flash
mode: gate
fail-on: high

The diff runs from the merge base of base to the scanned commit. base defaults to the pull request’s base, or to the commit before a push. The rest of the repository is context, not a target. See Diff scans.

On pull_request and pull_request_target events, the action scans the head of the pull request. On every other event it scans github.sha.

comment: true posts to the pull request twice: once when the scan starts, and again with the result when the job waits for it. Both carry a link to the scan. The job needs pull-requests: write.

name: zkao
on:
pull_request:
permissions:
contents: read
pull-requests: write
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: zksecurity/zkao-action@v1
with:
token: ${{ secrets.ZKAO_API_TOKEN }}
project: ${{ vars.ZKAO_PROJECT_ID }}
scan: flash
mode: wait
comment: true

The result comment carries counts and a link, never the findings themselves. On a public repository, spelling them out would disclose unfixed vulnerabilities to anyone who can read the pull request.

Comments are posted by github-actions[bot], since the action uses the workflow’s own token. To post under your own bot, mint a GitHub App installation token in an earlier step and pass it as github-token.

Trigger on issue_comment and the action takes commands from the pull request itself.

name: zkao
on:
issue_comment:
types: [created]
permissions:
contents: read
pull-requests: write
jobs:
scan:
if: github.event.issue.pull_request && contains(github.event.comment.body, '/zkao')
runs-on: ubuntu-latest
steps:
- uses: zksecurity/zkao-action@v1
with:
token: ${{ secrets.ZKAO_API_TOKEN }}
project: ${{ vars.ZKAO_PROJECT_ID }}
scan: flash
mode: wait
comment: true
Comment What happens
/zkao scan Audits the pull request’s change, with the kind the workflow configures.
/zkao scan max Audits it as flash or max instead.
/zkao help Posts the usage. No scan.
/zkao Posts the usage, rather than scanning.

The handle is slash-prefixed rather than @zkao, because GitHub turns an @handle into a link to whoever owns that account and notifies them, and zkao belongs to someone else. A leading slash on the command itself is optional, so /zkao scan and /zkao /scan mean the same thing.

A word after scan that is not a kind is ignored, so /zkao scan this one runs the workflow’s own kind rather than failing over a word nobody meant as a preset.

Set mention to an @handle you own and it still works. There an unrecognised word after the handle is left alone rather than answered, since it may be ordinary prose.

Only the repository’s owner, members and collaborators can start a scan this way. Comments from anyone else are ignored, so a passer-by cannot spend the project’s credits.

Change the handle with the mention input.

mode What happens
launch (default) Starts the scan and returns. The job never waits or fails on findings.
wait Waits for the scan and writes the findings to the job summary. The job fails only if the scan itself fails.
gate Waits, reports, and fails the job when open findings reach fail-on.
scan Runs
flash (default) Only the change since base, with one focused analysis led by a flagship model.
max Only the change since base, with every technique on flagship models.
a preset ref That preset, such as builtin:Max for the whole repository, or a custom one. List refs with zkao presets.

The older words still work. diff runs flash. rapid-review and quick-look run builtin:Flash. deep-audit runs builtin:Max.

Input Default What it does
token required Project API token. Use a secret.
project required The zkao project id.
budget recommended Credit budget for the scan. Defaults to what zkao recommends for this scan type on this repository.
mode launch launch, wait, or gate.
scan flash flash, max, or a preset ref.
base see above For scan: flash or scan: max, the commit the change is measured from.
fail-on high For mode: gate, the severity that fails the job: critical, high, medium, low, or info.
repository matched by name The zkao repository id. By default, the project repository whose owner and name match this GitHub repository.
commit see above Commit to scan.
branch workflow branch Branch the commit is on.
areas whole repository Comma-separated audit area keys to scope a scan of the code to. A scan of a change takes none.
guidance-file none A file whose content replaces the repository’s guidance for this scan.
timeout 10800 Seconds to wait in wait and gate modes. The scan keeps running on zkao after a timeout.
summary true Write the scan link, and the findings once waited for, to the job summary.
comment false Comment on the pull request when the scan starts and when it finishes. Needs pull-requests: write.
mention /zkao What a comment says to reach zkao.
github-token the workflow’s Token used to comment, and to read the pull request on an issue_comment event.
base-url https://zkao.io The zkao instance.
cli-version pinned Version of @zksecurity/zkao-cli the action runs.
Output Meaning
scan-id Id of the launched scan.
scan-url The scan on zkao.
status QUEUED in launch mode. COMPLETED, FAILED or CANCELLED once waited for.
findings-total Open findings, excluding false positives and duplicates. Empty in launch mode.
findings-critical, findings-high, findings-medium, findings-low, findings-info Open findings by severity.

Use them in later steps:

- uses: zksecurity/zkao-action@v1
id: zkao
with:
token: ${{ secrets.ZKAO_API_TOKEN }}
project: ${{ vars.ZKAO_PROJECT_ID }}
mode: wait
- run: echo "${{ steps.zkao.outputs.findings-total }} open findings at ${{ steps.zkao.outputs.scan-url }}"

A full scan on every push adds up. These keep it down.

  • Run on pull_request, or on main only.
  • Use scan: flash for pull requests.
  • Pass areas to scan only the audit areas a change touches. List area keys with zkao areas list <repoId>.
  • Set budget to cap each scan.

A scan of a repository zkao is still analyzing waits for that analysis to finish first.

The action is a composite step. It runs the published @zksecurity/zkao-cli against the public API. The runner needs node and jq, which every GitHub-hosted runner has.