AgentShield CLI
AgentShield audits the .claude folder for plaintext keys, broad permissions, dangerous hooks and risky MCP servers and grades the setup from A to F
- 1,317 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The scanner reads agent configuration, including files that may hold keys, and the --fix flag rewrites those files
- The --opus mode sends configuration data to the Anthropic API, and the --supply-chain-online option queries the npm registry
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/agentshieldDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The scanner reads agent configuration, including files that may hold keys, and the --fix flag rewrites those files
- The --opus mode sends configuration data to the Anthropic API, and the --supply-chain-online option queries the npm registry
This is third-party code. Review the repository files before installing.
What it does
AgentShield is a security scanner for AI agent setups, primarily Claude Code. The npx ecc-agentshield scan command finds the ~/.claude directory by itself, reads the config files and prints a report with a 0 to 100 score and an A to F grade. Findings are grouped into secrets, permissions, hooks, MCP servers and agents, and each lists the file, line, evidence and a fix. The rule set covers Anthropic, OpenAI and AWS keys in plaintext, allow rules such as Bash(*), the --dangerously-skip-permissions flag, command injection through ${file} interpolation in hooks, npx -y without confirmation, binding to 0.0.0.0 and autoApprove in MCP settings. The --fix flag swaps secrets for environment variable references and rescans afterwards, rolling the edits back if the score drops. agentshield init creates a hardened .claude directory with scoped permissions and safety hooks without overwriting existing files. For CI there is a GitHub Action with a severity threshold, SARIF output and baseline comparison. The --opus mode runs three roles through the Anthropic API: attacker, defender and auditor. --supply-chain turns on package provenance checks, and reports can add SOC 2 mapping.
Who it is for. For developers and teams that connect third-party skills, MCP servers and hooks to Claude Code and want to check that configuration before use or in CI.
Good fit when
- You have piled up dozens of skills, hooks and MCP servers in ~/.claude and want to know whether any hold plaintext keys or a Bash(*) allow rule
- Before connecting an MCP server from someone else's repo you want its risks assessed: launch via npx -y, binding to 0.0.0.0, autoApprove
- A repository with agent settings needs a pull request check: the GitHub Action fails on findings above a set severity and writes a SARIF report
- You need a safe baseline Claude Code setup: agentshield init adds scoped permissions and protective hooks
- An audit needs an evidence archive: the --evidence-pack option builds a portable bundle with hashes
Not a fit when
- You need to check application code or project dependencies for vulnerabilities: the scanner reads agent settings rather than product source
- You want to block dangerous agent commands at run time: AgentShield analyzes configuration before launch, and action interception is for other tools
- Node.js is missing: the scanner installs and runs through npm and npx
- You cannot send configuration to an external API: the --opus mode passes data to the Anthropic API and requires ANTHROPIC_API_KEY
Example request
Run npx ecc-agentshield scan and show the critical findings in my Claude Code configuration with suggested fixes.Limitations
- Node.js is required. Run it with npx ecc-agentshield scan.
- The main target is Claude Code settings; other environments (OpenCode, Codex, Gemini, Zed, VS Code) are covered by adapters with less depth.
- The --opus mode requires the ANTHROPIC_API_KEY variable, sends data to the Anthropic API and may cost money.
- Exit code 2 means a critical issue was found, and in CI that stops the build.
- Rules can produce false positives: findings from templates and examples are marked separately and weigh less.
How to disable. The scanner installs nothing into your configuration on its own, except with the --fix flag and the init command. For a global install remove the package with npm uninstall -g ecc-agentshield. In GitHub Actions delete the affaan-m/agentshield@v1 step.
FAQ
How do I check the security of a Claude Code configuration?
Run npx ecc-agentshield scan. The scanner finds ~/.claude, checks secrets, permissions, hooks and MCP servers and returns an A to F grade. Add --path for another directory, and --format json for CI output.
What does AgentShield find in MCP servers?
Servers with shell or filesystem-root access, npx -y launches without confirmation, secrets in config, remote URLs, binding to 0.0.0.0, the autoApprove setting and servers without timeouts. --supply-chain verifies package provenance.
How do I run AgentShield in GitHub Actions?
Add a step with uses: affaan-m/agentshield@v1 and the path, min-severity and fail-on-findings inputs. For a code scanning report set format: sarif. The baseline input enables comparison with a saved baseline.
Does AgentShield fix the problems it finds?
Partly. The --fix flag replaces plaintext keys with environment variables and narrows wildcard permissions, then rescans and rolls the edits back if the score drops. Some permission changes need human review.
What does AgentShield check in Claude Code hooks?
Command injection through ${file} in the shell, data sent out with curl, silent errors such as 2>/dev/null and || true, remote scripts downloaded and run at session start, reverse shells and log wiping. The report also flags the absence of PreToolUse hooks.
Discussion
No questions or reviews yet.
Related
CLI toolsAn authorized bug-bounty suite: 50 subagents, 26 commands and 2 bug-bounty-platform MCP servers for Claude Code, Codex and five more agents
A security scanner for AI-written code: secrets, dependencies, MCP and CI, findings investigated with evidence, and fixes you approve
MCP-Shield finds your MCP configs, connects to servers and scans tool descriptions for hidden commands, exfiltration channels and tool shadowing
The safehouse command runs Claude Code, Codex and other agents in a macOS sandbox: files are closed by default and you open folders with flags
A security scanner CLI for code and AI agents: vets .claude, hooks, MCP configs and SKILL.md before cloning and finds leaked keys
HOL Guard checks an AI agent's shell commands, secret reads, MCP calls and package installs before they run and holds risky actions until you decide
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| AgentShield (this entry) | no | 1,317 | |
| MCP Scanner | yes | 1,096 | inspects the MCP servers and their tools with three engines, while AgentShield audits the whole agent configuration |
| Skill Scanner | no | 2,621 | Cisco's scanner for the skills themselves, while AgentShield rates the settings, hooks and permissions around them |
| HOL Guard | yes | 971 | stops dangerous actions while the agent runs, while AgentShield checks the configuration in advance |
README in short
The README explains the motivation: the market for skills and MCP is growing faster than checking tools, and in January 2026 part of one skill marketplace turned out to be malicious. The quick start boils down to one npx command and shows a sample report. The main part describes rule categories for secrets, permissions, hooks, MCP and agent config, followed by auto-fix, external rule packs, the Opus mode and SOC 2 mapping. It closes with report formats, the command reference, the GitHub Action, the MiniClaw mini-server and an FAQ.