Agentshield Security Scanner

AgentShield Security Scanner

102-rule scanner for Claude Code agent configurations, MCP servers, hooks, and agent definitions. Built at Claude Code Hackathon (Feb 2026).

Trigger phrases: "scan agent config", "agentshield", "audit .claude/", "check MCP security", "hook injection", "agent permission audit", "secrets in config", "agent security scan"

When to Use

• Before merging any changes to .claude/settings.json, hooks, or MCP config
• After importing skills or agents from external repos
• CI gate on every PR touching agent configuration
• Before deploying to production Claude Code environment

5 Detection Categories (102 rules total)

1. Secrets (10 rules)

Detects: Anthropic keys (sk-ant-*), OpenAI (sk-proj-*), GitHub (ghp_*), AWS (AKIA*), Stripe, JWT tokens, private keys, DB connection strings, base64-obfuscated credentials.

# False positive filtering: env var refs ${VAR}, markdown fences, example contexts

2. Permissions (10 rules)

Detects:

• Wildcard allows: Bash(*), Write(*), Edit(*)
• Dangerous bypasses: dangerously-skip-permissions, --no-verify
• Destructive git: push --force, reset --hard, clean -f
• Sensitive paths: /etc/, ~/.ssh/, ~/.aws/
• Missing deny list entirely

3. Hooks (34 rules)

Injection patterns (CRITICAL):

• Variable interpolation in attacker-controllable context: ${file|command|content|input}
• Shell injection: sh -c with variable expansion
• curl/wget interpolation (data exfiltration)

HIGH: reverse shells, SSH key manipulation, credential store access, log tampering

MEDIUM: silent error suppression (2>/dev/null), 3+ chained shell commands, env var mutations

4. MCP Server Security (23 rules)

Risk levels:

• CRITICAL: Shell/command execution servers
• HIGH: Filesystem, browser automation, database servers
• MEDIUM: Messaging services (Slack, Discord, email)

Checks:

• npx -y (auto-install without review)
• Unrestricted filesystem paths (/, ~)
• PATH, LD_PRELOAD, NODE_OPTIONS overrides
• Unversioned npm packages, git URL deps

5. Agent Definitions (25 rules)

• Unrestricted tool combos: Bash + Write + Read = full system access
• Prompt injection patterns: "ignore previous instructions", role reassignment, jailbreak framing
• Hidden instructions: zero-width Unicode, bidirectional text, base64 obfuscation
• Supply chain: URL-based instruction loading, unsigned skill imports

CLI Usage

# Install
npm install -g ecc-agentshield

# Scan current project
agentshield scan .

# Output formats
agentshield scan . --format json        # machine-readable
agentshield scan . --format sarif       # GitHub Code Scanning
agentshield scan . --format html        # executive report
agentshield scan . --format markdown    # PR comment

# Auto-fix safe findings
agentshield scan . --fix

# Deep Opus analysis (3-agent attacker/defender/auditor pipeline)
agentshield scan . --opus

# Supply chain verification (MCP package provenance)
agentshield scan . --supply-chain

# Generate secure baseline config
agentshield init

# Continuous monitoring
agentshield watch .

Output Format

{
  "findings": [{
    "id": "HOOK-INJECT-001",
    "severity": "critical",
    "category": "hooks",
    "title": "Shell injection via variable interpolation",
    "file": ".claude/hooks/pre-commit.sh",
    "line": 12,
    "runtimeConfidence": "active-runtime",
    "fix": {
      "description": "Quote the variable",
      "before": "eval $INPUT",
      "after": "eval \"$INPUT\"",
      "auto": false
    }
  }],
  "score": 72,
  "grade": "C",
  "summary": { "critical": 1, "high": 2, "medium": 4, "low": 1 }
}

Score 0–100, grade A–F based on finding counts.

GitHub Actions Integration

- uses: affaan-m/agentshield@v1
  with:
    path: "."
    format: "sarif"
    fail-on-findings: "true"
  permissions:
    contents: read
    security-events: write

YAMTAM Integration

agentshield complements strix-scan.sh:

Anti-Fake-Pass

❌ Skipping scan "because it's just a config change"
❌ Trusting auto-fix blindly — review before applying
❌ Not running --supply-chain when adding new MCP servers
❌ Ignoring MEDIUM findings — hook chaining can escalate
❌ One-time scan instead of CI gate