This is the abridged developer documentation for zkao
# Build on zkao
> Launch security audits, triage findings, and publish results from your terminal, your CI, your code, or your AI agent.
zkao audits code for security bugs, with a focus on cryptography and zero-knowledge circuits. Everything you can do on a project in the app, you can also do through its API.
```bash
npm install -g @zksecurity/zkao-cli
zkao login
zkao scans launch --repo --budget 500
```
## Pick your tool [Section titled “Pick your tool”](#pick-your-tool) [CLI](/reference/cli/)The zkao command. JSON on stdout, built for shells and scripts. [TypeScript SDK](/reference/sdk/)A typed client generated from the OpenAPI spec, with helpers to wait on scans. [REST API](/api/)Every endpoint, request body, and response shape. [GitHub Action](/guides/github-action/)Scan every pull request's diff, or the whole repository on a schedule. [AI agents](/guides/agents/)A skill that teaches Claude Code and other agents to drive your project. [Authentication](/authentication/)Log in from a browser, or mint a scoped token for CI. ## Made for agents too [Section titled “Made for agents too”](#made-for-agents-too) llms.txt An index of these docs at [`/llms.txt`](/llms.txt), and all of them in one file at [`/llms-full.txt`](/llms-full.txt). Markdown pages Every page has a Markdown version. Replace its trailing slash with `.md`, or request it with `Accept: text/markdown`. Agent skill The skill lives at [`/skill.md`](/skill.md). Point your agent at it. OpenAPI spec The contract the SDK is generated from, at [`/openapi/v1.yaml`](/openapi/v1.yaml).
# Authentication
> Get a project API token through browser approval or by hand, and understand what its scopes and limits allow.
Every call to the zkao API uses a **project API token**. A token belongs to exactly one project. It carries a set of scopes and can be narrowed further to some repositories, an expiry date, and a spend limit. There are two ways to get one: approve the CLI in your browser, or create a token by hand. ## Browser approval [Section titled “Browser approval”](#browser-approval)
```bash
zkao login
```
The CLI starts a device authorization flow: 1. It prints a URL and a short code, and opens the URL in your browser. 2. On the **Authorize a CLI** page, you confirm that the code matches the one in your terminal. 3. You pick a project, review the requested scopes, and approve. You can also set a repository allowlist, an expiry, and a spend limit there. 4. The CLI receives the token and saves it to `~/.zkao/config.json`. Only approve a login you started yourself. Approving mints a real token for the project you select. By default the CLI requests `read`, `scans:launch`, `findings:write`, and `guidance:write`. The approval page pre-ticks them, and the approver can change them. To request other scopes, pass `--scope`:
```bash
zkao login --scope read publish
```
`zkao login --project ` preselects a project on the approval page. You can approve several projects in one login. Each gets its own saved token, and the first becomes the active project. Use `--no-browser` to print the URL without opening a browser. ### Agents and CI [Section titled “Agents and CI”](#agents-and-ci) A bare `zkao login` blocks until someone approves in the browser. That can take minutes and trip a command timeout. Non-interactive callers split it in two:
```bash
zkao login --no-wait --no-browser # prints the URL and code, then exits
# a person opens the URL and approves
zkao login --resume # polls once and exits
```
Repeat `zkao login --resume` until it prints `Authorized`. `Still waiting for approval` means nobody has approved yet. `--resume --timeout ` waits up to that long instead of polling once. Several logins can be pending at once. `--resume` finishes whichever is approved first and keeps the rest. A pending login expires after a while. Start a new one when `--resume` reports that it expired. ## Tokens created by hand [Section titled “Tokens created by hand”](#tokens-created-by-hand) A project admin can create a token under **Project Settings → Integrations** in the zkao app. Choose a name, the scopes, and optionally a repository allowlist, an expiry, and a spend limit. The token is shown once, together with the project id. It looks like this:
```plaintext
zkao_proj__
```
Store it as a secret. zkao cannot show it again. Hand it to the CLI or SDK through environment variables:
```bash
export ZKAO_API_TOKEN=zkao_proj_...
export ZKAO_PROJECT_ID=
```
Or save it to the config file:
```bash
zkao config set --token zkao_proj_... --project
```
## Scopes [Section titled “Scopes”](#scopes) A token carries a subset of these scopes: | Scope | Allows | | ------------------------ | --------------------------------------------------------------------------------------------------------------- | | `read` | List and read repositories, scans, findings, presets, and billing. | | `findings:write` | Comment on findings, change severity and resolution, override the triage verdict, pin a note. | | `guidance:write` | Update a repository’s guidance, manage its audit areas, and answer questions from Continuous Security analyses. | | `scans:launch` | Launch and cancel scans. | | `regression-tests:write` | Generate regression tests and create or retry their pull requests. | | `publish` | Publish a finding or a scan as a public page. | | `advisories:write` | Record which versions a security advisory affects. | | `contacts:read` | Read the advisory contact list. | | `contacts:write` | Add an advisory contact. | | `automations:write` | Select Continuous Security analyses, configure schedules and budgets, and prepare a branch’s next analysis. | A call that needs a scope the token lacks returns `403 forbidden`. The two contact scopes are held apart from the others. That list is who learns about a vulnerability before the public does, so neither `read` nor `advisories:write` reaches it. ## Limits on a token [Section titled “Limits on a token”](#limits-on-a-token) * **Repository allowlist.** The token only sees the listed repositories. An empty list means every repository in the project. * **Expiry.** The token stops working after this date. * **Spend limit.** The most credits the token may commit to scans, triage resumptions, and regression tests in the current billing period. A request past the limit returns `429`. Regression test requests require a token whose creator remains a project admin with verified GitHub write access. The GitHub App must have Contents and Pull requests write permissions for that repository. The default CLI login does not request `regression-tests:write`. Grant it explicitly when you want to create test pull requests. `zkao whoami` (or `GET /token`) returns the token’s project, organization, scopes, allowlist, expiry, and spend limit. Any valid token can call it, whatever its scopes. ## Errors [Section titled “Errors”](#errors) | Status | Meaning | | ------------------ | ---------------------------------------------------------------------------------------------------------- | | `401 unauthorized` | The token is missing, malformed, expired, or revoked. The response does not say which. | | `403 forbidden` | The token is valid but lacks the scope this call needs. | | `404 not_found` | The resource is outside the token’s project or repository allowlist. zkao does not confirm that it exists. | A token used against another project’s id gets a `404` whose message names the token’s own project. Send the token only in the `Authorization: Bearer` header. A token passed in the query string is rejected with `400`. ## Where the CLI stores credentials [Section titled “Where the CLI stores credentials”](#where-the-cli-stores-credentials) The CLI writes `~/.zkao/config.json` with owner-only permissions. It keeps one token per project, so logging in to a second project does not drop the first.
```bash
zkao config show # active settings and every saved project (tokens masked)
zkao config use # switch the active project
```
Settings resolve in this order, highest first: 1. Flags: `--token`, `--project`, `--base-url`. 2. Environment: `ZKAO_API_TOKEN`, `ZKAO_PROJECT_ID`, `ZKAO_URL`. 3. The saved config file. ## Revoking a token [Section titled “Revoking a token”](#revoking-a-token) Revoke a token under **Project Settings → Integrations**. It stops working at once. A token also stops working when its project or organization is archived. Caution Never commit a token to a repository or paste it into a log. If one leaks, revoke it and create a new one.
# Environments
> Point the CLI and SDK at production or staging, and install the release channel that matches.
zkao runs two public environments: | Environment | App | API base | Docs | | ----------- | ----------------- | -------------------------------- | ------------------------------------------------------ | | Production | `zkao.io` | `https://zkao.io/api/v1` | [`docs.zkao.io`](https://docs.zkao.io) | | Staging | `staging.zkao.io` | `https://staging.zkao.io/api/v1` | [`docs.staging.zkao.io`](https://docs.staging.zkao.io) | The CLI and SDK target production by default. Staging runs ahead of production and gets new features first. Its data and tokens are separate: a production token does not work on staging. ## `ZKAO_URL` [Section titled “ZKAO_URL”](#zkao_url) One environment variable, `ZKAO_URL`, points the CLI and SDK at an environment. It accepts any of these forms:
```bash
ZKAO_URL=staging.zkao.io
ZKAO_URL=https://staging.zkao.io
ZKAO_URL=https://staging.zkao.io/api/v1
```
All three resolve to `https://staging.zkao.io/api/v1`. A bare host gets `https://`. A value that already ends in `/api/v1` is used as is. The CLI’s `--base-url` flag and the SDK’s `baseUrl` option are used verbatim, with no normalization. They win over `ZKAO_URL`. ## The `next` release channel [Section titled “The next release channel”](#the-next-release-channel) The CLI and SDK ship on two npm dist-tags: * `latest` matches production. * `next` matches staging. Its versions look like `X.Y.Z-next.N`. Install the staging channel when you work against staging:
```bash
npm install -g @zksecurity/zkao-cli@next
```
Or pass `--next` to the install script:
```bash
curl -fsSL https://raw.githubusercontent.com/zksecurity/zkao-sdk/main/install.sh | bash -s -- --next
```
A CLI from the `next` channel checks the `next` tag for updates, and a `latest` CLI checks `latest`. ## Logging in to staging [Section titled “Logging in to staging”](#logging-in-to-staging) Set `ZKAO_URL` when you log in:
```bash
ZKAO_URL=staging.zkao.io zkao login --project
```
Each saved project remembers the base URL it was approved on. After that, you no longer need `ZKAO_URL` for that project. ## Switching between projects and environments [Section titled “Switching between projects and environments”](#switching-between-projects-and-environments)
```bash
zkao config show # every saved project, with its base URL
zkao config use # make another saved project active
```
Switching to a staging project points the CLI at staging. Switching back to a production project points it at production. To log in to the other environment, pass `ZKAO_URL` again. Without it, `zkao login` targets the active project’s environment.
# AI agents
> Give a coding agent the zkao skill so it can launch scans, triage findings, and edit guidance on your behalf.
The zkao skill teaches an agent to drive a project through MCP, the CLI, or HTTP. It covers login, scopes, scans, triage, guidance, credits, and publishing. Claude Code and Codex plugins share the same skill and MCP connection. An agent with the skill can handle requests like “enable formal verification on the main branch with a monthly budget of 500 credits” or “run a diff scan of this change”. ## Install the skill [Section titled “Install the skill”](#install-the-skill) * Claude Code The repository is a Claude Code plugin marketplace. Add it, then install the plugin:
```text
/plugin marketplace add zksecurity/zkao-sdk
/plugin install zkao@zkao
```
* Codex Add the repository as a plugin marketplace:
```bash
codex plugin marketplace add zksecurity/zkao-sdk
```
Install `zkao` from that marketplace in the desktop app’s Plugins directory. The portable plugin uses the same skill as Claude Code. * Other agents Save the skill into your agent’s skills directory:
```bash
curl -fsSL https://docs.zkao.io/skill.md -o SKILL.md
```
Agents without a skills system can read the same URL as context. Shell-based agents can use the CLI from the [Quickstart](/quickstart/). ## Connect with MCP [Section titled “Connect with MCP”](#connect-with-mcp) Add `https://zkao.io/api/mcp` as a remote MCP server in your client. It uses Streamable HTTP and OAuth. Follow the client’s sign-in flow to approve a project and its permissions. The plugin manifests configure this endpoint for Claude Code and Codex. You do not need to copy an API token into the plugin. The connection belongs to one project. Use its identity tool to check the project before acting. CLI login and MCP authorization are separate. For staging, configure `https://staging.zkao.io/api/mcp` instead. ## Complete the review [Section titled “Complete the review”](#complete-the-review) After analysis finishes, the agent reads the scan’s `triage` completeness. A `COMPLETED` scan can still have unreviewed findings. Those findings are withheld from results. When triage stopped on budget, the scan offers allowed resumption budgets. The agent can resume within the spending limit you authorized. It reuses the same request key and budget when retrying. It tracks the returned triage run, then checks the scan’s completeness again. See [Resume unfinished triage](/guides/scans/#resume-unfinished-triage). For fixes, the agent reads the finding’s evidence and verifies the change with a scan or recheck. Further scans and triage require an authorized credit budget. ## Docs for agents [Section titled “Docs for agents”](#docs-for-agents) Every page on this site has a plain Markdown version for agents. | URL | What it holds | | -------------------------------------- | -------------------------------------------------------------------------------- | | [`/llms.txt`](/llms.txt) | An index of the docs, following the [llms.txt](https://llmstxt.org/) convention. | | [`/llms-full.txt`](/llms-full.txt) | All guides and API reference pages in one file. | | [`/llms-small.txt`](/llms-small.txt) | A shorter bundle of guides. | | `.md` pages | One page as Markdown. Replace the trailing slash with `.md`. | | [`/openapi/v1.yaml`](/openapi/v1.yaml) | The full API contract. | Each page also has a **Copy as Markdown** button next to its title. Requests with `Accept: text/markdown` receive Markdown at the normal page URL. ## Logging in from an agent [Section titled “Logging in from an agent”](#logging-in-from-an-agent) A bare `zkao login` waits for browser approval for minutes. Most agent tool calls time out first. Split the login instead, so no command blocks. 1. Start the login. It prints a URL and a code, then exits.
```bash
zkao login --no-wait --no-browser --project
```
`--project` is optional. It preselects the project on the approval page. 2. The agent gives the URL and code to you. You open the URL, check the code, pick the project, and approve. 3. The agent finishes the login.
```bash
zkao login --resume
```
Each call returns at once. `Still waiting for approval` means try again later. `Authorized` means the token is saved. Pass `--timeout ` to wait up to that long in one call. You can approve several projects in one login. Each one gets its own saved token. `zkao config use ` switches between them. Caution Only approve a login you started. Approving mints a real API token for the project you pick. Revoke it any time under **Project Settings → Integrations**. For unattended agents, create a token by hand instead and pass it through `ZKAO_API_TOKEN` and `ZKAO_PROJECT_ID`. See [Authentication](/authentication/). ## Keeping the skill current [Section titled “Keeping the skill current”](#keeping-the-skill-current) The CLI checks npm for a newer release at most once a day. When one exists, every command prints a notice on stderr:
```text
zkao: version X.Y.Z is available (running A.B.C). Update with `npm install -g @zksecurity/zkao-cli`. If you are an agent working from a zkao skill file, update that too: it may describe fewer commands than the API now offers.
```
The notice never touches stdout, so piping output to `jq` keeps working. An agent that sees it should update the CLI and fetch the skill again. Set `ZKAO_NO_UPDATE_CHECK=1` to turn the check off.
# Credits and usage
> How the prepaid credit balance works, what a scan reserves, and how to read balance, usage, and monthly spend over the API.
zkao is pay as you go. You buy credits, and scans spend them. Credits are the only unit the API uses. ## Where the balance lives [Section titled “Where the balance lives”](#where-the-balance-lives) Every project belongs to an organization. The organization holds one prepaid balance. All of its projects share it. A project token still sees one project. The billing endpoints report the organization’s balance as seen from that project. Usage and monthly spend cover only that project’s activity. Credits are bought in the zkao app, not over the API. ## What a scan reserves [Section titled “What a scan reserves”](#what-a-scan-reserves) A launch reserves the scan’s full budget from the balance. The scan then spends only what its analysis uses, never more than the budget. When it finishes, the unused part is released. A cancelled scan releases its reservation too. So the balance has three numbers: | Field | Meaning | | ------------------ | -------------------------------------------------------------------- | | `balanceCredits` | The organization’s total prepaid balance. | | `reservedCredits` | Credits held by the organization’s queued and running scans. | | `availableCredits` | The balance minus reservations. This is what a new scan can reserve. | Active scans in other projects of the organization reduce `availableCredits` too. ## Check the balance [Section titled “Check the balance”](#check-the-balance) * CLI
```bash
zkao billing balance
```
* TypeScript
```ts
const { availableCredits, organization } = await zkao.getBillingBalance();
```
* curl
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/billing/balance
```
The response names the organization that owns the balance. Check `availableCredits` before choosing a budget. ## When credits run out [Section titled “When credits run out”](#when-credits-run-out) A launch whose budget the balance cannot cover fails with `402 insufficient_credits`. Add credits in the app, or launch with a smaller budget. Reading the balance and usage keeps working with an empty balance. A token can also carry its own spend limit, set when it was created. `zkao whoami` shows it as `spendLimitCredits`. A launch past that limit fails with `429 rate_limited`. ## Read the usage ledger [Section titled “Read the usage ledger”](#read-the-usage-ledger) The ledger lists every credit movement attributed to the project. Each event has a signed `credits` value. Negative means spent, positive means added or refunded. | Type | Meaning | | ------------------ | -------------------------------------------- | | `SCAN_DEDUCTION` | Credits a scan spent. | | `SCAN_REFUND` | Credits returned to the balance from a scan. | | `PURCHASE` | Credits bought. | | `STRIPE_REFUND` | A purchase refunded. | | `ADMIN_ADJUSTMENT` | A manual adjustment by zkao. | * CLI
```bash
zkao billing usage
zkao billing usage --from 2026-09-01 --to 2026-10-01 --limit 200
```
* TypeScript
```ts
const { from, to, events } = await zkao.getBillingUsage({
from: "2026-09-01T00:00:00Z",
});
```
* curl
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
"https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/billing/usage?from=2026-09-01T00:00:00Z"
```
The default range is the last 30 days. The response echoes the range it used. Events come newest first, up to 1,000. Movements made outside any project, such as an organization top-up, are not listed. ## Monthly summary [Section titled “Monthly summary”](#monthly-summary) The summary gives net credits spent on scans and net credits purchased, per calendar month in UTC. Months come newest first, and quiet months show zeros. Ask for up to 24 months. * CLI
```bash
zkao billing summary --months 6
```
* TypeScript
```ts
const months = await zkao.getBillingSummary({ months: 6 });
```
* curl
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
"https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/billing/summary?months=6"
```
# Diff scans
> Audit only what changed between a base and a head commit, which is cheap enough to run on every pull request.
A diff scan audits one change instead of the whole repository. It reads the code that changed between a base and a head commit. The rest of the repository is context, not a target. That makes it cheap and fast. ## How the change is measured [Section titled “How the change is measured”](#how-the-change-is-measured) * The **head** is the commit you scan. Set it with `commitHash` or `branch`, as for any scan. * The **base** is what the change is measured from. It can be a commit SHA, a branch, or a tag. zkao compares the two on GitHub and audits the change from their merge base to the head. The scan records that merge base SHA as its `baseCommit`. So a base branch that moved on since you branched off does not pull its new commits into the diff. ## Launch a diff scan [Section titled “Launch a diff scan”](#launch-a-diff-scan) 1. Push the head commit to GitHub. zkao reads both commits from there. 2. Launch with a diff preset and a base. `builtin:Flash Diff` is the cheap one. `builtin:Max Diff` runs every technique on flagship models. 3. Wait for it, as for any scan. See [Run scans](/guides/scans/#follow-a-scan). * CLI
```bash
zkao scans launch --repo --preset "builtin:Flash Diff" \
--base main --commit
zkao scans wait
```
* TypeScript
```ts
const { scanId } = await zkao.launchScan({
repositoryId: repoId,
presetRef: "builtin:Flash Diff",
baseCommit: "main",
commitHash: headSha,
});
const scan = await zkao.waitForScan(scanId);
```
* curl
```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"repositoryId":"","presetRef":"builtin:Flash Diff","baseCommit":"main","commitHash":""}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans
```
Confirm the preset ref with `zkao presets`. The budget works as for any scan. Leave it out to use the recommended budget. It is sized from the change, up to three times the preset’s minimum. When no earlier scan of the repository built its overview, the diff scan builds one first. That scan takes longer, and its minimum and recommended budgets are higher. The launch response then sets `buildsOverview` to `true`. You can also give a diff scan per-scan guidance. ## Diff scan errors [Section titled “Diff scan errors”](#diff-scan-errors) Only a diff scan preset takes a base, and it always needs one. | Status | Code | Cause | | ------ | ----------------------- | --------------------------------------------------------------------------------- | | `400` | `diff_base_required` | A diff scan was launched without a base. | | `400` | `diff_base_not_allowed` | A base was sent with a preset that is not a diff scan. | | `400` | `diff_base_invalid` | The base is not a valid name, does not exist, or shares no history with the head. | | `422` | `diff_empty` | The head changes nothing since the base. There is nothing to audit. | The message says which case applies. A failed comparison on GitHub’s side returns `400 bad_request`. That one is transient, so retry it later. ## Run diff scans in CI [Section titled “Run diff scans in CI”](#run-diff-scans-in-ci) Diff scans fit pull requests. Use the pull request’s base branch as the base and its head commit as the head. The [zkao GitHub Action](/guides/github-action/) does this for you with `scan: flash` or `scan: max`. It picks the pull request’s base, or the commit before a push. It can also fail the job when the scan finds issues above a severity.
# Triage findings
> List a project's findings, read one in full, and record your verdict with comments, severity and triage overrides, and resolution statuses.
A finding is one issue a scan reported. Each finding carries two separate statuses. * `triageStatus` is zkao’s own verdict on the finding. You can [override it](#override-the-triage-verdict) when you disagree. * `resolutionStatus` is your team’s decision about it. You set it. Reading findings needs the `read` scope. Review decisions need `findings:write`. Regression test requests need `regression-tests:write`. ## List findings [Section titled “List findings”](#list-findings) The list holds every finding in the project, most severe first. Filter it to one scan with its id. * CLI
```bash
zkao findings list
zkao findings list --scan --limit 100
```
* TypeScript
```ts
const { items, total } = await zkao.listFindings({ scanId, limit: 100 });
```
* curl
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
"https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings?scanId=&limit=100"
```
The list paginates with `page` and `limit`. The default limit is 50 and the maximum is 100. Each item has these fields. | Field | Meaning | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title`, `location`, `category` | What the issue is and where. | | `severity` | The effective severity: your override if set, otherwise zkao’s. | | `triageStatus` | zkao’s verdict, such as `CONFIRMED`, `FALSE_POSITIVE` or `DUPLICATE`. | | `confirmationEvidence` | For a `CONFIRMED` finding, `POC` when a proof of concept ran, or `ANALYSIS` when code analysis alone confirmed it. | | `resolutionStatus` | Your team’s decision. New findings start at `NOT_STARTED`. | | `notesCount` | How many comments the finding has. | | `source` | Where the finding was found: `kind` names the kind of scan, such as `continuous-security`, `pr-review` or `max`, and `branch` is the branch it scanned. Treat an unknown `kind` like `other`. | See [List findings](/api/operations/listfindings/) for the full schema. ## Read one finding [Section titled “Read one finding”](#read-one-finding) The detail view adds the description, impact, recommendation, commit, repository, and comments. * CLI
```bash
zkao findings get
```
* TypeScript
```ts
const finding = await zkao.getFinding(findingId);
console.log(finding.description, finding.recommendation, finding.notes);
```
* curl
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings/
```
### `ZK-` labels [Section titled “ZK- labels”](#zk--labels) A finding page on zkao shows a short label such as `ZK-3f9a2c1b`. It is the last eight characters of the finding id. Every finding endpoint accepts it in place of the full id, with or without the `ZK-` prefix. A label is unique within a project in practice, but not by construction. A label that matches two findings returns `409`. Use the full id then. ## Regression tests [Section titled “Regression tests”](#regression-tests) Request a minimal regression test for a confirmed finding. The test replays a fixed counterexample using the repository’s own test framework. It asserts the intended secure behavior, so it fails against vulnerable code. If the target revision still has the bug, the test-only pull request needs a fix before it can pass. The token needs `read` for readiness and status calls. It needs `regression-tests:write` to request a test or retry publication. Its creator must remain a project admin with verified GitHub write access. The GitHub App must have Contents and Pull requests write permissions for the repository. The readiness response names missing setup and provides an installation settings link when available.
```ts
const readiness = await zkao.getRegressionTestReadiness(findingId);
if (readiness.status !== "ready") throw new Error(readiness.message);
const { run } = await zkao.createRegressionTest(
findingId,
{ creditBudget: 100, targetBranch: "main" },
{ idempotencyKey: "one-regression-test-request" },
);
const current = await zkao.getRegressionTest(findingId, run.id);
console.log(current.status, current.pullRequestUrl);
```
The equivalent HTTP request is:
```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
-H "Content-Type: application/json" -H "Idempotency-Key: one-regression-test-request" \
-d '{"creditBudget":100,"targetBranch":"main"}' \
"https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings/$FINDING_ID/regression-tests"
```
Launch returns `202` with `run` and `replayed`. Omit `targetBranch` to use the repository’s default branch. The request pins that branch’s commit and reserves its own credit budget. Project and token spending limits include this budget. Reuse the same key, budget, and branch after an uncertain response. The API returns the original attempt without another reservation. Follow the run with `getRegressionTest`, separately from its source scan. `listRegressionTests(findingId)` returns the latest attempts. `PUBLISHED` includes the draft pull request URL. `BLOCKED` means a suitable test could not be verified. `FAILED` means generation failed. `PUBLICATION_FAILED` means the generated test was retained but opening its pull request failed. Retry that publication without another generation budget:
```ts
await zkao.retryRegressionTestPublication(findingId, run.id);
```
The HTTP endpoint is `POST /projects/{projectId}/findings/{findingId}/regression-tests/{runId}/retry-publication`. It takes no body and returns `202` with the run. Generation failures require a new paid attempt. ## Comment [Section titled “Comment”](#comment) A comment is a Markdown note on the finding. Your team sees it on zkao. * CLI
```bash
zkao findings comment "Reproduced on the release branch."
```
* TypeScript
```ts
const { noteId } = await zkao.addFindingNote(findingId, "Reproduced on the release branch.");
```
* curl
```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \
-d '{"content":"Reproduced on the release branch."}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings//notes
```
The response returns the new `noteId`. You can pin that note as the finding’s resolution note with [Pin a note](/api/operations/pinfindingnote/) or the SDK’s `pinFindingNote`. ## Override severity [Section titled “Override severity”](#override-severity) The levels are `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` and `INFO`. Clearing the override restores zkao’s severity. * CLI
```bash
zkao findings severity LOW
zkao findings severity none # clear the override
```
* TypeScript
```ts
await zkao.setFindingSeverity(findingId, "LOW");
await zkao.setFindingSeverity(findingId, null); // clear the override
```
* curl
```bash
curl -X PATCH -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \
-d '{"severity":"LOW"}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings//severity
```
## Override the triage verdict [Section titled “Override the triage verdict”](#override-the-triage-verdict) Replace zkao’s verdict with `CONFIRMED` or `FALSE_POSITIVE`. Setting the AI’s own verdict again clears the override. A note is added to the finding as a comment. * CLI
```bash
zkao findings triage false-positive \
--note "The caller checks the length before this point."
```
* TypeScript
```ts
await zkao.overrideFindingTriage(findingId, "FALSE_POSITIVE", {
note: "The caller checks the length before this point.",
});
```
* curl
```bash
curl -X PATCH -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \
-d '{"triageStatus":"FALSE_POSITIVE","note":"The caller checks the length before this point."}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings//triage
```
The response returns `triageStatus`, `previousTriageStatus`, and the comment’s `noteId`. The triage verdict is separate from the resolution status. Set the resolution to record what your team does about the finding. ## Set a resolution [Section titled “Set a resolution”](#set-a-resolution) | Status | Meaning | | ---------------- | ----------------------------------- | | `NOT_STARTED` | Nobody has looked at it yet. | | `IN_PROGRESS` | Someone is working on it. | | `RESOLVED` | Fixed. | | `MITIGATED` | Not fixed, but its risk is reduced. | | `WONT_FIX` | Accepted as is. | | `FALSE_POSITIVE` | Not a real issue. | | `DUPLICATE` | Already covered by another finding. | A status alone records the outcome, not the reason. Attach the reason in the same call, in one of two ways. * `note` is free text. It becomes a comment on the finding. * `reason` is a short code from a fixed catalog. It is also recorded as a comment. Pass one or the other. When both are present, the note wins. Both are ignored for `NOT_STARTED` and `IN_PROGRESS`. * CLI
```bash
zkao findings resolution FALSE_POSITIVE \
--note "The caller checks the length before this point."
zkao findings resolution WONT_FIX --reason risk_accepted
```
* TypeScript
```ts
await zkao.setFindingResolution(findingId, "FALSE_POSITIVE", {
note: { content: "The caller checks the length before this point." },
});
await zkao.setFindingResolution(findingId, "WONT_FIX", { reason: "risk_accepted" });
```
* curl
```bash
curl -X PATCH -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \
-d '{"resolutionStatus":"WONT_FIX","reason":"risk_accepted"}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings//resolution
```
Over HTTP, `note` can also reuse an existing comment: `{"existingNoteId": ""}`. ### Reason codes [Section titled “Reason codes”](#reason-codes) Each status offers its own codes. A code from another status returns `400` with the valid list. | Status | Codes | | ---------------- | ------------------------------------------------------------------------------------------- | | `RESOLVED` | `fixed_in_code`, `fixed_upstream`, `code_removed` | | `MITIGATED` | `compensating_control`, `limited_exposure`, `monitored` | | `FALSE_POSITIVE` | `not_reachable`, `guarded_elsewhere`, `intended_behavior`, `misread_code`, `bad_assumption` | | `WONT_FIX` | `risk_accepted`, `out_of_scope`, `not_worth_fixing`, `code_being_removed` | | `DUPLICATE` | `duplicate_of_finding`, `same_root_cause` | ## A triage pass [Section titled “A triage pass”](#a-triage-pass) 1. Find the latest completed scan.
```bash
zkao scans list
```
2. List its findings.
```bash
zkao findings list --scan
```
3. Read each one in full, including the proof of concept.
```bash
zkao findings get
```
4. Record the verdict, with the reason.
```bash
zkao findings severity MEDIUM
zkao findings resolution RESOLVED --reason fixed_in_code
```
Some knowledge applies to the whole repository, not one finding. A known non-issue is one example. A comment does not carry it into future scans. Put it in the [repository guidance](/guides/guidance/) instead.
# GitHub Action
> Launch a zkao scan from a GitHub workflow, report its findings in the job summary, and gate pull requests on severity.
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 [Section titled “Before you start”](#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](/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](/guides/credits/). ## Scan every push to main [Section titled “Scan every push to main”](#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. ## Gate pull requests on a diff scan [Section titled “Gate pull requests on a diff scan”](#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](/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 [Section titled “Comment on the pull request”](#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`. ## Run a scan from a comment [Section titled “Run a scan from a comment”](#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 [Section titled “Modes”](#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 [Section titled “What to run”](#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”](#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”](#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 [Section titled “Keeping the cost in check”](#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 `. * 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 [Section titled “How it works”](#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.
# Repository guidance
> Steer every scan of a repository with standing guidance on scope, threat model, and accepted risks, and keep it current over the API.
Guidance tells zkao what matters in your code. It covers scope, attacker powers, trusted components, security properties, severity expectations, and accepted risks. Good guidance makes scans sharper and cuts false positives. ## Three layers [Section titled “Three layers”](#three-layers) Guidance can come from three places. They stack, and a later layer can refine an earlier one. 1. **A committed `zkao.md`** at the repository root. It ships with your code and is read at the scanned commit. It changes only when you commit a change. 2. **Repository guidance**, stored in zkao. It applies to every scan of the repository without touching the code. This page is about this layer. 3. **Scan guidance**, sent with one launch. It replaces repository guidance for that scan only. See [Guide one scan](/guides/scans/#guide-one-scan). Repository guidance is the right home for a repository you do not control. It also suits knowledge you do not want to commit. Guidance is a strong steer, not an access-control boundary or a guaranteed file filter. To limit what a scan audits, scope it to [audit areas](/guides/scans/#scope-a-scan-to-audit-areas). ## Read guidance [Section titled “Read guidance”](#read-guidance) * CLI
```bash
zkao guidance get
```
* TypeScript
```ts
const { content, updatedAt } = await zkao.getRepositoryGuidance(repoId);
```
* curl
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories//guidance
```
`content` is `null` when no guidance is set. Reading needs the `read` scope. The committed `zkao.md` is not part of this response. ## Set or clear guidance [Section titled “Set or clear guidance”](#set-or-clear-guidance) Writing needs the `guidance:write` scope. Each change records a revision. Writing the content already stored is a no-op that returns `unchanged: true`. Guidance is limited to 100,000 characters. * CLI
```bash
zkao guidance set guidance.md
cat guidance.md | zkao guidance set -
zkao guidance clear
```
* TypeScript
```ts
const current = await zkao.getRepositoryGuidance(repoId);
await zkao.setRepositoryGuidance(repoId, newContent, {
expectedContent: current.content,
});
// Clear it.
await zkao.setRepositoryGuidance(repoId, null);
```
* curl
```bash
curl -X PUT -H "Authorization: Bearer $ZKAO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"# Scope\nAudit src/verifier only.","expectedContent":null}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories//guidance
```
### Avoid overwriting a concurrent edit [Section titled “Avoid overwriting a concurrent edit”](#avoid-overwriting-a-concurrent-edit) Teammates, and accepted suggestions in the app, also edit guidance. `expectedContent` protects you from clobbering their change. * Send the content you last read, or `null` if none was set. * If the stored guidance changed since then, the write fails with `409 conflict`. * Read it again, merge your change, and retry. * Leave `expectedContent` out for last writer wins. The CLI does the compare-and-set for you. `zkao guidance set` and `zkao guidance clear` read the current guidance first and send it as `expectedContent`. Pass `--force` to skip that check and overwrite. ## Keep it lean [Section titled “Keep it lean”](#keep-it-lean) Every line is read on every scan. A short file the analysis takes in beats a long one it skims. Use repository-relative paths. Never include credentials or secrets. Put durable facts in repository guidance or `zkao.md`. Put a one-off focus in scan guidance instead. Triage often surfaces knowledge that applies to the whole repository, such as a known non-issue. A comment on one finding does not carry it forward, but guidance does.
# Publish results
> Turn a finding or a completed scan into a public page you can share, optionally behind a password.
Publishing creates a public page on zkao for one finding or one scan. Anyone with the link can read it. Nothing else in the project becomes visible. Publishing needs the `publish` scope. `zkao login` does not request it by default. Ask for it when you log in:
```bash
zkao login --scope read scans:launch findings:write guidance:write publish
```
## Publish a finding [Section titled “Publish a finding”](#publish-a-finding) A published finding shows its title, severity, repository, commit, description, impact, and recommendation. You can also attach one of its comments as the team’s public response. Pass that comment’s id as the note. * CLI
```bash
zkao findings publish
zkao findings publish --note --password
```
* TypeScript
```ts
const { publicId, accessPassword } = await zkao.publishFinding(findingId, {
noteId,
withPassword: true,
});
```
* curl
```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \
-d '{"noteId":"","withPassword":true}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings//publish
```
The note must belong to the finding. Another finding’s note returns `400`. The finding id also accepts a [`ZK-` label](/guides/findings/#zk--labels). ## Publish a scan [Section titled “Publish a scan”](#publish-a-scan) A published scan lists the scan’s reported findings, most severe first. It covers the findings zkao confirmed, and those it marked as needing review. Only a `COMPLETED` scan can be published. * CLI
```bash
zkao scans publish
zkao scans publish --password
```
* TypeScript
```ts
const { publicId, accessPassword } = await zkao.publishScan(scanId, { withPassword: true });
```
* curl
```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \
-d '{"withPassword":true}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans//publish
```
## The result [Section titled “The result”](#the-result) Both calls return the same shape.
```json
{
"artifactId": "…",
"publicId": "…",
"accessPassword": null
}
```
The public page lives at one of these URLs. * `https://zkao.io/public/findings/` * `https://zkao.io/public/scans/` ## Password protection [Section titled “Password protection”](#password-protection) With `withPassword`, zkao generates a password and returns it as `accessPassword`. Visitors must enter it to read the page. Share it separately from the link. Caution Publishing again keeps the same link, but resets the options. A call without `withPassword` removes the password. A call with it generates a new one. For a finding, a call without a note removes the public response. ## Unpublishing [Section titled “Unpublishing”](#unpublishing) The API publishes but does not unpublish. Unpublish a page from the finding or scan on zkao. See [Publish a finding](/api/operations/publishfinding/) and [Publish a scan](/api/operations/publishscan/) for the full schemas.
# Run scans
> Pick a repository and a scan type, launch a scan with a credit budget, follow it to the end, and cancel it if needed.
A scan audits one commit of one repository. You choose the scan type and a credit budget. zkao reserves the budget, runs the analysis, and records findings on the project. The TypeScript examples use a client created as shown in the [SDK reference](/reference/sdk/). The curl examples assume `ZKAO_API_TOKEN` and `ZKAO_PROJECT_ID` are set. ## The flow [Section titled “The flow”](#the-flow) 1. Find the repository and check that it is ready. 2. Pick a scan type (a preset). 3. Launch the scan with a budget. 4. Wait for it to finish. 5. Read its findings. See [Triage findings](/guides/findings/). ## Find a repository [Section titled “Find a repository”](#find-a-repository) List the repositories in the project. A token restricted to some repositories only sees those. * CLI
```bash
zkao repos
```
* TypeScript
```ts
const repositories = await zkao.listRepositories();
```
* curl
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories
```
Each repository has a `readiness` field. A repository added moments ago is `analyzing`. zkao makes a one-time pass over it first, and that pass costs no credits. A launch during that pass fails with `409 repository_initializing`. Wait for `ready` instead of retrying the launch. * CLI
```bash
zkao repos:wait
```
* TypeScript
```ts
await zkao.waitForRepositoryReady(repoId);
```
* curl
```bash
# Poll until the repository reports "readiness": "ready".
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories
```
The SDK waits up to 30 minutes by default. It backs off between polls and honors `Retry-After`. ## Pick a scan type [Section titled “Pick a scan type”](#pick-a-scan-type) A preset is a scan type. Each one runs a fixed set of analyses. Broader types run more analysis and need a larger budget. * CLI
```bash
zkao presets
```
* TypeScript
```ts
const presets = await zkao.listScanPresets();
```
* curl
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scan-presets
```
The builtin presets come in two tiers. Flash runs one focused analysis, led by a flagship model when it audits the code or a change. Max runs every technique on flagship models. Each tier has a preset for the code (`builtin:Flash`, `builtin:Max`), a change (`builtin:Flash Diff`, `builtin:Max Diff`), open findings (`builtin:Flash Retriage`, `builtin:Max Retriage`), and resolved findings (`builtin:Flash Regression Check`, `builtin:Max Regression Check`). Earlier names still resolve. Each preset has a `ref`, a `name`, a `description`, and a `minCredits` floor. Pass the `ref` when you launch. Without one, the launch uses the first active preset. ## Choose a budget [Section titled “Choose a budget”](#choose-a-budget) The budget is the most a scan may spend, in credits. zkao reserves it at launch and never charges more. Credits the scan does not use go back to the balance. You can leave the budget out. zkao then picks the budget it recommends for this scan type and scope on this repository. The recommendation follows what past scans of the repository spent. The first scan of a repository starts at the scan type’s minimum. A diff scan is sized from its change instead, up to three times the minimum. The launch response tells you which budget was used. A scan that runs short of budget stops early, so treat its coverage as partial. See [Credits and usage](/guides/credits/) for how reservations affect the balance. ## Launch a scan [Section titled “Launch a scan”](#launch-a-scan) * CLI
```bash
zkao scans launch --repo --preset --budget 500
```
* TypeScript
```ts
const { scanId, creditBudget } = await zkao.launchScan({
repositoryId: repoId,
presetRef: ref,
creditBudget: 500,
});
```
* curl
```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"repositoryId":"","presetRef":"","creditBudget":500}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans
```
The API answers `202` with `scanId`, `queued`, `creditBudget`, and `buildsOverview`. Launching needs the `scans:launch` scope. ### Choose the commit [Section titled “Choose the commit”](#choose-the-commit) By default a scan runs on the head of the repository’s default branch. * `branch` scans the head of that branch, resolved when the scan launches. * `commitHash` pins one commit (7 to 40 hex characters). It wins over `branch`. * `commitMessage` is optional metadata shown with the scan. The CLI flags are `--branch`, `--commit`, and `--message`. The commit must be pushed to GitHub, because zkao reads it from there. ### Scope a scan to audit areas [Section titled “Scope a scan to audit areas”](#scope-a-scan-to-audit-areas) An audit area is a named subsystem of the repository. zkao discovers areas when it maps the code. You can add your own. Scoping a scan to a few areas keeps a large repository affordable. * CLI
```bash
zkao areas list
zkao scans launch --repo --preset "builtin:Max" --area --area
```
* TypeScript
```ts
const { areas } = await zkao.listAuditAreas(repoId);
await zkao.launchScan({
repositoryId: repoId,
presetRef: "builtin:Max",
auditAreaKeys: [areas[0].key],
});
```
* curl
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories//audit-areas
```
Each area reports its size in files and lines from one branch’s map. Pass `--branch` (or `branch`) to read another branch’s sizes. Leave the area list out to scan the whole repository. Or describe the code to audit in your own words with `--scope` (or `auditScope`). A key the current map no longer names fails the launch. zkao never drops it silently, so a budget sized for one area never runs against everything. An area is a name and a description, never a file list. Each scan resolves it against the code at its own commit. * CLI
```bash
zkao areas add "Proof verifier" --description "On-chain verifier and its key loading"
zkao areas rm
```
* TypeScript
```ts
const area = await zkao.createAuditArea(
repoId,
"Proof verifier",
"On-chain verifier and its key loading",
);
await zkao.deleteAuditArea(repoId, area.key);
```
* curl
```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Proof verifier","description":"On-chain verifier and its key loading"}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories//audit-areas
```
Adding and deleting areas needs the `guidance:write` scope. Only custom areas can be deleted. Deleting a discovered area returns `409`. ### Guide one scan [Section titled “Guide one scan”](#guide-one-scan) Guidance tells a scan what matters: scope, threat model, and accepted risks. A launch can carry guidance for that scan only. It replaces the repository’s stored guidance for this run. A `zkao.md` committed in the repository still applies underneath. * CLI
```bash
zkao scans launch --repo --guidance focus.md
cat focus.md | zkao scans launch --repo --guidance -
```
* TypeScript
```ts
await zkao.launchScan({
repositoryId: repoId,
guidance: "Focus on the proof verifier. The prover is trusted.",
});
```
* curl
```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"repositoryId":"","guidance":"Focus on the proof verifier."}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans
```
In the API, the `guidance` field has three states: * Left out: the scan uses the repository’s stored guidance. * A string: that text replaces it for this scan. * `null` or an empty string: the scan runs with no stored guidance layer. Guidance is limited to 100,000 characters. See [Repository guidance](/guides/guidance/) for the standing layer. ## Follow a scan [Section titled “Follow a scan”](#follow-a-scan) A scan moves through these statuses: | Status | Meaning | | ------------ | -------------------------------------------------------- | | `QUEUED` | Accepted and waiting to start. | | `PROCESSING` | Running. | | `COMPLETED` | Analysis finished. Check `triage` for unfinished review. | | `FAILED` | Stopped on an error. | | `CANCELLED` | Cancelled before it finished. | The last three are terminal. While a scan runs, its `progress` field reports `phasesCompleted`, `phasesTotal`, and a weighted `percent`. There is no time estimate. How long a scan takes depends on the repository and its guidance. A finished scan carries a `findingsSummary` with counts by severity. The easiest way to follow a scan is to wait on it. * CLI
```bash
zkao scans wait
zkao scans wait --timeout 7200
```
* TypeScript
```ts
const scan = await zkao.waitForScan(scanId, {
onPoll: (s) => console.log(s.status, s.progress?.percent),
});
```
* curl
```bash
curl -i -H "Authorization: Bearer $ZKAO_API_TOKEN" \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans/
```
`zkao scans wait` prints each poll on stderr and the final scan as JSON on stdout. Its `--timeout` is in seconds. The SDK’s `waitForScan` gives up after one hour by default. Set `timeoutMs` for longer scans, and pass a `signal` to abort. ### Poll politely [Section titled “Poll politely”](#poll-politely) If you poll by hand, read the `Retry-After` header on the scan response. It says how many seconds to wait before the next poll. It is present only while the scan is not terminal. A token that polls too fast gets `429 rate_limited`, also with `Retry-After`. Wait that long before the next request. The CLI and SDK do this for you. ## Resume unfinished triage [Section titled “Resume unfinished triage”](#resume-unfinished-triage) A completed scan can have findings that triage did not review. Unreviewed findings are withheld from results. Read `triage` on the scan detail before treating it as a complete review. | Field | Meaning | | ---------------- | ------------------------------------------------------------------- | | `status` | `pending`, `running`, `complete`, `budget_exhausted`, or `blocked`. | | `untriagedCount` | Findings still awaiting review. | | `activeRunId` | Active triage run, or `null`. | | `resume` | Allowed credit budgets after a budget stop, or `null`. | Resumption is available after a budget stop on a completed scan whose billing has settled. Unfinished findings must remain and no triage run may be active. Choose a budget within the offer and your authorized spending limit. Resumed triage uses the scan’s settings and only reviews the findings left over. It reserves a separate budget and returns unused credits. * CLI
```bash
zkao scans get
zkao scans resume-triage --budget --idempotency-key
zkao scans triage-wait
zkao scans get
```
* TypeScript
```ts
const { run } = await zkao.resumeTriage(
scanId,
{ creditBudget: authorizedCredits },
{ idempotencyKey: requestKey },
);
await zkao.waitForTriageRun(scanId, run.id);
const scan = await zkao.getScan(scanId);
console.log(scan.triage);
```
* curl
```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: " \
-d '{"creditBudget":250}' \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans//triage/resume
```
Resumption needs `scans:launch` and respects the token’s repository and spending limits. Keep the same key and budget when retrying the same request. That returns the original run without reserving another budget. A different budget with that key returns `409`. Use a new key only for another authorized run. The parent scan stays `COMPLETED` while resumed triage runs. Poll the returned run with `getTriageRun` or its CLI counterpart. Read the scan’s `triage` again after the run finishes. A run can finish at its budget cap with findings still awaiting review. For a `blocked` triage status, contact support with a link to the scan. ## List scans [Section titled “List scans”](#list-scans) Scans are listed newest first. The list is paginated with `page` and `limit` (at most 100, default 50). * CLI
```bash
zkao scans list --limit 20
zkao scans get
```
* TypeScript
```ts
const { items, total } = await zkao.listScans({ limit: 20 });
const detail = await zkao.getScan(items[0].id);
```
* curl
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
"https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans?limit=20"
```
## Cancel a scan [Section titled “Cancel a scan”](#cancel-a-scan) You can cancel a queued or running scan. zkao stops its work, marks it `CANCELLED`, and releases its reserved credits. Work already in flight settles what it actually spent as it winds down. * CLI
```bash
zkao scans cancel
```
* TypeScript
```ts
await zkao.cancelScan(scanId);
```
* curl
```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans//cancel
```
Cancelling needs the `scans:launch` scope. A scan that already reached `COMPLETED` or `FAILED` cannot be cancelled and returns `400`. ## Launch errors [Section titled “Launch errors”](#launch-errors) | Status | Code | What to do | | ------ | ------------------------- | ----------------------------------------------------------------------------------------- | | `400` | `bad_request` | Fix the request. The message names the problem. | | `400` | `diff_base_*` | See [Diff scans](/guides/diff-scans/). | | `402` | `insufficient_credits` | Add credits, or launch with a smaller budget. | | `403` | `forbidden` | The token lacks `scans:launch`. | | `404` | `not_found` | The repository is outside the token’s project or repository allowlist. | | `409` | `repository_initializing` | Wait for the repository to be `ready`. | | `422` | `diff_empty` | The diff scan has nothing to audit. | | `429` | `rate_limited` | The token’s spend limit is reached, or it sent too many requests. Wait for `Retry-After`. | The full contract is in the API reference for [launchScan](/api/operations/launchscan/) and [getScan](/api/operations/getscan/).
# Quickstart
> Install the zkao CLI, authorize it for a project, launch a scan, and read its findings.
This page takes you from nothing to your first findings in a terminal. You need Node 18 or later and a zkao project with at least one repository. 1. **Install the CLI.**
```bash
npm install -g @zksecurity/zkao-cli
```
This installs the `zkao` command. For a one-off run without installing, prefix commands with `npx @zksecurity/zkao-cli`. You can also use the install script:
```bash
curl -fsSL https://raw.githubusercontent.com/zksecurity/zkao-sdk/main/install.sh | bash
```
2. **Authorize it for a project.**
```bash
zkao login
```
The CLI opens a browser page and prints a short code. Check that the page shows the same code. Pick a project, review the permissions, and approve. The CLI saves the token for that project. There is nothing to copy. Confirm which project you are connected to:
```bash
zkao whoami
```
See [Authentication](/authentication/) for tokens, scopes, and non-interactive logins. 3. **Find a repository.**
```bash
zkao repos
```
Note the `id` of the repository to scan. Its `readiness` must be `ready`. A repository added moments ago is `analyzing` for a short while. `zkao repos:wait ` blocks until it is ready. 4. **Pick a scan preset.**
```bash
zkao presets
```
Each preset is a scan type. Note the `ref` of the one you want. 5. **Launch the scan.**
```bash
zkao scans launch --repo --preset
```
The response carries the `scanId` and the budget the scan reserved, in credits. Without `--budget`, zkao picks the budget it recommends for this scan type on this repository. Pass `--budget ` to set your own ceiling. `zkao billing balance` shows the credits available to the project. 6. **Wait for it to finish.**
```bash
zkao scans wait
```
The scan moves from `QUEUED` to `PROCESSING` to `COMPLETED`. Scans take minutes. `wait` polls at the pace the server asks for, so you do not need your own loop. 7. **Read the findings.**
```bash
zkao findings list --scan
zkao findings get
```
`get` returns the full finding, including the description, proof of concept, and recommended fix. Every command prints JSON on stdout, so it pipes cleanly into `jq` or a script. `zkao --help` lists every command. ## Launch without the CLI [Section titled “Launch without the CLI”](#launch-without-the-cli) The same launch over plain HTTP or the TypeScript SDK: * curl
```bash
curl -X POST "https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans" \
-H "Authorization: Bearer $ZKAO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"repositoryId":"","presetRef":""}'
```
* TypeScript
```ts
import { ZkaoClient } from "@zksecurity/zkao-sdk";
const zkao = new ZkaoClient({
token: process.env.ZKAO_API_TOKEN!,
projectId: process.env.ZKAO_PROJECT_ID!,
});
const { scanId } = await zkao.launchScan({ repositoryId: "", presetRef: "" });
await zkao.waitForScan(scanId);
const { items } = await zkao.listFindings({ scanId });
```
## Next steps [Section titled “Next steps”](#next-steps) * [Scans](/guides/scans/) covers presets, budgets, branches, areas, and per-scan guidance. * [Triage findings](/guides/findings/) covers severity, resolution, and notes. * [CLI reference](/reference/cli/) lists every command and flag.
# API conventions
> Base URL, authentication, errors, pagination, rate limits, and identifiers shared by every zkao API endpoint.
These rules apply to every endpoint in the [API reference](/api/). The machine-readable contract is the OpenAPI spec at [`/openapi/v1.yaml`](/openapi/v1.yaml). ## Base URL [Section titled “Base URL”](#base-url)
```plaintext
https://zkao.io/api/v1
```
Project resources live under `/projects/{projectId}`, for example `/projects/{projectId}/scans`. The one exception is `GET /token`, which needs no project id. Staging uses `https://staging.zkao.io/api/v1`. See [Environments](/environments/). ## Authentication [Section titled “Authentication”](#authentication) Send a project API token in the `Authorization` header:
```plaintext
Authorization: Bearer zkao_proj__
```
A token in the query string is rejected with `400`. See [Authentication](/authentication/) for how to get a token and what its scopes allow. ## Requests and responses [Section titled “Requests and responses”](#requests-and-responses) Request and response bodies are JSON. Send `Content-Type: application/json` with a body. Timestamps are ISO 8601 strings. ## Errors [Section titled “Errors”](#errors) Every error uses one envelope:
```json
{ "error": { "code": "not_found", "message": "Not found" } }
```
Branch on `code`. The `message` is for people and can change. | Status | Code | Meaning | | ------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `bad_request` | The request is invalid. The message says why. | | `400` | `budget_below_minimum` | The budget is below the scan’s minimum. `minimumCredits` names it. A repository’s first diff scan also builds its overview, so its minimum is higher. | | `400` | `diff_base_required`, `diff_base_not_allowed`, `diff_base_invalid` | A diff scan’s base is missing, given to a preset that refuses it, or malformed. | | `401` | `unauthorized` | The token is missing, malformed, expired, or revoked. | | `402` | `insufficient_credits` | The organization’s credits cannot cover the scan. | | `403` | `forbidden` | The token lacks the scope this call needs. | | `404` | `not_found` | The resource does not exist, or is outside the token’s project or repository allowlist. | | `409` | `conflict` | A concurrent change, such as guidance edited since you read it, or an ambiguous `ZK-` label. | | `409` | `repository_initializing` | The repository is still being analyzed. Retry once its `readiness` is `ready`. | | `422` | `diff_empty` | A diff scan has no change to audit between the base and the head. | | `429` | `rate_limited` | Too many requests, or the token’s spend limit is reached. | | `500` | `internal` | Something failed on zkao’s side. | zkao answers `404`, not `403`, for anything outside a token’s reach. That way a token cannot probe which ids exist. The SDK throws `ZkaoApiError` for any non-2xx response, with `.status`, `.code`, and `.message`. The CLI prints `Error (): ` on stderr and exits with code 1. ## Pagination [Section titled “Pagination”](#pagination) List endpoints for scans and findings take `page` and `limit` query parameters:
```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
"https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings?page=2&limit=100"
```
* `page` starts at 1. * `limit` defaults to 50 and is capped at 100. They return:
```json
{ "items": [], "page": 2, "limit": 100, "total": 312 }
```
Keep requesting pages until `page * limit >= total`. Other lists, such as repositories and presets, return everything in one response. ## Rate limits and polling [Section titled “Rate limits and polling”](#rate-limits-and-polling) Each token has a request ceiling per time window. Normal use never reaches it. Past it, the API returns `429 rate_limited` with a `Retry-After` header in seconds. Wait that long before retrying. While a scan is still running, `GET /scans/{scanId}` returns an advisory `Retry-After` header. It says how long to wait before polling again. Honor it instead of polling in a tight loop. The SDK’s `waitForScan` and the CLI’s `zkao scans wait` do this for you. A launch that would push a token past its spend limit also returns `429`. ## Identifiers [Section titled “Identifiers”](#identifiers) Ids are opaque strings. Treat them as such. A finding also has a `ZK-` label, shown on its page. The label is the id’s last eight characters. Every endpoint that takes a `findingId` also accepts the label, with or without the `ZK-` prefix. A label that matches more than one finding in the project returns `409 conflict`. Use the full id then. Projects, organizations, and repositories also carry a `slug`. Slugs form the readable app URLs, such as `/orgs//projects//repos/`. API paths use ids, not slugs. ## Credits [Section titled “Credits”](#credits) Every budget, balance, and spend in the API is in credits. Credits are the only unit the API reports. See [Credits and billing](/guides/credits/). ## Versioning [Section titled “Versioning”](#versioning) The major version is part of the path: `/api/v1`. New endpoints and new response fields can appear within v1. Ignore fields your client does not recognize.
# CLI reference
> Every zkao command, argument, and option, with the settings and environment variables the CLI reads.
The `zkao` command ships in the `@zksecurity/zkao-cli` package. It needs Node 18 or later.
```bash
npm install -g @zksecurity/zkao-cli
```
To run a single command without installing, use `npx @zksecurity/zkao-cli `. `zkao --help` and `zkao --help` always list the commands of the version you run. ## Output and exit codes [Section titled “Output and exit codes”](#output-and-exit-codes) * Commands that call the API print their result as JSON on stdout. Pipe it to `jq` or parse it. * Progress lines, warnings, and the update notice go to stderr. They never mix into the JSON. * `login`, `config set`, and `config use` print plain status lines instead of JSON. * The exit code is `0` on success and `1` on any failure. * An API error prints `Error (): ` on stderr. The codes are listed in [API conventions](/reference/api-conventions/). Pass `--json-errors` for API errors as JSON on stderr. The envelope is `{ "error": { "status": 409, "code": "conflict", "message": "..." } }`. Set `ZKAO_NO_UPDATE_CHECK=1` when parsing stderr. ## Global options [Section titled “Global options”](#global-options) These options work with every command. | Option | Meaning | | ------------------ | ------------------------------------------------------------------------------------------- | | `--token ` | Project API token. Overrides `ZKAO_API_TOKEN` and saved credentials. | | `--project ` | Project id. Overrides `ZKAO_PROJECT_ID` and the active project. | | `--base-url ` | API base URL, used exactly as given. Prefer `ZKAO_URL` unless you need a non-standard base. | | `--json-errors` | Print API errors as JSON on stderr. | | `-V, --version` | Print the CLI version. | | `-h, --help` | Show help for the CLI or a command. | ## Settings and environment [Section titled “Settings and environment”](#settings-and-environment) Each setting is taken from the first source that has it. 1. The command-line flag. 2. The environment variable. 3. The config file, `~/.zkao/config.json`. | Variable | Meaning | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `ZKAO_API_TOKEN` | Project API token (`zkao_proj_...`). | | `ZKAO_PROJECT_ID` | Project id. Picks that project’s saved token when no token is given. | | `ZKAO_URL` | Environment to target. Accepts a host, an origin, or a full API URL, such as `staging.zkao.io`. See [Environments](/environments/). | | `ZKAO_NO_UPDATE_CHECK` | Set to any value to turn off the update notice. | | `ZKAO_DEBUG` | Set to any value to log update-check failures on stderr. | The config file stores one token per project and remembers which project is active. Each saved project keeps its own base URL, so staging and production projects can live side by side. The file is written with owner-only permissions. A login started with `--no-wait` is kept in `~/.zkao/pending-login.json` until it resolves. ## Update notice [Section titled “Update notice”](#update-notice) At most once a day, after a command has printed its output, the CLI asks the npm registry for the newest version. When a newer one exists, later commands print one line on stderr:
```plaintext
zkao: version X.Y.Z is available (running A.B.C). Update with `npm install -g @zksecurity/zkao-cli`. ...
```
A prerelease install (`X.Y.Z-next.N`) follows the `next` channel and suggests `@zksecurity/zkao-cli@next`. The check never delays a command or changes its output. ## Authentication [Section titled “Authentication”](#authentication) ### `zkao login` [Section titled “zkao login”](#zkao-login) Authorize the CLI in your browser. The CLI prints a URL and a short code. You open the URL, confirm the code matches, pick one or more projects, and approve. The CLI saves a token for each approved project and makes the first one active. | Option | Meaning | | --------------------- | ------------------------------------------------------------------------------------------------------------------ | | `--no-browser` | Print the URL instead of opening a browser. | | `--no-wait` | Start the login, print the URL and code, and exit. Finish it with `--resume`. | | `--resume` | Poll a login started with `--no-wait`. Polls once by default. | | `--timeout ` | With `--resume`, keep polling up to this long. | | `--scope ` | Scopes to request. The default is `read scans:launch findings:write guidance:write`. The approver can change them. | The global `--project ` preselects that project on the approval page. For agents and CI, split the login so no call blocks:
```bash
zkao login --no-wait --no-browser # prints the URL and code, then exits
zkao login --resume # repeat until it prints "Authorized"
```
`--resume` prints `Still waiting for approval` while the login is pending. Several logins can be pending at once, and `--resume` finishes whichever is approved. See [Authentication](/authentication/). ### `zkao whoami` [Section titled “zkao whoami”](#zkao-whoami) Print the token’s id, name, scopes, repository allowlist, expiry, and spend limit, plus the project and organization it belongs to. Warns on stderr when the token belongs to a different project than the configured one. ## Config [Section titled “Config”](#config) ### `zkao config set` [Section titled “zkao config set”](#zkao-config-set) Save settings to `~/.zkao/config.json`. | Option | Meaning | | ------------------ | -------------------------------- | | `--token ` | Token to save. | | `--project ` | Project id to save or switch to. | | `--base-url ` | API base URL to save. | A token given without `--project` is looked up with the API and saved under the project it belongs to. A project id given alone switches to that project’s saved token. ### `zkao config show` [Section titled “zkao config show”](#zkao-config-show) Print the resolved settings with the token masked. Also lists every saved project with its name, organization, base URL, and whether it is active. ### `zkao config use ` [Section titled “zkao config use \”](#zkao-config-use-projectid) Make a project with saved credentials the active one. Fails when no token is saved for it. ## Repositories [Section titled “Repositories”](#repositories) ### `zkao repos` [Section titled “zkao repos”](#zkao-repos) List the project’s repositories. Each has an `id` and a `readiness` of `ready` or `analyzing`. ### `zkao repos:wait ` [Section titled “zkao repos:wait \”](#zkao-reposwait-repositoryid) Wait until a repository is ready to scan, then print it. A newly added repository is `analyzing` for a while, and a scan launched on it fails with `repository_initializing`. | Option | Meaning | | ---------------- | ---------------------------------------------------------------- | | `--timeout ` | Give up after this many milliseconds. The default is 30 minutes. | ## Presets [Section titled “Presets”](#presets) ### `zkao presets` [Section titled “zkao presets”](#zkao-presets) List the scan presets the project can launch. Pass a preset’s `ref` to `zkao scans launch --preset`. ## Scans [Section titled “Scans”](#scans) ### `zkao scans launch` [Section titled “zkao scans launch”](#zkao-scans-launch) Launch a scan and print its id. Needs the `scans:launch` scope. | Option | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `--repo ` | Repository id. Required. | | `--budget ` | Maximum budget in credits, reserved at launch. Omit it to use the budget zkao recommends for this scan type on this repository. | | `--preset ` | Scan preset ref from `zkao presets`. Defaults to the first active preset. | | `--branch ` | Branch to scan, resolved to its head commit. Ignored when `--commit` is set. | | `--commit ` | Commit to scan. | | `--base ` | Base commit, branch, or tag of a diff scan. The scan audits only the change from it. Requires a diff preset. | | `--message ` | Commit message to record with the scan. | | `--guidance ` | Guidance for this scan only, from a file or `-` for stdin. Replaces the repository’s guidance for this run. | | `--area ` | Audit area to scope the scan to. Repeat it for several. See `zkao areas list`. | | `--scope ` | The code to audit, in your own words, instead of `--area`. | See [Scans](/guides/scans/) and [Diff scans](/guides/diff-scans/). ### `zkao scans list` [Section titled “zkao scans list”](#zkao-scans-list) List scans, most recent first. | Option | Meaning | | ------------- | --------------------- | | `--page ` | Page number. | | `--limit ` | Page size, up to 100. | ### `zkao scans get ` [Section titled “zkao scans get \”](#zkao-scans-get-scanid) Print one scan’s status and detail. The status is `QUEUED`, `PROCESSING`, `COMPLETED`, `FAILED`, or `CANCELLED`. ### `zkao scans wait ` [Section titled “zkao scans wait \”](#zkao-scans-wait-scanid) Poll a scan until it is `COMPLETED`, `FAILED`, or `CANCELLED`, then print the final detail. It backs off between polls and honors the server’s `Retry-After`. Each poll prints a progress line on stderr. Ctrl-C stops waiting. The command exits `0` whichever final status the scan reaches. Read `status` in the output. | Option | Meaning | | --------------------- | --------------------------------------------------------- | | `--timeout ` | Give up after this many seconds. The default is one hour. | ### `zkao scans cancel ` [Section titled “zkao scans cancel \”](#zkao-scans-cancel-scanid) Cancel a running or queued scan. Needs the `scans:launch` scope. The reserved credits not yet spent are released. A completed or failed scan cannot be cancelled. ### `zkao scans resume-triage ` [Section titled “zkao scans resume-triage \”](#zkao-scans-resume-triage-scanid) Resume triage after its budget cap left findings unreviewed. Needs the `scans:launch` scope. Read the scan’s `triage.resume` offer before choosing a budget. | Option | Meaning | | ------------------------- | ------------------------------------------------------------------- | | `--budget ` | Explicit credit budget within the offer. Required. | | `--idempotency-key ` | Stable request key of up to 128 visible ASCII characters. Required. | The result contains `run` and `replayed`. Reuse the same key and budget when retrying the request. The same request returns its original run even after that run finishes. A different budget with that key fails with `409`. ### `zkao scans triage-get ` [Section titled “zkao scans triage-get \ \”](#zkao-scans-triage-get-scanid-runid) Read one resumed triage run. It reports `status`, `findingCount`, and `budgetExhausted`. ### `zkao scans triage-wait ` [Section titled “zkao scans triage-wait \ \”](#zkao-scans-triage-wait-scanid-runid) Wait for that triage run to finish. It honors `Retry-After` and prints progress on stderr. `--timeout ` defaults to one hour. Ctrl-C stops waiting. The parent scan stays `COMPLETED` during resumed triage. Read its `triage` again after the run finishes. A completed triage run can still leave findings unreviewed. ### `zkao scans publish ` [Section titled “zkao scans publish \”](#zkao-scans-publish-scanid) Publish a completed scan as a public page. Needs the `publish` scope. The output’s `publicId` names the page, at `https://zkao.io/public/scans/`. | Option | Meaning | | ------------ | ------------------------------------------------------------------------- | | `--password` | Protect the page with a generated password, returned as `accessPassword`. | See [Publishing](/guides/publishing/). ## Findings [Section titled “Findings”](#findings) The read commands need the `read` scope. Commands that change a finding say which scope they need. `` accepts a finding’s full id or the `ZK-` label shown on its page. A label that matches more than one finding is refused. Use the full id then. ### `zkao findings list` [Section titled “zkao findings list”](#zkao-findings-list) List findings across the project, or for one scan. | Option | Meaning | | ------------- | ----------------------------- | | `--scan ` | Only findings from this scan. | | `--page ` | Page number. | | `--limit ` | Page size, up to 100. | ### `zkao findings get ` [Section titled “zkao findings get \”](#zkao-findings-get-findingid) Print a finding’s full detail, including its proof of concept and notes. ### `zkao findings details` [Section titled “zkao findings details”](#zkao-findings-details) Print the full detail of a scan’s findings, of a set of findings, or both, in one call. It returns the findings shown in the app. It fetches every page unless `--page` is given. | Option | Meaning | | ------------- | -------------------------------------------------------------------------------------------------------- | | `--scan ` | Only findings from this scan. | | `--ids ` | Comma-separated finding ids or `ZK-` labels, at most 50. Ids that match nothing are listed in `missing`. | | `--page ` | Fetch only this page. | | `--limit ` | Page size, up to 50. | ### `zkao findings comment ` [Section titled “zkao findings comment \ \”](#zkao-findings-comment-findingid-text) Add a comment to a finding. Needs the `findings:write` scope. ### `zkao findings severity ` [Section titled “zkao findings severity \ \”](#zkao-findings-severity-findingid-level) Override a finding’s severity with `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, or `INFO`. Pass `none` to clear the override. Case does not matter. Needs the `findings:write` scope. ### `zkao findings resolution ` [Section titled “zkao findings resolution \ \”](#zkao-findings-resolution-findingid-status) Set a finding’s resolution status: `NOT_STARTED`, `IN_PROGRESS`, `RESOLVED`, `WONT_FIX`, `MITIGATED`, `FALSE_POSITIVE`, or `DUPLICATE`. Needs the `findings:write` scope. | Option | Meaning | | ----------------- | --------------------------------------------------------------------------------------------------------------------------- | | `--note ` | Record the reason as a comment in the same call. | | `--reason ` | Record the reason as a catalog code instead. Valid codes depend on the status. A wrong one is rejected with the valid list. | `--note` wins when both are given. Both are ignored for `NOT_STARTED` and `IN_PROGRESS`. See [Triage findings](/guides/findings/) for the reason codes. ### `zkao findings triage ` [Section titled “zkao findings triage \ \”](#zkao-findings-triage-findingid-verdict) Override zkao’s triage verdict with `confirmed` or `false-positive`. Needs the `findings:write` scope. Setting the AI’s own verdict again clears the override. | Option | Meaning | | --------------- | ------------------------------------------------ | | `--note ` | Record the reason as a comment in the same call. | The result has `triageStatus`, `previousTriageStatus`, and the comment’s `noteId`, or `null` without a note. ### `zkao findings publish ` [Section titled “zkao findings publish \”](#zkao-findings-publish-findingid) Publish a finding as a public page. Needs the `publish` scope. The output’s `publicId` names the page, at `https://zkao.io/public/findings/`. | Option | Meaning | | ----------------- | ------------------------------------------------------------------------- | | `--note ` | Note to show as the published note. | | `--password` | Protect the page with a generated password, returned as `accessPassword`. | ## Guidance [Section titled “Guidance”](#guidance) Guidance is text that every scan of a repository reads. See [Repository guidance](/guides/guidance/). ### `zkao guidance get ` [Section titled “zkao guidance get \”](#zkao-guidance-get-repoid) Print a repository’s guidance. ### `zkao guidance set ` [Section titled “zkao guidance set \ \”](#zkao-guidance-set-repoid-file-) Set a repository’s guidance from a file, or from stdin with `-`. Needs the `guidance:write` scope. By default the CLI reads the current guidance first and sends it along. If someone changed it in between, the write fails with a conflict instead of overwriting their edit. | Option | Meaning | | --------- | ---------------------------------------------- | | `--force` | Overwrite without the concurrent-change check. | ### `zkao guidance clear ` [Section titled “zkao guidance clear \”](#zkao-guidance-clear-repoid) Remove a repository’s guidance. It takes the same check and `--force` option as `set`. ## Audit areas [Section titled “Audit areas”](#audit-areas) An audit area is a named subsystem of a repository. A scan can be scoped to one or more areas instead of the whole repository. ### `zkao areas list ` [Section titled “zkao areas list \”](#zkao-areas-list-repoid) List a repository’s audit areas and their keys. | Option | Meaning | | ------------------- | ------------------------------------------------------------------------------------ | | `--branch ` | Read area sizes from this branch’s map. Defaults to the repository’s default branch. | ### `zkao areas add ` [Section titled “zkao areas add \ \”](#zkao-areas-add-repoid-name) Add a custom area. Its key is derived from the name. Needs the `guidance:write` scope. | Option | Meaning | | ---------------------- | -------------------------------- | | `--description ` | What this part of the code does. | ### `zkao areas rm ` [Section titled “zkao areas rm \ \”](#zkao-areas-rm-repoid-areakey) Delete a custom area. An area that a scan’s map named is refused. Needs the `guidance:write` scope. ## Continuous Security [Section titled “Continuous Security”](#continuous-security) Continuous Security analyzes a branch on its own, paid from a monthly budget. `get` needs the `read` scope. The other commands need `automations:write`. Each command takes `--branch `. It defaults to the repository’s default branch. ### `zkao continuous get ` [Section titled “zkao continuous get \”](#zkao-continuous-get-repoid) Print the branch’s schedule, what it spent this month, and its monthly budget bounds. `availableFeatures` lists the analysis IDs the branch offers. `enabledFeatures` lists the selected IDs. The schedule runs when `enabled` is true. ### `zkao continuous on ` [Section titled “zkao continuous on \”](#zkao-continuous-on-repoid) Turn automatic analysis on, or resume it. A new schedule starts at the default monthly budget unless `--budget` is given. | Option | Meaning | | ------------------------ | ---------------------------------------------------------------------------------------- | | `--budget ` | Monthly budget in credits, within the minimum and maximum that `get` reports. | | `--area ` | Audit area to rotate through, one per run. Repeat it for several. See `zkao areas list`. | | `--whole-repo` | Scan the whole repository every run. It cannot be combined with `--area`. | | `--enable-analysis ` | Add an analysis to the branch’s selection. Repeat to add several. | | `--only-analysis ` | Replace the whole selection. Repeat for each analysis to keep. | This command enables formal verification (FV) alongside the other analyses on `main`.
```bash
zkao continuous on --branch main --budget --enable-analysis formal-verification
```
### `zkao continuous set ` [Section titled “zkao continuous set \”](#zkao-continuous-set-repoid) Change the selected analyses, monthly budget or audit areas. It takes the same options as `on`. To switch an existing schedule to FV alone at its current budget, run `zkao continuous set --branch main --only-analysis formal-verification`. If the branch has no schedule, use `on` to create one. ### `zkao continuous off ` [Section titled “zkao continuous off \”](#zkao-continuous-off-repoid) Pause automatic analysis. The schedule and its settings are kept. ### `zkao continuous prepare ` [Section titled “zkao continuous prepare \”](#zkao-continuous-prepare-repoid) Plan the branch’s next analysis without running it, as **Prepare next analysis** does in the app. Preparing spends no credits. It works whether automatic analysis is on or off. A preparation already in progress on the branch is reused. It fails with `400` when the branch has no active Continuous Security, and with `409` while the repository is still being prepared. ### `zkao continuous rm ` [Section titled “zkao continuous rm \”](#zkao-continuous-rm-repoid) Remove the schedule. Scans it already ran are kept. ## Questions [Section titled “Questions”](#questions) A Continuous Security analysis can ask the project’s members a question. ### `zkao questions list` [Section titled “zkao questions list”](#zkao-questions-list) List the open questions, oldest first. Each has an `id`, its `repositoryId` and `branch`, the question `text`, the `options` it offers, and the analysis that asked it. ### `zkao questions answer ` [Section titled “zkao questions answer \”](#zkao-questions-answer-questionid) Answer a question with one of its options, a note, or both. Needs the `guidance:write` scope. The analysis reads the answer in its next session. The answer counts as that of the member who created the token, who needs a project role of their own. A question that was already answered or dismissed fails with `409`. | Option | Meaning | | ------------------ | ------------------------------------------------------------ | | `--option