HOL Guard
Open-source antivirus for AI agents: blocks risky tools, secret access, prompt injection, malicious packages, MCP servers, plugins, and skills at runtime.
Evidence shows an approval flow (approvals/receipts), per-change confirmation on setup, local-first operation, least-privilege CI with SHA-pinned actions, and hash-required docker installs; but least_privilege and sensitive_data_handling claims rest mostly on README assertions with no policy-engine source shown, so deducted. Publisher 'HOL/Hashgraph Online' is unverified with only an mcp-name marker, so source_attribution scores 1.
CI is exceptionally thorough (96 shards, compatibility matrix, contract tests, mutation baseline) and pytest markers are well structured; but passing results cannot be confirmed statically and failure-message quality is only inferable from troubleshooting/doctor/diff docs; self_consistency is docked because multiple entry-point aliases (hol-guard/plugin-guard) map to the same cli.main.
Audience and scenarios are well covered (individuals, teams, CI), the support matrix documents enforcement and failure behavior per harness, and boundaries are honestly stated ('coverage depends on events each agent exposes'); trigger_precision is docked because rule-matching quality is only inspectable via command test/explain, not assessable statically; environment fit is proven across Python 3.10–3.14 and multi-OS CI.
Information architecture is clear (doc table, spec directories, extension directory), install notes are complete with pipx/update/verify, the FAQ covers key questions, and Apache-2.0 text matches pyproject; deductions: no CHANGELOG file (only a releases link), naming carries legacy baggage (internal package codex_plugin_scanner, aliases plugin-guard/plugin-ecosystem-scanner), and the maintainer is an unverified org with no explicit governance/roadmap file.
Output formats span text//markdown/sarif with structured Action outputs, giving high usability; the local agent-security layer plus plugin-scanner combination has clear marginal value (automated approvals with receipts, AIBOM export); cost_benefit is docked because pipx installation, policy configuration, and optional cloud sync add operational surface and effectiveness depends on rule-library quality that cannot be proven statically.
Claims are traceable via linked docs, published trust-scoring specs, contracts shipped in the wheel, and a CI-generated extension directory; cross-source consistency partially checks out (README/pyproject/SECURITY.md agree on version and license, CI matches the documented test matrix), but external evidence (PyPI, Scorecard) cannot be independently confirmed in this static review, hence a deduction; fact/inference separation is excellent — drafts are labeled as drafts and coverage is explicitly conditional.
- Publisher identity is not verified by a curated registry; verify the GitHub-org-to-PyPI correspondence yourself before relying on it.
- Guard installs hooks and modifies agent configuration on your machine; run --dry-run and diff first, and confirm an uninstall/recovery path before granting changes.
- Optional Guard Cloud and supply-chain sync perform external network calls; disable sync and audit the local-vs-cloud documentation if you require fully offline operation.
- This is a static review with no execution; actual precision/recall (false-positive rate) of the detection rules is unverified — pilot in a controlled environment first.
- No CHANGELOG file exists; reconcile GitHub releases against the pyproject version before upgrading.
What does this agent do, and when should you use it?
HOL Guard is a local-first, open-source security layer from the hashgraph-online organization that reviews AI agent actions before they run: shell commands, file access, package installs, and MCP tool calls. It detects secret exposure, destructive operations, prompt injection, and supply-chain risks, then allows, blocks, or requests approval according to your policy. The repository ships two PyPI distributions: `hol-guard` for runtime protection and `plugin-scanner` for pre-publish security and quality scanning of agent plugins. Protection connects through native agent hooks, managed MCP proxies, and launch integrations, with adapters for Codex, Claude Code, Cursor, Gemini CLI, and many other agents. It runs locally without an account, using a CLI and local dashboard for approvals and decision receipts; optional Guard Cloud adds shared history, team policy, and fleet management. The project is licensed under Apache-2.0.
After hol-guard init, a first-run wizard discovers supported agents and walks through protection setup. At runtime it intercepts and reviews shell commands (hol-guard command test 'rm -rf ./build' and command explain inspect classification and matching rules without executing), package installs (hol-guard supply-chain sync/scan/explain evaluates operations against supply-chain intelligence, e.g. [email protected]), plugin/skill/agent configuration changes (via artifact inventory), MCP server configuration and tool calls (through hooks and managed proxies), and prompts and tool results for injection. Paused actions route to the approval center (hol-guard approvals approve/deny), and decisions are recorded as local receipts (hol-guard receipts). Additional commands cover inventory, AI bill of materials export (hol-guard abom --format ), and doctor/diff diagnostics. plugin-scanner provides scan, lint, verify, submit, and doctor subcommands, detects six package formats (Codex, Claude Code, DeepSeek Harness, Gemini CLI, Kimi Code, OpenCode), checks manifests, hardcoded secrets, MCP transport and command configuration, GitHub Actions permissions, and lockfiles, and reports in text, JSON, Markdown, and SARIF. A companion GitHub Action (ai-plugin-scanner-action) enforces CI security gates.
- An engineer running Codex or Claude Code on a dev machine who wants destructive commands like rm -rf blocked before they execute.
- A team using multiple agents (Cursor, Gemini CLI, etc.) that wants one unified policy and approval center for sensitive-file and credential access.
- Developers worried about malicious npm dependencies who evaluate packages with
supply-chain scanbefore installing. - Maintainers publishing agent plugins, skills, or MCP integrations who use
plugin-scanner scan/verifyas a CI security and quality gate. - Security teams needing auditability, tracing every allowed or blocked decision via
hol-guard receiptsand local receipts.
What are this agent's strengths and limitations?
- Local-first: protection, approvals, and decision receipts work without any account; cloud features are optional, not mandatory.
- Broad coverage in one tool: shell commands, file access, package installs, plugins/skills/MCP servers, and prompt injection.
- Native hook integration for agents like Codex, with managed launches refusing to start if required hooks are missing or disabled, preventing silent bypass.
- plugin-scanner produces machine-readable SARIF/JSON reports and ships a GitHub Action for direct CI gating.
- Requires Python 3.10+ and pipx; Cisco-enhanced analysis adds Python 3.11–3.14 or Docker constraints, making the install stack heavier.
- Coverage depends on the events each agent exposes; the support matrix shows enforcement, approval, and failure behavior differ per integration.
- Each agent needs its own integration installed via hooks or proxies, so existing workflows must be configured per agent.
- Protection runs on the local machine; team policy and fleet visibility require deploying the optional Guard Cloud.
How do you install or deploy this agent?
Requires Python 3.10+ and pipx:
bash
pipx install hol-guard
hol-guard initThe first-run wizard discovers supported agents and walks you through setup. Verify with:
bash
hol-guard --version
hol-guard statusUpdate with hol-guard update. Install the scanner separately: pipx install plugin-scanner. Optional Cisco skill analysis: pipx install 'plugin-scanner[cisco]' (Python 3.11–3.14); Cisco MCP analysis needs the repo Docker image or uv sync --extra dev --extra cisco --group cisco-mcp --python 3.13. A container image is also published on ghcr.
How do you use this agent?
Enable protection for an agent: hol-guard install codex, then hol-guard run codex --dry-run before hol-guard run codex. Everyday commands: hol-guard status, hol-guard doctor codex, hol-guard diff codex, hol-guard approvals, hol-guard command explain 'git clean -ndx', hol-guard supply-chain scan, hol-guard abom --format , hol-guard connect for optional cloud sync. Scanner usage: plugin-scanner scan ., plugin-scanner lint ., plugin-scanner verify ., with options like --format sarif --output plugin-scanner.sarif, --fail-on-severity high, and --ecosystem claude. In CI, pair it with the hashgraph-online/ai-plugin-scanner-action.
How does this agent compare with similar options?
The README explicitly splits the two distributions: hol-guard protects agent runtime activity on your machine, while plugin-scanner inspects plugin packages and enforces security and quality checks in CI. They are published from the same repository and complement each other rather than compete.
FAQ
Do I need a cloud account?
Which AI agents are supported?
Why did Guard pause my command?
hol-guard approvals, inspect with hol-guard command explain '<command>', and review decisions with hol-guard receipts.