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

HOL Guard：面向 AI 代理的开源杀毒软件

HOL Guard 版本
插件扫描器版本
HOL Guard 下载量
插件扫描器下载量
Python 3.10+
CI
发布
容器镜像
OpenSSF 评分卡
许可证
GitHub 星标
代码检查：ruff

| HOL 完整深色标志 | 在危险的 AI 操作危及你的机器之前将其阻止。 HOL Guard 是面向 AI 代理、工具、插件、技能、MCP 服务器和软件包安装的本地优先安全层。安装 HOL Guard阅读文档PyPI 软件包（hol-guard）报告问题 |
| :--- | :--- |

HOL Guard 会在代理操作运行之前对其进行审查：shell 命令、文件访问、软件包安装和 MCP 工具调用。它会检测密钥泄露、破坏性操作、提示注入和供应链风险，然后根据你的策略允许、阻止或请求批准。
在本地运行，无需账户。使用 CLI 和本地仪表板来管理防护、处理审批并检查决策历史。可选的 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 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。Paseo 通过这些原生提供商集成获得支持，并具有按提供商划分的覆盖范围。

例如，要显式设置 Codex：

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

试运行会在启动前记录当前工件状态。对于 Codex，Guard 会安装原生工具前钩子，如果这些钩子缺失或被禁用，则拒绝托管启动。
Agent 支持矩阵 · 故障排除

日常使用

| 任务 | 命令 |
| :--- | :--- |
| 检查保护状态 | hol-guard status |
| 诊断 agent 集成 | hol-guard doctor codex |
| 启动前检查更改 | hol-guard diff codex |
| 查看待处理的审批 | hol-guard approvals |
| 批准或拒绝请求 | hol-guard approvals approve  / hol-guard approvals deny  |
| 读取决策历史 | 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 查看已记录的决策。

扩展目录列出了从运行时注册表生成的命令覆盖范围。外部贡献需要明确选择加入；必需的核心保护仍保持启用。要添加覆盖范围，请遵循扩展贡献指南。

检查软件包

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

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

插件扫描器

本仓库还提供 plugin-scanner，这是一个供维护者在发布 agent 插件、技能和 MCP 集成之前进行安全和质量检查的 CLI。

pipx install plugin-scanner
plugin-scanner scan .
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 分析。报告支持文本、JSON、Markdown 和 SARIF。

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

质量等级使用适用于每个包的检查。信任评分有单独的溯源和权重；请参阅技能、MCP 和插件评分参考。

GitHub Actions

将扫描器添加到插件仓库：

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/ 中。

可选的 Cisco 分析

基础包无需 Cisco 依赖即可运行。要添加 Cisco 技能扫描，请使用 Python 3.11 至 3.14，并在隔离环境中安装该额外组件：

pipx install 'plugin-scanner[cisco]'

要进行 Cisco MCP 分析，请使用仓库的 Docker 镜像 或 cisco-mcp 依赖组：

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 额外组件提供技能扫描；单独的 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 | 带有 dsh.bundle、声明的补丁和 Cordis apply(ctx) 导出的 package.json，或者对于仅补丁捆绑包，将 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 检测仓库中受支持的包，或显式选择生态系统：

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

扫描器检查的内容

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

信任评分的工作原理

Plugin Scanner 在报告信任来源的同时报告质量等级。质量分数在适用的检查项之间进行归一化，因此可选表面不会抬高包的等级。

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

- 技能信任本地草案
- MCP 信任草案
- Codex 插件信任草案

CLI 用法

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 | 用于拉取请求和问题的可供审查的报告。 |
| sarif | GitHub 代码扫描和安全自动化。 |

GitHub Action

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

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

插件作者提交流程

使用 submission_enabled: true，在插件达到配置的阈值时打开或复用提交问题。submission_token 必须具有在目标提交仓库中创建问题的权限。该 action 会输出提交状态和问题 URL 作为输出。

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

用于插件生态系统自动化的注册表负载

设置 registry_payload_output 以写入供注册表或徽章流水线使用的机器可读负载。该 action 还会公开 score、grade、grade_label、max_severity 和 findings_total 输出，并可以写入作业摘要。

HOL Registry Broker 插件 是 HOL Plugin Registry 中一个代理插件的示例。其 注册表列表 提供了当前的信任信息。

为什么选择 HOL Guard
AI 智能体可以在一次会话中运行命令、安装依赖、读取文件并调用外部工具。HOL Guard 在受支持的执行点审查这些操作，并将策略决策、审批请求和回执保存在一起。

将其用于开发者机器上的 AI 智能体安全、连接工具周围的 MCP 安全，以及针对包和插件的供应链检查。团队可以添加 Guard Cloud 以实现共享审批和策略管理，同时保留本地保护。

常见问题

什么是 HOL Guard？

HOL Guard 是面向 AI 智能体的开源防病毒和运行时保护工具。它会审查受支持的工具调用、shell 命令、文件访问和包操作，以发现诸如机密泄露、提示注入、破坏性操作和恶意依赖等风险。

HOL Guard 在没有云账户的情况下能工作吗？

可以。本地保护、CLI 命令、审批和回执无需登录即可工作。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 的适配器。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 '' 检查该命令，并使用 hol-guard receipts 查看记录的决策。

文档

| 指南 | 内容 |
| :--- | :--- |
| 快速开始 | 安装、手动设置、包保护和常用命令。 |
| 智能体支持 | 集成覆盖范围和审批行为。 |
| 架构 | 运行时组件和决策流程。 |
| 策略规范 | GuardPolicy 文档格式。 |
| 策略配方 | 常见工作流的配置示例。 |
| 扩展 | 内置命令规则和贡献指南。 |
| 贡献一个扩展 | 使用 CLI 生成、审查、集成并测试一个新扩展。 |
| 本地 vs. 云端 | 本地能力和可选的云服务。 |
| 故障排除 | 诊断和恢复。 |
| 安全 | 漏洞报告和披露政策。 |

贡献一个新扩展

使用 Extension Builder CLI 将导出的命令元数据或 MCP 工具清单转换为贡献文件和测试。它可离线工作：它读取导出内容，而不会导入或运行目标工具。

1. 提出覆盖范围。 检查 扩展目录 中现有的覆盖范围。对于新能力，请打开一个 扩展提案，其中包含提议的 command. ID、支持的操作、破坏性示例、安全对应项和上游参考。当某个现有扩展已经拥有该操作时，请扩展该扩展。

按照 开发设置 操作，然后从你的 HOL Guard 检出目录运行下面的示例。uv run --no-sync 使用该检出目录中已安装的开发版本。

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、贡献元数据、原生检测器、生成的测试和一个文件清单。

其他输入：--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 贡献，生成器使用 --launcher 和 --package，而不是 --executable。有关完整命令和分页要求，请参阅 MCP 工具包示例。
3. 审查操作并重新生成。 读取 report.json，并将发现的操作与上游实现进行比较。在编辑前复制审查文件：

cp samplectl-kit/review.json samplectl-review.json

编辑 samplectl-review.json，保持其发现绑定和操作 ID 不变。CLI 操作使用 review 或 block；根操作保持为 review。对于你已评估的条目，将 reviewed: true 设置为 true，并附上理由和公开的 HTTPS 证据引用。仅对精确、已验证的安全调用添加 safeArgv。审查格式包含一个完整的条目示例。

从保存的快照重新编译，而不是编辑生成的检测器或清单：

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

diff 对于相等的套件退出码为 0，当有效套件不同时退出码为 1。如果上游导出发生变化，请生成并审查新的快照。

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

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

检查列出的路径和生成的文件。在运行以下命令之前，将打印的计划摘要复制到该命令中：

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

写入操作会将审查后的计划应用到贡献文件、外部信任映射、目录注册、打包和作者归属记录。现有 ID 或冲突文件会停止集成以进行审查。

5. 测试并提交拉取请求。 对于 samplectl 示例：

uv run --no-sync python scripts/release/stage_guard_cloud_review_artifacts.py
uv run --no-sync pytest -q tests/test_generated_cli_samplectl_extension.py
uv run --no-sync pytest -q \
tests/test_guard_extension_contribution.py \
tests/test_guard_extension_trust.py \
tests/test_guard_command_extension_registry.py
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

对于不同的 slug，请使用你生成的测试文件名。为破坏性操作、安全预览、别名、重新排序的标志、引用、格式错误的输入和复合命令添加测试用例。对更改的 Python 文件运行 lint 和格式化检查。检查最终差异，提交集成和重新生成的目录，并针对 main 打开一个 PR，链接提案和测试结果。包含生成的作者归属记录；将临时套件目录和原始上游导出排除在 PR 之外。
社区贡献保持为外部且默认关闭。 测试必须证明它们在本机管理员启用之前是惰性的。生成、应用或合并贡献不会激活它，其检测器也无法削弱 Guard 的必需保护。

完整构建器参考 · 贡献审查要求 · 外部扩展契约 · 构建器验证

开发

克隆仓库并使用 uv 安装开发依赖：

git clone https://github.com/hashgraph-online/hol-guard.git
cd hol-guard
uv sync --extra dev
uv run ruff check src tests
uv run ruff format --check src tests
uv run pytest --tb=short
uv build

对于可选的 Cisco 覆盖，请使用上面的依赖组命令。有关贡献要求，请参阅 CONTRIBUTING.md；有关集成测试，请参阅测试矩阵。

资源

- HOL 插件注册表
- Hugging Face 上的 HOL 插件安全数据集
- HOL 标准文档
- OpenAI Codex 插件文档
- 模型上下文协议文档
- Cisco AI Skill Scanner
- Cisco AI MCP Scanner
- HOL GitHub 组织

社区

由 Hashgraph Online 维护。

- 报告 bug 或请求功能
- 浏览发布版本
- 探索插件安全数据集

许可证

根据 Apache-2.0 许可。