Quickstart

This walkthrough assumes you've already installed Gadriel and authenticated. We'll scaffold a repository, run a scan, read the results, and generate a report bundle.

1. Initialize the repo

Run init from the root of the project you want to protect:

bashCOPY
gadriel code init

This is the consolidated scaffold. It creates and wires up:

• .security/ — where scan findings, SBOMs, and reports are written.
• git hooks — the pre-commit gate that scans staged files before every commit.
• MCP server config — so your AI assistant can read findings and drive fixes (see AI Coding Integration).
• CLAUDE.md — guidance the assistant reads (part of the .claude/ scaffold).
• .gitignore — entries so scan artifacts aren't accidentally committed.

By default, init also syncs the OSV vulnerability database for the ecosystems it detects, so your first scan runs with CVE detection already on.

Useful init flags

2. Run a scan

bashCOPY
gadriel code scan .

Gadriel loads its rule corpus, auto-detects which of the 6 scan types apply, and writes results to .security/findings.json. A run looks like this:

  → loading rules from ~/.gadriel/cache/policies/... (source=vendored)
    loaded 2858 rule(s)
  → scanning .
    graph: 4 node(s) (0 dep node(s), 0 import edge(s) from lockfiles)
    SAST: workspace-aware (cross-file Python + JS/TS + Rust + Go taint enabled)
  ⚠ OSV data not available — CVE detection is DEGRADED (not GREEN).
  → Intercepted before commit: 100.0%
  ✓ SBOM emitted
      SPDX 2.3:        ./.security/sbom.spdx.json
      CycloneDX 1.5:   ./.security/sbom.cyclonedx.json

  ✓ scan complete — 1 finding(s)
    security risk (1): 0 critical, 0 high, 0 medium, 1 low, 0 info
    ⚠ 1 unverified high/critical-severity finding(s) at low confidence — review, not panic
    verdict:  PARTIAL · coverage DEGRADED (overall 8.95/10.0)
    scan types: secrets: 1
    written:  ./.security/findings.json

Reading the verdict line

verdict:  PARTIAL · coverage DEGRADED (overall 8.95/10.0)

• verdict — the overall outcome from the 8-pillar score:
  • PASS — no policy violations; safe to commit.
  • PARTIAL — some controls not fully satisfied; review before committing.
  • FAIL — a blocking violation.
• coverage — how complete the scan data was:
  • GREEN — every applicable scan type ran with full data.
  • DEGRADED — one or more scan types ran with reduced data (e.g. the OSV CVE database hasn't been synced, so CVE-dependent rules were skipped).
• overall X/10.0 — the weighted pillar score (see Scoring & Verdicts).

3. Read the findings

bashCOPY
gadriel code findings

  findings: ./.security/findings.json
    • 1 total
  by risk: (severity × confidence)
    • low: 1
    ⚠ 1 unverified (high/critical severity but low confidence — review, not panic)

┌────────────────────┬───────────────────────┬──────────┬──────┬─────────┬────────┬──────┬────────────┐
│ ID                 ┆ Risk                  ┆ Severity ┆ Tier ┆ Type    ┆ File   ┆ Line ┆ Excerpt    │
╞════════════════════╪═══════════════════════╪══════════╪══════╪═════════╪════════╪══════╪════════════╡
│ CODE-W3-SECRET-056 ┆ low (1.9) ⚠UNVERIFIED ┆ high     ┆ LOW  ┆ secrets ┆ app.py ┆ 4    ┆ [REDACTED] │
└────────────────────┴───────────────────────┴──────────┴──────┴─────────┴────────┴──────┴────────────┘

Note the Risk column combines severity × confidence — a high-severity but low-confidence match is flagged ⚠UNVERIFIED ("review, not panic") rather than blocking you. This is central to Gadriel's false-positive prevention. Secret excerpts are always [REDACTED].

For machine-readable output (the raw OCSF envelope), add --format json:

bashCOPY
gadriel code findings --format json

The findings.json file itself carries the verdict, per-pillar scores, and each finding:

jsonCOPY
{
  "schema_version": "1.1.0",
  "scan_types_run": ["sast", "secrets", "api", "container", "sca", "config"],
  "verdict": "PARTIAL",
  "overall_score": 8.95,
  "pillar_scores": {
    "security": 3.33, "compliance": 10.0, "safety": 10.0,
    "operational": 6.5, "finops": 10.0, "coherence": 10.0,
    "teamwork": 10.0, "bias": 10.0
  },
  "severity_counts": { "critical": 0, "high": 1, "medium": 0, "low": 1, "info": 0 },
  "findings": [ /* ... */ ]
}

Triage a finding

Confirm a real issue, dismiss a false positive, or hand it to your AI agent:

bashCOPY
gadriel code fix CODE-W3-SECRET-056 --false-positive

See False Positives for the full triage workflow.

4. Generate a report

Produce the browsable HTML report bundle plus the JSON payload:

bashCOPY
gadriel code report

This writes a static HTML bundle to .security/reports/index.html (and report.json) plus, by default, an executive summary PDF. For auditor-ready compliance reports, target a framework:

bashCOPY
gadriel code report --compliance soc2 --format pdf
gadriel code report --all-frameworks

Frameworks include eu-ai-act, nist-ai-rmf, soc2, hipaa, pci-dss, and owasp-llm-top10. See Reports and Compliance.

What's next

• Wire the scanner into every layer of your workflow — Execution Layers (file-save → pre-commit → PR → CI/CD).
• Let your AI assistant fix findings automatically — AI Coding Integration.
• Tune what runs and what blocks — Configuration.