# Diff scans

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

* 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

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](https://docs.zkao.io/guides/scans/#follow-a-scan).

CLI

```bash
zkao scans launch --repo <repoId> --preset "builtin:Flash Diff" \
  --base main --commit <headSha>
zkao scans wait <scanId>
```

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":"<repoId>","presetRef":"builtin:Flash Diff","baseCommit":"main","commitHash":"<headSha>"}' \
  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

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

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

Tip

After a complex change to cryptographic code, a diff scan is a cheap second look before merging.
