hol-guard

HOL Guard: Open-Source Antivirus for AI Agents

	Stop risky AI actions before they compromise your machine. HOL Guard is a local-first security layer for AI agents, tools, plugins, skills, MCP servers, and package installs. Install HOL Guard Read the documentation PyPI Package (hol-guard) Report an Issue

HOL Guard brings antivirus-style runtime protection to AI agents. It evaluates supported agent actions and local artifacts for secret exposure, prompt injection, unsafe commands, malicious packages, and MCP risks. Guard can allow safe work, block known threats, pause ambiguous actions for approval, and record security receipts for later review.

Use HOL Guard locally without a cloud account. Connect Guard Cloud when you want synchronized evidence, team policies, fleet visibility, and shared approval workflows.

Install HOL Guard

pipx install hol-guard
hol-guard init

hol-guard init discovers compatible AI agents, explains each setup change before applying it, and guides you through your first protected action.

Install guide · Supported agents · Local vs. cloud · Security policy

What HOL Guard Protects

Guard prefers the strongest integration each agent exposes. Enforcement depth varies by agent and event type; see the support matrix for the exact current contract.

Supported AI Agents

HOL Guard currently integrates with Codex, Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Hermes, OpenClaw, OpenCode, Antigravity, Kimi Code, Grok, Pi / oh-my-pi, and ZCode.

These developer agents are Guard's deepest integrations today, but the product boundary is broader: the same policy, supply-chain, approval, and evidence layers are designed to protect AI agents and their local tool ecosystems as new adapters are added.

Why HOL Guard

Most security tools see only one part of an AI agent's attack surface. Code scanners run after files change. Sandboxes constrain a process but do not understand agent intent. MCP gateways see MCP traffic but not local shell commands, package installs, skills, hooks, or agent configuration.

HOL Guard combines those signals at the local runtime boundary. It discovers the agent and its tools, evaluates supported actions against one policy, requests human approval only when needed, and records the resulting decision. The goal is practical protection without turning ordinary AI-assisted work into a stream of prompts.

Choose the Right Package

hol-guard is the end-user antivirus and runtime protection product. plugin-scanner is the maintainer and CI companion for analyzing agent ecosystem packages before release.

Guard Operations

To update an existing pipx install from PyPI:

pipx upgrade hol-guard

If you installed Guard with pipx, verify the active user command before testing local flows:

command -v hol-guard
hol-guard --version

For a local wheel build, install into the pipx-managed hol-guard environment. Do not test with PYTHONPATH=src; that bypasses the same package path users run.

python3 -m build --wheel
hol-guard update --wheel dist
hol-guard --version

hol-guard update --wheel accepts either a specific .whl file or a directory and picks the newest matching hol_guard-*.whl.

To force a specific release, use Python package specifier syntax:

pipx install --force 'hol-guard==2.0.345'

Do not use hol-guard@<version>; pipx treats that as a separate app name, not a package version.

hol-guard init is the first-run guided setup. It shows a progressive plan first, then gates each side effect: approve dashboard, Guard completes it, then approve app protection, Guard completes it, then approve Cloud connect and notifications. Nothing opens or changes until you approve that checkpoint. Use hol-guard init --yes only for automation when you already trust the plan.

Manual and follow-up commands:

pipx run hol-guard bootstrap
pipx run hol-guard hermes bootstrap
pipx run hol-guard run codex --dry-run
pipx run hol-guard run codex
pipx run hol-guard approvals
pipx run hol-guard receipts
pipx run hol-guard status
pipx run hol-guard connect
pipx run hol-guard connect status
pipx run hol-guard connect repair
pipx run hol-guard sync
pipx run hol-guard supply-chain sync
pipx run hol-guard supply-chain scan
pipx run hol-guard supply-chain explain minimist@1.2.5 --ecosystem npm
pipx run hol-guard explain install-connect
pipx run hol-guard command test 'git reset --hard HEAD~1'
pipx run hol-guard command explain 'grep "rm -rf|git clean" README.md'
pipx run hol-guard command extensions

What you get from Guard:

• Detects supported AI agent configuration on your machine
• Records a baseline before you trust a tool
• Pauses cleanly on new or changed artifacts before launch
• Queues blocked changes in a localhost approval center when the harness cannot prompt inline
• Stores receipts locally so you can review decisions later
• Keeps sync optional until you actually want shared history

See docs/guard/get-started.md for the full local flow.

Inspect command protection without running it

Command safety extensions make Guard's shell, Git, filesystem, system, Windows, data-protection, container, Kubernetes, encoded-execution, and self-protection behavior inspectable. Required core extensions cannot be mistaken for optional integrations. They are built-in capability boundaries over the same parser used by harness hooks, not downloadable regex bundles.

Each extension publishes stable rule IDs and structured rule metadata. Command inspection also returns a canonical, side-effect-free parse model with wrapper, pipeline, environment-override, provenance, and confidence details so automation can distinguish exact parsing from malformed or unsupported input.

Use command test for a concise classification and command explain for the complete evaluation trace. Both are side-effect free: they do not execute the command, evaluate final policy, create an approval, or record a receipt. Use --json for a stable automation contract.

hol-guard command test 'rm -rf ./build'
hol-guard command explain 'grep "rm -rf|git clean" README.md'
hol-guard command extensions command.git --json

Structured core rules preserve every match in a compound command. A Git preview such as git clean -ndx remains safe, while an unrelated destructive segment still produces review. New structured coverage feeds the same runtime artifact and policy pipeline as existing command classifications.

Guard: Protection Levels

HOL Guard is antivirus for AI agents. It evaluates supported runtime events and local artifacts, then applies the active policy before execution where the agent provides a pre-action boundary. Other integrations use native approval, managed proxy, launch-time, or post-action evidence surfaces according to the support matrix.

Choose a protection level with hol-guard settings set security-level <level>:

If you are unsure, start with Balanced. You can promote to Strict after reviewing your first week of receipts.

Guard: Troubleshooting

Why was my command paused?

Guard paused a command because one or more detectors fired. To see exactly what triggered:

hol-guard receipts          # review recent decisions
hol-guard doctor            # run a probe and see which detectors are active
hol-guard doctor --perf     # include per-detector timing

If the block looks like a false positive, you can approve it from the receipts view or from the dashboard at http://localhost:6174.

How do I clear approvals?

From the terminal:

hol-guard approvals         # list pending approvals
hol-guard approvals clear   # clear all pending approvals (prompts for confirmation)

From the dashboard: open http://localhost:6174, go to the Approval Center, and use the Clear all button. You will be asked to confirm before any approvals are removed.

How do I require human proof before saved approvals?

Enable the local approval gate when saved allow decisions, global trust, policy clears, or settings changes should require a human password before Guard persists them:

hol-guard settings approval-password enable \
  --new-password '<password>' \
  --confirm-password '<password>' \
  --cooldown-seconds 900
hol-guard settings approval-password status

Use cooldown only for ordinary non-global allow decisions. Guard still requires fresh proof for global allow, policy clear, settings import/reset, disabling the gate, disabling TOTP, and recovery. When TOTP is enabled, it replaces password proof and cooldown is disabled, so every protected action requires a current authenticator code. To unlock or lock the current password-only approval window from a terminal:

hol-guard approvals unlock --duration 15m
hol-guard approvals lock

For Google Authenticator-compatible second-factor proof, enroll TOTP after the password gate is enabled:

hol-guard settings approval-totp enroll --current-password '<password>' --device-label '<device>'
hol-guard settings approval-totp verify --current-password '<password>' --code 123456
hol-guard settings approval-totp status

TOTP uses SHA-1, 6 digits, 30-second steps, and a Base32 otpauth://totp/HOL%20Guard:<device> provisioning URI. Guard stores the seed encrypted locally, rejects replayed steps, and never includes the seed in settings export, receipts, or public status. When TOTP is enabled, disabling TOTP or the password gate requires a current authenticator code instead of the password.

Approval proof creates only a 30-second, transaction-local grant for the exact action, scope, subject, and session nonce being processed. The grant is never returned to the browser or reused as a general login session. Guard tracks password and authenticator failures independently and locks the active factor after five failed attempts; rotating either factor revokes outstanding grants and any saved recovery, session, or trusted-device state.

Guard: Advisory Sync Privacy

Guard's advisory database updates are optional and pull-only. When you run hol-guard advisories sync, Guard fetches a signed advisory list from advisories.hol.org. No local file paths, harness configs, receipt data, or workspace identifiers are sent to any server during sync.

Advisory sync requires a HOL Guard Cloud account. If you have not signed in, sync is skipped and Guard continues using the locally bundled advisory database. Run hol-guard connect to connect a free account, or hol-guard connect --headless on SSH/CI hosts.

Scanner Quickstart

pipx install plugin-scanner
plugin-scanner lint .
plugin-scanner verify .

# GitHub Actions PR gate
- name: AI plugin quality gate
  uses: hashgraph-online/ai-plugin-scanner-action@v1
  with:
    plugin_dir: "."
    fail_on_severity: high
    min_score: 80

When to add plugin-scanner:

• You publish plugins, skills, or marketplace packages
• You want a CI gate before release
• You need SARIF, verification payloads, or submission artifacts

If your repository uses a Codex marketplace root like .agents/plugins/marketplace.json, keep plugin_dir: ".". The scanner will discover local ./plugins/... entries automatically, scan each local plugin manifest, and skip remote marketplace entries instead of treating the repo root as a single plugin.

Need More Detail?

• Contributor setup: jump to Development
• Local Guard docs: docs/guard/get-started.md
• GitHub Action docs: hashgraph-online/ai-plugin-scanner-action
• Registry and trust references: keep reading below

git clone https://github.com/hashgraph-online/hol-guard.git
cd hol-guard
uv sync --extra dev --extra cisco --group cisco-mcp
pytest -q

pip install hol-guard

pip install plugin-scanner

pip install "hol-guard[cisco]"

pip install "plugin-scanner[cisco]"

pipx install hol-guard
pipx install plugin-scanner