Triage findings
A finding is one issue a scan reported. Each finding carries two separate statuses.
triageStatusis zkao’s own verdict on the finding. You can override it when you disagree.resolutionStatusis 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”The list holds every finding in the project, most severe first. Filter it to one scan with its id.
zkao findings listzkao findings list --scan <scanId> --limit 100const { items, total } = await zkao.listFindings({ scanId, limit: 100 });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 for the full schema.
Read one finding
Section titled “Read one finding”The detail view adds the description, impact, recommendation, commit, repository, and comments.
zkao findings get <findingId>const finding = await zkao.getFinding(findingId);console.log(finding.description, finding.recommendation, finding.notes);curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings/<findingId>ZK- labels
Section titled “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”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.
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:
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:
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”A comment is a Markdown note on the finding. Your team sees it on zkao.
zkao findings comment <findingId> "Reproduced on the release branch."const { noteId } = await zkao.addFindingNote(findingId, "Reproduced on the release branch.");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>/notesThe response returns the new noteId. You can pin that note as the finding’s resolution note with Pin a note or the SDK’s pinFindingNote.
Override severity
Section titled “Override severity”The levels are CRITICAL, HIGH, MEDIUM, LOW and INFO. Clearing the override restores zkao’s severity.
zkao findings severity <findingId> LOWzkao findings severity <findingId> none # clear the overrideawait zkao.setFindingSeverity(findingId, "LOW");await zkao.setFindingSeverity(findingId, null); // clear the overridecurl -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>/severityOverride the triage verdict
Section titled “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.
zkao findings triage <findingId> false-positive \ --note "The caller checks the length before this point."await zkao.overrideFindingTriage(findingId, "FALSE_POSITIVE", { note: "The caller checks the length before this point.",});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>/triageThe 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”| 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.
noteis free text. It becomes a comment on the finding.reasonis 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.
zkao findings resolution <findingId> FALSE_POSITIVE \ --note "The caller checks the length before this point."
zkao findings resolution <findingId> WONT_FIX --reason risk_acceptedawait 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 -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>/resolutionOver HTTP, note can also reuse an existing comment: {"existingNoteId": "<noteId>"}.
Reason codes
Section titled “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”-
Find the latest completed scan.
Terminal window zkao scans list -
List its findings.
Terminal window zkao findings list --scan <scanId> -
Read each one in full, including the proof of concept.
Terminal window zkao findings get <findingId> -
Record the verdict, with the reason.
Terminal window zkao findings severity <findingId> MEDIUMzkao 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 instead.
