/config-security-scan

name: config-security-scan
description: >-
  Statically review a Claude Code / AI-agent setup for security misconfigurations
  — risky hooks, over-broad permissions, untrusted or cleartext MCP servers,
  hardcoded secrets, endpoint redirection, over-privileged agents/skills, and
  prompt-injection in steering files. Use when asked to audit a `.claude/`
  directory, `settings.json`, `.mcp.json`, a plugin/marketplace, or `CLAUDE.md`,
  or to add a config-security gate to CI. Drives the `agentscanner` CLI.

Goal

A triaged, prioritized view of the security risks in a Claude Code configuration — the trust-bearing artifacts that steer the agent and run code on its behalf — with each real finding confirmed against the offending line and a concrete fix, plus a hardening path so the issue does not recur.

Why this matters

A hook is arbitrary code that runs on every tool call; an MCP server is an arbitrary process; a permission rule decides what the agent may do un-prompted; a skill or `CLAUDE.md` is untrusted text that steers the model. Misconfigurations and malicious contributions in these files create real risk — code execution, credential exfil, permission bypass, supply-chain compromise, and prompt injection. This skill scans for them **without ever executing what it parses** (agentscanner reads config as data only — see `reference.md`).

Steps

1. **Ensure the tool is available** — `agentscanner` is a published PyPI package (Apache-2.0), independent of this marketplace. Prefer `uvx agentscanner …` (no install) or `pipx install agentscanner`. See `reference.md` for invocation, scopes, and CI wiring. Do not vendor or reimplement it. 2. **Scope the scan** — decide what to cover: the repo's project config (`.claude/`, `.mcp.json`, `CLAUDE.md`), the user scope (`~/.claude`, via `--include-user`), or a plugin/marketplace tree. Each finding is tagged with its scope (project / local / user / managed / plugin). Note: the scan `PATH` is a **repo root** — always point it at the directory that *contains* `.claude/` / `plugins/`, never a bare subdirectory (see `reference.md`), or discovery silently finds nothing. 3. **Run the scanner** — `agentscanner scan <repo-root>` (add `--output sarif --output-file agentscanner.sarif` for code scanning, `--fail-on HIGH` for a CI gate). Run `agentscanner list-checks` for the authoritative, current catalog of checks and severities — treat that output as the source of truth, not memory. 4. **Triage each finding** — open the cited `file:line` and confirm it. Is the broad `Bash(*)` allow intentional? Is the MCP `env` secret a real key or a placeholder? Is the `bypassPermissions` mode deliberate and scoped? Classify true positive / false positive / accepted-risk, and suppress accepted ones via the documented ignore mechanism rather than lowering the bar globally. 5. **Remediate** — give the specific fix: scope an over-broad permission, move a secret to a helper/env reference, pin an MCP package, switch a remote MCP to HTTPS, drop an over-privileged agent's `tools: *`, or remove injected steering. 6. **Harden** — point to a secure baseline (`agentscanner`'s `hardened/` reference settings) so the config is correct by construction, and propose a CI gate so regressions are caught on every change.

Output

A triaged findings table: check-id · severity · scope · `file:line` · what it catches · TP/FP/accepted · fix. Confirmed issues → `security-reporting:finding` (and SARIF for GitHub code scanning). Recommend a CI gate (`--fail-on HIGH`) and the hardened baseline as the durable follow-up.

Notes

• **Categories you'll see** (run `list-checks` for specifics): hooks (remote-code

execution, unsafe paths, network calls, missing timeouts), permissions (bypass modes, over-broad `Bash`, unscoped dangerous commands), MCP (plaintext secrets, cleartext `http://`, auto-trust-all, unpinned packages), env (endpoint/ token redirection away from Anthropic), secrets, agents/skills (over-privilege, risk-tier spoofing, missing signatures), and prompts (injection/hidden-unicode in steering files).

• This complements, not replaces: `sast-sca` scans your application source;

`supply-chain-security` covers dependency provenance; `agentic-ai-security` secures agents you *build*. This skill secures the Claude Code **setup itself**.

• The scanner is static and read-only; reachability/intent still need human triage,

so always confirm at the cited line before reporting.