# AgentShield
**Security auditor for AI agent configurations**
Scans Claude Code setups for hardcoded secrets, permission misconfigs,
hook injection, MCP server risks, and agent prompt injection vectors.
Available as CLI, GitHub Action, and [GitHub App](https://github.com/apps/ecc-tools) integration.
[](https://www.npmjs.com/package/ecc-agentshield)
[](https://www.npmjs.com/package/ecc-agentshield)
[]()
[]()
[](LICENSE)
[Quick Start](#quick-start) · [What It Catches](#what-it-catches) · [API Reference](#api-reference) · [Opus Pipeline](#opus-46-deep-analysis---opus) · [GitHub Action](#github-action) · [Distribution](#distribution) · [MiniClaw](#miniclaw) · [Changelog](./CHANGELOG.md)
Preferred compute sponsor: Run or self-host any open-source model. Itô is ECC's suggested compute provider. Any GPU provider works. ECC only links to the Itô dashboard for sign-in and GPU rental or management; it does not create or manage rentals or provision compute or serving. Managed inference through Itô is not live yet.
---
## Why
The AI agent ecosystem is growing faster than its security tooling. In January 2026 alone:
- **12%** of a major agent skill marketplace was malicious (341 of 2,857 community skills)
- A **CVSS 8.8** CVE exposed 17,500+ internet-facing instances to one-click RCE
- The Moltbook breach compromised **1.5M API tokens** across 770,000 agents
Developers install community skills, connect MCP servers, and configure hooks without any automated way to audit the security of their setup. AgentShield scans your `.claude/` directory and flags vulnerabilities before they become exploits.
Built at the [Claude Code Hackathon](https://cerebralvalley.ai/e/claude-code-hackathon) (Cerebral Valley x Anthropic, Feb 2026). Part of the [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) ecosystem (42K+ stars).
## Quick Start
```bash
# Scan your Claude Code config (no install required)
npx ecc-agentshield scan
# Or install globally
npm install -g ecc-agentshield
agentshield scan
```
That's it. AgentShield auto-discovers your `~/.claude/` directory, scans all config files, and prints a graded security report.
Discovery intentionally skips common generated directories such as `node_modules`, build output, and `.dmux` worktree mirrors so transient copies do not duplicate findings.
```
AgentShield Security Report
Grade: F (0/100)
Score Breakdown
Secrets ░░░░░░░░░░░░░░░░░░░░ 0
Permissions ░░░░░░░░░░░░░░░░░░░░ 0
Hooks ░░░░░░░░░░░░░░░░░░░░ 0
MCP Servers ░░░░░░░░░░░░░░░░░░░░ 0
Agents ░░░░░░░░░░░░░░░░░░░░ 0
● CRITICAL Hardcoded Anthropic API key
CLAUDE.md:13
Evidence: sk-ant-a...cdef
Fix: Replace with environment variable reference [auto-fixable]
● CRITICAL Overly permissive allow rule: Bash(*)
settings.json
Evidence: Bash(*)
Fix: Restrict to specific commands: Bash(git *), Bash(npm *), Bash(node *)
Summary
Files scanned: 6
Findings: 73 total — 19 critical, 29 high, 15 medium, 4 low, 6 info
Auto-fixable: 8 (use --fix)
```
### More commands
```bash
# Scan a specific directory
agentshield scan --path /path/to/.claude
# Auto-fix safe issues (replaces hardcoded secrets with env var references)
agentshield scan --fix
# JSON output for CI pipelines
agentshield scan --format json
# Generate an HTML executive security report
agentshield scan --format html > report.html
# Generate a portable audit bundle
agentshield scan --evidence-pack ./agentshield-evidence
# Three-agent Claude Opus adversarial analysis (requires ANTHROPIC_API_KEY)
agentshield scan --opus --stream
# Generate a secure baseline config
agentshield init
```
JSON reports now expose `findings[].runtimeConfidence` when AgentShield can distinguish active runtime config from project-local settings, template/example inventories, installed Claude plugin caches, declarative plugin manifests, and manifest-resolved non-shell hook implementations. Reports also include local harness adapter evidence for Claude Code, OpenCode, Codex, Gemini, Zed, VS Code, dmux, terminal-agent wrappers, and project-local templates when matching markers are present.
## What It Catches
**268 rules** across 15 modules, graded A to F with a 0 to 100 numeric score. Recognized defenses are listed and never penalized.
#### Scoring and recognized defenses
The score starts at 100 per category and only findings deduct from it: critical 25, high 15, medium 5, low 2, info 0. Protective configuration the scanner finds (deny and ask lists, sandbox settings, blocking PreToolUse hooks, read-only agent tool lists, Codex `sandbox_mode`, Hermes manual approvals, and similar) is listed in every report under "Recognized Defenses" so it gets credit and is visibly never penalized. Defenses do not add points either: the score cannot be gamed by adding decorative deny rules, it can only be lowered by real findings. Guard-pattern findings the permission rules emit at info severity ("Deny/ask rule blocking ...", "Prohibition of ...", "Mention of ...") are enforced to a zero deduction in `src/reporter/score.ts`.
### Secrets Detection
| What | Examples |
|------|----------|
| API keys | Anthropic (`sk-ant-`), OpenAI (`sk-proj-`/`sk-`), xAI (`xai-`), AWS (`AKIA`), Google/Gemini (`AIza`), Stripe (`sk_test_`/`sk_live_`) |
| Tokens | GitHub PATs (`ghp_`/`github_pat_`), Linear (`lin_api_`), Cloudflare (`CF_API_TOKEN=`), Slack (`xox[bprs]-`), JWTs (`eyJ...`), Bearer tokens |
| Credentials | Hardcoded passwords, database connection strings (postgres/mongo/mysql/redis), private key material |
| Env leaks | Secrets passed through environment variables in configs, `echo $SECRET` in hooks |
### Permission Audit (17 rules)
| What | Examples |
|------|----------|
| Wildcard access | `Bash(*)`, `Write(*)`, `Edit(*)` — unrestricted tool permissions |
| Missing deny lists | No deny rules for `rm -rf`, `sudo`, `chmod 777` |
| Dangerous flags | `--dangerously-skip-permissions` usage |
| Mutable tool exposure | All mutable tools (Write, Edit, Bash) allowed without scoping |
| Destructive git | `git push --force`, `git reset --hard` in allowed commands |
| Unrestricted network | `curl *`, `wget`, `ssh *`, `scp *` in allow list without scope |
### Hook Analysis (40 rules)
| What | Examples |
|------|----------|
| Command injection | `${file}` interpolation in shell commands — attacker-controlled filenames become code |
| Data exfiltration | `curl -X POST` with variable interpolation sending data to external URLs |
| Silent errors | `2>/dev/null`, `\|\| true` — failing security hooks that silently pass |
| Missing hooks | No PreToolUse hooks, no Stop hooks for session-end validation |
| Network exposure | Unthrottled network requests in hooks, sensitive file access without filtering |
| Session startup | SessionStart hooks that download and execute remote scripts |
| Package installs | Global `npm install -g`, `pip install`, `gem install`, `cargo install` in hooks |
| Container escape | Docker `--privileged`, `--pid=host`, `--network=host`, root volume mounts |
| Credential access | macOS Keychain, GNOME Keyring, /etc/shadow reads |
| Reverse shells | `/dev/tcp`, `mkfifo + nc`, Python/Perl socket shells |
| Clipboard access | `pbcopy`, `xclip`, `xsel`, `wl-copy` — exfiltration via clipboard |
| Log tampering | `journalctl --vacuum`, `rm /var/log`, `history -c` — anti-forensics |
### MCP Server Security (49 rules)
| What | Examples |
|------|----------|
| High-risk servers | Shell/command MCPs, filesystem with root access, database MCPs, browser automation |
| Supply chain | `npx -y` auto-install without confirmation — typosquatting vector |
| Hardcoded secrets | API tokens in MCP environment config instead of env var references |
| Remote transport | MCP servers connecting to remote URLs (SSE/streamable HTTP) |
| Shell metacharacters | `&&`, `\|`, `;` in MCP server command arguments |
| Missing metadata | No version pin, no description, excessive server count |
| Sensitive file args | `.env`, `.pem`, `credentials.json` passed as server arguments |
| Network exposure | Binding to `0.0.0.0` instead of localhost |
| Auto-approve | `autoApprove` settings that skip user confirmation for tool calls |
| Missing timeouts | High-risk servers without timeout — resource exhaustion risk |
Supply-chain verification (`agentshield scan --supply-chain`) extracts MCP
package references plus root `package.json` and `package-lock.json` dependency
evidence, then reports provenance counts for npm vs git, pinned vs unpinned,
known-good packages, and npm-registry-backed metadata. Add
`--supply-chain-online` to query npm for downloads, maintainers, postinstall
scripts, deprecation, and package age.
Package-manager hardening checks also scan `.npmrc`, `.yarnrc.yml`, and
`pnpm-workspace.yaml` for plaintext registry credentials, explicit dependency
lifecycle-script enablement, and missing or weak release-age cooldowns where the
package manager supports them. npm configs are checked for lifecycle-script
blocking and unsupported release-age keys that can create false confidence; use
pnpm `minimumReleaseAge` / `minimum-release-age`, Yarn `npmMinimalAgeGate`, or an
external package-manager policy wrapper for cooldown enforcement.
AgentShield also scans AI developer-tool persistence surfaces used by recent npm
and PyPI campaign payloads, including Claude Code hook settings,
`.claude/router_runtime.js`, VS Code `tasks.json` folder-open automation,
Zed project `tasks.json`, `.vscode/setup.mjs`, `.zed/setup.mjs`, GitHub
workflow drop-ins, LaunchAgent/systemd dead-man switch artifacts,
`gh-token-monitor` token-store files, metadata-service credential targets, and
reported exfiltration or second-stage network indicators. These indicators are
emitted as critical hook findings so CI can fail fast even after the malicious
package has been uninstalled.
#### MCP Confidence Notes
AgentShield scans both active MCP config and repository-shipped MCP templates.
- Findings from `.mcp.json`, `mcp.json`, `.claude/mcp.json`, `.claude.json`, and active `settings.json` are highest-confidence runtime exposure only under active Claude configuration roots; copies in docs, examples, or template directories are classified separately.
- Findings from `settings.local.json` are emitted as `runtimeConfidence: project-local-optional`.
- Findings from locations such as `mcp-configs/`, `config/mcp/`, or `configs/mcp/` indicate risky MCP definitions present in repository templates, not guaranteed active runtime enablement.
- JSON, markdown, terminal, and HTML outputs now expose source context via `runtimeConfidence: active-runtime | project-local-optional | template-example | docs-example | plugin-cache | plugin-manifest | hook-code`.
- Non-secret `template-example` MCP findings are score-weighted at `0.25x`, and one template file is capped at `10` deduction points per score category so a single MCP catalog cannot score like dozens of enabled servers.
- In template files, findings such as risky server type, remote URL transport, `npx -y`, unpinned packages, and environment inheritance are still valuable, but they should be interpreted as "this repo ships a risky MCP template" rather than "this MCP is definitely enabled right now."
- Aggregate findings like large MCP server counts are especially likely to overstate runtime exposure when the source file is a template catalog.
### Agent Config Review (41 rules)
| What | Examples |
|------|----------|
| Unrestricted tools | Agents with Bash access, no `allowedTools` restriction |
| Prompt injection surface | Agents processing external/user-provided content without defenses |
| Auto-run instructions | `CLAUDE.md` containing "Always run", "without asking", "automatically install" |
| Hidden instructions | Unicode zero-width characters, HTML comments, base64-encoded directives |
| URL execution | `CLAUDE.md` instructing agents to fetch and execute remote URLs |
| Time bombs | Delayed execution instructions triggered by time or absence conditions |
| Data harvesting | Bulk collection of passwords, credentials, or database dumps |
| Prompt reflection | `ignore previous instructions`, `you are now`, DAN jailbreak, fake system prompts |
| Output manipulation | `always report ok`, `remove warnings from output`, suppress security findings |
Structured JSON under `.claude/subagents/` and `.claude/slash-commands/` is analyzed like agent config when it declares `allowedTools` or similar tool metadata. Slash commands under `commands/` and `slash-commands/` are typed `command-md`: they get the injection and dangerous-instruction rules but not the skill packaging hygiene rules, which only apply to `SKILL.md`. Freeform `skill-md` prompt text still has narrower security coverage than `agent-md` and `CLAUDE.md`.
#### Scanner Accuracy Notes
- Live audit notes and follow-up items are tracked in [`false-positive-audit.md`](./false-positive-audit.md).
- The most useful operator guidance is in the audit's [`Triage Rules For Current Reports`](./false-positive-audit.md#triage-rules-for-current-reports) section.
- The audit doc also includes a reusable [`False-Positive Taxonomy`](./false-positive-audit.md#false-positive-taxonomy), [`Repo Audit Worksheet`](./false-positive-audit.md#repo-audit-worksheet), and [`Release Gate For Accuracy Changes`](./false-positive-audit.md#release-gate-for-accuracy-changes).
- Cross-file hook-manifest awareness now suppresses settings-only `hooks-no-pretooluse` when a companion `hooks/hooks.json` manifest defines PreToolUse hooks.
- Manifest-referenced hook implementations are now discovered from `hooks/hooks.json`-style indirection; shell targets continue through hook rules, and non-shell `hook-code` targets now emit targeted findings for explicit `output(...)` context injection, transcript input access, and remote shell payloads executed via child-process wrappers.
- Current known high-signal caveats are broader non-shell hook execution that still needs language-aware analysis beyond those current `hook-code` signals, and `skill-md` prompt text that still bypasses most agent/injection rules.
- `runtimeConfidence` now appears on MCP findings, `settings.local.json`, docs/examples, installed Claude plugin caches, plugin manifests, and manifest-resolved non-shell hook code. Scoring discounts non-secret `template-example` and `docs-example` findings at `0.25x`, non-secret `project-local-optional` findings at `0.75x`, and non-secret `plugin-cache` / `plugin-manifest` findings at `0.5x`. Non-secret `template-example` findings are also capped at `10` deduction points per file and score category so one catalog file cannot dominate the grade. `hook-code` findings currently stay at full weight, but the active rules there are narrow language-aware implementation signals.
- Practical reading rule: `template-example` means "repo ships this risky template", not "this is definitely enabled right now."
- Practical reading rule: `docs-example` means "repo ships risky sample guidance", not "this example is active runtime config."
- Practical reading rule: `plugin-cache` means "installed plugin content is present on disk", not "this file is top-level runtime config"; real secrets still stay critical.
- Practical reading rule: `plugin-manifest` means "the repo declares this hook behavior", while `hook-code` means "the scanner reached the referenced non-shell implementation."
- Current edge case: docs-only example trees now re-add the standalone `CLAUDE.md` example file for scanning, but still suppress the rest of the nested example subtree unless a runtime companion exists.
- Current edge case: tutorial/example bundles outside the current `docs/`, `commands/`, `examples/`, `samples/`, `demo/`, `tutorial/`, `guide/`, `cookbook/`, and `playground/` heuristics can still be treated as live config until broader example-root classification lands.
- Docs-only nested `CLAUDE.md` roots under `docs/` are now skipped unless runtime config companions exist in the same subtree.
- Exact `Bash(curl https://...)` and `Bash(wget https://...)` allow entries with pinned literal URLs no longer trigger the generic `permissions-permissive-*` finding; wildcard and dynamic network permissions still do.
- Exact `Bash(node scripts/foo.js ...)` and `Bash(python3 ./tools/audit.py ...)` wrapper commands no longer trigger the generic interpreter-access finding; inline eval forms such as `node -e` and `python -c` still do.
- Exact read-only Docker inventory commands such as `Bash(docker ps)` and `Bash(docker image ls)` no longer trigger the generic Docker-access finding; execution-oriented forms such as `docker run` and `docker exec` still do.
- Exact `settings.local.json` allowlists now downgrade `permissions-no-deny-list` from high to medium when every allow entry is fully specified; wildcard or dynamic project-local permissions still keep the higher severity.
- Exact local-only `settings.local.json` allowlists now also downgrade `hooks-no-pretooluse` from medium to low; broader or network-capable project-local configs still keep the higher severity.
- Comment-only shell-hook lines are now ignored by the hook exfiltration, sensitive-path, and silent-fail regex rules, so inline remediation notes and commented examples no longer look like live hook behavior.
- Narrow specialist agents, subagents, and slash commands now downgrade generic Bash-access and escalation-chain findings from high to medium; broader generalist workflows still keep the higher severity.
- Repo-scoped filesystem MCP servers using relative paths like `./` now grade lower than unrestricted root/home filesystem access; root-level filesystem exposure still stays high.
- Defensive agent-review content that mentions patterns like ``fetch(userProvidedUrl)`` no longer triggers `agents-injection-surface`; direct instructions to fetch/process external content still do.
- `agents-explorer-write` now uses role metadata and the lead agent intro instead of any later workflow/example text, so procedural `search for ...` steps in normal worker prompts no longer get mislabeled as explorer-style agents. Example: `chief-of-staff.md` no longer trips that rule just because it contains `gog gmail search ...`.
- `agents-oversized-prompt` now measures effective prompt size instead of raw file length, discounting fenced code blocks and Markdown tables. Example-heavy agents like `chief-of-staff.md` and `planner.md` no longer trip the rule, while prose-heavy agents still do.
- Markdown example/test passwords in example-like paths such as `docs/`, `commands/`, `examples/`, `tutorials/`, and `demos/` are now suppressed when the surrounding context is clearly instructional; that suppression does not apply to normal agent/config markdown.
#### False-Positive Audit Workflow
Use this workflow when a repo scan looks noisy or when you are tuning AgentShield rules.
1. Start with JSON output so you can inspect file paths, `runtimeConfidence`, and score impact directly.
2. Separate active runtime findings from lower-confidence source kinds before changing any rules.
3. Validate suspected false positives against at least one real repo and one minimal synthetic fixture.
4. Prefer source-aware reclassification and wording changes before adding blanket suppression.
5. Keep real secrets and explicit execution paths visible even inside examples, manifests, or templates.
6. Re-run targeted tests, then the full gate, before changing release behavior.
Recommended commands:
```bash
agentshield scan --path /repo --format json > report.json
jq '.findings | group_by(.runtimeConfidence // "none") | map({
runtimeConfidence: (.[0].runtimeConfidence // "none"),
count: length
})' report.json
jq '.findings | group_by(.file) | map({
file: .[0].file,
count: length
}) | sort_by(-.count)[:20]' report.json
```
Confidence-first triage commands:
```bash
# Highest-signal findings first: active runtime + project-local
jq '.findings
| map(select((.runtimeConfidence // "active-runtime") | IN("active-runtime","project-local-optional")))
| map(select(.severity | IN("critical","high","medium")))
| map({file, severity, runtimeConfidence, title})' report.json
# Lower-confidence inventory that usually needs interpretation, not suppression
jq '.findings
| map(select((.runtimeConfidence // "") | IN("template-example","docs-example","plugin-cache","plugin-manifest")))
| map({file, severity, runtimeConfidence, title})' report.json
```
Recommended audit order:
- `active-runtime` and `project-local-optional`: treat as highest-signal findings first.
- `template-example`, `docs-example`, and `plugin-cache`: confirm whether the repo or installed plugin cache is shipping risky guidance versus actually enabling it.
- `plugin-manifest`: confirm whether the risk is in declarative hook wiring or the referenced implementation.
- `hook-code`: confirm whether the implementation actually injects context, reads transcripts, or shells out in a risky way.
Rule-design guidelines:
- Prefer source-aware labeling over suppression. If a finding is real but lower confidence, keep it visible and say why.
- Prefer cross-file context over single-file guesses. Companion manifests and referenced hook implementations usually matter more than isolated config.
- Prefer narrow, behavior-based `hook-code` rules over generic wrapper heuristics. `spawnSync("bash", ["-lc", "curl ... | bash"])` is high-signal; ordinary `spawnSync("prettier", ...)` is not.
- Do not downgrade real secrets just because they appear in docs or examples. Structural findings can be downgraded; committed credentials should stay critical.
- Keep example-root heuristics evidence-based. Today the scanner treats `docs/`, `commands/`, `examples/`, `example/`, `samples/`, `sample/`, `demo/`, `demos/`, `tutorial/`, `tutorials/`, `guide/`, `guides/`, `cookbook/`, and `playground/` as example-like paths.
When you change rule accuracy, update both:
- [`false-positive-audit.md`](./false-positive-audit.md) with the new baseline and remaining gaps
- the targeted regression tests for the specific rule family you changed
- `agentshield scan --corpus-gate` in CI so the built-in attack corpus must stay fully detected; failed corpus gates now include a prioritized accuracy improvement plan by category, missing rule, and missed config
- the corpus now includes an env proxy/DNS exfiltration fixture so proxy hijack, runtime import mutation, env-token exfiltration, credential-store access, and clipboard access stay covered together
- if you are filing a scanner-noise bug, start from the audit doc's [`False-Positive Issue Template`](./false-positive-audit.md#false-positive-issue-template)
#### Reducing False Positives In Practice
The current scan profile is not dominated by broken matchers. It is mostly dominated by lower-confidence source kinds that need different interpretation.
Current patterns from the latest live scans:
- template MCP inventory is still the biggest noise source by count in `everything-claude-code`
- example/tutorial config needs example-aware wording and weighting, not blanket suppression
- declarative hook manifests and executable hook implementations need different handling
- many remaining agent findings are policy findings about intentionally privileged agents, not obvious rule bugs
- the latest alert review reduced specialist agent-capability severity inflation, repo-scoped filesystem MCP inflation, and template-catalog score inflation; remaining noise is now mostly template count/interpretation and active-runtime remote MCP URLs
Recurring pattern signatures to recognize:
- one template file dominating the report usually means confidence/weighting work, not a broken matcher
- broad `agents-*` clusters across files with explicit tool metadata usually mean policy review, not false-positive suppression
- very small `project-local-optional` clusters usually mean scope is already modeled and only severity may need tuning
- a repo-scoped filesystem MCP with relative-path args should not be treated like root/home filesystem access
When to open a false-positive issue instead of just triaging the report:
- the same finding pattern reproduces across at least one real repo and one minimal synthetic fixture
- the finding is wrong for its own source kind, not just lower-confidence than `active-runtime`
- the fix needs matcher changes, not just better wording, score weighting, or cross-file context
- the finding would still be misleading even after reading `runtimeConfidence`
Recommended operating model:
- Start with `runtimeConfidence` before changing any rule. Separate `active-runtime` from `template-example`, `docs-example`, `plugin-cache`, `plugin-manifest`, and `project-local-optional`.
- Reclassify before suppressing. If the finding is real but lower confidence, keep it visible and adjust wording or score weight instead of hiding it.
- Keep secrets on a stricter standard. Real credentials should stay critical even in docs, examples, plugin caches, or manifests.
- Use cross-file context whenever possible. Settings, manifests, and referenced hook implementations usually need to be read together.
- For `hook-code`, add only narrow language-aware rules for explicit risky behavior. Avoid broad wrapper heuristics.
- For agent rules, anchor on role metadata and lead instructions before matching arbitrary later prose.
Repo conventions that help AgentShield scan accurately:
- put reusable MCP catalogs under template paths such as `mcp-configs/` instead of live runtime config files
- keep local-only overrides in `settings.local.json`
- keep tutorials and examples under example-like paths such as `docs/`, `examples/`, `tutorials/`, `demos/`, or `guides/`
- keep `hooks/hooks.json` declarative and put the implementation in separate hook script files
- keep large agent examples inside fenced code blocks so prompt-size and role heuristics stay accurate
Current high-value places to audit first:
- files with the highest finding count
- files with `runtimeConfidence: template-example` or `plugin-cache`
- `settings.local.json` findings that may be project-local rather than repo-wide
- `plugin-manifest` findings that need confirmation in the referenced implementation
- `hook-code` findings that involve context injection, transcript access, or child-process execution
## Features
### Auto-Fix Engine (`--fix`)
Automatically applies safe fixes:
- Replaces hardcoded secrets with `${ENV_VAR}` references
- Tightens wildcard permissions (`Bash(*)` → scoped `Bash(git *)`, `Bash(npm *)`)
Only fixes marked `auto: true` are applied. Permission changes require human review.
**Verify-after-fix:** `--fix` does not trust itself. After applying fixes it re-scans the target, and if the posture score regressed or a new high/critical finding appeared (the kind of churn a naive permission tighten can cause), it rolls every modified file back to its original content. On success it prints a tamper-evident attestation digest binding the before/after score and finding deltas, so the kept fixes are provably non-regressing.
### External Rule Packs (`--rule-pack`)
Run community or private detection rules alongside the built-ins, without recompiling:
```bash
agentshield scan --rule-pack ./my-pack.json
agentshield scan --rule-pack ./pack-a.json --rule-pack ./pack-b.json # repeatable
```
A pack is a JSON file validated with the same fail-closed approach as `--policy` (bad JSON, schema violations, duplicate ids, or an uncompilable regex abort the scan):
```json
{
"version": 1,
"name": "my-pack",
"rules": [
{
"id": "tool-poisoning-001",
"name": "Tool description poisoning",
"description": "Hidden instruction in a tool description",
"severity": "high",
"category": "injection",
"patterns": ["ignore (?:all )?previous instructions"],
"fileTypes": ["agent-md", "claude-md"]
}
]
}
```
Each pattern is a JS regex run against file content; `fileTypes` is optional and scopes a rule to specific config types. External findings count toward the overall grade. Anyone with a pack in this shape can plug in.
### Secure Init (`agentshield init`)
Generates a hardened `.claude/` directory with scoped permissions, safety hooks, and security best practices. Existing files are never overwritten.
### Claude Opus Deep Analysis (`--opus`)
Three-agent adversarial pipeline powered by Claude Opus (claude-opus-5 by default; the injection tester uses claude-sonnet-5):
1. **Red Team (Attacker)** — finds exploitable attack vectors and multi-step chains
2. **Blue Team (Defender)** — evaluates existing protections and recommends hardening
3. **Auditor** — synthesizes both perspectives into a prioritized risk assessment
The Attacker finds that `curl` hooks with `${file}` interpolation + `Bash(*)` = command injection pivot. The Defender notes no PreToolUse hooks exist to stop it. The Auditor chains them into a prioritized action list.
```bash
agentshield scan --opus # Red + Blue run in parallel
agentshield scan --opus --stream # Sequential with real-time output
agentshield scan --opus --stream -v # Verbose — see full agent reasoning
```
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Phase 1a: ATTACKER (Red Team) ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
✓ Attacker analysis complete (4521 tokens)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Phase 1b: DEFENDER (Blue Team) ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
✓ Defender analysis complete (3892 tokens)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Phase 2: AUDITOR ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
Risk Level: CRITICAL
Opus Score: █████░░░░░░░░░░░░░░░ 15/100
```
Requires `ANTHROPIC_API_KEY` environment variable.
#### OrcaRouter provider
The `--opus` and `--injection` analysis modes can also run through
[OrcaRouter](https://www.orcarouter.ai), an OpenAI/Anthropic-compatible gateway
that routes each request to the most cost-effective upstream model:
```bash
export ORCAROUTER_API_KEY=your-key-here
agentshield scan --opus --provider orcarouter
agentshield scan --injection --provider orcarouter
```
The provider points the Anthropic client at `https://api.orcarouter.ai` and
uses the gateway's namespaced model ids (e.g. `anthropic/claude-sonnet-5`,
`anthropic/claude-opus-5`). The default provider remains Anthropic.
With `--provider orcarouter` the scanned configuration contents are sent to
OrcaRouter's API instead of Anthropic's, so do not use it on configs containing
secrets you have not redacted.
### Compliance Mapping (`--compliance`)
Map findings to audit-framework control IDs so GRC teams get an auditor-ready coverage artifact instead of a raw findings list:
```bash
agentshield scan --compliance soc2 # SOC 2 Trust Services Criteria
agentshield scan --compliance pci,iso # comma-separated
agentshield scan --compliance all # SOC 2 + PCI DSS + ISO 27001
```
Each framework prints a control-coverage table (control id, title, highest severity, finding count, examples), ordered by severity:
```
## Compliance Mapping: SOC 2 (Trust Services Criteria)
Mapped 194/194 findings to 5 control(s). 0 finding(s) had no mapped control.
| Control | Title | Highest | Findings | Examples |
| CC6.1 | Logical access - credentials | critical | 76 | Hardcoded Anthropic API key; ... |
```
Mapping is finding-category-level guidance (SOC 2, PCI DSS v4.0, ISO/IEC 27001:2022 Annex A), not a certified crosswalk; confirm control applicability with your auditor.
### Output Formats
| Format | Flag | Use Case |
|--------|------|----------|
| Terminal | `--format terminal` (default) | Interactive use |
| JSON | `--format json` | CI pipelines, programmatic access |
| Markdown | `--format markdown` | Documentation, PRs |
| HTML | `--format html` | Executive report with risk posture and priorities |
| Evidence pack | `--evidence-pack