ankos report

ankos report analyzes an evidence directory produced by ankos scan and emits a PCI DSS readiness report. Use it to see what the next QSA visit will surface before it surfaces, to drive a sprint of remediation work, or to ship a clean artifact to your security lead each week.

Synopsis

ankos report <evidence-dir> [flags]

Quick start

# Default: human-readable text to stdout
ankos report ./ankos-evidence-20260526-153045

# Write an HTML report to a file
ankos report ./ankos-evidence-20260526-153045 \
  --format html -o ./pci-report.html

# Just the top 10 highest-priority findings
ankos report ./ankos-evidence-20260526-153045 --top 10

# See your PCI score over time (sparkline + dated history)
ankos report ./ankos-evidence-20260526-153045 --trend

# Post a readiness summary to a GitHub Actions job summary
ankos report ./ankos-evidence-20260526-153045 --format github

# CI gate: exit non-zero if there are any "action needed" findings
ankos report ./ankos-evidence-20260526-153045 --fail-on action-needed

Flags

Output formats

Text

The default. Human-readable, ANSI-color-coded, designed for terminal review. It reads top-to-bottom as a map, not a log dump:

1. At a glance — the Ankos PCI Score, the readiness counts (ready / needs attention / review), a coverage line ("Evidence collected for N of 12 requirements"), and the top items to address first.
2. All 12 PCI requirements — each with a one-line rollup ("4 checks — 2 ready, 1 needs attention, 1 review") and its per-check findings, severity, and suggestion. Requirements 9 and 12 are largely procedural (physical access; security policies) and appear as ○ NOT COLLECTED with a note that the QSA assesses them from documentation.
3. Next steps — a short, state-aware block routing you to ankos remediate, ankos verify, and ankos export (the free local qsa-package ZIP — see verify integrity and hand off).

If any collector hit an error during the scan (for example, an AccessDenied from a too-narrow IAM role), a collection issues warning is shown up front — so an incomplete scan is never mistaken for a clean one. Sections fold together based on --severity and --top.

Findings marked ! REVIEW carry a Consider: suggestion; requirements whose collector never ran show ○ NOT COLLECTED with the exact ankos scan --collectors <name> command to gather them.

JSON

Structured output suitable for piping into other tools or storing in a data warehouse. The shape mirrors Report.Requirements[] with nested Findings[] per requirement. Pipe-friendly:

ankos report ./evidence --format json | jq '.requirements[] | select(.status == "ACTION NEEDED")'

With -o, writes the JSON to a file and prints ✓ Report written to <path> to stderr — so pipelines stay clean.

CSV

One row per finding. Columns: requirement, requirement_title, check, status, severity, detail, pci_sub_reqs, remediation, narrative, account_id, region, collected_at, pci_score.

Use this when handing the report to a non-engineering audience that lives in spreadsheets, or when joining against another system's data.

HTML

A standalone, self-contained dashboard — a single HTML file with embedded CSS and an inline SVG score gauge, no external assets or JavaScript. It renders (and prints to PDF) offline, so it's the natural artifact to email to a colleague or your QSA.

It leads with a score gauge, a readiness bar, the "N of 12 requirements" coverage strip, and — once you have a score history — the change since your last run, followed by the full per-requirement tables. A print stylesheet keeps the remediation column in exported PDFs.

ankos report ./evidence --format html -o ./pci-report.html
# ✓ Report written to ./pci-report.html

GitHub

Renders the report as a Markdown summary for a GitHub Actions run. When $GITHUB_STEP_SUMMARY is set, it writes to the job summary (score, trend delta, readiness table, top findings); otherwise it prints to stdout. It also emits ::warning:: workflow annotations so findings surface inline on the pull request.

ankos report ./evidence --format github

The wording is evidence-readiness only — "N findings need attention", never "failed". Pair it with --fail-on to break the build; the exit code drives CI while the summary stays QSA-safe. See CI/CD integration.

PCI score and coverage

The headline Ankos PCI Score is a 0–100 evidence-readiness measure weighted by finding severity and status — higher means more of the expected evidence is collected and clean. It is an evidence-readiness signal, not a compliance score; the final determination is your QSA's.

Two honesty rules keep the number meaningful:

• Un-scanned requirements don't inflate it. A requirement whose collector never ran is NOT COLLECTED and is excluded from the score entirely — an empty scan can't read as "100%".
• Coverage is stated as a fact. The report shows "Evidence collected for N of 12 requirements" so the score is always read alongside how much was actually scanned.

Score trend

Every report run appends its score to a local history file (~/.ankos/score-history.jsonl), keyed by account + region and deduped by scan time. The at-a-glance line then shows the change since your last run, and --trend renders the full history:

ankos report ./evidence --trend

  Ankos PCI Score — trend
  123456789012 · us-east-1

  ▁▃▄▆▇█

  2026-05-01    58 / 100
  2026-05-15    64 / 100   +6
  2026-06-01    78 / 100   +14

This is entirely local — no upload, no credentials — and is the cheapest way to show progress toward an assessment over time.

CI gating with --fail-on

--fail-on lets the command participate in a build pipeline as a quality gate. Exit codes:

Typical pattern: run nightly in CI, with --fail-on action-needed so the build only breaks on serious findings, and review-level items get filed as work without blocking deploys.

Diff mode

ankos report ./evidence-current --diff ./evidence-last-month

Leads with the PCI score delta (PCI Score: 64 → 78 (+14)), then surfaces what changed between two scans: which findings appeared, which were resolved, which status transitions happened. Only changes that actually got worse count as regressions — a finding moving from READY to INFO is treated as neutral, not a regression. Useful as a weekly review artifact or as drift detection between quarterly cycles.

For a richer drift workflow (with baseline tracking and CI exit codes specific to drift), use ankos drift instead.

Suppressing accepted findings

Findings your team has reviewed and accepted (with reason + approver + optional expiry) live in .ankosignore. The report respects this file by default — accepted findings are excluded from the active list and shown in a separate "Accepted" section at the end.

Manage acceptances with ankos ignore add / list / expired.

Limiting scope

--scope-file (default .ankosscope) defines which AWS resources are inside your PCI cardholder data environment (CDE). The report still analyzes everything that was scanned, but resources outside the scope appear in an "Out of scope" appendix rather than driving the headline PCI score.

Manage scope with ankos scope init / show / validate.

Exit codes