Reports & Outputs

Every Gadriel Code scan writes its results into a .security/ directory at the root of the scanned repository. That directory is the single place to look for everything the tool produces: the canonical machine-readable findings, the human-facing HTML report bundle, per-framework compliance reports, the SBOM, and the operational data store that powers trends and drift.

This page describes each artifact, the schema of the canonical findings.json, the HTML report bundle, and how to read findings from the command line.

Related pages: Compliance reporting · SBOM · Troubleshooting.

The .security/ directory

A scanned repository accumulates the following layout. Not every file is present on every run — SBOM, compliance, and report bundles are only written by the commands that produce them.

.security/
├── findings.json              # Canonical findings (OCSF-style envelope) — see below
├── pillar-scores.json         # Per-pillar scores
├── metrics.json               # Scan metrics
├── metrics/                   # scan-activity.json, learning.json, gadriel-progress.json
├── sbom.spdx.json             # SPDX 2.3 SBOM        (gadriel code sbom)
├── sbom.cyclonedx.json        # CycloneDX 1.5 SBOM   (gadriel code sbom)
├── audit-log.jsonl            # Append-only reasoning/audit log (NDJSON)
├── reports/                   # HTML report bundle   (gadriel code report)
│   ├── index.html
│   ├── findings.html
│   ├── compliance.html
│   ├── drift.html
│   ├── trends.html
│   ├── audit.html
│   ├── executive-summary.pdf
│   └── report.json
├── compliance/                # Per-framework reports (gadriel code report --compliance …)
│   ├── <slug>.md / <slug>.typ / <slug>.pdf
│   └── …
├── store/                     # RVF operational data store — see below
│   └── *.rvf
└── history/                   # Time-series snapshots
    └── YYYY-MM-DD/
        ├── findings.json
        ├── pillar-scores.json
        └── metrics.json

The location of .security/ can be relocated with the security_dir configuration key. A --ephemeral scan writes to a throwaway temp directory instead of the repo.

The canonical findings.json

findings.json is the source of truth for a scan. It is an OCSF-style envelope (OcsfReport) that wraps an array of typed findings together with scan-level metadata, scores, and coverage information. Every other artifact — the HTML bundle, the compliance reports, gadriel code findings — is derived from it, and downstream consumers should read this file rather than scraping HTML.

Envelope fields

Finding fields

Each entry in findings[] is a typed Finding. The most commonly used fields:

Finding id format

Code-layer finding ids follow the grammar:

CODE-W<pillar>-<scan_type_code>-<NNN>

• W1–W8 map to the eight pillars (W1 Security, W2 Compliance, W3 Safety, W4 Operational, W5 FinOps, W6 Coherence, W7 Teamwork, W8 Bias).
• <scan_type_code> is one of L1–L9 (SAST, numbered by OWASP Web Top 10 position), AI, ATLAS, GRAPH, PRED, SCA, SECRET, CONFIG, CONTAINER, API.
• NNN is a three-digit zero-padded sequence, scoped to the pillar × scan-type pair.

Example: CODE-W1-L3-007 is the 7th Security/SAST-injection rule. Runtime (Preflight) findings use separate grammars (MATH-F*-NNN, ATLAS-NNN, GOV-NNN) and are distinguished by the CODE- prefix or the layer field.

Secret redaction

Secret findings never write the secret value into findings.json. The value is replaced with [REDACTED], preserving a short recognizable prefix (up to 12 characters, e.g. sk-ant-api03-, AKIA, ghp_). The full value lives only in the encrypted .security/secrets-vault.enc.

Reading findings from the CLI

bashCOPY
gadriel code findings                # human-readable table (default)
gadriel code findings --format json  # machine-readable JSON

gadriel code findings reads .security/findings.json from the current working directory (it errors if the file is absent).

• --format table (default) prints the total count, a "by risk" breakdown along the severity × confidence axis, a count of unverified findings (high/critical severity but low confidence), and then the findings table.
• --format json validates the file as an OcsfReport and prints it, additively enriching each finding with flat convenience fields (file, line, message, and a location {file, line} object) derived from the context. It never overwrites existing keys, and the on-disk file stays canonical OCSF.

The only accepted format values are table and json.

The HTML report bundle

bashCOPY
gadriel code report

The report command renders a self-contained, offline HTML bundle into .security/reports/. Point a browser at it, zip it, or attach it to a compliance package — it works with no network access.

Self-contained and offline by design

The bundle makes no CDN or network requests. Fonts use the system font stack; CSS is inlined in <style>; data is embedded in <script type="application/json">; and charts use a Chart.js bundle vendored into the crate (pinned by SHA-256 checksum), never fetched at runtime. This is enforced by tests that fail the build if a network client crate is linked in or if an external URL appears outside an inline data script.

Report flags

Executive summary PDF

Every gadriel code report run generates executive-summary.pdf by default, rendered in-process from an embedded Typst template (no external binary required). Failure to render it is non-fatal — the rest of the bundle still writes. Opt out with --no-executive.

The report command also drives per-framework compliance output; see Compliance reporting.

The RVF operational data store

.security/store/*.rvf holds Gadriel's operational data — the longitudinal state that powers trends, drift, compliance history, and audit search across scans. These are binary RVF files (not meant to be hand-edited), keyed by a per-run ULID.

Inspect the store from the CLI:

bashCOPY
gadriel code store list      # every .rvf: kind, size, mtime  (alias: status)
gadriel code store verify    # integrity: signatures, witness chain, truncation

store verify reports one of: ok, missing_sidecar, rvf_truncated, witness_chain_broken, signature_invalid, or not_checked per file. Both subcommands accept --format table|json.

Quick reference