agentshield README

项目的 README,来自 github.com/affaan-m/agentshield。合并为一个 markdown 文件:README.md。

AgentShield

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 integration.

npm version npm downloads tests coverage License: MIT

Quick Start · What It Catches · API Reference · Opus Pipeline · GitHub Action · Distribution · MiniClaw · Changelog

Itô Markets
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:

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 (Cerebral Valley x Anthropic, Feb 2026). Part of the Everything Claude Code ecosystem (42K+ stars).

Quick Start

# 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

# 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.

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

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:

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:

# 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:

Rule-design guidelines:

When you change rule accuracy, update both:

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:

Recurring pattern signatures to recognize:

When to open a false-positive issue instead of just triaging the report:

Recommended operating model:

Repo conventions that help AgentShield scan accurately:

Current high-value places to audit first:

Features

Auto-Fix Engine (--fix)

Automatically applies safe fixes:

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:

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):

{
  "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.

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, an OpenAI/Anthropic-compatible gateway that routes each request to the most cost-effective upstream model:

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:

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 <dir> Audit and buyer reviews
Remediation plan --remediation-plan <path> Stable-fingerprint fix queue for CI and ticketing

Evidence packs write a deterministic directory containing manifest.json, README.md, agentshield-report.json, agentshield-report.html, agentshield-results.sarif, policy-evaluation.json, baseline-comparison.json, supply-chain.json, and ci-context.json, and remediation-plan.json. The manifest records SHA-256 digests and byte counts for bundle artifacts plus a bundle digest over the machine-readable evidence. ci-context.json records whitelisted GitHub Actions workflow, commit, run, and runner provenance without copying arbitrary environment variables into the bundle. Redaction is enabled by default for local paths, usernames, emails, and token-shaped strings; use --no-evidence-redact only for private internal bundles.

Remediation plans write a JSON queue of findings with stable hashed fingerprints, severity, file, fixability, ordered workflow phases, and the recommended next command. The workflow phases route safe auto-fixes first, manual-review findings second, and verification last so maintainers can attach the plan to CI tickets without turning every finding into a separate thread. They intentionally omit raw evidence and fix before/after values so teams can attach the plan to tickets without copying token-shaped strings.

Verify a saved evidence pack before attaching it to CI artifacts or customer handoffs:

agentshield evidence-pack verify ./agentshield-evidence
agentshield evidence-pack verify ./agentshield-evidence --json

Inspect a verified evidence pack when a downstream GitHub App, Linear sync, or security-review workflow needs a compact readback without opening every artifact:

agentshield evidence-pack inspect ./agentshield-evidence
agentshield evidence-pack inspect ./agentshield-evidence --json

Aggregate multiple verified evidence packs when an operator needs fleet-level routing across repos, teams, or harnesses. The JSON output includes operatorReadback for promotion status/digest checks and reviewItems with source evidence paths and owner-ready recommendations for packs that need follow-up:

agentshield evidence-pack fleet ./repo-a-evidence ./repo-b-evidence
agentshield evidence-pack fleet ./repo-a-evidence ./repo-b-evidence --json

operatorReadback is the stable field for downstream GitHub App, Linear, or ECC Tools routing. It reports ready, status, digest, owner counts, blocking review counts, approval routes, deterministic approvalIds, and the next operator action so fleet promotion can be gated without parsing terminal prose. Each review item also carries the same approvalId plus a Linear-friendly ticket externalId, allowing sync jobs to dedupe owner approval threads across reruns.

JSON Report Shape

agentshield scan --format json is the supported machine-readable scanner interface today.

{
  "timestamp": "2026-03-13T19:42:00.000Z",
  "targetPath": "/repo/.claude",
  "score": {
    "grade": "C",
    "numericScore": 66,
    "breakdown": {
      "secrets": 100,
      "permissions": 70,
      "hooks": 80,
      "mcp": 35,
      "agents": 45
    }
  },
  "summary": {
    "totalFindings": 29,
    "critical": 1,
    "high": 7,
    "medium": 8,
    "low": 10,
    "info": 3,
    "filesScanned": 17,
    "autoFixable": 2,
    "defenses": 4
  },
  "defenses": [
    {
      "id": "defense-deny-list",
      "title": "Permission deny list",
      "file": ".claude/settings.json",
      "detail": "6 deny rules; covers .env, ~/.ssh, curl, sudo, rm -rf. Deny wins over allow regardless of specificity.",
      "harness": "claude-code"
    }
  ],
  "findings": [
    {
      "id": "mcp-risky-filesystem",
      "severity": "medium",
      "category": "mcp",
      "title": "Template defines risky MCP server: filesystem",
      "description": "Repository template includes a high-risk filesystem MCP server.",
      "file": "mcp-configs/mcp-servers.json",
      "runtimeConfidence": "template-example"
    }
  ]
}

Notes:

API Reference

AgentShield currently has three distinct automation surfaces:

Important packaging note:

Detailed request/response and schema notes live in API.md.

GitHub Action

- name: AgentShield Security Scan
  uses: affaan-m/agentshield@v1
  with:
    path: "."
    min-severity: "medium"
    fail-on-findings: "true"

Inputs:

Input Default Description
path . Path to scan
min-severity medium Minimum severity: critical, high, medium, low, info
fail-on-findings true Fail the action if findings meet severity threshold
format terminal Output format: terminal, json, markdown, sarif
sarif-output agentshield-results.sarif SARIF output path when format is sarif
baseline "" Optional AgentShield baseline JSON path for drift comparison
save-baseline "" Optional path to write the current scan as a new baseline
policy "" Optional organization policy JSON path
fail-on-policy true Fail the action if the organization policy is non-compliant
supply-chain true Verify MCP npm/git package provenance and known malicious package risk
supply-chain-online false Query npm registry metadata during supply-chain verification
fail-on-supply-chain follows fail-on-findings Fail the action when supply-chain verification finds critical or high package risks
evidence-pack "" Optional directory for a portable audit evidence bundle
verify-evidence-pack true Verify evidence-pack artifact hashes after writing
policy-promotion-manifest "" Optional policy export manifest to verify and promote or dry-run
policy-promotion-pack "" Policy pack id when the manifest contains multiple packs
policy-promotion-output .agentshield/policy.json Active policy path to write when promotion dry-run is disabled
policy-promotion-dry-run true Verify promotion review evidence without writing the active policy
fail-on-policy-promotion false Fail when promotion review items still require action

Outputs: score (0–100), grade (A–F), total-findings, critical-count, sarif-path, baseline-path, baseline-status, new-findings, resolved-findings, unchanged-findings, score-delta, policy-status, policy-violations, policy-promotion-status, policy-promotion-pack, policy-promotion-review-items, policy-promotion-action-required-count, policy-promotion-digest, supply-chain-status, supply-chain-risky-packages, supply-chain-critical-count, supply-chain-high-count, package-manager-hardening-status, package-manager-hardening-findings, package-manager-hardening-critical-count, package-manager-hardening-high-count, package-manager-hardening-registry-credentials, package-manager-hardening-lifecycle-scripts, package-manager-hardening-release-age-gates, evidence-pack-path, evidence-pack-status, evidence-pack-digest

The action writes a markdown job summary and emits GitHub annotations inline on affected files. When format: sarif is set, it also writes a SARIF 2.1.0 report that can be uploaded to GitHub code scanning with github/codeql-action/upload-sarif. When baseline is set, the action appends a baseline drift summary, emits regression annotations for new findings, and reports baseline-status as passed, failed, missing, or not-run. When policy is set, the SARIF report includes organization-policy violations as agentshield-policy/* code-scanning results, appends the organization policy result to the job summary, emits policy violation annotations, and fails by default unless fail-on-policy: "false" is set. When policy-promotion-manifest is set, the action verifies the selected policy export digest, emits promotion review-item counts, appends the owner/protected-rollout/runtime-smoke review items to the job summary, and marks runtime smoke as verified when the same job also scans with the promoted policy. Supply-chain verification runs offline by default for MCP package references, appends package-risk evidence to the job summary, writes real supply-chain.json evidence packs, and fails on critical/high package risk whenever the action is in failing mode unless fail-on-supply-chain: "false" is set. Package-manager hardening outputs and job-summary evidence separately count plaintext registry credentials, lifecycle-script drift, and release-age gate drift so CI and hosted consumers can route supply-chain configuration risk even when the main finding gate is collecting evidence only.

Baseline drift gate:

- name: AgentShield Drift Gate
  uses: affaan-m/agentshield@v1
  with:
    path: "."
    baseline: ".github/agentshield-baseline.json"
    fail-on-findings: "false"

Use fail-on-findings: "false" when the workflow should fail only on drift from the baseline. Keep the default fail-on-findings: "true" when any current finding at or above min-severity should still fail the action.

CLI Reference

agentshield scan [options]         Scan configuration directory
  -p, --path <path>                Path to scan (default: ~/.claude or cwd)
  -f, --format <format>            Output: terminal, json, markdown, html, sarif
  -o, --output <path>              Write the primary report output to a file
  --fix                            Auto-apply safe fixes
  --opus                           Enable Claude Opus multi-agent analysis
  --provider <provider>            LLM provider for --opus/--injection: anthropic or orcarouter
  --stream                         Stream Opus analysis in real-time
  --injection                      Run active prompt injection testing
  --sandbox                        Execute hooks in a sandbox and observe behavior
  --taint                          Run taint analysis (data flow tracking)
  --deep                           Run injection + sandbox + taint + opus together
  --log <path>                     Write structured scan logs to a file
  --log-format <format>            Log format: ndjson or json
  --corpus                         Run built-in attack corpus benchmark
  --corpus-gate                    Fail if the built-in attack corpus regresses
  --baseline <path>                Compare against a baseline file
  --save-baseline <path>           Save current scan results as a baseline file
  --gate                           Fail on new critical/high findings or score drop
  --supply-chain                   Verify MCP package provenance and risk
  --supply-chain-online            Include npm registry metadata
  --compliance <frameworks>        Map findings to controls: soc2, pci, iso, all

  --rule-pack <path>               Load an external JSON rule pack (repeatable)
  --policy <path>                  Validate against an organization policy
  --evidence-pack <dir>            Write portable evidence bundle
  --remediation-plan <path>        Write stable-fingerprint JSON remediation plan
  --no-evidence-redact             Disable evidence-pack redaction
  --min-severity <severity>        Filter: critical, high, medium, low, info
  -v, --verbose                    Show detailed output

agentshield init                   Generate secure baseline config
agentshield baseline write         Write a scan baseline JSON file
agentshield evidence-pack fleet    Summarize multiple evidence packs for routing
agentshield evidence-pack inspect  Verify and summarize an evidence bundle
agentshield evidence-pack verify   Verify artifact and bundle digests
agentshield policy export          Export policy packs plus checksum manifest
agentshield policy init            Generate an organization policy preset
agentshield policy promote         Verify and promote an exported policy

Report footer CTA: terminal and markdown reports can append a one-line ECC Tools Pro footer. It is off by default. Set AGENTSHIELD_CTA=1 (or ECC_CTA=1) to enable it; set AGENTSHIELD_NO_CTA=1 (or ECC_NO_CTA=1) to hard-suppress it, which wins over opt-in. JSON and SARIF output never include it.

Baseline write:

agentshield baseline write --path .claude --output .github/agentshield-baseline.json
agentshield baseline write --path .claude --output baseline.json --json

The baseline command is a first-class wrapper around the existing scan baseline format. New baselines store stable hashed evidence fingerprints and omit raw evidence values, so teams can keep baseline snapshots in CI without copying token-shaped strings into long-lived artifacts. Existing raw-evidence baselines remain comparable during migration. Use it to create the accepted snapshot, then compare future scans with agentshield scan --baseline .github/agentshield-baseline.json --gate.

Runtime monitor lifecycle:

# Install the PreToolUse runtime monitor
agentshield runtime install

# Check whether the hook, policy, and log path are healthy
agentshield runtime status --check

# Back up invalid runtime files and restore a healthy install
agentshield runtime repair

Organization policy files support enterprise metadata and temporary exceptions:

agentshield policy init --pack enterprise --owner [email protected]
agentshield policy init --pack regulated --name "Acme Regulated Policy"
agentshield policy export --output-dir .github/agentshield-policies --owner [email protected]
agentshield policy export --pack ci-enforcement --name-prefix "Acme" --json
agentshield policy promote --manifest .github/agentshield-policies/manifest.json --pack ci-enforcement --output .agentshield/policy.json
agentshield policy promote --manifest .github/agentshield-policies/manifest.json --pack ci-enforcement --dry-run --json

Policy pack presets are starter baselines, not hidden SaaS policy. oss keeps public repos permissive while requiring destructive-command deny entries; team adds the runtime hook; enterprise raises score gates and blocks broad tool allowlists; regulated disallows critical/high findings and bans broader MCP/tool surfaces; high-risk-hooks-mcp focuses on hook/MCP-heavy repos; and ci-enforcement is tuned for branch-protection evidence.

Policy export writes one JSON policy file per selected pack plus a manifest.json containing SHA-256 digests. This gives platform teams a stable artifact bundle for branch-protection review, audit attachment, or downstream policy promotion without relying on generated console output.

Policy promotion is the review gate for those exported bundles. It reads the export manifest, verifies the selected policy file digest, validates the policy schema, and only then writes the active policy path. Use --dry-run --json in review workflows to prove the exact pack, source file, output path, owner list, and digest before a protected branch or operator copies the policy into place. Promotion results also include reviewItems for owner approval, protected PR rollout, and the runtime smoke test needed before enabling an enforcing CI gate.

{
  "version": 1,
  "name": "Acme Corp Security Policy",
  "policy_pack": "enterprise",
  "owners": ["[email protected]"],
  "min_score": 85,
  "max_severity": "high",
  "required_deny_list": ["Bash(rm -rf"],
  "exceptions": [
    {
      "id": "AS-EX-001",
      "rule": "required_hooks",
      "owner": "[email protected]",
      "reason": "Legacy repository migration window",
      "expires_at": "2026-06-30T23:59:59.000Z",
      "scope": "agentshield",
      "ticket": "SEC-1234"
    }
  ]
}

Policy evaluation now includes an exception lifecycle audit in terminal output and GitHub Action summaries: total exceptions, active exceptions, exceptions expiring within seven days, expired exceptions, owners, tickets, scopes, and days until expiry. This keeps temporary waivers visible in branch-protection evidence instead of letting them become silent permanent bypasses.

Exit codes:

Security Rules Summary

Category Rules Patterns Severity Range
Secrets 10 14 Critical -- Medium
Permissions 10 -- Critical -- Medium
Hooks 34 -- Critical -- Low
MCP Servers 23 -- Critical -- Info
Agents 25 -- Critical -- Info
Total 102 14

Architecture

src/
├── index.ts              CLI entry point (commander)
├── action.ts             GitHub Action entry point
├── types.ts              Type system + Zod schemas
├── scanner/
│   ├── discovery.ts      Config file discovery
│   └── index.ts          Scan orchestrator
├── rules/
│   ├── index.ts          Rule registry
│   ├── secrets.ts        Secret detection (10 rules, 14 patterns)
│   ├── permissions.ts    Permission audit (17 rules)
│   ├── mcp.ts            MCP server security (26 rules)
│   ├── hooks.ts          Hook analysis (40 rules)
│   └── agents.ts         Agent config review (41 rules)
├── reporter/
│   ├── score.ts          Scoring engine (A-F grades)
│   ├── terminal.ts       Color terminal output
│   ├── json.ts           JSON + Markdown output
│   └── html.ts           Self-contained HTML report
├── fixer/
│   ├── transforms.ts     Fix transforms (secret, permission, generic)
│   └── index.ts          Fix engine orchestrator
├── init/
│   └── index.ts          Secure config generator
└── opus/
    ├── prompts.ts        Attacker/Defender/Auditor system prompts
    ├── pipeline.ts       Three-agent Claude Opus pipeline
    └── render.ts         Opus analysis rendering

MiniClaw

MiniClaw is a minimal, sandboxed AI agent runtime bundled with AgentShield. Where typical agent platforms expose many attack surfaces (Telegram, Discord, email, community plugins), MiniClaw presents a single HTTP endpoint backed by an isolated sandbox.

# Start with secure defaults (localhost:3847, no network, safe tools only)
npx ecc-agentshield miniclaw start

# Custom configuration
npx ecc-agentshield miniclaw start --port 4000 --network localhost --rate-limit 20

Or use as a library:

import { startMiniClaw } from 'ecc-agentshield/miniclaw';

const { server, stop } = startMiniClaw();
// Listening on http://localhost:3847

MiniClaw-specific package exports and HTTP endpoints are documented in src/miniclaw/README.md and summarized in API.md. The React dashboard source lives in src/miniclaw/dashboard.tsx, but it is not yet published as a separate npm subpath.

Security Model

Four independently enforced layers:

Request → [Rate Limit] → [CORS] → [Size Cap] → [Sanitize Prompt]
                                                       ↓
                                                 [Tool Whitelist]
                                                       ↓
                                                   [Sandbox FS]
                                                       ↓
                                                 [Filter Output] → Response

HTTP API

Method Endpoint Description
POST /api/prompt Send a prompt
POST /api/session Create a sandboxed session
GET /api/session Session info
DELETE /api/session/:id Destroy session + cleanup
GET /api/events/:sessionId Security audit events
GET /api/health Health check

MiniClaw has zero external runtime dependencies — Node.js built-ins only (http, fs, path, crypto). The optional React dashboard requires React 18+ as a peer dependency.

Development

npm install          # Install dependencies
npm run dev          # Development mode
npm test             # Run tests
npm run test:coverage # Coverage report
npm run typecheck    # Type check
npm run build        # Build
npm run scan:demo    # Demo scan against vulnerable examples

Distribution

AgentShield is available through multiple channels:

Channel Use Case Install
Standalone CLI Direct scanning from your terminal npm install -g ecc-agentshield or npx ecc-agentshield scan
GitHub Action Automated security checks on PRs in CI/CD uses: affaan-m/agentshield@v1
ECC Plugin Claude Code users via the ECC skill ecosystem Install through Everything Claude Code
ECC Tools GitHub App Integrated scanning across your GitHub org Install at github.com/apps/ecc-tools
ECC Tools Pro GitHub App with automated repo analysis, Stripe billing ($19/seat/mo) Install

FAQ

What is AgentShield?

AgentShield is a security auditor for AI agent configurations. It scans Claude Code setups for hardcoded secrets, permission misconfigs, hook injection, MCP server risks, and agent prompt injection vectors.

Feature Description
Security Auditor Scans .claude/ directory for vulnerabilities
Multiple Surfaces CLI, GitHub Action, GitHub App integration
Auto-Fix Replaces hardcoded secrets with env var references
Graded Reports Security score (0-100) with findings breakdown
Opus Pipeline Three-agent adversarial analysis with Anthropic API
Evidence Pack Portable audit bundle for compliance

What can AgentShield detect?

Category Examples
Secrets Hardcoded API keys, tokens, private keys, connection strings
Permissions Overly permissive allow rules like Bash(*)
Hooks Hook injection vectors, unsafe hooks
MCP Servers MCP server risks, malicious MCP configs
Agents Agent prompt injection vectors

How to get started?

Quick Start (no install):

npx ecc-agentshield scan

Install globally:

npm install -g ecc-agentshield
agentshield scan

Auto-fix safe issues:

agentshield scan --fix

What output formats are available?

Format Use Case
Default Terminal graded security report
JSON CI pipelines and automation
HTML Executive security report
Evidence Pack Portable audit bundle for compliance

What is the Opus Pipeline?

The Opus Pipeline is a three-agent adversarial analysis that runs on Claude Opus through the Anthropic API:

  1. Attacker: hunts for exploitable weaknesses in the scanned config
  2. Defender: proposes concrete hardening for each weakness
  3. Auditor: reconciles both views into a ranked risk assessment

Usage:

agentshield scan --opus --stream

What is MiniClaw?

MiniClaw is a sandboxed agent runtime included with AgentShield:

Is AgentShield free and open source?

Yes! AgentShield is MIT licensed and free to use. Built at the Claude Code Hackathon (Cerebral Valley x Anthropic, Feb 2026).

How to contribute?

Contributions welcome! Check the repository for issues and pull requests. See CONTRIBUTING.md for guidelines.

Where to get help?

Resource Link
Repository github.com/affaan-m/agentshield
npm Package npmjs.com/package/ecc-agentshield
Changelog CHANGELOG.md
Everything Claude Code github.com/affaan-m/everything-claude-code
Twitter @affaanmustafa

License

MIT


Built by @affaanmustafa · Part of Everything Claude Code

agentshield (affaan-m/agentshield)

正在搜索数据库…

这是什么?AgentShield 是一款面向 AI 智能体配置的安全扫描器。它检查 Claude Code 配置、MCP 服务器和工具权限中的安全漏洞,并输出一份带评级的报告。
它是独立应用、代码库还是插件?它是一个命令行扫描器,也可以在 CI 中作为 GitHub Action 运行,或作为 ECC 插件使用,还可以通过 GitHub App 集成来使用。
我该如何运行第一次扫描?按照快速开始的步骤操作即可:扫描器会自动找到你的 ~/.claude/ 目录,读取所有配置文件,并输出一份带评级的安全报告。
它能发现所有问题吗?有没有已知的盲区?不能。README 承认存在一些缺口:非 shell 的 hook 执行需要更深入的语言感知分析;技能(skill)中的提示词文本,其覆盖程度不如智能体文件那样全面。
它会把我的配置文件发送到别处吗?扫描在本地进行。只有可选的 --supply-chain-online 参数会让它去查询 npm,获取软件包下载量、维护者和包龄等信息。
它能发现哪些类型的问题?包括硬编码的 API 密钥和令牌、通配符或缺失的权限拒绝列表、hook 中的命令注入、高风险的 MCP 服务器,以及 CLAUDE.md 和智能体文件中的提示词注入文本。规则总数为 268 条。
0 到 100 的分数是怎么算的?每个类别从 100 分开始,只有发现的问题会扣分:严重扣 25 分,高危扣 15 分,中危扣 5 分,低危扣 2 分,提示信息扣 0 分。已识别的防护措施会列在报告中,但不加分。
它也检查 MCP 服务器吗?检查。它有 49 条 MCP 规则,涵盖 shell 和文件系统服务器、npx -y 自动安装、MCP env 配置中的硬编码令牌,以及远程传输方式。
它和 Everything Claude Code 是什么关系?AgentShield 是 Everything Claude Code 生态的一部分。README 称该生态拥有 42K+ 星标,AgentShield 也以 ECC 插件的形式发布。
作者
affaan-m
大小
2.3 MB
星标
1.4K
时长
9个月
提交 · 90 天