AI 代理杀毒防护 hashgraph-online/hol-guard

HOL Guard：面向 AI 智能体的开源杀毒软件

OpenSSF Scorecard
Vercel OSS Program

| HOL whole dark logo | 在危险的 AI 操作拖垮你的机器之前拦住它。 HOL Guard 是本地优先的安全层，守护 AI 智能体、工具、插件、技能、MCP 服务器和软件包安装。安装 HOL Guard阅读文档PyPI 包（hol-guard）提交 Issue |
HOL Guard 会在智能体执行操作前先审查：shell 命令、文件访问、软件包安装、MCP 工具调用。它能识别密钥泄露、破坏性操作、提示词注入和供应链风险，然后按你的策略放行、拦截或请求批准。

无需账号即可在本地运行。用命令行和本地仪表盘管理防护、处理批准请求、查看决策历史。可选的 Guard Cloud 提供共享历史、团队策略和集群管理。

快速开始 · 支持的智能体 · 插件扫描器 · 文档 · 贡献扩展 · 开发

安装 HOL Guard

需要 Python 3.10 或更高版本，以及 pipx。

pipx install hol-guard
hol-guard init

首次运行向导会探测支持的智能体，并带你完成防护设置。每次改动设置前它都会先询问，包括打开仪表盘、安装智能体集成、连接可选的云服务。

检查安装：

hol-guard --version
hol-guard status

更新已有安装：

hol-guard update

手动安装见安装指南。带升级说明的注释版发行说明在 hol.org/guard/releases；原始发行版和预发行版在 GitHub releases 页面。

HOL Guard 防护什么

| 层面 | 防护 |
| Shell 命令和文件访问 | 审查破坏性操作、敏感文件访问、凭据泄露和可疑的外发命令。 |
| 软件包安装 | 安装前，结合供应链情报评估支持的包管理器操作。 |
| 插件、技能和智能体配置 | 清点本地产物，并在启动前审查新增或变更的工具。 |
| MCP 服务器和工具 | 检查服务器配置，并通过支持的钩子和托管代理审查工具调用。 |
| 提示词和工具结果 | 筛查支持的事件，识别提示词注入和敏感内容。 |
| 批准与证据 | 把决策路由到原生提示或批准中心，并记录本地凭据供审查。 |

Guard 通过原生智能体钩子、托管 MCP 代理和启动集成接入。覆盖范围取决于各智能体暴露的事件；支持矩阵记录了每个集成的强制执行、批准下发和失败行为。

支持的 AI 智能体

Codex、Claude Code、GitHub Copilot CLI、Cursor、Cline、Gemini CLI、Grok、Hermes、Kimi Code、Pi、oh-my-pi、OpenClaw、OpenCode、Antigravity、ZCode 和 Devin。Paseo 通过上述原生服务商集成获得支持，并覆盖每个服务商。

例如，要显式设置 Codex：

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

试运行会在启动前记录当前产物状态。对于 Codex，Guard 会安装原生 pre-tool 钩子；如果这些钩子缺失或被禁用，则拒绝受管启动。

智能体支持矩阵 · 故障排查

日常使用

| 任务 | 命令 |
| 查看保护状态 | hol-guard status |
| 诊断智能体集成 | hol-guard doctor codex |
| 启动前检查变更 | hol-guard diff codex |
| 查看待处理的审批 | hol-guard approvals |
| 批准或拒绝请求 | hol-guard approvals approve <request-id> / hol-guard approvals deny <request-id> |
| 查看决策历史 | hol-guard receipts |
| 列出已跟踪的产物 | hol-guard inventory |
| 导出 AI 物料清单 | hol-guard abom --format json |
| 扫描工作区依赖 | hol-guard supply-chain scan |
| 连接可选的云同步 | hol-guard connect |

理解被暂停的命令

查看命令的分类与匹配规则：

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

command test 和 command explain 只检查命令，不执行它，也不创建审批。用 hol-guard approvals 处理待处理的请求，用 hol-guard receipts 查看已记录的决策。

扩展目录列出了由 Rust 编译的目录生成的命令覆盖范围。外部贡献需要显式选择加入；必需的核心保护保持启用。要添加覆盖范围，请遵循扩展贡献指南。

检查软件包

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

软件包判定结果包含可用的公告证据和生态覆盖范围。包管理器拦截参见入门指南，处理误报参见修复指南。

插件扫描器

本仓库还提供 plugin-scanner，这是一款命令行工具，面向希望在发布智能体插件、技能和 MCP 集成前做安全与质量检查的维护者。

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

| 命令 | 用途 |
| scan | 在检测到的各类包表面上给出安全发现与质量报告。 |
| lint | 规则级的编写反馈。 |
| verify | 安装表面与运行时就绪检查。 |
| submit | 为单个插件包生成提交产物。 |
| doctor | 组件诊断与故障排查包。 |

扫描器能识别 Codex、Claude Code、DeepSeek Harness、Gemini CLI、Kimi Code 和 OpenCode 的包格式。用 plugin-scanner --list-ecosystems 列出全部，或用 --ecosystem 选定其中一个。在 Codex 市场根目录下，它会自动发现本地插件条目。

检查范围覆盖清单文件、密钥、MCP 传输与命令配置、审批默认值、技能、依赖锁文件，以及 GitHub Actions 权限。可选的 Cisco 集成会额外加入技能与 MCP 分析。报告支持 text、JSON、Markdown 和 SARIF。
bash
plugin-scanner scan . --format sarif --output plugin-scanner.sarif
plugin-scanner scan . --fail-on-severity high

质量评级只采用适用于各个包的检查项。信任评分有独立的来源与权重；参见技能、MCP 和插件评分参考。

GitHub Actions

把扫描器加进插件仓库： yaml 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

SARIF 上传、提交工作流和机器可读输出，参见 action 文档。action 源码维护在 action/。

可选的 Cisco 分析

基础包不依赖 Cisco 也能用。要加上 Cisco 技能扫描，请用 Python 3.11 到 3.14，并在隔离环境中安装该 extra： bash pipx install 'plugin-scanner[cisco]'

要做 Cisco MCP 分析，用仓库的 Docker 镜像或 cisco-mcp 依赖组： bash
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

已发布的 cisco extra 提供技能扫描；单独的 cisco-mcp 组提供 MCP 扫描器。依赖版本与 Python 约束维护在 pyproject.toml。

生态支持

| 生态 | 检测表面 |
| 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，需带 dsh.bundle、声明的补丁，以及 Cordis 的 apply(ctx) 导出；纯补丁包则把 dsh.bundle.mode 设为 "patch" |
| Gemini CLI | gemini-extension.json、commands/*/.toml |
| Kimi Code | kimi.plugin.json、.kimi-plugin/plugin.json，以及声明的技能、智能体、命令、提示词和 MCP 服务器 |
| OpenCode | opencode.json、opencode.jsonc、.opencode/commands、.opencode/plugins |

用 --ecosystem auto 自动检测仓库里支持的包，也可以显式指定生态： bash plugin-scanner scan ./plugins-repo --ecosystem claude plugin-scanner scan ./dsh-plugin --ecosystem deepseek-harness

扫描器检查什么

| 类别 | 覆盖范围 |
| 清单校验 | 必填字段、版本、声明的路径、接口元数据、链接和资源。 |
| 安全 | 硬编码密钥、不安全的 MCP 命令与传输方式、有风险的审批默认值。 |
| 运维安全 | GitHub Actions 权限与固定依赖版本、特权 checkout 模式、Dependabot、锁文件。 |
| 插件打包 | README 与许可证文件、技能 frontmatter、忽略规则、误提交的环境文件。 |
| 市场 | 清单有效性、本地包发现、安全的源路径。 |
| 技能与 MCP 分析 | 可选 Cisco 集成提供的分析器可用性、发现结果和可分析性。 |
| 代码质量 | 动态代码执行与 shell 注入模式。 |

信任评分怎么算

Plugin Scanner 在给出信任来源的同时，也报告质量等级。质量分会在所有适用的检查项之间归一化，所以可选的部分不会抬高包的等级。

技能信任采用 HCS-28 基线适配器 ID、权重和分母规则。MCP 与 Codex 插件信任采用本地规范中记录的显式适配器、权重和贡献模式：

- Skill Trust Local Draft
- MCP Trust Draft
- Codex Plugin Trust Draft

命令行用法 bash

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

对于仓库级市场，scan、lint、verify 和 doctor 可以指向根目录。submit 只针对单个插件包。

对齐 Codex 规范

扫描器能识别 Codex 插件清单、接口元数据、声明的资源以及市场包：

- 本地清单路径使用 ./ 前缀；lint --fix 会保留或补上这些前缀。
- 首选的市场位置是 .agents/plugins/marketplace.json，同时兼容根目录下的 marketplace.json。
- 接口校验会检查声明的链接和资源，不要求填写未公开的 type 字段。
- verify --online 检查 HTTP 远程地址是否可达。Stdio 服务端的执行会跳过，留待人工审查。

上游格式参见 Codex 插件文档 和 Model Context Protocol 规范。

配置与基线示例

在 .plugin-scanner.toml 中配置扫描器：

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

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

GitHub Action 要求先设置 trust_repository_policy: true，仓库自有的配置和基线才能改变它的判定结果。只有当你确实希望工作流信任某项策略时，才开启这个选项。

报告格式

| 格式 | 用途 |
| text | 终端摘要，包含分类汇总和发现项。 |
| json | 结构化报告，供脚本和集成使用。 |
| markdown | 便于审阅的报告，用于 pull request 和 issue。 |
| sarif | GitHub 代码扫描和安全自动化。 |

GitHub Action

AI Plugin Scanner Action 支持安全门禁、SARIF 上传、提交接收和注册表载荷。源码位于 action/，发布工作流 负责分发 action 包。

旧版 HOL Codex Plugin Scanner Action 仍然可用，供现有工作流使用。

插件作者提交流程

设置 submission_enabled: true，插件达到配置的阈值时就会创建或复用提交 issue。submission_token 必须拥有在目标提交仓库创建 issue 的权限。该 action 会把提交状态和 issue URL 作为输出。

submission_score_threshold、submission_token 以及目标仓库相关选项，参见 action 的输入参考。

面向插件生态自动化的注册表载荷

设置 registry_payload_output，即可写出机器可读的载荷，供注册表或徽章流水线使用。该 action 还会输出 score、grade、grade_label、max_severity 和 findings_total，并可以写入 job summary。
HOL Registry Broker 插件是 HOL Plugin Registry 里智能体插件的一个示例。它的注册表条目提供最新信任信息。

为什么需要 HOL Guard

AI 智能体可以在一次会话里运行命令、安装依赖、读取文件、调用外部工具。HOL Guard 在支持的执行点审查这些操作，把策略决策、审批请求和回执放在一起。

用它来做开发机上的 AI 智能体安全、连接工具周边的 MCP 安全，以及包和插件的供应链检查。团队可以加上 Guard Cloud，共享审批和策略管理，同时保留本地防护。

常见问题

HOL Guard 是什么？

HOL Guard 是面向 AI 智能体的开源杀毒与运行时防护。它审查支持的工具调用、shell 命令、文件访问和包操作，识别密钥泄露、提示词注入、破坏性操作、恶意依赖等风险。

没有云账号，HOL Guard 能用吗？

能。本地防护、命令行命令、审批和回执都不需要登录。Guard Cloud 是可选的，它增加同步证据、团队管控和集群可见性。功能边界见本地 Guard 与 Guard Cloud。

HOL Guard 支持哪些 AI 智能体？

Guard 内置适配器，支持 Codex、Claude Code、GitHub Copilot CLI、Cursor、Cline、Gemini CLI、Grok、Hermes、Kimi Code、Pi、oh-my-pi、OpenClaw、OpenCode、Antigravity、ZCode 和 Devin。Paseo 通过这些原生服务商集成获得支持，覆盖范围因服务商而异。支持矩阵说明每个适配器支持哪些事件和执行路径。

HOL Guard 和 Plugin Scanner 有什么区别？

安装 hol-guard，保护你机器上的智能体活动。安装 plugin-scanner，检查插件包，在 CI 里强制执行安全和质量检查。本仓库构建并发布这两个发行版。

HOL Guard 如何保护 MCP 服务器？

Guard 检查 MCP 服务器配置，并通过智能体钩子和托管代理审查支持的 MCP 工具调用。Plugin Scanner 检查 MCP 配置和 HTTP 远程可达性；可选的 Cisco MCP 分析会补充静态安全发现。

Guard 为什么暂停了我的命令？

该操作可能按你当前的策略需要审批，或者它的工具或产物发生了变化。先运行 hol-guard approvals，用 hol-guard command explain '<command>' 查看命令，再用 hol-guard receipts 查看记录的决策。

文档

遇到注册或原生权限过期错误，见扩展控制恢复。

| 指南 | 内容 |
| 快速上手 | 安装、手动配置、包保护，以及常用命令。 |
| 智能体支持 | 集成覆盖范围与审批行为。 |
| 架构 | 运行时组件与决策流程。 |
| 策略规范 | GuardPolicy 文档格式。 |
| 策略配方 | 常见工作流的配置示例。 |
| 扩展 | 内置命令规则与贡献指南。 |
| 原生扩展编写 | 规范 JSON 源、Rust 编译器、可移植夹具与评审套件。 |
| 贡献扩展 | 用命令行生成、评审、集成并测试新扩展。 |
| 本地 vs. 云端 | 本地能力与可选云服务。 |
| 故障排查 | 诊断与恢复。 |
| 安全 | 漏洞上报与披露策略。 |

贡献新扩展

命令扩展以声明式 JSON 编写，由 Rust 编译并求值。在 contributions/command-sources/command.<name>.json 里添加元数据、权限、匹配器树和安全变体，再用可移植 JSON 夹具验证行为。多数扩展只是组合已有的原生操作；只有当现有匹配器契约无法表达目标行为时，才需要新增 Rust 操作。

| 贡献内容 | 编写输入 | 验证方式 |
| 命令覆盖 | contributions/command-sources/command.<name>.json | 由 guard-command-source test 求值的可移植夹具。 |
| MCP 服务器知识 | contributions/mcp-servers/<id>.json | MCP 贡献测试与原生目录校验。 |
| 新匹配器语义 | rust/crates/guard-command/ 中经评审的 Rust 改动 | 原生契约、准入、求值与回归测试。 |

Rust 编译器生成命令描述符、目录和原生匹配器程序。Python 仍属于命令行、构建编排和测试的一部分；新增命令覆盖不需要 Python 检测器，也不需要注册表登记。直接编写源码请见编写指南，运行时边界请见架构。

Extension Builder 命令行可以从导出的命令元数据生成这些命令源和可移植夹具。它也支持 MCP 清单。它离线工作，读取导出内容时不导入、不运行目标工具。

用 Builder 的 plan-and-apply 流程生成规范源和夹具。尽早开一个草稿 PR 做范围评审。在把该 PR 标记为可评审之前，运行 scripts/prepare_extension_contribution.py --source ... --fixture ... 同步确定性 projections，然后运行 hol-guard extensions handoff --repo . --source ... --fixture ...。handoff 检查会在最终评审前抓出缺失的生成描述符、目录条目和源绑定。

1. 在 PR 里定义覆盖范围。 查看 Extension directory 和当前 open pull requests，确认是否已有或重叠的覆盖。要新增能力，用 Command extension 模板开一个草稿 PR，附上拟定的 command.<name> ID、支持的操作、破坏性示例、对应的安全操作，以及上游参考。范围评审在 PR 上进行，不需要单独开 issue。如果某个操作已经归现有扩展管，就扩展那个扩展。

按 development setup 配置好，然后在你的 HOL Guard checkout 里运行下面的示例。uv run --no-sync 用的是该 checkout 里已安装的开发版本。

2. 生成贡献套件。 这个示例用的是仓库内自带的合成 samplectl 清单。换成你自己的贡献时，把输入和元数据替换成你工具的导出结果和公开的发布者信息。

uv run --no-sync hol-guard extensions generate --from cli \
--input docs/guard/extension-builder/examples/cli-surface.json \
--slug samplectl --executable samplectl --name 'Sample CLI' \
--publisher community.example --publisher-name 'Example Maintainer' \
--homepage https://example.test/samplectl \
--upstream-version 1.0.0 --output samplectl-kit

uv run --no-sync hol-guard extensions validate samplectl-kit

输出目录必须是新目录，且父目录已存在。命令套件包含 discovery.json、review.json、report.json、规范 JSON 源、可移植的原生 fixture、生成的描述符，以及文件清单。MCP 套件包含贡献元数据和生成的 Python 测试。

其他输入：--from help 读取保存的命令帮助；--from click 读取 Click 的 Context.to_info_dict() 导出；--from oclif 读取 oclif.manifest.json；--from mcp 读取完整的 tools/list 导出结果；--from snapshot 重放 discovery.json。上面的 cli 示例用的是规范化后的 guard.cli-surface.v1 JSON。

MCP 贡献不用 --executable，改用 --launcher 和 --package。完整命令和分页要求见 MCP kit example。

3. 检查操作并重新生成。 读 report.json，把发现的操作和上游实现对照。编辑前先复制评审文件：

cp samplectl-kit/review.json samplectl-review.json
编辑 samplectl-review.json，保持它的 discovery 绑定和 operation ID 不变。CLI 操作使用 review 或 block；根操作保持 review。为你已评估的条目设置 reviewed: true，并附上理由和公开的 HTTPS 证据引用。只对经过验证、确切安全的调用添加 safeArgv。review 格式 包含完整的条目示例。

审查保存的快照后重新编译：

uv run --no-sync hol-guard extensions generate --from snapshot \
--input samplectl-kit/discovery.json \
--review samplectl-review.json --output samplectl-reviewed

uv run --no-sync hol-guard extensions validate samplectl-reviewed
uv run --no-sync hol-guard extensions diff samplectl-kit samplectl-reviewed

"$HOL_GUARD_NATIVE_SOURCE_COMPILER" test \
< samplectl-reviewed/artifacts/tests/fixtures/command-source-samplectl.v1.json

diff 在 kit 相等时退出 0，在有效 kit 不同时退出 1。Rust fixture runner 只评估命令文本，不执行它。如果上游导出发生变化，生成并审查新快照。

4. 预览并应用集成。 在你的贡献分支上，预览对当前 checkout 的改动：

uv run --no-sync hol-guard extensions apply samplectl-reviewed --repo .

检查列出的路径和生成的文件。运行下一条命令前，把打印出的 plan digest 复制进去：

uv run --no-sync hol-guard extensions apply samplectl-reviewed --repo . \
--expected-plan THE_PRINTED_PLAN_DIGEST \
--write

写入会集成规范源、fixture、生成的贡献描述符、外部信任映射、打包和作者归属记录。下一步重新生成完整程序和目录。已有 ID 或文件冲突会停止集成，等待审查。

5. 测试并提交 pull request。 按照 native 验证流程 重新生成完整目录，针对该程序重新构建编译器和运行时，并对集成后的源运行贡献的 fixture。这同样涵盖更新已有扩展的情况，此时向打包基线添加内容会与已有 ID 冲突。然后运行贡献检查并重新生成公开目录：

uv run --no-sync python scripts/release/stage_guard_cloud_review_artifacts.py
uv run --no-sync pytest -q \
tests/test_guard_extension_contribution.py \
tests/test_guard_extension_trust.py \
tests/test_native_source_program.py \
tests/test_guard_command_extension_registry.py
uv run --no-sync python scripts/export_extension_directory.py
uv run --no-sync python scripts/export_extension_directory.py --check
uv run --no-sync python scripts/render_command_extension_directory.py
uv run --no-sync python scripts/render_command_extension_directory.py --check
git diff --check
为破坏性操作、安全预览、别名、重排后的参数、引号处理、格式错误的输入和复合命令添加测试用例。改动原生语义时运行 Rust 检查，改动工具链时运行相关的 Python 检查。检查最终 diff，提交规范输入、生成的投影、测试用例和编写记录，并把测试结果更新到针对 main 的现有草稿 PR 上。交接检查通过后，将其标记为可供评审。不要把临时工具包目录和上游原始导出放进 PR。

社区贡献始终属于 External，且默认关闭。 测试必须证明：在本地管理员启用之前，它们不会生效。生成、应用或合并贡献都不会将其激活，其规则也无法削弱 Guard 的必需防护。

Full builder reference · Contribution review requirements · External extension contract · Builder validation

Development

The development toolchain includes Python 3.10 or newer, uv, and Rust 1.88.0, pinned in rust/rust-toolchain.toml. Rust builds the native runtime and extension compiler; Python supplies the CLI and development tooling. The commands below use a POSIX shell from the repository root. See CONTRIBUTING.md for Windows setup and the checks for each kind of change.

git clone https://github.com/hashgraph-online/hol-guard.git
cd hol-guard
uv sync --frozen --extra dev
rustup toolchain install 1.88.0 --profile minimal --component rustfmt --component clippy
cargo +1.88.0 build --locked --release --manifest-path rust/Cargo.toml \
-p guard-command --bin guard-command-source
cargo +1.88.0 build --locked --release --manifest-path rust/Cargo.toml \
-p hol-guard-runtime

export HOL_GUARD_NATIVE_SOURCE_COMPILER="$PWD/rust/target/release/guard-command-source"
export HOL_GUARD_NATIVE_TEST_SOURCE_COMPILER="$HOL_GUARD_NATIVE_SOURCE_COMPILER"
export HOL_GUARD_NATIVE_BINARY="$PWD/rust/target/release/hol-guard-runtime"

uv run --no-sync python scripts/build_native_command_program.py \
--compiler "$HOL_GUARD_NATIVE_SOURCE_COMPILER" --check
uv run --no-sync pytest tests/test_guard_extension_builder_public_docs.py \
tests/test_native_source_program.py --tb=short

Those compiler overrides are for an editable checkout. Installed native wheels use their bundled compiler and verify its manifest. After changing canonical sources or Rust semantics, regenerate the projections and rebuild as described in the validation guide.

For Python tooling and package changes:

uv run --no-sync ruff check src tests
uv run --no-sync ruff format --check src tests
uv build

For optional Cisco coverage, use the dependency group command above. See CONTRIBUTING.md for contribution requirements and the testing matrix for integration tests.

Resources

- HOL Plugin Registry
- HOL Plugin Security dataset on Hugging Face
- HOL Standards Documentation
- OpenAI Codex Plugin Documentation
- Model Context Protocol Documentation
- Cisco AI Skill Scanner
- Cisco AI MCP Scanner
- HOL GitHub Organization

Community

Maintained by Hashgraph Online.

- Report a bug or request a feature
- Browse release notes
- See who builds Guard
- Browse raw GitHub releases
- Explore the plugin security dataset

License

Licensed under Apache-2.0.