From 77be80c69bdf6abbdddb0dd51a787c19e0f5524b Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Wed, 11 Feb 2026 03:27:07 -0800 Subject: [PATCH] feat: add AgentShield security-scan skill and README integration New skill: /security-scan wraps ecc-agentshield to audit .claude/ configs for vulnerabilities, misconfigs, and injection risks. Covers: CLAUDE.md secrets, settings.json permissions, MCP server risks, hook injection, agent tool restrictions. Produces A-F security grade. Also adds AgentShield section to Ecosystem Tools in README with links to GitHub repo and npm package. --- README.md | 25 ++++++ skills/security-scan/SKILL.md | 164 ++++++++++++++++++++++++++++++++++ 2 files changed, 189 insertions(+) create mode 100644 skills/security-scan/SKILL.md diff --git a/README.md b/README.md index 48b7137..e439549 100644 --- a/README.md +++ b/README.md @@ -229,6 +229,7 @@ everything-claude-code/ | |-- springboot-tdd/ # Spring Boot TDD (NEW) | |-- springboot-verification/ # Spring Boot verification (NEW) | |-- configure-ecc/ # Interactive installation wizard (NEW) +| |-- security-scan/ # AgentShield security auditor integration (NEW) | |-- commands/ # Slash commands for quick execution | |-- tdd.md # /tdd - Test-driven development @@ -345,6 +346,30 @@ Both options create: - **Instinct collections** - For continuous-learning-v2 - **Pattern extraction** - Learns from your commit history +### AgentShield — Security Auditor + +Scan your Claude Code configuration for vulnerabilities, misconfigurations, and injection risks. + +```bash +# Quick scan (no install needed) +npx ecc-agentshield scan + +# Auto-fix safe issues +npx ecc-agentshield scan --fix + +# Deep analysis with Opus 4.6 +npx ecc-agentshield scan --opus --stream + +# Generate secure config from scratch +npx ecc-agentshield init +``` + +Checks CLAUDE.md, settings.json, MCP servers, hooks, and agent definitions. Produces a security grade (A-F) with actionable findings. + +Use `/security-scan` in Claude Code to run it, or add to CI with the [GitHub Action](https://github.com/affaan-m/agentshield). + +[GitHub](https://github.com/affaan-m/agentshield) | [npm](https://www.npmjs.com/package/ecc-agentshield) + ### 🧠 Continuous Learning v2 The instinct-based learning system automatically learns your patterns: diff --git a/skills/security-scan/SKILL.md b/skills/security-scan/SKILL.md new file mode 100644 index 0000000..8a0c6f1 --- /dev/null +++ b/skills/security-scan/SKILL.md @@ -0,0 +1,164 @@ +--- +name: security-scan +description: Scan your Claude Code configuration (.claude/ directory) for security vulnerabilities, misconfigurations, and injection risks using AgentShield. Checks CLAUDE.md, settings.json, MCP servers, hooks, and agent definitions. +--- + +# Security Scan Skill + +Audit your Claude Code configuration for security issues using [AgentShield](https://github.com/affaan-m/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: + +```bash +# 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: + +```bash +# 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 + +```bash +# 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): + +```bash +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: + +```bash +# Requires ANTHROPIC_API_KEY +export ANTHROPIC_API_KEY=your-key +npx ecc-agentshield scan --opus --stream +``` + +This runs: +1. **Attacker (Red Team)** — finds attack vectors +2. **Defender (Blue Team)** — recommends hardening +3. **Auditor (Final Verdict)** — synthesizes both perspectives + +### Initialize Secure Config + +Scaffold a new secure `.claude/` configuration from scratch: + +```bash +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: + +```yaml +- 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](https://github.com/affaan-m/agentshield) +- **npm**: [npmjs.com/package/ecc-agentshield](https://www.npmjs.com/package/ecc-agentshield)