面向 AI 代理的开源杀毒软件：在运行时阻止高风险工具、机密访问、提示注入、恶意软件包、MCP 服务器、插件和技能。
 | HOL Guard 是面向 AI 代理、工具、插件、技能、MCP 服务器和软件包安装的本地优先安全层。 |
|---|
HOL Guard 在代理操作运行之前对其进行审查：shell 命令、文件访问、软件包安装和 MCP 工具调用。它能够检测密钥泄露、破坏性操作、提示注入和供应链风险，然后根据你的策略允许、阻止或请求批准。
无需账户即可在本地运行。使用 CLI 和本地仪表板来管理防护、处理审批请求并查看决策历史。可选的 Guard Cloud 增加了共享历史记录、团队策略和集群管理功能。
快速开始 · 支持的代理 · 插件扫描器 · 文档 · 贡献扩展 · 开发
需要 Python 3.10 或更高版本以及 pipx。```bash pipx install hol-guard hol-guard init
首次运行向导会检测受支持的代理，并引导你完成防护设置。在每次进行设置更改之前，它都会先询问，包括打开仪表板、安装代理集成以及连接可选的云服务。
检查你的安装：```bash
hol-guard --version
hol-guard status
要更新现有安装：```bash hol-guard update
手动设置请参阅[安装指南](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/get-started.md)。版本详情和预发布版本请查看[发布页面](https://github.com/hashgraph-online/hol-guard/releases)。
## HOL Guard 防护内容
| 防护面 | 防护说明 |
| :--- | :--- |
| **Shell 命令与文件访问** | 审查破坏性操作、敏感文件访问、凭据泄露以及可疑的外连命令。 |
| **软件包安装** | 在安装前，依据供应链情报评估受支持的包管理器操作。 |
| **插件、技能与代理配置** | 清点本地工件，并在启动前审查新增或变更的工具。 |
| **MCP 服务器与工具** | 检查服务器配置，并通过受支持的钩子和托管代理审查工具调用。 |
| **提示词与工具结果** | 筛查受支持的事件，以发现提示词注入和敏感内容。 |
| **审批与证据** | 将决策路由至原生提示或审批中心，并记录本地回执以供审查。 |
Guard 通过原生代理钩子、托管 MCP 代理和启动集成进行连接。覆盖范围取决于各代理所暴露的事件；[支持矩阵](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/harness-support.md)记录了各集成的强制执行、审批交付和故障行为。
## 支持的 AI 代理
Codex、Claude Code、GitHub Copilot CLI、Cursor、Cline、Gemini CLI、Grok、Hermes、Kimi Code、Pi、oh-my-pi、OpenClaw、OpenCode、Antigravity 和 ZCode。[Paseo](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/paseo.md) 通过这些原生提供商集成获得支持，并具有各提供商对应的覆盖范围。
例如，要显式设置 Codex：```bash
hol-guard install codex
hol-guard run codex --dry-run
hol-guard run codex
试运行会在启动前记录当前工件状态。对于 Codex，Guard 会安装原生 pre-tool 钩子，如果这些钩子缺失或被禁用，则拒绝托管启动。
检查命令的分类和匹配规则：```bash 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` 查看已记录的决策。
[扩展目录](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/extensions/README.md) 列出了由运行时注册表生成的命令覆盖范围。外部贡献需要明确选择加入；必需的核心保护保持启用。要添加覆盖范围，请遵循[扩展贡献指南](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/extensions/contributing.md)。
### 检查软件包```bash
hol-guard supply-chain sync
hol-guard supply-chain scan
hol-guard supply-chain explain [email protected] --ecosystem npm
包判定结果包含可用的公告证据和生态系统覆盖范围。有关包管理器拦截，请参阅入门指南；有关处理误报，请参阅修复指南。
本仓库还提供 plugin-scanner，这是一个供维护者在发布 agent 插件、技能和 MCP 集成之前进行安全与质量检查的 CLI。```bash
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。```bash
plugin-scanner scan . --format sarif --output plugin-scanner.sarif
plugin-scanner scan . --fail-on-severity high
质量等级使用适用于每个包的检查项。信任评分具有独立的来源和权重；请参阅 skill、MCP 和 plugin 评分参考。
将扫描器添加到插件仓库：```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 文档](https://github.com/hashgraph-online/ai-plugin-scanner-action)。action 源代码维护在 [`action/`](https://github.com/hashgraph-online/hol-guard/blob/main/action) 中。
<a id="install-the-package-you-need"></a>
<a id="resolver-safe-cisco-extra"></a>
### 可选的 Cisco 分析
基线包无需 Cisco 依赖即可运行。要添加 Cisco 技能扫描，请使用 Python 3.11 至 3.14，并在隔离环境中安装该额外组件：```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`](https://github.com/hashgraph-online/hol-guard/blob/main/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` 检测仓库中受支持的包，或显式选择生态系统：```bash
plugin-scanner scan ./plugins-repo --ecosystem claude
plugin-scanner scan ./dsh-plugin --ecosystem deepseek-harness
Plugin Scanner 在报告信任来源的同时报告质量等级。质量分数在适用的检查项之间进行归一化，因此可选表面不会抬高包的等级。
技能信任使用 HCS-28 基线适配器 ID、权重和分母规则。MCP 和 Codex 插件信任使用本地规范中记录的显式适配器、权重和贡献模式：
plugin-scanner scan ./my-plugin --format json --profile public-marketplace
plugin-scanner lint ./my-plugin --list-rules plugin-scanner lint ./my-plugin --explain README_MISSING
plugin-scanner lint ./my-plugin --fix --profile strict-security
plugin-scanner verify ./my-plugin --format json plugin-scanner verify ./my-plugin --online --format text
plugin-scanner submit ./my-plugin --profile public-marketplace --attest dist/plugin-quality.json
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 插件文档](https://developers.openai.com/codex/plugins) 和 [Model Context Protocol 规范](https://modelcontextprotocol.io)。
## 配置 + 基线示例
在 `.plugin-scanner.toml` 中配置扫描器：```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 |
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 中 agent 插件的一个示例。其 注册表条目 提供当前信任信息。
AI agent 可以在一次会话中运行命令、安装依赖、读取文件并调用外部工具。HOL Guard 在支持的执行点审查这些操作，并将策略决策、审批请求和回执保持在一起。
将其用于开发者机器上的 AI agent 安全、连接工具的 MCP 安全，以及包和插件的供应链检查。团队可以添加 Guard Cloud 以实现共享审批和策略管理，同时保留本地保护。
HOL Guard 是面向 AI agent 的开源防病毒和运行时保护。它审查受支持的工具调用、shell 命令、文件访问和包操作，以发现密钥泄露、提示注入、破坏性操作和恶意依赖等风险。
可以。本地保护、CLI 命令、审批和回执无需登录即可工作。Guard Cloud 是可选的，它增加了同步证据、团队控制和集群可见性。有关功能边界，请参阅 本地 Guard 与 Guard Cloud。
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 以保护您机器上的 agent 活动。安装 plugin-scanner 以检查插件包并在 CI 中执行安全和质量检查。本仓库构建并发布这两个发行版。
Guard 检查 MCP 服务器配置，并通过 agent 钩子和托管代理审查受支持的 MCP 工具调用。Plugin Scanner 检查 MCP 配置和 HTTP 远程可达性；可选的 Cisco MCP 分析会增加静态安全发现项。
该操作可能需要根据您的活动策略获得审批，或者其工具或产物可能已发生变化。首先运行 hol-guard approvals，使用 hol-guard command explain '<command>' 检查该命令，并使用 hol-guard receipts 查看记录的决策。
使用 Extension Builder CLI 将导出的命令元数据或 MCP 工具清单转换为贡献文件和测试。它可离线工作：读取导出内容，而无需导入或运行目标工具。
1. 提出覆盖范围。 检查 扩展目录 中现有的覆盖范围。对于新功能，请提交 扩展提案，包含拟议的 command.<name> ID、支持的操作、破坏性示例、安全对应项和上游参考。当现有扩展已拥有该操作时，请扩展该扩展。
按照 开发设置 操作，然后在您的 HOL Guard 检出目录中运行以下示例。uv run --no-sync 使用该检出目录中已安装的开发版本。
2. 生成贡献工具包。 此示例使用已检入的合成 samplectl 清单。对于您自己的贡献，请将输入和元数据替换为您工具的导出内容和公开发布者详细信息。```bash
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 工具包示例](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/extension-builder/README.md#generate-an-mcp-kit)。
**3. 审查操作并重新生成。** 阅读 `report.json`，并将发现的操作与上游实现进行对比。编辑前先复制审查文件：```bash
cp samplectl-kit/review.json samplectl-review.json
编辑 samplectl-review.json，保持其发现绑定和操作 ID 不变。CLI 操作使用 review 或 block；根操作保持为 review。对于你已评估的条目，将 reviewed: true 设置为 true，并附上理由和公开的 HTTPS 证据引用。仅对精确、已验证的安全调用添加 safeArgv。review 格式 包含完整的条目示例。
从保存的快照重新编译，而不是编辑生成的检测器或清单：```bash
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` 对相同的 kit 退出码为 `0`，对不同的有效 kit 退出码为 `1`。如果上游导出发生变化，请生成并审查新的快照。
**4. 预览并应用集成。** 在你的贡献分支上，预览对当前检出内容的更改：```bash
uv run --no-sync hol-guard extensions apply samplectl-reviewed --repo .
检查列出的路径和生成的文件。在运行以下命令之前，将打印的计划摘要复制到该命令中：```bash
uv run --no-sync hol-guard extensions apply samplectl-reviewed --repo .
--expected-plan THE_PRINTED_PLAN_DIGEST
--write
写入操作将经过审核的计划应用到贡献文件、外部信任映射、目录注册、打包以及作者归属记录。现有 ID 或冲突文件会停止集成以进行审核。
**5. 测试并提交拉取请求。** 对于 `samplectl` 示例：```bash
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 和格式化检查。检查最终 diff，提交集成和重新生成的目录，并针对 main 打开一个 PR，链接提案和测试结果。包含生成的创作记录；将临时 kit 目录和原始上游导出排除在 PR 之外。
社区贡献保持为 External 且默认关闭。 测试必须证明它们在本地管理员启用之前是惰性的。生成、应用或合并贡献不会激活它，其检测器无法削弱 Guard 的必需保护。
完整构建器参考 · 贡献审查要求 · 外部扩展契约 · 构建器验证
克隆仓库并使用 uv 安装开发依赖：```bash 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](https://github.com/hashgraph-online/hol-guard/blob/main/CONTRIBUTING.md)；有关集成测试，请参阅[测试矩阵](https://github.com/hashgraph-online/hol-guard/blob/main/docs/guard/testing-matrix.md)。
## 资源
- [HOL 插件注册表](https://hol.org/registry/plugins)
- [Hugging Face 上的 HOL 插件安全数据集](https://huggingface.co/datasets/HashgraphOnline/hol-plugin-security)
- [HOL 标准文档](https://hol.org/docs/standards)
- [OpenAI Codex 插件文档](https://developers.openai.com/codex/plugins)
- [模型上下文协议文档](https://modelcontextprotocol.io)
- [Cisco AI Skill Scanner](https://pypi.org/project/cisco-ai-skill-scanner/)
- [Cisco AI MCP Scanner](https://pypi.org/project/cisco-ai-mcp-scanner/)
- [HOL GitHub 组织](https://github.com/hashgraph-online)
## 社区
由 [Hashgraph Online](https://github.com/hashgraph-online) 维护。
- [报告 bug 或请求新功能](https://github.com/hashgraph-online/hol-guard/issues)
- [浏览发布版本](https://github.com/hashgraph-online/hol-guard/releases)
- [探索插件安全数据集](https://huggingface.co/datasets/HashgraphOnline/hol-plugin-security)
## 许可证
基于 [Apache-2.0](https://github.com/hashgraph-online/hol-guard/blob/main/LICENSE) 许可。
| 任务 | 命令 |
|---|
| 检查保护状态 | 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 |
| 类别 | 覆盖范围 |
|---|
| 清单验证 | 必填字段、版本、声明的路径、接口元数据、链接和资源。 |
| 安全性 | 硬编码密钥、不安全的 MCP 命令和传输方式，以及有风险的审批默认值。 |
| 运维安全 | GitHub Actions 权限和固定依赖、特权检出模式、Dependabot 和锁文件。 |
| 插件打包 | README 和许可证文件、技能 frontmatter、忽略规则，以及意外提交的环境文件。 |
| 市场 | 清单有效性、本地包发现和安全源路径。 |
| 技能和 MCP 分析 | 来自可选 Cisco 集成的分析器可用性、发现结果和可分析性。 |
| 代码质量 | 动态代码执行和 shell 注入模式。 |
| 用于脚本和集成的结构化报告。 |
markdown | 用于拉取请求和议题的审查就绪报告。 |
sarif | GitHub 代码扫描和安全自动化。 |
| 指南 | 内容 |
|---|
| 快速开始 | 安装、手动设置、包保护和常用命令。 |
| Agent 支持 | 集成覆盖范围和审批行为。 |
| 架构 | 运行时组件和决策流程。 |
| 策略规范 | GuardPolicy 文档格式。 |
| 策略配方 | 常见工作流的配置示例。 |
| 扩展 | 内置命令规则和贡献指南。 |
| 贡献扩展 | 使用 CLI 生成、审查、集成并测试新扩展。 |
| 本地与云 | 本地功能和可选的云服务。 |
| 故障排除 | 诊断和恢复。 |
| 安全 | 漏洞报告和披露策略。 |