/skill

Security Scan

Use AgentShield to check Claude Code setup files.

AgentShield was made by affaan-m. Full credit goes to the author and project team.

When to use this skill

Use it:

• When you set up a Claude Code project
• After you change CLAUDE.md, .claude/settings.json, hooks, agents, or MCP settings
• Before you commit setup changes
• When you join a project that already has Claude Code files
• During a regular safety check

What to scan

Also check user-level files if they are in scope. Do not scan files outside the path the user asked for.

Before the scan

1. Find the project root.
2. Check that the target path exists.
3. Check whether AgentShield is installed:

npx ecc-agentshield --version

If the command is not available, ask before installing it. Do not install tools without clear approval.

Install it with:

npm install -g ecc-agentshield

Or run it once with npx:

npx ecc-agentshield scan .

Note that npx may fetch and run code from npm. Tell the user before the first use.

Scan steps

1. Run a basic scan

From the project root:

npx ecc-agentshield scan

For one Claude Code folder:

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

Show only medium or higher issues:

npx ecc-agentshield scan --min-severity medium

If the project has more than one .claude/ folder, scan each one. Do not assume the root folder covers all workspaces.

2. Pick an output form

Use the normal terminal report for a local check:

npx ecc-agentshield scan

Use JSON for scripts:

npx ecc-agentshield scan --format json

Use Markdown for a report:

npx ecc-agentshield scan --format markdown

Use HTML for a local web report:

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

Reports may contain file names, commands, or secret-like text. Do not commit or share a report until you check it.

3. Review each result

For every issue:

1. Open the named file and line.
2. Check that the result is real.
3. Rate its harm and reach.
4. Give the smallest safe fix.
5. Mark false alarms as such. Do not hide them without a reason.

Never print a full key, token, cookie, or password. Mask all but a few safe chars.

4. Apply fixes with care

AgentShield can apply fixes that it marks as safe:

npx ecc-agentshield scan --fix

Before using --fix:

• Ask for approval.
• Make sure work can be restored with Git or a backup.
• Note any work that is not yet saved.
• Do not run it on a path with unknown files.

After using --fix:

1. Review every file change.
2. Run the scan again.
3. Run any project tests that cover the changed files.
4. Do not claim an issue is fixed until the new scan confirms it.

Auto-fix may:

• Replace saved secrets with environment variable names
• Narrow wildcard access
• Leave hard fixes for manual review

It may miss custom file forms or break a setup that needs wide access. Review all changes.

Deep scan

A deep scan uses an Anthropic API key:

export ANTHROPIC_API_KEY=your-key
npx ecc-agentshield scan --opus --stream

Use this only when the user asks for it and the key is already set in a safe place. Never put a real key in a command, file, log, chat, or report.

The deep scan uses three roles:

1. Attacker: Looks for ways to break the setup
2. Defender: Gives safer rules
3. Reviewer: Checks both views and gives a final result

Treat model findings as leads. Check each one in the real files.

Create a safe setup

For a new project only:

npx ecc-agentshield init

This may create:

• settings.json with narrow access and deny rules
• CLAUDE.md with safe use rules
• An MCP settings file

Do not run init over an existing setup until you know which files it may replace. Save or commit current work first.

GitHub Actions

Add this step only when the user asks for a CI check:

- uses: affaan-m/agentshield@v1
  with:
    path: "."
    min-severity: "medium"
    fail-on-findings: true

Pin the action to a trusted release or full commit ID when the project rules require it. Check that the path matches the real project root.

Grades

A high grade does not prove the setup is safe. A scan can miss new or custom risks.

Issue order

Fix issues in this order.

Critical

Fix now:

• API keys or tokens saved in setup files
• Bash(*) or other full shell access
• Hook input placed into a shell command without safe checks
• MCP servers that can run any shell command

If a secret is found, removing it from the file is not enough. Revoke it, make a new one, and check Git history.

High

Fix before real use:

• Rules that tell Claude to run commands without review
• Missing deny rules
• Agents with shell access they do not need

Medium

Fix when you can:

• Hidden hook errors such as 2>/dev/null or || true
• Missing PreToolUse safety hooks
• MCP servers that use npx -y and fetch code on run

Info

Review and note:

• MCP servers with no clear note about their job
• Safe deny rules that the scan lists as good practice

Edge cases

• If no Claude Code files exist, report that there was nothing to scan.
• If a file cannot be read, name it and say the scan was not complete.
• If a path is a link, show where it points before scanning it.
• If generated files cause repeat alerts, fix the source file first.
• If a needed rule looks risky, explain why it is needed and narrow its scope.
• If the scan tool fails, report the command, safe error text, and exit code. Do not call the project safe.
• If a result is unclear, do not auto-fix it.

Example

A user asks: “Check this project before I commit my Claude settings.”

Run:

npx ecc-agentshield scan --path .claude --min-severity medium

Then report:

Scan result: C, 3 issues

Critical:
- .claude/settings.json allows Bash(*).
  Fix: allow only the few commands this project needs.

High:
- .claude/hooks/check.sh puts file input into a shell command.
  Fix: pass the file as a quoted argument and check its path.

Medium:
- .claude/mcp.json uses npx -y with no fixed package version.
  Fix: use a reviewed, fixed version.

No files were changed.

Ask before running --fix.

Links

• Author and source: affaan-m/agentshield
• npm package: ecc-agentshield