Skip to content

Triage findings

View .md

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

The list holds every finding in the project, most severe first. Filter it to one scan with its id.

Terminal window
zkao findings list
zkao findings list --scan <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.

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

Terminal window
zkao findings get <findingId>

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.

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:

Terminal window
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.

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

Terminal window
zkao findings comment <findingId> "Reproduced on the release branch."

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

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

Terminal window
zkao findings severity <findingId> LOW
zkao findings severity <findingId> none # clear the override

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.

Terminal window
zkao findings triage <findingId> false-positive \
--note "The caller checks the length before this point."

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.

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.

Terminal window
zkao findings resolution <findingId> FALSE_POSITIVE \
--note "The caller checks the length before this point."
zkao findings resolution <findingId> WONT_FIX --reason risk_accepted

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

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
  1. Find the latest completed scan.

    Terminal window
    zkao scans list
  2. List its findings.

    Terminal window
    zkao findings list --scan <scanId>
  3. Read each one in full, including the proof of concept.

    Terminal window
    zkao findings get <findingId>
  4. Record the verdict, with the reason.

    Terminal window
    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 instead.