Skip to content

armgit / ECC

Public Imported from GitHub
0

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.md
index 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 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 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)