# GitHub Action

The [`zksecurity/zkao-action`](https://github.com/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

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](https://docs.zkao.io/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](https://docs.zkao.io/guides/credits/).

## Scan every push to main

```yaml
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.

Tip

`@v1` follows every `v1.x` release. To pin an exact version, use a full commit SHA instead.

## 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`.

```yaml
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](https://docs.zkao.io/guides/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

`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`.

```yaml
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`.

Note

A push carries no pull request. When the pushed branch has one open, the action finds it and comments there anyway.

## Run a scan from a comment

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

```yaml
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.

Caution

A workflow triggered by `issue_comment` only ever runs from the repository’s **default branch**. On any other branch GitHub never dispatches it, and nothing happens with no error to explain it. The default branch is also where the comment event reads the workflow from, so the commit under test comes from the pull request, not from `github.sha`.

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.

## Modes

| `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

| `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

| 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

| 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:

```yaml
      - 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

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.

## How it works

The action is a composite step. It runs the published [`@zksecurity/zkao-cli`](https://www.npmjs.com/package/@zksecurity/zkao-cli) against the public API. The runner needs `node` and `jq`, which every GitHub-hosted runner has.
