sec — an agentic security-review plugin for Claude Code

Point it at any codebase or running app and get a prioritized, evidence-backed security review with verified fixes — combining battle-tested open-source scanners with parallel LLM "hunter" agents and a per-finding verifier that exists to kill false positives. Reusable across projects; installs once, scans anything.

Honest framing up front. This is a serious, well-architected tool that finds real vulnerabilities — and it has measured limitations. I ran it against a real 171k-LOC production app, hand-verified every finding, and wrote down exactly what it got right and wrong in docs/VALIDATION.md. Read that before trusting any number here. Treat the tool as a strong lead-generator a human verifies, not an oracle.

Built solo as a portfolio project to explore where agentic security review is heading (2026): scanner-grounded recall, LLM reasoning for the logic flaws scanners miss, adversarial verification for precision, and a Non-Human-Identity / AI-agent extension.

---

Why it's built this way (the core idea)

LLMs are high-recall, low-precision at finding vulnerabilities — published work puts raw output around 1 true positive per 50 reports. A naive "ask the LLM to find bugs" tool drowns you in confident hallucinations. So this plugin is a scanner-grounded hybrid:

                         /sec:scan  (orchestrator)
          ┌───────────────────────┴───────────────────────┐
   deterministic scanners                          agent hunters (parallel)
   (recall floor + machine evidence)               (logic flaws scanners miss)
   Opengrep · gitleaks · TruffleHog                injection · auth · crypto
   OSV-Scanner · Trivy · nuclei · testssl          exposure · config · NHI · agent-identity
          └───────────────────────┬───────────────────────┘
                          one findings schema  +  EVIDENCE RULE
                    (no concrete proof → finding is dropped at merge)
                                   │
                 per-finding ADVERSARIAL VERIFIER  (tries to refute each finding;
                 ≥0.8 confidence gate; machine-proven findings take a trusted shortcut)
                                   │
                 enrich (CWE → OWASP-2025 / NHI Top 10, EPSS, KEV)  →  score (P0–P3)
                                   │
                 self-contained HTML report + SARIF   →   /sec:fix (triage-gated, re-verifying)

• Deterministic work in scripts, judgment in agents. Scanners, parsing, dedup, and scoring are zero-dependency, unit-tested Node scripts; triage, exploitability assessment, threat modeling, and fixes are agents.
• The evidence rule is the main defense against hallucination: a finding without a concrete code reference, scanner fingerprint, request/response, or screenshot is discarded before it can reach a report.
• The verifier is the precision tier: every agent-claimed finding gets an independent agent prompted to refute it. (Its measured effectiveness is still being quantified — see VALIDATION.)

Commands

Command	What it does
/sec:init	Detect stack, record scope/authorization, scaffold security/, install scanners into the plugin's data dir
/sec:scan [category] [--diff]	Static sweep — scanners ∥ category hunters → merge → verify → score → HTML report
/sec:secrets	gitleaks (working tree + history) → TruffleHog live-verification escalation
/sec:deps	OSV-Scanner (all lockfiles) + Trivy → EPSS/KEV enrichment + reachability heuristic
/sec:dynamic [url]	Authorized live-app testing — headers, TLS, exposed endpoints, nuclei, + a Playwright prober (IDOR, injection reflection). Hard authorization gate enforced in code
/sec:threat-model	STRIDE model → security/threat-model.md + hunter focus areas
/sec:nhi [--cloud]	Non-Human-Identity review — inventory from code/IaC/CI, OWASP NHI Top 10 posture, ownership-from-git, opt-in read-only cloud discovery; renders an NHI Top 10 scorecard
/sec:agents	AI-agent & MCP identity posture — standing credentials, unscoped tool access, destructive tools without human-in-the-loop
/sec:rotate <secret>	Read-only rotation planner — finds consumers, ranks blast radius, emits a staged zero-downtime plan (never rotates)
/sec:fix [run-id]	One triage gate → autonomous fix + re-verify loop; pauses on auth/crypto patches; never weakens a control
/sec:full [--no-fix]	Chains every producer into one merged, verified, scored report, then the fix loop
/sec:status	Read-only digest — open findings by priority bucket, tallies, suggested next action

Prioritization

CWE-keyed (the stable taxonomy), with OWASP Top 10 2025 and OWASP NHI Top 10 labels derived from it. Findings are ranked by a CVSS × EPSS × reachability formula with a KEV override and an age/staleness multiplier for identity findings, bucketed P0–P3 — so confirmed, exploitable, reachable issues rise and low-probability transitive-dependency noise sinks. (See docs/GUIDE.md for the worked examples and why CVSS-first is the wrong default.)

Quickstart

# Try it locally without installing
git clone https://github.com/Benjaminfranck/cyber-security-plugin.git
cd cyber-security-plugin
npm test                 # 96 unit/integration tests
claude --plugin-dir .    # load the plugin into Claude Code, then run /sec:init in your project

/sec:init installs the scanner toolbelt into ${CLAUDE_PLUGIN_DATA} — your project stays clean.

What's tested

• 96 unit/integration tests (npm test) — schema + evidence rule, scoring, enrichment, every scanner adapter against recorded outputs, the report renderer, the authorization gate, the security-header checker, NHI inventory/rotation/cloud parsing, and the fixture recall/false-positive benchmark.
• fixtures/vuln-app/ — a deliberately vulnerable app (static + runtime + NHI/MCP) with VULNS.md ground truth. Planted secrets are AWS's documented non-functional example credentials — no real secrets anywhere in this repo (see SECURITY.md).
• A real-repo evaluation with every finding hand-verified — methodology, true positives, false positives, and the bugs it surfaced in the tool — in docs/VALIDATION.md.

Documentation

Doc	What's in it
docs/GUIDE.md	The educational deep-dive: each vulnerability class taught with real code, the verifier gate, the prioritization math, the scanners, the defensive guardrails
docs/VALIDATION.md	Honest evaluation on real code — what it found, what it got wrong, the FP numbers, the roadmap they imply
SECURITY.md	Defensive posture, authorization model, and the test-fixture/example-credential note

How it was built

Four phases, each spec → plan → test-driven implementation → review → merge:

1. Static core — schema, scoring, enrichment, 5 scanner adapters, 5 category hunters, the verifier, report.
2. Dynamic + threat-model — authorized DAST (headers/TLS/nuclei + Playwright prober), STRIDE.
3. Fix loop + pipeline — the triage-gated re-verifying fixer, /sec:full, /sec:status.
4. NHI / agentic-identity — the Non-Human-Identity extension (inventory, OWASP NHI Top 10 scorecard, ownership, rotation, MCP-agent posture).

Scope & honesty

• It is not a replacement for GitHub Advanced Security / Snyk / Wiz (no call-graph reachability, proprietary vuln DBs, dashboards, or continuous monitoring), nor a competitor to enterprise Non-Human-Identity platforms — it's a developer-side, code-first complement.
• Its real value over running the underlying scanners yourself: the LLM triage/verification, the authorization/logic-flaw hunting that pattern tools miss, the unified prioritized report, and the interactive fix loop.
• The wrapped scanners (Opengrep, gitleaks, TruffleHog, OSV-Scanner, Trivy, nuclei, testssl.sh) are downloaded at runtime, not redistributed; each keeps its own license.

License

MIT. Built by Benjamin Franck, 2026. Third-party scanner licenses: see NOTICE.