Security Scan Skill

Audit your Claude Code configuration for security issues using AgentShield.

When to Activate

• Setting up a new Claude Code project

• After modifying .claude/settings.json, CLAUDE.md, or MCP configs

• Before committing configuration changes

• When onboarding to a new repository with existing Claude Code configs

• Periodic security hygiene checks

What It Scans

File

Checks

CLAUDE.md

Hardcoded secrets, auto-run instructions, prompt injection patterns

settings.json

Overly permissive allow lists, missing deny lists, dangerous bypass flags

mcp.json

Risky MCP servers, hardcoded env secrets, npx supply chain risks

hooks/

Command injection via interpolation, data exfiltration, silent error suppression

agents/*.md

Unrestricted tool access, prompt injection surface, missing model specs

Prerequisites

AgentShield must be installed. Check and install if needed:

# Check if installed

npx ecc-agentshield --version

# Install globally (recommended)

npm install -g ecc-agentshield

# Or run directly via npx (no install needed)

npx ecc-agentshield scan .

Usage

Basic Scan

Run against the current project's .claude/ directory:

# Scan current project

npx ecc-agentshield scan

# Scan a specific path

npx ecc-agentshield scan --path /path/to/.claude

# Scan with minimum severity filter

npx ecc-agentshield scan --min-severity medium

Output Formats

# Terminal output (default) — colored report with grade

npx ecc-agentshield scan

# JSON — for CI/CD integration

npx ecc-agentshield scan --format json

# Markdown — for documentation

npx ecc-agentshield scan --format markdown

# HTML — self-contained dark-theme report

npx ecc-agentshield scan --format html > security-report.html

Auto-Fix

Apply safe fixes automatically (only fixes marked as auto-fixable):

npx ecc-agentshield scan --fix

This will:

• Replace hardcoded secrets with environment variable references

• Tighten wildcard permissions to scoped alternatives

• Never modify manual-only suggestions

Opus 4.6 Deep Analysis

Run the adversarial three-agent pipeline for deeper analysis:

# Requires ANTHROPIC_API_KEY

export ANTHROPIC_API_KEY=your-key

npx ecc-agentshield scan --opus --stream

This runs:

• Attacker (Red Team) — finds attack vectors

• Defender (Blue Team) — recommends hardening

• Auditor (Final Verdict) — synthesizes both perspectives

Initialize Secure Config

Scaffold a new secure .claude/ configuration from scratch:

npx ecc-agentshield init

Creates:

• settings.json with scoped permissions and deny list

• CLAUDE.md with security best practices

• mcp.json placeholder

GitHub Action

Add to your CI pipeline:

- uses: affaan-m/agentshield@v1

  with:

    path: '.'

    min-severity: 'medium'

    fail-on-findings: true

Severity Levels

Grade

Score

Meaning

A

90-100

Secure configuration

B

75-89

Minor issues

C

60-74

Needs attention

D

40-59

Significant risks

F

0-39

Critical vulnerabilities

Interpreting Results

Critical Findings (fix immediately)

• Hardcoded API keys or tokens in config files

• Bash(*) in the allow list (unrestricted shell access)

• Command injection in hooks via ${file} interpolation

• Shell-running MCP servers

High Findings (fix before production)

• Auto-run instructions in CLAUDE.md (prompt injection vector)

• Missing deny lists in permissions

• Agents with unnecessary Bash access

Medium Findings (recommended)

• Silent error suppression in hooks (2>/dev/null, || true)

• Missing PreToolUse security hooks

• npx -y auto-install in MCP server configs

Info Findings (awareness)

• Missing descriptions on MCP servers

• Prohibitive instructions correctly flagged as good practice

Links

• GitHub: github.com/affaan-m/agentshield

• npm: npmjs.com/package/ecc-agentshield