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 GuardRead the documentationPyPI Package (hol-guard)Report an Issue

HOL Guard reviews 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.

Run it locally without an account. Use the CLI and local dashboard to manage protection, resolve approvals, and inspect decision history. Optional Guard Cloud adds shared history, team policy, and fleet management.

Get started · Supported agents · Plugin scanner · Documentation · Contribute an extension · Contribute an adapter · Development

Install HOL Guard

Requires Python 3.10 or newer and pipx.

pipx install hol-guard
hol-guard init

The first-run wizard discovers supported agents and walks you through protection setup. It asks before each setup change, including opening the dashboard, installing agent integrations, and connecting optional cloud services.

Check your installation:

hol-guard --version
hol-guard status

To update an existing installation:

hol-guard update

For manual setup, see the installation guide. Annotated release notes with upgrade context live at hol.org/guard/releases; raw releases and prereleases are on the GitHub releases page.

What HOL Guard Protects

Surface · Protection Shell commands and file access · Reviews destructive operations, sensitive file access, credential exposure, and suspicious outbound commands. Package installs · Evaluates supported package-manager operations against supply-chain intelligence before installation. Plugins, skills, and agent configuration · Inventories local artifacts and reviews new or changed tools before launch. MCP servers and tools · Inspects server configuration and reviews tool calls through supported hooks and managed proxies. Prompts and tool results · Screens supported events for prompt injection and sensitive content. Approvals and evidence · Routes decisions to native prompts or the approval center, and records local receipts for review.

Guard connects through native agent hooks, managed MCP proxies, and launch integrations. Coverage depends on the events each agent exposes; the support matrix documents enforcement, approval delivery, and failure behavior per integration.

Supported AI Agents

Codex, Claude Code, GitHub Copilot CLI, Cursor, Cline, Gemini CLI, Grok, Hermes, Kimi Code, Pi, oh-my-pi, OpenClaw, OpenCode, Antigravity, ZCode, and Devin. Paseo is supported through these native provider integrations, with per-provider coverage.

For example, to set up Codex explicitly:

hol-guard install codex
hol-guard run codex --dry-run
hol-guard run codex

The dry run records the current artifact state before launch. For Codex, Guard installs native pre-tool hooks and refuses a managed launch if those hooks are missing or disabled.

Agent support matrix · Troubleshooting

Everyday Use

Task · Command Check protection status · hol-guard status Diagnose an agent integration · hol-guard doctor codex Inspect changes before launch · hol-guard diff codex Review pending approvals · hol-guard approvals Approve or deny a request · hol-guard approvals approve / hol-guard approvals deny Read decision history · hol-guard receipts List tracked artifacts · hol-guard inventory Export an AI bill of materials · hol-guard abom --format json Scan workspace dependencies · hol-guard supply-chain scan Connect optional cloud sync · hol-guard connect

Understand a paused command

Inspect the command's classification and matching rules:

hol-guard command test 'rm -rf ./build'
hol-guard command explain 'git clean -ndx'
hol-guard command extensions command.git --json

command test and command explain inspect the command without executing it or creating an approval. Use hol-guard approvals to resolve a pending request and hol-guard receipts to review the recorded decision.

The Extension directory lists command coverage generated from the Rust-compiled catalog. External contributions require explicit opt-in; required core protections remain enabled. To add coverage, follow the Extension contribution guide.

Check a package

hol-guard supply-chain sync
hol-guard supply-chain scan
hol-guard supply-chain explain minimist@1.2.5 --ecosystem npm

The package verdict includes the available advisory evidence and ecosystem coverage. See the get-started guide for package-manager interception and the remediation guide for handling false positives.

Plugin Scanner

This repository also ships plugin-scanner, a CLI for maintainers who want security and quality checks before publishing agent plugins, skills, and MCP integrations.

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

Command · Purpose scan · Security findings and a quality report across detected package surfaces. lint · Rule-level authoring feedback. verify · Install-surface and runtime readiness checks. submit · A submission artifact for one plugin package. doctor · Component diagnostics and troubleshooting bundles.

The scanner detects Codex, Claude Code, DeepSeek Harness, Gemini CLI, Kimi Code, and OpenCode package formats. Use plugin-scanner --list-ecosystems to list them or --ecosystem to select one. At a Codex marketplace root, it discovers local plugin entries automatically.

Checks cover manifests, secrets, MCP transport and command configuration, approval defaults, skills, dependency lockfiles, and GitHub Actions permissions. Optional Cisco integrations add skill and MCP analysis. Reports support text, JSON, Markdown, and SARIF.

plugin-scanner scan . --format sarif --output plugin-scanner.sarif
plugin-scanner scan . --fail-on-severity high

Quality grades use the checks applicable to each package. Trust scoring has separate provenance and weights; see the skill, MCP, and plugin scoring references.

GitHub Actions

Add the scanner to a plugin repository:

name: Plugin security
on: [push, pull_request]

permissions:
  contents: read

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
      - uses: hashgraph-online/ai-plugin-scanner-action@fdb49f9d85321a2ced2933301b395dd3c1ce9c8f # v1.2.631
        with:
          plugin_dir: "."
          min_score: 80
          fail_on_severity: high

See the action documentation for SARIF uploads, submission workflows, and machine-readable outputs. The action source is maintained in action/.

Optional Cisco analysis

The baseline packages work without Cisco dependencies. To add Cisco skill scanning, use Python 3.11 through 3.14 and install the extra in an isolated environment:

pipx install 'plugin-scanner[cisco]'

For Cisco MCP analysis, use the repository's Docker image or the cisco-mcp dependency group:

uv sync --extra dev --extra cisco --group cisco-mcp --python 3.13
uv run plugin-scanner scan . --cisco-skill-scan on --cisco-mcp-scan on

The published cisco extra provides skill scanning; the separate cisco-mcp group supplies the MCP scanner. Dependency versions and Python constraints are maintained in pyproject.toml.

Ecosystem Support

Ecosystem · Detection surfaces Codex · .codex-plugin/plugin.json, marketplace.json, .agents/plugins/marketplace.json Claude Code · .claude-plugin/plugin.json, .claude-plugin/marketplace.json DeepSeek Harness · package.json with dsh.bundle, declared patches, and Cordis apply(ctx) exports, or dsh.bundle.mode set to "patch" for patch-only bundles Gemini CLI · gemini-extension.json, commands/**/*.toml Kimi Code · kimi.plugin.json, .kimi-plugin/plugin.json, declared skills, agents, commands, prompts, and MCP servers OpenCode · opencode.json, opencode.jsonc, .opencode/commands, .opencode/plugins

Use --ecosystem auto to detect supported packages in a repository, or select an ecosystem explicitly:

plugin-scanner scan ./plugins-repo --ecosystem claude
plugin-scanner scan ./dsh-plugin --ecosystem deepseek-harness

What The Scanner Checks

Category · Coverage Manifest validation · Required fields, versions, declared paths, interface metadata, links, and assets. Security · Hardcoded secrets, unsafe MCP commands and transports, and risky approval defaults. Operational security · GitHub Actions permissions and pinned dependencies, privileged checkout patterns, Dependabot, and lockfiles. Plugin packaging · README and license files, skill frontmatter, ignore rules, and accidentally committed environment files. Marketplace · Manifest validity, local package discovery, and safe source paths. Skill and MCP analysis · Analyzer availability, findings, and analyzability from optional Cisco integrations. Code quality · Dynamic code execution and shell-injection patterns.

How Trust Scoring Works

Plugin Scanner reports a quality grade alongside trust provenance. Quality scores are normalized across applicable checks, so optional surfaces do not inflate a package's grade.

Skill trust uses the HCS-28 baseline adapter IDs, weights, and denominator rules. MCP and Codex plugin trust use explicit adapters, weights, and contribution modes documented in the local specifications:

• Skill Trust Local Draft
• MCP Trust Draft
• Codex Plugin Trust Draft

CLI Usage

# Structured security report
plugin-scanner scan ./my-plugin --format json --profile public-marketplace

# Inspect authoring rules
plugin-scanner lint ./my-plugin --list-rules
plugin-scanner lint ./my-plugin --explain README_MISSING

# Apply supported mechanical fixes
plugin-scanner lint ./my-plugin --fix --profile strict-security

# Verify package readiness; --online permits live probes
plugin-scanner verify ./my-plugin --format json
plugin-scanner verify ./my-plugin --online --format text

# Generate a submission artifact for one plugin
plugin-scanner submit ./my-plugin --profile public-marketplace --attest dist/plugin-quality.json

# Collect component diagnostics
plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip

For a repository marketplace, scan, lint, verify, and doctor can target the root. submit targets one plugin package.

Codex Spec Alignment

The scanner recognizes Codex plugin manifests, interface metadata, declared assets, and marketplace packages:

• Local manifest paths use ./ prefixes; lint --fix preserves or adds them.
• .agents/plugins/marketplace.json is the preferred marketplace location, with root marketplace.json supported for compatibility.
• Interface validation checks declared links and assets without requiring an undocumented type field.
• verify --online checks HTTP remote reachability. Stdio server execution is skipped for manual review.

See the Codex plugin documentation and Model Context Protocol specification for upstream formats.

Config + Baseline Example

Configure the scanner in .plugin-scanner.toml:

[scanner]
profile = "public-marketplace"
baseline_file = "baseline.txt"
ignore_paths = ["tests/*", "fixtures/*"]

[rules]
disabled = ["README_MISSING"]
severity_overrides = { CODEXIGNORE_MISSING = "low" }

The GitHub Action requires trust_repository_policy: true before repository-owned configuration and baselines can change its verdict. Enable that option only for policy you intend the workflow to trust.

Report Formats

Format · Use text · Terminal summaries with category totals and findings. json · Structured reports for scripts and integrations. markdown · Review-ready reports for pull requests and issues. sarif · GitHub code scanning and security automation.

GitHub Action

The AI Plugin Scanner Action supports security gates, SARIF uploads, submission intake, and registry payloads. Its source lives in action/, and the publication workflow distributes the action bundle.

The legacy HOL Codex Plugin Scanner Action remains available for existing workflows.

Plugin Author Submission Flow

Use submission_enabled: true to open or reuse a submission issue when a plugin meets the configured threshold. submission_token must have permission to create issues in the target submission repository. The action emits submission status and issue URLs as outputs.

See the action's input reference for submission_score_threshold, submission_token, and the target repository options.