| 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
