# Triage findings

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

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 <scanId> --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=<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](https://docs.zkao.io/api/operations/listfindings/) for the full schema.

## Read one finding

The detail view adds the description, impact, recommendation, commit, repository, and comments.

CLI

```bash
zkao findings get <findingId>
```

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

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

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

A comment is a Markdown note on the finding. Your team sees it on zkao.

CLI

```bash
zkao findings comment <findingId> "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/<findingId>/notes
```

The response returns the new `noteId`. You can pin that note as the finding’s resolution note with [Pin a note](https://docs.zkao.io/api/operations/pinfindingnote/) or the SDK’s `pinFindingNote`.

## Override severity

The levels are `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` and `INFO`. Clearing the override restores zkao’s severity.

CLI

```bash
zkao findings severity <findingId> LOW
zkao findings severity <findingId> 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/<findingId>/severity
```

## 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 <findingId> 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/<findingId>/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

| 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 <findingId> FALSE_POSITIVE \
  --note "The caller checks the length before this point."


zkao findings resolution <findingId> 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/<findingId>/resolution
```

Over HTTP, `note` can also reuse an existing comment: `{"existingNoteId": "<noteId>"}`.

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

Tip

Prefer a note when the reasoning has any detail worth keeping. A code alone loses it.

## A triage pass

1. Find the latest completed scan.

   ```bash
   zkao scans list
   ```

2. List its findings.

   ```bash
   zkao findings list --scan <scanId>
   ```

3. Read each one in full, including the proof of concept.

   ```bash
   zkao findings get <findingId>
   ```

4. Record the verdict, with the reason.

   ```bash
   zkao findings severity <findingId> MEDIUM
   zkao findings resolution <findingId> 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](https://docs.zkao.io/guides/guidance/) instead.
