GitHub Action
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.
Before you start
Section titled “Before you start”-
Add the repository to a zkao project. A scan needs at least one project member with GitHub access to the repository.
-
Create a project API token with the
readandscans:launchscopes. See Authentication. -
In the GitHub repository settings, store the token as the secret
ZKAO_API_TOKEN. Store the project id as the variableZKAO_PROJECT_ID. -
Keep credits on the organization. A scan reserves its budget at launch. See Credits.
Scan every push to main
Section titled “Scan every push to main”name: zkaoon: 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.
Gate pull requests on a diff scan
Section titled “Gate pull requests on a diff scan”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: zkaoon: 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: highThe 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 on the pull request
Section titled “Comment on the pull request”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: zkaoon: 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: trueThe 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.
Run a scan from a comment
Section titled “Run a scan from a comment”Trigger on issue_comment and the action takes commands from the pull request itself.
name: zkaoon: 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. |
What to run
Section titled “What to run”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.
Inputs
Section titled “Inputs”| 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. |
Outputs
Section titled “Outputs”| 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 }}"Keeping the cost in check
Section titled “Keeping the cost in check”A full scan on every push adds up. These keep it down.
- Run on
pull_request, or onmainonly. - Use
scan: flashfor pull requests. - Pass
areasto scan only the audit areas a change touches. List area keys withzkao areas list <repoId>. - Set
budgetto cap each scan.
A scan of a repository zkao is still analyzing waits for that analysis to finish first.
How it works
Section titled “How it works”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.
