Reading Reports

A Cerberus report is designed to be useful to three audiences at once: executives who need a score, engineers who need line numbers, and security leads who need remediation guidance. This page explains each section and how to turn it into action.

Executive summary

The top of the report shows the target, scan timestamp, native Cerberus score, and native letter grade. Feeder and ALIGNMENT evidence never silently changes this score.

Check states

Every one of the 59 native checks in a report is in exactly one of four states — a report is not credible unless all four are visible, not just failures:

• pass — applicable, evaluated, no findings.
• fail — applicable, evaluated, one or more findings (or a stated repository-level reason, e.g. "No SECURITY.md found").
• not_applicable — the check's precondition wasn't met (for example, a Docker-specific check when the repo has no Dockerfile), with the reason shown.
• skipped — the check couldn't be evaluated (file budget exhausted, a fetch error), with the reason shown.

The four counts always sum to 59. If they do not, something in the native scan is broken.

Orchestration sections

• native mirrors the unchanged native score, grade, counts, and flattened findings while legacy top-level fields remain compatible.
• alignment contains a separate score, grade, counts, and findings for repository and coding-agent policy.
• feeders summarizes completed, not_applicable, unavailable, and failed tools and preserves per-tool provenance.
• policy records combined blockers and warnings. Critical evidence or at least two high findings fails the default policy; optional missing tools warn, while strict requested-tool failures block.

The combined policy is visible report data. It does not implicitly replace the native --fail-under exit gate.

Agent summary

The next section breaks the score down by agent. Each row shows:

• The agent name and domain (for example, SENTINEL · Code Analysis).
• The agent's score out of its weight (its share of the 100-point total).
• The check counts broken down by state (pass, fail, n/a, and skip).

Use this table to assign work. If SHIELD has two high findings, assign the frontend team to it. If WATCHTOWER is clean, your infrastructure/CI configuration is in good shape.

Detailed findings

Each failed check expands into one or more findings. A finding contains:

• Severity badge — color-coded CRITICAL, HIGH, MEDIUM, or LOW.
• Check name and CWE — for example, "Hardcoded credential assignment" / CWE-798.
• File and line — the exact location of the flagged code, including the file path and line number.
• Snippet — the actual matched line from the source file, and a permalink pinned to the scanned commit SHA (.../blob/{sha}/{path}#L{n}) so the link never rots.
• Risk and remediation — why it matters and a concrete fix; many checks also include a copyable suggested-fix code block.

Normalized ALIGNMENT and feeder findings add a source tool, raw rule ID, confidence when available, alignment category where applicable, stable fingerprint, and remediation. Secret values and potentially secret-bearing source snippets are omitted or redacted.

How to prioritize

Work in severity order:

1. CRITICAL — fix today. These are usually exploitable and high-impact.
2. HIGH — fix this week. They are serious but may require chaining with other issues.
3. MEDIUM — schedule in the next sprint. These reduce resilience or leak information.
4. LOW — add to the backlog. These are hygiene and best-practice improvements.

Remediation workflow

We recommend the following workflow for every report:

1. Confirm the finding. Open the file and line number and verify the snippet is real. Static analysis can occasionally flag test fixtures or intentionally unsafe demo code.
2. Apply the recommendation. Each card includes a specific fix, such as switching to parameterized queries or replacing a Dockerfile USER directive.
3. Write a regression test. Where possible, add a test that prevents the issue from returning. For example, a test that asserts no secrets are present in source.
4. Re-run Cerberus. Verify the score improved and the finding disappeared from the report.
5. Document exceptions. If a finding is a false positive or an accepted risk, document the rationale for auditors and future reviewers.

Coverage metadata

Every report includes a coverage block so you can judge how complete the scan actually was:

• filesInTree — total files in the repository's tree.
• filesEligible — files that matched a source glob and weren't excluded.
• filesScanned — files actually fetched and evaluated (bounded by the ≤2,000 files / ≤2 MB per file budget).
• filesSkipped and skipReasons — anything left out, and why. Cerberus never silently truncates without saying so.
• bytesScanned and truncated — total volume scanned, and whether the file budget was hit.

The report also carries repo metadata (description, stars, license, archived status, last-pushed date) and the exact commit sha that was scanned, so findings are reproducible and their permalinks stay valid.

Sharing and archiving

A report can be exported as normalized JSON (--json), standalone HTML (--html), SARIF (--sarif), or a separate feeder bundle (--feeder-json). Browser exports continue to cover the native web scan.

• Email it to stakeholders.
• Attach it to a fundraising data room or security questionnaire.
• Upload it to a compliance folder for audit evidence.
• Feed the JSON into other tooling, or the SARIF output into GitHub code scanning.

Web-app scans are cached in the browser's localStorage keyed by owner/repo@sha for 24 hours. CLI reports are written wherever you point the output flags. Treat every report as sensitive: paths, dependency names, and vulnerability descriptions may disclose useful security information even after credential redaction.