agentic-security
Agentic-Security scanner + MCP server for Gemini CLI. Provides 17 MCP tools the Gemini agent can call directly: scan, query taint, explain f
Open source Open in the app JSON README (API)
About
Agentic-Security scanner + MCP server for Gemini CLI. Provides 17 MCP tools the Gemini agent can call directly: scan, query taint, explain finding, find rule module, look up CVE, synthesize / verify / apply fix, synthesize / apply SCA upgrade, append / read scratchpad, append / read AGENTS.md memory, query triage/findings memory, query cache telemetry.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- clear-capabilities
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.148.4
- Stars
- 113
- Forks
- 21
- Last push
- 2026-09-09T19:40:48Z
- Repository state
- ativo
- Language
- JavaScript
- License
- NOASSERTION
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-09-07 21:05:29
- Origin id
clear-capabilities/agentic-security
README
# agentic-security
[](https://github.com/Clear-Capabilities/agentic-security/actions/workflows/ci.yml)
[](./LICENSE)
[]()
[]()
<img src="https://raw.githubusercontent.com/Clear-Capabilities/agentic-security/main/docs/brand/patch-bug-scene.svg" align="right" width="220" alt="Patch the mascot side-eyeing a bug on a monitor — agentic-security's signature scene">
<h3>
Build faster with an<br>
Agentic Workforce.<br>
Find what's exploitable.<br>
Prove what's fixed.
</h3>
> Built by **[Clear Capabilities](https://www.clearcapabilities.com/)**.
**In one sentence:** agentic-security scans the code your AI agent just wrote (or your whole repo) for security bugs, explains each one in plain English with a dollar-cost estimate instead of a CVE number, and can fix it for you — every fix is re-verified before it ever touches your disk.
**Contents:** [What it does](#what-agentic-security-does) · [5-minute quickstart](#5-minute-quickstart) · [Findings vs. assurance](#findings-vs-assurance) · [See it in action](#see-it-in-action) · [Install](#install) · [Documentation](#documentation) · [Commands](#commands) · [What makes it different](#what-makes-it-different) · [Fixes are verified, not trusted](#fixes-are-verified-not-trusted) · [Stop overpaying for tokens](#stop-overpaying-for-tokens) · [Code Boundaries](#code-boundaries) · [Language coverage](#language-coverage) · [Compliance frameworks](#compliance-frameworks) · [What this is not](#what-this-is-not)
---
## What agentic-security does
Five capabilities, each answering a question a plain vulnerability scanner doesn't:
**Find It.** A 12-pillar deterministic scan — SAST, SCA (OSV + CISA KEV + function-level reachability), secrets, IaC, prompt-injection, MCP/agent-tool audit, auth/authZ — across 8 first-class languages. Where a data flow is involved, the finding carries `chain[]`, a real hop-by-hop path from where tainted data entered to where it reached the sink — not just a line number.
**Prove It.** A scan reports on itself, not just on your code. The `scanHealth` object tracks whether every analyzer actually finished — files scanned, analyzers completed vs. failed vs. timed out, feed freshness (KEV/EPSS/calibration) — and `toShipVerdict()` folds that into the one-screen answer everyone actually reads: `✅ Safe to deploy` only when there are zero actionable findings **and** the scan itself completed cleanly. Zero findings from an incomplete scan is `⚠️ Scan incomplete — cannot confirm safe to deploy`, never a false green light. See [Findings vs. assurance](#findings-vs-assurance) below.
**Fix It Safely.** Every patch — a rule's stored fix, a zero-LLM deterministic swap, or one an agent composed for a finding with no stored fix — goes through the same gate before it's written: rescan-clean, no new finding of medium severity or higher, lint-clean. A completeness tier (`FULL` / `MITIGATION` / `WORKAROUND`) tells you honestly how much of the fix actually landed, and a residual-risk guard rejects a hand-wavy "adequately handled" claim that the mechanical evidence contradicts.
**Govern It.** Automated technical-control evidence for 10 bundled compliance frameworks, an egress policy — configured via `mode: allow`/`deny`/`local-only` — that returns an `allow`/`deny` decision on every outbound model call *before* a prompt is even built, and state governance — TTL-bound retention, opt-in encryption, `export`, `legal-hold` — for everything the scanner writes to disk.
**Explain It.** No CVE jargon. Every finding explains the stakes, an estimated dollar cost (`riskDollars`, honestly labeled `scenario_default` until you configure your own organization's numbers), and the fix — in language a non-security teammate can act on.
| Capability | What Agentic Security Answers |
|---|---|
| **Find It** | Where is the code actually exploitable — not just where a pattern happened to match? |
| **Prove It** | Did the scan itself finish, or is "0 findings" secretly an incomplete analysis? |
| **Fix It Safely** | Did this patch actually work, or did it just make the detector stop firing? |
| **Govern It** | What evidence do I have for an auditor, a privacy reviewer, or a security lead — and what does the tool honestly admit it couldn't check? |
| **Explain It** | What's the real-world stakes of this finding, in language the whole team understands? |
---
## 5-minute quickstart
This repo ships a small, deliberately vulnerable [demo app](examples/demo-app/) so a first run always finds something — clone this repo (or point the scanner at your own project instead once you've tried it) and run:
```bash
npx @clear-capabilities/agentic-security-scanner ci examples/demo-app --assurance strict
```
`ci` is the CI-shaped entry point — the same command your pipeline runs — and `--assurance strict` is the flag that makes it gate on whether the scan *itself* finished cleanly, not just on what it found. (`--assurance` only exists on `ci`; there is no `scan --assurance`.) Real captured output, from a repo with stale EPSS cache data (captured with `agentic-security` on `PATH` after a global install — see [Install](#install) below; the `npx` form above produces the identical output):
```text
$ agentic-security ci examples/demo-app --assurance strict
[ci] full scan (no baseline ref detected)
[ci] 45 findings — 3 critical · 6 high · 7 medium · 17 low
[ci] ⚠ scan-health=partial — EPSS exploit-probability data is stale (20699 day(s) old)
[ci] artifacts: .agentic-security/findings.{json,sarif,junit.xml}
[ci] fail-on=critical scan-exit=3
[ci] assurance gate FAILED (mode=strict): strict mode requires a fully complete scan; scanHealth.status is 'partial'
```
That one run shows two different failure classes at once:
- **`fail-on=critical scan-exit=3`** — the severity gate. Real vulnerabilities were found at or above your threshold. Fix: triage and remediate — see [Fixing vulnerabilities](docs/guides/fixing-vulnerabilities.md).
- **`assurance gate FAILED (mode=strict)`** — the assurance gate. The analysis itself didn't finish cleanly (here, a stale EPSS cache), independent of how many findings turned up. Fix: investigate the scan, not the findings — see [Scan health troubleshooting](docs/troubleshooting/scan-health.md).
`advisory` and `standard` (the default) are mechanically identical — neither ever fails the build over scan health. Only `strict` gates. Full walkthrough with more captured output: [Assurance modes](docs/walkthroughs/assurance-modes.md). For the guided, 15-minute version of this (install → scan → read the verdict → fix a finding → export a report → run it on your own project), see the **[full quickstart](docs/guides/quickstart.md)**.
---
## Findings vs. assurance
The quickstart run above shows why "0 findings" was never actually the same claim as "safe to deploy." A scan answers two different questions — *what did we find*, and *did the analysis that looked for it actually finish* — and `toShipVerdict()` (`scanner/src/report/index.js`) is the one place both get folded into a single, three-state answer:
```js
const scanIncomplete = scan.scanHealth?.status && scan.scanHealth.status !== 'complete';
const clean = actionable.length === 0 && !scanIncomplete;
```
- **`clean` → `✅ Safe to deploy`** — zero actionable findings, and the scan itself completed. The only state that means what "0 findings" used to be assumed to mean.
- **`scanIncomplete`, zero actionable findings → `⚠️ Scan incomplete — cannot confirm safe to deploy`** — nothing actionable turned up, but the analysis didn't finish cleanly (the same EPSS-staleness condition from the quickstart above, on a run that happened to have zero findings instead of 45). "Nothing found" can't be read as "nothing's there."
- **otherwise → `❌ Not safe to deploy`** — actionable findings exist, regardless of scan health.
A scan that finds nothing is no longer automatically "safe" — it's only safe if it also finished cleanly. That's what `scanHealth` exists to make visible, and it's structurally protected: one analyzer throwing an exception is isolated (`runDetector()` in `pipeline/detector-runner.js`) so it can't silently drop every *other* analyzer's findings for that file — a real gap the project found and fixed during its own assurance-hardening work (two detectors, `scanWeb3Advanced` and `scanK8sAdmission`, were bypassing the isolating wrapper).
Full walkthrough with the real `scanHealth` JSON shape, field by field, and the fault-isolation story in detail: **[Scan health](docs/walkthroughs/scan-health.md)**.
---
## See it in action
<img src="https://raw.githubusercontent.com/Clear-Capabilities/agentic-security/main/docs/brand/patch-alert.svg" align="right" width="120" alt="Patch · ALERT — finding detected">
```text
─────────────────────────────────────────────────────────────────
❌ Not safe to deploy · api-billing
─────────────────────────────────────────────────────────────────
3 critical · 8 high · 22 medium · 41 advisory
🔥 2 actively exploited in the wild (CISA KEV)
✓ 1 CONFIRMED (PoC built by /triage --validate)
[critical] SQL Injection api/users.ts:42
Could leak PII for ~5,000 users.
Estimated cost if exploited: $125k–$1.3M
Fix: use parameterized query — db.query('SELECT * FROM users WHERE id = ?', [id])
[critical] Hardcoded Stripe live key src/lib/billing.ts:7
Could enable fraudulent charges against your account.
Estimated cost if exploited: $50k–$500k (chargebacks + Stripe fees)
Fix: rotate via /agentic-security:fix --rotate-secret --auto, then move to env var
[critical] Missing webhook signature api/stripe-webhook.ts:12
Anyone can POST a fake "payment.succeeded" and unlock paid features.
Estimated cost if exploited: cost of a free subscription × every attacker
Fix: stripe.webhooks.constructEvent(rawBody, signature, endpointSecret)
How many do you want to fix?
1. Critical only (3 fixes)
2. Critical + High (11 fixes)
3. Critical + High + Medium (33 fixes)
─────────────────────────────────────────────────────────────────
```
No CVE jargon. The stakes, the cost, the fix. Every dollar estimate above is honestly scoped — see [Risk in dollars](docs/guides/risk-dollars.md) for the disclosure mechanism behind it, and [Reading a finding's evidence](docs/walkthroughs/finding-evidence.md) for what backs a real finding field by field.
---
## Install
**Requirements:** Node.js ≥ 24 (the scanner and hooks run on it either way — Claude Code doesn't provide its own).
In **Claude Code** (recommended) — two steps:
```text
/plugin marketplace add https://github.com/Clear-Capabilities/agentic-security
/plugin install agentic-security@clearcapabilities
```
The first command registers the marketplace as a source; the second actually installs the plugin. Then restart Claude Code (or `/reload-plugins`). To update later: `/plugin marketplace update clearcapabilities` followed by `/plugin install agentic-security@clearcapabilities`.
In your **terminal** (no Claude Code required) — every command in this README and the docs also works prefixed with `npx @clear-capabilities/agentic-security-scanner` instead of the bare `agentic-security`; the two are interchangeable, they just differ in whether npm re-resolves the package on every invocation:
```bash
npx @clear-capabilities/agentic-security-scanner secure .
```
Or install once and use the shorter form (`agentic-security`, or its alias `as`) everywhere:
```bash
npm install -g @clear-capabilities/agentic-security-scanner
agentic-security secure .
```
**Want a shareable report?** Any scan can export a self-contained, browser-viewable HTML page (severity charts, STRIDE breakdown, filterable findings) — or JSON / Markdown / SARIF / OSCAL:
```bash
npx @clear-capabilities/agentic-security-scanner scan . --format html --output report.html
# open report.html (formats: html · json · md · sarif · oscal · csv)
```
`--format oscal` emits a NIST [OSCAL](https://pages.nist.gov/OSCAL-Reference/models/) 1.1.2 `assessment-results` document, and `compliance --report <framework> --format oscal` emits a control-level one. Read [docs/OSCAL.md](docs/OSCAL.md) before consuming either: an OSCAL finding is a binary satisfied/not-satisfied claim about a control, so a control this engine could not decide carries **no finding at all** rather than a fabricated verdict.
Also works with Codex, Cursor, and Gemini CLI — [harness setup](docs/HARNESS_COMPATIBILITY.md).
---
## Documentation
New here? Start with the **[15-minute quickstart](docs/guides/quickstart.md)**, or browse the **[full doc index](docs/README.md)**. Otherwise, find your lane:
**Developer** — write code, get findings fixed
- [Quickstart](docs/guides/quickstart.md) — install, scan, fix, verify, export
- [Scanning](docs/guides/scanning.md) — modes, output formats, exit codes, reading findings, suppression
- [Fixing vulnerabilities](docs/guides/fixing-vulnerabilities.md) — the triage → fix → verify loop
- [Reading a finding's evidence](docs/walkthroughs/finding-evidence.md) — every real field, explained one at a time
- [SBOM & AI-BOM](docs/guides/sbom-and-ai-bom.md) — inventory dependencies and AI components
- [Responding to a leaked secret](docs/guides/leaked-secrets.md) — the rotation playbook
- [Finding provenance](docs/guides/finding-provenance.md) — which commit introduced a finding
**AppSec** — set the gate, read the evidence
- [Scan health](docs/walkthroughs/scan-health.md) — what `scanHealth` measures, and why one failing analyzer can't hide another's findings
- [Assurance modes](docs/walkthroughs/assurance-modes.md) — `advisory` / `standard` / `strict`, real captured output
- [Architecture: the finding lifecycle](docs/architecture/finding-lifecycle.md) — the real module pipeline, detector to report
**Privacy** — trace where sensitive data actually goes
- [Code Boundaries](docs/guides/data-flow-explorer.md) — the field-level graph, browsable locally in your own terminal
- [Watch one field's journey](docs/walkthroughs/privacy-data-flow.md) — the same fixture, hop by hop
- [Model egress policy](docs/walkthroughs/model-egress.md) — what leaves your machine, and what's redacted first
**Compliance** — evidence for a framework, honestly scoped
- [Compliance](docs/guides/compliance.md) — the honesty model, and why the satisfied rate is never reported over all of a framework's controls
- [Coverage maps](docs/compliance/) — per-control coverage for 5 of the 10 bundled frameworks, where one exists
- [Risk in dollars](docs/guides/risk-dollars.md) — the scenario-disclosure mechanism behind every `riskDollars` estimate
**Platform Engineering** — wire it into CI/CD, manage what it writes to disk
- [CI setup](docs/guides/ci-setup.md) — gate every pull request; severity gate vs. assurance gate
- [Configuration & env vars](docs/reference/configuration.md) — every toggle and `.agentic-security/` file
- [State & retention](docs/governance/state-and-retention.md) — TTLs, encryption, `export`, `legal-hold`
**Reference**
- [CLI](docs/reference/cli.md) · [Output schema](docs/reference/output-schema.md) · [Glossary](docs/reference/glossary.md)
- [Examples gallery](docs/examples/README.md) — thirteen real findings, one screen each
- [Concepts](docs/concepts.md) — evidence before severity; deterministic vs. model-assisted
- [Troubleshooting: scan health](docs/troubleshooting/scan-health.md) — why a scan reported `partial`, and how to fix it
- [Architecture](docs/ARCHITECTURE.md) · [Metrics](docs/METRICS.md) · [Scorecard](docs/SCORECARD.md) · [Agent threat model](docs/AGENT_THREAT_MODEL.md)
---
## Commands
Not sure where to start? Just run **`/agentic-security:secure`** (also: `--tour`, `--help`, `--daily`) — it looks at your project and tells you what to run next. Everything else is grouped below by what you're trying to do:
**Find and fix problems**
- **`find-and-fix-everything`** — One-shot scan + fix every severity in one command. The "just make it safe" path for **vibecoders** (people building with an AI agent doing most of the typing).
- **`scan`** — Run the scanner. Modes: full / diff / watch / baseline / archaeology / scanner-meta. `--watch` re-scans incrementally on every file change and prints a live risk-delta.
- **`triage`** — Decide on findings. Modes: id / show / explain / validate / tournament / red-team / exploit / query / deep (red/blue/auditor deep-dive on one finding).
- **`fix`** — Remediation. Modes: id / all / pr / sca / compliance / rotate-secret / vault / harden / trim / generate. Every patch — deterministic or agent-composed — is re-verified (rescan-clean + no new ≥medium + lint) before it's written; `--all` runs independent findings in parallel and never halts on the first failure.
**Reporting and audits**
- **`posture`** — Posture + reporting. Modes: status / report-card / harness / trend / threat / playbook / mgmt / cache.
- **`compliance`** — Compliance + auditor flows. Modes: report / walkthrough / attestation / audit / pr / privacy. Also a real CLI subcommand: `agentic-security compliance [--gap|--list|--walkthrough <id>] [--format cli|json|md] [--fail-on gap]`.
- **`supply`** — Supply chain. Modes: check / sbom / cve-alerts / license.
**Set up guardrails**
- **`setup`** — Workflow installers + guards. Modes: hooks / ci / predeploy / bodyguard / destructive-guard / model-optimizer. `--ci` generates a multi-provider CI gate; `--predeploy` blocks vercel/fly/wrangler deploys on critical findings.
**Experimental**
- **`labs`** — Experimental + AI-driven. Modes: claude-audit / model-rescan / synthesize-rule / cross-repo / risk-dollars / time-to-fix / llm.
- **`hunt`** *(CLI-only — no slash command)* — LLM discovery over the call-graph partition, gated by the deterministic engine (see [What makes it different](#what-makes-it-different)). Run it as `agentic-security hunt --root <dir>`; `--lens a,b` narrows the angles. Needs `AGENTIC_SECURITY_LLM_ENDPOINT`, is token-expensive, capped at 2000 files, and is advisory — it never gates a build and never writes to `last-scan.json`.
Every slash command is invoked as `/agentic-security:<name>` (e.g. `/agentic-security:scan`); `hunt` is the one CLI-only exception. Every legacy single-purpose alias still works and is redirected to its new mode automatically. There is no per-subcommand `--help` — only bare `agentic-security help` prints usage; passing `--help` after any subcommand is silently ignored as an unset flag and the command runs for real instead.
---
## What makes it different
- **Plain-English findings with dollar-cost estimates.** Best/likely/worst-case exposure, grounded in IBM Cost of a Data Breach 2024 and 25+ public settlement records, honestly labeled `scenario_default` until you configure your own organization's inputs — see [Risk in dollars](docs/guides/risk-dollars.md). Not CVE numbers.
- **Intercepts insecure AI-generated code before it hits disk.** The `/setup --bodyguard` hook blocks SQLi via concat, hardcoded API keys, `eval` on user input, and more — in real time, as your AI writes.
- **12-pillar scan in one command.** SAST, SCA, secrets, IaC, LLM safety, MCP agent-tool audit, auth/authZ, pipeline integrity, container **build files**, deploy config, supply chain, and trend tracking.
<br>_Container scope: Dockerfiles and compose files are analysed as source. **Built images are NOT scanned** — no base-image CVE lookup, no layer secret extraction, no digest-pinning verification of a pulled image. If you need image scanning, run a dedicated image scanner alongside this one._
- **Function-level reachability across every dependency.** OSV ecosystem_specific parsing, GHSA fix-commit analysis, vendored code fingerprinting, Java IR call-graph matching, and LLM-assisted function extraction — not just a hardcoded hints list.
- **SCA reachability tiers.** Every dependency classified as `function-reachable`, `import-reachable`, `build-only`, `manifest-only`, or `transitive-only` — so you fix what matters.
- **CISA KEV + EPSS prioritization.** Separates "this could theoretically be bad" from "people are running scripts that exploit this today."
- **SARIF codeFlows for taint traces.** Multi-step source-to-sink paths (the same `chain[]` evidence covered in [Reading a finding's evidence](docs/walkthroughs/finding-evidence.md)) rendered natively in GitHub Code Scanning, DefectDojo, and VS Code SARIF Viewer.
- **One-command fix, always verified.** Every patch is previewed, backed up, and revertible — see [Fixes are verified, not trusted](#fixes-are-verified-not-trusted) below.
- **Auto-baseline for legacy codebases.** `--set-baseline` snapshots existing findings; `--since-baseline` shows only what's new. Day-one usable on any project.
- **Refutes its own findings.** A default falsification pass (`posture/falsification.js`) takes each candidate and tries to *disprove* it — looking for the control that would actually block it (a context-matched sanitizer, a dominating guard) and demoting confidence on the ones it can. Recall-preserving: nothing is silently dropped, and `severity` is never touched by this pass. See [Concepts: evidence before severity](docs/concepts.md#evidence-before-severity).
- **Coverage you can audit.** Enumerates every attacker-reachable entry point — HTTP handlers, queue consumers, cron jobs, CLI args, uploads — and reports the disposition of each, so you can see it looked at your whole attack surface, not just where a finding happened to fire. A confirmed finding then triggers a repo-wide sweep for sibling instances the detectors missed, with honest "N found / M candidate / K mitigated" accounting.
- **An LLM discovery layer the deterministic engine keeps honest.** `hunt` partitions your call graph into disjoint focus areas and sends each through seven independent lenses — injection, authorization, crypto, business logic, feature abuse, chained, wildcard — to propose the flaws no rule can encode. Nothing it proposes is taken on faith: every candidate is routed back through the taint engine for corroboration, then faces a three-angle panel prompted to *refute* it, and only a majority refutation drops it. Severity comes from the evidence tier, never from the model, so this layer cannot emit `critical`. If the endpoint is missing or the panel goes silent, the report says so in plain words rather than reporting a clean run it did not earn. See [Deterministic vs. model-assisted](docs/concepts.md#deterministic-vs-model-assisted).
- **Hardens itself against the code it scans.** A tested threat model treats attacker-authored finding text as untrusted input everywhere it reaches an LLM prompt or a rendered PR/issue report — so the tool can't be turned against you by the repo it's auditing. See [Agent threat model](docs/AGENT_THREAT_MODEL.md).
Deep engine details — [architecture](docs/ARCHITECTURE.md) · [finding lifecycle](docs/architecture/finding-lifecycle.md).
---
## Fixes are verified, not trusted
Every patch — whether it's a rule's stored fix, a zero-LLM deterministic swap, or one an agent composed for a finding with no stored fix — goes through the same gate before it touches disk: **rescan-clean, no new ≥medium finding, lint-clean.** If a patch doesn't pass, it isn't written. This is what makes `/find-and-fix-everything` real instead of a to-do list:
- **Deterministic zero-LLM patches** for safe, context-independent classes (weak hash → SHA-256, TLS verification re-enabled) — no model call, no guessing.
- **A verified path for everything else.** A finding with only a template or a plain-English remediation note — the common case — is now fixable: the agent composes the patch, the deterministic verifier proves it safe, then it's applied.
- **Regression tests ship with the fix.** When the scan built a PoC for a finding, the generated test comes along — it fails before the patch and passes after.
- **Parallel, and it doesn't stop at the first flake.** Independent findings fix concurrently; a single failing test doesn't halt the batch — every finding gets a fixed/skipped/refused verdict, and the loop reports its own **acceptance rate**.
- **You can see your security debt aging.** Every scan stamps each finding's age and flags anything past its remediation SLA (critical: 7 days, high: 30, …).
- **Every fix carries an honest completeness tier.** `FULL` / `MITIGATION` / `WORKAROUND`, computed from mechanical signals (did the sink change? are all callers routed through the fix? does a test flip from fail to pass?) — and a residual-risk guard rejects hand-wavy "adequately handled" claims, so a partial fix can never masquerade as a complete one.
Real captured verification legs, real rejection messages, and the three separate verify-loop vocabularies this project uses (never blended into one): **[Verified remediation](docs/walkthroughs/verified-remediation.md)**.
---
## Stop overpaying for tokens
Your agentic workforce runs on tokens. agentic-security watches each prompt and tells you when a cheaper model or lower reasoning depth would answer it just as well — and it's the only tool that does this **cache-aware**, accounting for the prompt cache a model switch would throw away.
```text
💡 This simple one-off sits on a deep warm cache (~250k tokens). Switching your
main model would discard it — instead run this as a Haiku 4.5 subagent: it
answers in its own context (~84% cheaper) and leaves your Opus 4.8 cache intact.
```
- **Per-prompt model + depth advice, cache-aware.** Suggests the cheapest model + effort that still does the job — you tap `/model` + `/effort`. Prefers a cache-preserving effort drop over a plain model switch, and shows a switch's break-even point ("worth it past ~N more turns"). Zero added tokens; the analysis is purely local.
- **Cache bodyguard.** Warns *before* an edit to `CLAUDE.md` or `.claude/settings` silently invalidates your cache and forces a costly cold re-read.
- **Measured, not guessed.** `/posture --cache` reports what prompt caching actually **saved** and **wasted** this session, in real dollars — plus a running predicted-vs-realized check on the optimizer's own advice.
- **Beyond this session — lints your own AI app's LLM calls too.** Scanning a project that calls Anthropic, OpenAI, Gemini, or xAI? It flags prompt-cache killers and over-provisioned calls, with a fix in that provider's own framework — e.g. an OpenAI app gets "gpt-5.4 at `reasoning_effort: low`."
- **Opt-in: an actual choice, not just a tip.** Set `interactive: true` and a qualifying prompt gets you a real `AskUserQuestion` menu — keep your defaults, get the `/model` command to run yourself, or have Claude apply the cheaper model to its own delegated sub-agent work for the rest of the session. Costs a little real context on the prompts where it fires, unlike everything else in this section.
On by default (advisory only — a hook can't switch your model for you); disable per-project via `/setup --model-optimizer` or the kill switch. Full detail, including the live cost HUD, session budget, and interactive mode — [cache economics](docs/MODEL_COST_OPTIMIZATION.md).
---
## Code Boundaries
A finding tells you one line is dangerous. The **Data Flow Explorer** tells
you where a piece of data — a credit card number, a patient record, a
password — comes from, everywhere it flows to, and what protects it at
every hop, across your whole architecture. Same field, same sink, two code
paths, two honestly different verdicts — never one call flagged "dangerous"
in the abstract:
```mermaid
flowchart LR
Web(["🌐 Web App<br/>checkout form"]) -->|card_number| Pay["⚙️ Payments Service"]
Pay -->|"✅ maskCard() → masked"| Logs["📄 Application Logs"]
Pay -->|"❌ logged raw, no transform"| Logs
linkStyle 1 stroke:#1e8449,stroke-width:3px
linkStyle 2 stroke:#c0392b,stroke-width:3px
```
```bash
AGENTIC_SECURITY_LINEAGE_DEEP=1 npx @clear-capabilities/agentic-security-scanner scan .
npx @clear-capabilities/agentic-security-scanner explore .
```
```text
agentic-security explore: serving /Users/you/your-project
URL: http://127.0.0.1:53214/#token=3f9a1c...(64 hex chars)
Open this URL in a browser — the page authenticates itself automatically.
```
That starts a local, **read-only, loopback-only** web server over your
already-scanned graph — nothing leaves your machine — with four linked
views: the architecture graph itself (colored by protection status),
a privacy lifecycle view (where PII/PHI/PCI/financial data goes), a
trace/evidence view (click any flow for the exact hops and evidence),
and an inventory of every source and sink, including ones nothing
currently reaches. (`explore` itself makes no model calls at all — it just
loads the already-scanned, already-signed graph and serves it locally. The
*scan* step that builds that graph is the one covered by the same egress
policy documented in [Model egress](docs/walkthroughs/model-egress.md).)
Everything the browser shows also exports — `png`/`svg` for a doc, a
self-contained `html` report, a DPIA or RoPA for compliance, an executive
risk briefing, or raw `json`/`csv`. Compare two scans to catch newly
introduced disclosures (`dataflow diff`), simulate a hypothetical fix
before making it (`dataflow scenario apply` — every simulated verdict is
honestly labeled `HYPOTHETICAL`, never mistaken for a real one), assess
blast radius from a compromised node, or link data flow across two
separately-scanned repositories (`federate declare`).
Full walkthrough — [Code Boundaries guide](docs/guides/data-flow-explorer.md). Narrative, hop-by-hop companion using this exact `card_number` example — [Watch one field's journey](docs/walkthroughs/privacy-data-flow.md).
---
## Language coverage
Eight first-class languages, with cross-language detectors for the OWASP-relevant injection and crypto-misuse classes.
| Language | Vuln-class coverage |
|----------|---------------------|
| JavaScript / TypeScript | full (flow engine + structural) |
| Python | full (flow engine + structural) |
| Java | full |
| Kotlin | full |
| Go | full |
| Ruby | full |
| PHP | full |
| C# | full |
Detected across these languages: SQL injection, command injection, path traversal, LDAP injection, XPath injection, reflected XSS, SSRF, XXE, code injection (eval / SpEL / Groovy / Roslyn / template), insecure deserialization, hardcoded secrets, weak password hashing, weak ciphers (DES/RC4/Blowfish/ECB), static/zero IV, insecure randomness, CSRF, open redirect, HTTP response splitting, unrestricted file upload, missing authentication on state-changing routes, broken object/function-level authorization (BOLA/BFLA), and ReDoS — plus the JS/Python-specific classes (prototype pollution, mass assignment) and the LLM/agent-tool surface.
The detectors are precision-first: parameterized queries, escaped output, allow-list guards, CSPRNG-derived IVs, framework CSRF middleware, and token-auth schemes are recognized and **not** flagged.
---
## Compliance frameworks
`/compliance --report <framework>` generates automated technical-control evidence, mapped against:
| Framework | `<framework>` id | Coverage map |
|---|---|---|
| NIST AI 600-1 (2024) — Generative AI Profile | `nist-ai-600-1` | [coverage](docs/compliance/nist-ai-600-1-coverage.md) |
| NIST SP 800-171 Rev. 3 — Protecting CUI¹ | `nist-800-171-r3` | [coverage](docs/compliance/nist-800-171-r3-coverage.md) · [demo](docs/brand/nist-800-171-demo.gif) |
| NIST Cybersecurity Framework 2.0 | `nist-csf-2` | — |
| NIST Privacy Framework 1.1 | `nist-privacy-1-1` | [coverage](docs/compliance/nist-privacy-1-1-coverage.md) |
| OWASP ASVS 5.0 | `owasp-asvs-5` | [coverage](docs/compliance/owasp-asvs-coverage.md) |
| OWASP Top 10 for LLM Applications 2025 | `owasp-llm-top-10` | [coverage](docs/compliance/owasp-llm-top10-coverage.md) |
| EU AI Act | `eu-ai-act` | [`scripts/eu-ai-act/`](scripts/eu-ai-act/) |
| GDPR · HIPAA Security Rule · CCPA | `gdpr` · `hipaa-security-rule` · `ccpa` | — |
¹ 800-171 is the control basis for CMMC Level 2 and DFARS 252.204-7012 contracts, but this
tool does **not** perform a CMMC assessment, compute an SPRS score, or issue a certification —
CMMC certification requires a C3PAO-conducted assessment. See [coverage: what this is
not](docs/compliance/nist-800-171-r3-coverage.md#what-this-is-not) before citing this report's
output in any self-attestation.
Real `compliance --list` returns all 10 of these; 5 have a dedicated per-control coverage map today, tracked as a known gap rather than papered over — see [Compliance](docs/guides/compliance.md).
`/compliance --walkthrough <framework>` adds step-by-step auditor narratives with per-control evidence mapping — or bring your own controls at `.agentic-security/compliance/<id>/controls.json`.
This is one of **three separate compliance-state vocabularies** this codebase uses — the framework-report flow above, the Data Flow Explorer's obligation overlay, and the custom compliance-policy gate are three distinct, differently-named systems that are never unified into one. See [Compliance](docs/guides/compliance.md#three-separate-compliance-state-vocabularies--not-one-unified-model) and the [glossary](docs/reference/glossary.md#the-three-compliance-vocabularies) for all three, named distinctly.
### NIST Privacy Framework 1.1 — and what it refuses to claim
`agentic-security compliance` (also `/compliance --privacy`) assesses all 104
PF 1.1 controls and writes `.agentic-security/privacy-framework.{json,md}`. It
reads the last scan rather than re-scanning, exits **2** if there is no scan to
assess, and exits **1** only when you ask for it with `--fail-on gap`. Each gap carries an actionable
remediation and is emitted as an ordinary finding (`family: privacy-compliance`,
`CWE-359`), so `/fix` handles it like anything else. Findings are opt-in via
`AGENTIC_SECURITY_PRIVACY_FRAMEWORK=1` — a compliance opinion shouldn't silently
become your build failure.
The part worth reading: NIST rates each control for code-testability, and on
these 104 it is **23 yes, 33 partial, 48 no**. So every control lands in one of
four buckets and the bucket is always shown — **gap** (mapped signal failing),
**not assessed** (code-testable, but this engine has no signal for it),
**manual** (governance/policy, outside any scanner's reach), **satisfied**.
Controls in *not assessed* and *manual* are never counted as satisfied, and the
satisfied rate is reported over the controls actually assessed, never over all
104. A scan that examined no files reports everything as *not assessed* rather
than passing. A privacy report that quietly marks 48 governance controls "passed"
because no rule fired against them is manufacturing assurance someone will hand
to an auditor — this one tells you exactly how much of the framework it did not
check.
---
## What this is not
- **Not a SaaS dashboard.** It's a CLI + Claude Code plugin.
- **Not a replacement for a pentester.** Static analysis catches patterns; humans catch business-logic flaws. The `security-logic-reviewer` subagent and `/triage --validate` close part of the gap, not all of it.
- **Not magic.** It can miss novel vulnerabilities, especially anything that requires understanding intent.
- **Not free for resale.** PolyForm Internal Use license. Use it to make your own code safe and secure. Don't repackage it as a competing scanner.
- **Not an auditor-issued certification.** Compliance output is automated technical-control evidence mapped to a framework's controls — never "compliant," "certified," or "audit-passed." See [Compliance: the honesty model](docs/guides/compliance.md#the-honesty-model--why-this-wont-inflate-your-score).
- **Not proof of absence.** A clean scan (`scanHealth.status: 'complete'`, zero actionable findings) means nothing exploitable was found by what did run — not that nothing is wrong. Every evidence field on a finding exists to say how much to trust it, never to promise there isn't another one the scan missed. See [Concepts: evidence before severity](docs/concepts.md#evidence-before-severity).
- **Not a bare "verified" claim.** A fix report always carries a named completeness tier — `FULL`, `MITIGATION`, or `WORKAROUND` — never an unqualified "verified." See [Verified remediation](docs/walkthroughs/verified-remediation.md).
---
## License & security
Full legal terms in [LICENSE](./LICENSE). Found a security issue in the tool itself? See [SECURITY.md](./SECURITY.md) for how to report it privately.
---
> Built with care by **[Clear Capabilities](https://www.clearcapabilities.com/)**. Found a bug, have a feature idea, want to talk? Please create a GitHub issue.