Scan coverage

A scan record used to answer one question: what failed. GET /api/v2/findings returns the vulnerable results, and everything else was absent. That is enough to open tickets and not enough to produce evidence, because the question an assessor asks first is the other one: was this control tested on this date, and did the system pass.

GET /api/v2/scans/{id} now carries a coverage block built from a per-probe attempt record, so both sides of the run are readable.

Required scope: scans:read.

Response

curl -sS https://penaxtra.com/api/v2/scans/$SCAN_ID \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "51d7c9b4-829f-4f75-af5f-77b9a9df8fda",
  "endpoint_id": "f7e8903a-96d2-4d29-9f87-663cca4aa1f3",
  "status": "completed",
  "trigger_type": "manual",
  "started_at": "2026-08-05 17:26:37+00",
  "completed_at": "2026-08-05 17:27:03+00",
  "cost_usd": "0.0000",
  "probes_run": 18,
  "probes_failed": 0,
  "regression_count": 3,
  "coverage": {
    "tested": 18,
    "passed": 8,
    "failed": 3,
    "inconclusive": 7,
    "errored": 0
  }
}

tested is the sum of the other four.

Read inconclusive as its own category

It is not a pass. A probe that ran without producing a confident verdict tells you nothing about the control, and folding it into passed would overstate coverage in exactly the way a timed-out probe counted as run overstates it. When a pipeline needs a single number, use passed / tested and report inconclusive alongside it rather than absorbing it.

A high inconclusive count usually means the judge panel is off or narrowed. Check the LLM provider configuration before reading it as a property of the target.

errored and coverage claims

probes_run counts attempts, not successes. A scan can report status: "completed" with a non-zero errored, which means it finished the list but did not observe the target for those probes. Treat any evidence claim built from a scan with errored > 0 as covering tested - errored probes, and say so in whatever you generate downstream.

Regressions

regression_count is the number of probes that were attempted in the previous comparable scan against the same endpoint, did not come back vulnerable then, and are vulnerable now. Findings carry is_regression for the same set.

This is stricter than it reads. A probe that was never run before is new, not a regression, and a probe that errored in the baseline is not evidence of a prior pass, so neither counts. Both distinctions need the per-probe record; without it, "absent from the previous scan" was ambiguous and ad-hoc scans had no usable baseline at all.

Scans that ran before the attempt record existed produce an empty baseline and flag nothing, rather than reporting every current failure as a regression.

Worked example

Fail a build when coverage drops or a regression appears:

set -euo pipefail

S=$(curl -sS "https://penaxtra.com/api/v2/scans/$SCAN_ID" \
      -H "Authorization: Bearer $TOKEN")

TESTED=$(jq -r '.coverage.tested'  <<<"$S")
ERRORED=$(jq -r '.coverage.errored' <<<"$S")
FAILED=$(jq -r '.coverage.failed'  <<<"$S")
REGRESSED=$(jq -r '.regression_count' <<<"$S")

if [ "$ERRORED" -gt 0 ]; then
  echo "coverage incomplete: $ERRORED of $TESTED probes did not reach the target" >&2
  exit 1
fi
if [ "$REGRESSED" -gt 0 ]; then
  echo "$REGRESSED probe(s) passed on the previous run and fail now" >&2
  exit 1
fi
echo "$FAILED failing of $TESTED tested"

Gate on errored before reading the verdict counts. A scan that could not reach the target produces a low failed count for the wrong reason, and a pipeline that only checks failed reads an outage as an improvement.

Related

• Scan suites API
• Findings API
• Reports API
• API authentication

Last reviewed: 2026-08-05. Reviewed by: Engineering. Content type: Developer documentation. Reach the maintainers: [email protected] .