security-assessment¶

Deep security assessment + adversarial ML red-team for Claude Code. This plugin is a companion to dev-team, which provides the reusable primitives (codebase-recon, ACCEPTED-RISKS convention, versioned primitives contract, SARIF-first tool orchestration).

Design¶

This plugin inverts the usual "LLM does everything" pattern. Deterministic tools do the detection, and hooks automate invocation. The plugin reserves LLM agents for what they do best: business-logic reasoning, narrative annotation, cross-repo attack chains, executive prose, and the judgment stages of FP-reduction.

When to use this vs. `/code-review`¶

This plugin is the deep layer. Use it for audits, release gates, milestone reviews, publication-grade reports, and red-team runs. Runtime is minutes (recon → parallel tools → parallel judgment → FP-reduction → narratives → exec report).

For inline checkpoints during active development, use /code-review. It invokes the sibling security-review agent from the dev-team plugin. That agent makes a single opus pass in seconds, which suits every commit. This plugin also invokes the same agent internally at Phase 1b of /security-assessment, so running the agent during development is complementary, not redundant. When a /code-review finding warrants deeper analysis (FP-reduction, reachability, compliance mapping, domain-layer review), escalate to /security-assessment here.

Pattern-visible vulnerability classes (single-line regex, stable AST shape, ≤10% false-positive rate) are authoritatively detected by the semgrep rules under knowledge/semgrep-rules/*.yaml, not by agent prompts. The class → surface boundary is encoded in plugins/dev-team/knowledge/security-review-rule-map.yaml.

LLM-safety coverage bound¶

static coverage via llm-safety.yaml is intentionally narrow — it catches pattern-visible issues but is NOT a substitute for runtime LLM safety testing

Static coverage handles hardcoded LLM keys, insecure model loading (ONNX/pickle deserialization), and prompt-template string injection. The red-team harness (Phase C) integrates runtime LLM-safety tools (garak, rebuff, PyRIT) when needed.

Install¶

Prerequisites¶

Required:

Claude Code installed and authenticated.
The dev-team plugin. This plugin depends on its primitives contract (^1.0.0), codebase-recon agent, and ACCEPTED-RISKS convention.
Python ≥ 3.10 — the red-team harness requires it.
jq — JSON parsing in hooks + pipeline glue.

Tier-1 static-analysis tools (required for /security-assessment to produce useful output): semgrep, gitleaks, trivy, hadolint, actionlint. See the User Guide tool-install matrix for per-tool coverage, install commands, and missing-tool impact.

Optional tools (broader coverage; the pipeline degrades gracefully without them): checkov, bandit, gosec, bearer, osv-scanner, grype, kube-linter, trufflehog, detect-secrets, deptry, kube-score, govulncheck, joern (call-graph reachability for FP-reduction), pandoc, weasyprint.

Install the tools¶

macOS — one command:

./plugins/security-assessment/install-macos.sh           # tier-1 only
./plugins/security-assessment/install-macos.sh --all     # tier-1 + optional + PDF deps
./plugins/security-assessment/install-macos.sh --dry-run # preview commands without running

Windows — PowerShell (requires Scoop):

# If needed, allow local scripts first (run once in an elevated session):
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

.\plugins\security-assessment\install-windows.ps1          # tier-1 only
.\plugins\security-assessment\install-windows.ps1 -All     # tier-1 + optional + PDF deps
.\plugins\security-assessment\install-windows.ps1 -DryRun  # preview commands without running

You can re-run the installer on all platforms. Each step skips tools that are already present.

Linux / other platforms: use the install hints in the table above. All tools ship prebuilt Linux binaries through their GitHub releases or pip.

Install the plugin¶

# From the marketplace
claude plugin marketplace add https://github.com/bdfinst/agentic-dev-team
claude plugin install security-assessment@bfinster

# From a local clone
claude plugin install --scope project /path/to/agentic-dev-team/plugins/security-assessment

Verify¶

./plugins/security-assessment/install.sh

The check validates these conditions:

dev-team present with primitives-contract ^1.0.0.
Python ≥ 3.10 on PATH.
Tier-1 tool presence. Absence of any required tool is a hard failure.
Optional tool presence — warnings only.

Run without installing (zero-install flow)¶

scripts/run-assessment-local.sh runs the full pipeline from the repo checkout. The script auto-detects the claude CLI and runs the LLM judgment phases when the CLI is available. Otherwise, the script degrades to deterministic-only output. See docs/user-guide-security-assessment.md for the full runbook.

Commands¶

Command	Purpose
`/security-assessment <path>`	Full pipeline: recon → tool battery → LLM narrative agents → FP-reduction → compliance → service-comm diagram → exec report
`/cross-repo-analysis <paths>`	Shared credentials and service-communication analysis across multiple repos
`/redteam-model <target>`	Adversarial ML red-team probes against a self-owned target
`/export-pdf <report.md>`	PDF export via pandoc / weasyprint
`/upgrade`	Update the plugin to the latest marketplace release; offer to enable marketplace-level auto-update

Documentation¶

Doc	Covers
Workflows	Pipeline phases, orchestrator commands, red-team flow
Skills catalog	All skills and commands with descriptions and options
Agents	Assessment, cross-repo, and red-team agents with dispatch model
User guide	Full runbook — install, run, interpret results
Accepted risks format	`ACCEPTED-RISKS.md` schema and suppression rules
Comparative testing	Measuring coverage parity against the reference prompt-heavy pipeline

Update¶

Run /upgrade from any Claude Code session with this plugin loaded. The command:

Reads the installed version from claude plugin list.
Checks the auto-update flag on the bfinster marketplace and asks for consent before enabling it (the same flag the /plugin UI toggles).
Detects the install scope and passes --scope <scope> to claude plugin update so project- and local-scope installs upgrade correctly.
Warns if the companion dev-team plugin is not installed. That plugin provides primitives this plugin depends on.
Reports the previous and new version, and prompts you to restart.

Manual fallback when /upgrade is unavailable:

claude plugin update --scope <scope> security-assessment@bfinster

Safety defaults¶

Hooks default ON in this plugin (see CLAUDE.md § "Hooks default ON"). The PostToolUse auto-scan hook fires on Edit/Write of security-relevant file types.
Red-team targets default to self-owned only: localhost + RFC1918 + ::1. Public targets require an explicit --self-certify-owned artifact whose SHA-256 is logged to the audit trail.

See CLAUDE.md for the opt-out snippet.

Status¶

Shipped and released. Current version: 3.4.0 (see CHANGELOG.md). Every phase is live:

✅ dev-team Phase A primitives: codebase-recon agent, ACCEPTED-RISKS convention, security-primitives-contract v1.0.0, contract-version-guard hook, SARIF-first tool orchestration
✅ This plugin's own agents (judgment, cross-repo, red-team)
✅ Six-stage FP-reduction (joern reachability with LLM fallback)
✅ Adversarial ML red-team harness
✅ Publication-ready executive report
✅ release-please catalog + versioning config