gadriel

Gadriel is a code-security scanner for AI-assisted development. It runs SAST, SCA, secret, config, container, and API scans over your codebase and integrates with AI coding agents (Claude Code, Cursor, Copilot) via git hooks and an MCP server.

Beta program: This release is part of the Gadriel developer beta. Sign up at https://app.gadriel.ai/developers/ to get your CLI token.

Platform support: Linux x64/arm64 (glibc), macOS (Intel & Apple Silicon), and Windows x64. The correct prebuilt binary is selected automatically at install time via npm optionalDependencies.

Prerequisites

Node.js >= 18. Do not use the apt nodejs package on Ubuntu/Debian — it ships Node 12 and is too old. Use nvm:

# On a bare VM you may need curl first: sudo apt install -y curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# Restart your shell, then:
nvm install --lts

Linux glibc >= 2.35. The prebuilt binary requires Ubuntu 22.04+, Debian 12+, RHEL 9+, or Amazon Linux 2023+. Older distros (Ubuntu 20.04, Debian 11, CentOS 7) are not supported.

Troubleshooting install failures:

• EACCES on npm install -g — you're on a system Node with a root-owned prefix. Do not use sudo. Switch to nvm (above) and reinstall.
• GLIBC_2.x not found — your OS is too old; see glibc requirement above.

Install

npm install -g gadriel
gadriel --version

The gadriel package is a thin launcher; the actual binary is delivered by a platform package (@gadriel/cli-linux-x64, -linux-arm64, -darwin-x64, -darwin-arm64, or -win32-x64), selected automatically at install time via npm optionalDependencies.

Quick start

# 1. Authenticate — paste a token from https://app.gadriel.ai/developers/tokens
gadriel auth login

# 2. Scaffold code-security in your repo
#    Creates .security/, git hooks, MCP server config, and CLAUDE.md.
#    Also syncs the OSV CVE database for the languages it detects, so
#    your first scan has CVE detection ready (only downloads the
#    ecosystems your repo uses — pass --skip-osv to defer).
gadriel code init

# 3. Scan the current repo
gadriel code scan .

# 4. Open the HTML report
open .security/reports/index.html

New in 1.1.3 — Effective Risk consistency + bullet-proofing audit:

• Effective Risk now drives every report surface — the Executive PDF's "Risk Prevented" headline + band chips and the HTML report's home severity bar are computed on confidence-adjusted Effective Risk (were raw severity), so a low-confidence critical FP no longer shows as a confirmed critical anywhere. The effective band never exceeds the raw severity (confidence only de-escalates), validated across C/Rust/Go/Python repos.
• Self-skip for Gadriel's own rule corpus — repos that vendor gadriel-code-policies no longer get false secret hits from the example patterns inside the rule definitions.
• Systematic FP prevention (10-repo audit, ADR-122) — non-production trees (sample/example/integration/extras/bench/profiling/doc/build scripts) are demoted, and three more web-framework rules are gated behind a framework import. See docs/adr/ADR-122 for the full FP-class remediation roadmap.

New in 1.1.2 — Effective Risk + cross-language false-positive prevention:

• Effective Risk — every finding now carries a confidence-adjusted risk (severity × confidence), the same idea as CVSS Report Confidence. A low-confidence "critical" no longer reads as a confirmed one: it shows as Low with an UNVERIFIED badge, while genuine high-confidence findings stay at the top. Effective Risk is the primary axis across the CLI, the HTML report, the Executive PDF, and the compliance PDFs (raw severity + confidence are shown in the detail tables). KPIs and headline counts are computed on Effective Risk; the effective band never exceeds the raw severity. Validated across C/Rust/Go/Python repos.
• Cross-language SAST false-positive prevention (ADR-120/121) — measured ~−21% SAST findings on a fresh 10-repo out-of-sample benchmark with recall preserved. Source-provenance taxonomy, format-string/macro and variadic-forwarder gates, web-framework-import gating for request-only rules, argument-shape narrowing, test/fuzz-path down-ranking, and protocol-mandated weak-crypto suppression via C/C++ caller-context.
• Offline recovery hints now point at PREFLIGHT_OFFLINE=1 (the env var that actually works) instead of a non-existent --offline flag.

🎉 1.0.0 — General Availability. The first stable release of the Gadriel code-security CLI. Highlights across the suite:

• 6 scan domains in one pass — SAST, SCA/CVE, secrets, config/IaC, container, and API — with ~2,800 built-in rules.
• 12 languages with SAST front-ends (C, C++, C#, Go, Java, Kotlin, JavaScript, TypeScript, PHP, Python, Ruby, Rust, Swift); deep cross-function + cross-file taint on Python, JS/TS, Go, Rust, C, PHP (sanitizer-aware, confidence-tiered — not regex matching).
• SCA across 11 ecosystems (npm, PyPI, Maven, Go, crates.io, RubyGems, NuGet, Composer, Hex, Pub, Hackage) with offline CVE matching.
• 9 AI-assistant integrations (Claude Code, Claude Desktop, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, JetBrains, ChatGPT, Google AI Studio) via local MCP + hooks.
• Compliance reporting mapped to EU AI Act, NIST AI RMF, SOC 2, HIPAA, PCI-DSS, OWASP LLM Top 10 — auditor PDFs + an Executive (CISO) summary.
• Scales to large monorepos — bounded, responsive scans on 100k+-node call graphs.
• 100% local & deterministic — your code never leaves the machine (ADR-090), $0 API cost, byte-identical results.

New in 0.11.7 — Executive (CISO) report, KPIs & test-coverage:

• gadriel code report now also generates a single-file Executive Security Report PDF (.security/reports/executive-summary.pdf) by default — a board-ready summary that leads with risk prevented, a page-1 KPI scorecard (open criticals, risk reduction, compliance pass rate, critical density), severity badges, a findings-over-time trend chart, a "progress since first scan" banner, and an estimated avoided-API-cost economics model. Fully offline and deterministic (no source ever leaves the machine). Pass --no-executive to skip.
• New test-coverage scan signal: per-language unit-test presence is assessed during the scan and surfaced as warning findings (a "Test Coverage" domain) — no test suite is executed.
• gadriel code doctor --platform <p> parity manifest now covers every supported platform (including claude-code).

New in 0.11.1 — SAST precision & multi-platform:

• Full multi-platform release: Linux x64/arm64, macOS Intel/Apple-Silicon, Windows x64.
• C/C++ buffer-overflow rules (CWE-120 strcpy/strcat family) now run a fail-open dataflow check: calls with a string-literal source, or a destination provably sized from the source (malloc(strlen(src)+1) then strcpy), are no longer flagged. Genuinely unbounded copies still fire.
• ADR-112 confidence tiering across SAST and secrets findings reduces false positives while preserving recall on the planted-secret corpus.
• Propagated-taint engines activated for C, C++, and PHP front-ends.

New in 0.10.6: gadriel code init now front-loads the OSV vulnerability-database sync for the ecosystems detected in your repo, so your first gadriel code scan runs with CVE detection already enabled — no slow mid-scan download. Use --skip-osv for air-gapped setups. (If you skip it, the first scan still auto-syncs on demand.)

Manual OSV sync is still available any time: gadriel code policies --osv

Getting started (full guide)

Full onboarding guide: docs/beta/getting-started.md

Code-security commands

| Command | What it does | |---|---| | gadriel auth login | Authenticate with your portal token | | gadriel auth status | Show current token name, expiry, and scopes | | gadriel code init | Scaffold .security/, git hooks, MCP server, CLAUDE.md | | gadriel code scan | Run SAST + SCA + secrets + config + container + API scans | | gadriel code policies --osv | Sync the OSV CVE vulnerability database (required once) | | gadriel code watch | Watch files and scan on save (Layer-1 fast path) | | gadriel code findings | Read findings from .security/findings.json | | gadriel code fix <id> | Confirm, dismiss, or hand a finding to an AI agent | | gadriel code sbom | Export an SBOM (SPDX 2.3 + CycloneDX 1.5) | | gadriel code report | Compliance reports + static HTML bundle + executive PDF | | gadriel code dashboard | Local web dashboard (binds 127.0.0.1) | | gadriel code mcp | Start the MCP server for Claude Code / IDE integrations | | gadriel code doctor --platform <p> | Integration parity manifest for an AI-assistant platform |

Output formats: --format table|json|html|ocsf.

Scan flags

| Flag | Default | Description | |------|---------|-------------| | --fail-on <severity> | none | Exit non-zero on findings at or above level (low, medium, high, critical) | | --format <fmt> | table | Terminal summary format | | --no-html | false | Skip HTML report (faster in CI) | | --no-osv | false | Skip CVE detection entirely | | --offline | false | No network calls at all | | --staged | false | Scan only git-staged files (pre-commit) | | --git-history | false | Deep sweep of all git commits (Layer-4) |

Claude Code integration

After gadriel code init, open Claude Code in your project directory:

claude

Slash commands available:

| Command | What it does | |---------|-------------| | /gadriel-scan | Full scan of the repo | | /gadriel-scan src/auth | Scan a specific path | | /gadriel-fix CODE-W1-L1-001 | AI-assisted fix for a finding | | /gadriel-reports | Generate compliance PDFs (EU AI Act, NIST, OWASP…) |

Exit codes

| Code | Meaning | |------|---------| | 0 | Clean — no gate tripped | | 1 | Security gate tripped (--fail-on threshold breached) | | 2 | Tooling error / crash | | 7 | Auth required — run gadriel auth login |

Documentation

• Getting started: https://app.gadriel.ai/developers/
• Full docs: https://gadriel.ai
• Issues: https://github.com/Gadriel-ai/preflight/issues

License

MIT