AgentShield is a security scanner for AI agent configurations. It discovers a .claude/ directory, scans the configuration files in it, and prints a graded report — a letter grade from A to F and a 0–100 score, broken down by category, with each finding carrying a file, line, evidence excerpt, and suggested fix. Discovery skips generated directories such as node_modules and build output so transient copies do not duplicate findings.
The rule set covers 102 rules in five categories: secrets (10 rules over 14 patterns, spanning provider API keys, tokens, credentials, and environment leaks), permissions (10 rules, such as wildcard tool grants and missing deny lists), hooks (34 rules, covering command injection through interpolated filenames, exfiltration, silent failures, container escape, reverse shells, and log tampering), MCP servers (23 rules, covering high-risk server types, npx -y auto-install, remote transports, and auto-approval), and agent configuration (25 rules, covering unrestricted tools, prompt-injection surface, hidden instructions, and output manipulation).
Findings carry a runtimeConfidence label separating active runtime configuration from project-local settings, template and documentation examples, plugin caches, plugin manifests, and manifest-resolved hook code. Scoring discounts the lower-confidence kinds — 0.25x for template and docs examples, 0.5x for plugin cache and manifest, 0.75x for project-local — and caps a single template file at 10 deduction points per category, while real secrets stay critical wherever they appear.
Beyond the default scan, AgentShield can auto-apply the fixes marked safe, generate a hardened starting configuration, run a three-agent adversarial pipeline (red team, blue team, auditor) that requires an Anthropic API key, and verify MCP package provenance against npm and git, with an online mode that queries the registry for downloads, maintainers, postinstall scripts, deprecation, and package age.
Output formats are terminal, JSON, Markdown, HTML, and SARIF 2.1.0, plus an evidence pack whose redacted manifest records SHA-256 digests and byte counts, and a remediation plan of findings with stable hashed fingerprints. The GitHub Action wraps the same scan with baseline drift comparison, policy gating, and inline annotations. A separate component, MiniClaw, is a sandboxed agent runtime exposing one HTTP endpoint behind rate limiting, prompt sanitisation, a three-tier tool whitelist, and a per-session isolated filesystem.
Features
- Graded scan: A–F grade and 0–100 score with per-category breakdown across secrets, permissions, hooks, MCP servers, and agents
- 102 rules: secret patterns, permission audit, hook analysis, MCP server security, and agent configuration review
- Confidence labelling: runtime, project-local, template, docs, plugin-cache, plugin-manifest, and hook-code sources scored at different weights
- Auto-fix: --fix replaces hardcoded secrets with environment-variable references and tightens wildcard permissions
- Adversarial analysis: --opus runs attacker, defender, and auditor passes into a prioritised risk assessment
- Supply-chain checks: MCP package provenance, npm registry metadata, and package-manager hardening
- Output formats: terminal, JSON, Markdown, HTML, SARIF, evidence pack, and remediation plan
- Evidence packs: deterministic bundles with digest manifests and redaction, plus verify, inspect, and fleet commands
- Baselines and gates: save a baseline, compare later scans, and fail on new critical or high findings
- Organization policy: validate against a policy file, export policy packs, and promote them with review evidence
- GitHub Action: scan on pull requests with annotations, job summary, SARIF upload, and policy or drift gating
- MiniClaw runtime: sandboxed agent behind one HTTP endpoint, with rate limiting, prompt sanitisation, tool tiers, and no external runtime dependencies
