agentscanner

Static security scanner for Claude Code configuration — settings, permissions, hooks, MCP servers, agents/subagents, skills, slash commands, and CLAUDE.md. Think Checkov / Terrascan, but for your .claude/ directory.

Claude Code is customized through powerful, trust-bearing artifacts: 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 without asking; a skill or CLAUDE.md is untrusted text that steers the model. Misconfigurations and malicious contributions create real risk — code execution, credential exfil, permission bypass, supply-chain compromise, and prompt injection. agentscanner finds them.

Core safety invariant

agentscanner never executes what it parses. It does not run hook commands, launch MCP servers, resolve apiKeyHelper/statusLine scripts, or fetch any URL. It reads untrusted config as data only — the moment a scanner execs its input, it becomes the vulnerability.

Install

pip install agentscanner        # or: pipx install agentscanner / uvx agentscanner

Usage

agentscanner scan .                       # scan the current repo's .claude/, .mcp.json, CLAUDE.md
agentscanner scan . --include-user        # also scan ~/.claude (user scope)
agentscanner scan . --severity-threshold HIGH
agentscanner scan . --output sarif --output-file agentscanner.sarif   # for GitHub code scanning
agentscanner scan . --fail-on HIGH        # CI gate: nonzero exit on HIGH+ findings
agentscanner list-checks                  # show the check catalog

Every resource is tagged with its scope (project / local / user / managed / plugin), so a single run cleanly covers a repo, your global config, or both.

Check catalog (v1)

See DESIGN.md for the architecture, threat model, and the verified Claude Code semantics the permission checks are grounded in. A secure baseline config lives in hardened/.

CI

GitHub Actions (SARIF upload to code scanning):

- run: pipx install agentscanner
- run: agentscanner scan . --output sarif --output-file agentscanner.sarif --soft-fail
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: agentscanner.sarif }

pre-commit:

- repo: local
  hooks:
    - id: agentscanner
      name: agentscanner
      entry: agentscanner scan . --fail-on HIGH
      language: system
      pass_filenames: false

Prior art & license

Inspired by awesome-claude-security (used as inspiration and as a corpus to scan, not as a source of rule text). All rules are independently authored. License: Apache-2.0.