The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add AgentShield security-scan skill and README integration
Affaan Mustafa77be80c69bdf
diff --git a/README.md b/README.mdindex 48b7137a8..e439549a5 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 v2The instinct-based learning system automatically learns your patterns:diff --git a/skills/security-scan/SKILL.md b/skills/security-scan/SKILL.mdnew file mode 100644index 000000000..8a0c6f138--- /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)