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

	在风险性 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.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 钩子，如果这些钩子缺失或被禁用，则拒绝托管启动。

Agent 支持矩阵 · 故障排除

日常使用

任务	命令
检查保护状态	hol-guard status
诊断 agent 集成	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 [email protected] --ecosystem npm

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

插件扫描器

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

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 分析。报告支持 text、JSON、Markdown 和 SARIF。

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

质量等级使用适用于每个包的检查项。信任评分具有独立的来源和权重；请参阅 skill、MCP 和 plugin 评分参考。

GitHub Actions

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

name: Plugin security
on: [push, pull_request]

permissions:
  contents: read