# AgentShield

> Security auditor for AI agent configurations that scans Claude Code setups for hardcoded secrets, permission misconfigs, hook injection, MCP server risks, and prompt injection vectors.

AgentShield is an MIT-licensed, open-source security scanner built specifically for AI agent configurations, with a focus on Claude Code setups. Created by Affaan Mustafa at the Claude Code Hackathon (Cerebral Valley × Anthropic, February 2026), it is available as a CLI tool, GitHub Action, ECC plugin, and GitHub App integration.

## What It Is

AgentShield scans your `.claude/` directory and flags security vulnerabilities before they become exploits. It covers 268 rules across 15 modules — secrets detection, permission auditing, hook analysis, MCP server security, and agent config review — and produces a graded security report (A–F, 0–100 numeric score). The tool is designed to fill a gap the README describes as the AI agent ecosystem growing faster than its security tooling.

## What It Catches

AgentShield's rule engine spans five major categories:

- **Secrets Detection** — Hardcoded API keys (Anthropic, OpenAI, xAI, AWS, Google, Stripe), GitHub PATs, JWTs, database connection strings, and environment variable leaks
- **Permission Audit (17 rules)** — Wildcard access like `Bash(*)`, missing deny lists, dangerous flags like `--dangerously-skip-permissions`, unrestricted network commands
- **Hook Analysis (40 rules)** — Command injection via `${file}` interpolation, data exfiltration hooks, silent error suppression, reverse shells, clipboard access, container escape patterns
- **MCP Server Security (49 rules)** — High-risk server types, supply-chain risks from `npx -y` auto-install, hardcoded secrets in MCP env config, remote transport exposure, auto-approve settings
- **Agent Config Review (41 rules)** — Unrestricted tool access, prompt injection surfaces, hidden Unicode instructions, URL execution directives, jailbreak patterns

Recognized defenses (deny lists, sandbox settings, blocking PreToolUse hooks) are credited in every report and never penalized.

## Architecture and Distribution

The scanner is written in TypeScript and structured around a discovery layer, a rule registry, a scoring engine, and multiple output reporters. It ships through four channels:

- **Standalone CLI** — `npx ecc-agentshield scan` or global install via npm
- **GitHub Action** — `uses: affaan-m/agentshield@v1` with SARIF output, baseline drift gating, and organization policy enforcement
- **ECC Plugin** — Integration through the Everything Claude Code skill ecosystem
- **ECC Tools GitHub App** — Org-wide scanning; a Pro tier with automated repo analysis is also available

Output formats include terminal, JSON, Markdown, HTML executive reports, SARIF for GitHub code scanning, portable evidence packs, and remediation plan JSON files.

## Claude Opus Deep Analysis Pipeline

The `--opus` flag activates a three-agent adversarial pipeline powered by Claude Opus:

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 pipeline runs Red and Blue in parallel by default, or sequentially with `--stream` for real-time output. It requires an `ANTHROPIC_API_KEY` and can also route through OrcaRouter as an alternative provider.

## MiniClaw: Sandboxed Agent Runtime

Bundled with AgentShield, MiniClaw is a minimal sandboxed AI agent runtime that exposes a single HTTP endpoint backed by an isolated sandbox. It enforces four independently layered controls: rate limiting and CORS at the server level, a prompt router that strips 12+ injection pattern categories, a three-tier tool whitelist (Safe/Guarded/Restricted), and a sandboxed filesystem with path traversal blocking and symlink escape detection. MiniClaw has zero external runtime dependencies beyond Node.js built-ins.

## Update: AgentShield v1.6.0

The latest release is v1.6.0, published September 10, 2026. The repository was last updated September 24, 2026, and has accumulated 1,219 stars and 268 forks since its February 2026 creation at the Claude Code Hackathon. Recent development has focused on `runtimeConfidence` labeling for MCP findings, score-weighted discounting for template/example findings, supply-chain verification with npm registry metadata, compliance mapping to SOC 2, PCI DSS, and ISO 27001, and an organization policy gate with export/promote workflows for enterprise CI enforcement.

## Features
- 268 security rules across 15 modules
- Secrets detection for API keys, tokens, and credentials
- Permission audit with 17 rules
- Hook analysis with 40 rules
- MCP server security with 49 rules
- Agent config review with 41 rules
- A-F graded security reports with 0-100 numeric score
- Auto-fix engine for safe issues
- Claude Opus three-agent adversarial pipeline
- GitHub Action with SARIF output
- Baseline drift gating
- Organization policy enforcement
- Compliance mapping to SOC 2, PCI DSS, ISO 27001
- Supply-chain verification for MCP packages
- External rule packs support
- MiniClaw sandboxed agent runtime
- Multiple output formats: terminal, JSON, Markdown, HTML, SARIF
- Portable evidence packs for audits
- Remediation plan JSON files
- runtimeConfidence labeling for findings
- Secure baseline config generator

## Integrations
Claude Code, Anthropic API, GitHub Actions, GitHub App, OrcaRouter, npm, Everything Claude Code (ECC), ECC Tools, SARIF / GitHub Code Scanning, Linear, SOC 2, PCI DSS, ISO 27001

## Platforms
MACOS, WEB, API, VSC_EXTENSION, DEVELOPER_SDK, CLI

## Pricing
Open Source, Free tier available

## Version
v1.6.0

## Links
- Website: https://cerebralvalley.ai/e/claude-code-hackathon
- Documentation: https://github.com/affaan-m/agentshield/blob/main/API.md
- Repository: https://github.com/affaan-m/agentshield
- EveryDev.ai: https://www.everydev.ai/tools/agentshield