security-scan

Use it when:: You set up or change a .claude/ directory, onboard to a repo with Claude Code configs, or want a periodic security check.
It does:: Runs AgentShield over CLAUDE.md, settings.json, mcp.json, hooks and agent files, and grades the setup from A to F.
You get:: Findings ranked critical, high, medium and info, in the terminal or as JSON, Markdown or a standalone HTML report.
Can also:: Auto-fix safe issues, scaffold a locked-down .claude/ setup, or add a GitHub Action that fails CI on findings.
Unlike ECC's security-review:: That one is a checklist for writing app code; this one audits the agent's own configuration.
Needs:: Node to run the ecc-agentshield package; an Anthropic API key only for the --opus deep analysis.

Runs AgentShield through npx or a global npm install. The optional --opus deep analysis needs your Anthropic API key, so your configuration goes to Anthropic's API.

TL;DR

AgentShield is a scanner for Claude Code configuration by ECC's own author, and this skill is how the agent runs it. It checks CLAUDE.md for hardcoded secrets, auto-run instructions and prompt-injection patterns; settings.json for overly broad allow lists, missing deny lists and bypass flags; mcp.json for risky servers, secrets in env and npx supply-chain risk; hooks for command injection, data exfiltration and silenced errors; and agent definitions for unrestricted tool access. The score maps to a grade from A (90 to 100) to F (under 40). Critical findings include API keys in config, Bash(*) in the allow list and shell-running MCP servers; high ones include missing deny lists; medium ones include `|| true` in hooks and `npx -y` in MCP configs. `--fix` replaces hardcoded secrets with environment variable references and narrows wildcard permissions, leaving manual-only items alone. `init` writes a fresh settings.json, CLAUDE.md and placeholder mcp.json. `--opus` runs three agents in turn, an attacker, a defender and an auditor, for a deeper verdict.

Summarizes the skill at d2ef268.

npx skills add https://github.com/affaan-m/ecc --skill security-scan

skills.sh page Source on GitHub All skills from affaan-m/ecc

Total Downloads: 5,700 on skills.sh, Nov 9, 2026
Repo stars: 299,776 affaan-m/ecc
First seen: May 19, 2026 on skills.sh

Weekly Downloads

471

+78% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	264
Sep 28	183
Oct 5	158
Oct 12	251
Oct 19	446
Oct 26	436
Nov 2	499
Nov 9	471

Category	category:security category:software-engineering Compliance, guardrails, skill vetting and browser fingerprinting. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:tool Operates a CLI, API, app or bundled script to get something done.
Effect	effect:local Its own steps create or change files, git state or local tools.
Needs	needs:cli A specific command-line tool or desktop app must be installed, such as gh, agent-browser, LibreOffice, Obsidian or a vendor CLI.
Publisher	by:official A verified publisher on skills.sh, or the company or maintainer behind the product the skill operates.
Topics	security guardrails
Stack	stack:agentshield stack:claude

SKILL.md

From affaan-m/ecc at d2ef268. Checked daily, last changed Nov 6, 2026.

Frontmatter

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. Use when auditing a .claude/ directory — CLAUDE.md, settings.json, MCP servers, hooks, or agent definitions.
metadata:
  origin: ECC

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