/security-scan

description: Run AgentShield against agent, hook, MCP, permission, and secret surfaces.
agent: ecc:security-reviewer
subtask: true

Security Scan Command

Run AgentShield against the current project or a target path, then turn the findings into a prioritized remediation plan.

Usage

`/security-scan [path] [--format text|json|markdown|html] [--min-severity low|medium|high|critical] [--fix]`

• `path` (optional): defaults to the current project. Use a `.claude/` path, a repo root, or a checked-in template directory.
• `--format`: output format. Use `json` for CI, `markdown` for handoffs, and `html` for standalone review reports.
• `--min-severity`: filters lower-priority findings.
• `--fix`: applies only AgentShield fixes explicitly marked as safe and auto-fixable.

Deterministic Engine

Prefer the packaged scanner:

npx ecc-agentshield scan --path "${TARGET_PATH:-.}" --format text

For local AgentShield development, run from the AgentShield checkout:

npm run scan -- --path "${TARGET_PATH:-.}" --format text

Do not invent findings. Use AgentShield output as the source of truth and separate scanner facts from follow-up judgment.

Review Checklist

1. Identify active runtime findings first:

• hardcoded secrets
• broad permissions
• executable hooks
• MCP servers with shell, filesystem, remote transport, or unpinned `npx`
• agent prompts that handle untrusted content without defenses

2. Separate lower-confidence inventory:

• docs examples
• template examples
• plugin manifests
• project-local optional settings

3. For each critical or high finding, return:

• file path
• severity
• runtime confidence
• why it matters
• exact remediation
• whether it is safe to auto-fix

4. If `--fix` is requested, state the planned edits before applying fixes. 5. Re-run the scan after fixes and report the before/after score.

Output Contract

Return:

1. Security grade and score. 2. Counts by severity and runtime confidence. 3. Critical/high findings with exact paths. 4. Lower-confidence findings grouped separately. 5. A remediation order. 6. Commands run and whether the scan was local, CI, or npx-backed.

CI Pattern

Use AgentShield in GitHub Actions for enforced gates:

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

Links

• Skill: `skills/security-scan/SKILL.md`
• Agent: `agents/security-reviewer.md`
• Scanner: <https://github.com/affaan-m/agentshield>

Arguments

$ARGUMENTS:

• optional target path
• optional AgentShield flags