hashgraph-online/hol-guard

# HOL 防护 [](https://pypi.org/project/hol-guard/) [](https://pypi.org/project/plugin-scanner/) [](https://pypi.org/project/hol-guard/) [](https://pypi.org/project/plugin-scanner/) [](#安装所需软件包) [](https://github.com/hashgraph-online/hol-guard/actions/workflows/ci.yml) [](https://github.com/hashgraph-online/hol-guard/actions/workflows/publish.yml) [](https://github.com/hashgraph-online/hol-guard/pkgs/container/hol-guard) [](https://scorecard.dev/viewer/?uri=github.com/hashgraph-online/hol-guard) [](./LICENSE) [](https://github.com/hashgraph-online/hol-guard/stargazers) [](https://github.com/astral-sh/ruff) |  | **使用 `hol-guard` 本地保护您的 Harness。** 当您需要维护者和 CI 检查插件、技能、MCP 服务器和市场包时，请使用 `plugin-scanner`。

[PyPI 包 (`hol-guard`)](https://pypi.org/project/hol-guard/)
[PyPI 包 (`plugin-scanner`)](https://pypi.org/project/plugin-scanner/)
[HOL 插件注册表](https://hol.org/registry/plugins)
[HOL GitHub 组织](https://github.com/hashgraph-online)
[报告问题](https://github.com/hashgraph-online/hol-guard/issues) | | :--- | :--- | ## 从这里开始 | 如果您想... | 安装 | 启动方式 | | :--- | :--- | :--- | | 在工具运行前保护 Codex、Claude Code、Copilot CLI、Hermes、Cursor、Gemini 或 OpenCode | `hol-guard` | `hol-guard start` | | 在发布前于 CI 中检查和验证软件包 | `plugin-scanner` | `plugin-scanner verify .` | ## Guard 快速入门 ``` pipx install hol-guard hol-guard init ``` `hol-guard init` 是首次运行的引导设置。它会先显示一个渐进式计划，然后对每个副作用进行门控：批准仪表板，Guard 完成它，然后批准应用保护，Guard 完成它，然后批准云连接和通知。在您批准该检查点之前，不会打开或更改任何内容。仅当您已信任该计划并需要自动化时才使用 `hol-guard init --yes`。 手动和后续命令： ``` pipx run hol-guard bootstrap pipx run hol-guard hermes bootstrap pipx run hol-guard run codex --dry-run pipx run hol-guard run codex pipx run hol-guard approvals pipx run hol-guard receipts pipx run hol-guard status pipx run hol-guard connect pipx run hol-guard connect status pipx run hol-guard connect repair pipx run hol-guard sync pipx run hol-guard explain install-connect ``` 您从 Guard 获得的功能： - 检测您机器上的本地 harness 配置 - 在您信任工具前记录基线 - 在启动前对新增或更改的制品进行干净暂停 - 当 harness 无法内联提示时，将被阻止的更改排入本地主机批准中心 - 在本地存储收据，以便您稍后审查决策 - 保持同步可选，直到您真正想要共享历史记录 完整的本地流程请参见 [docs/guard/get-started.md](docs/guard/get-started.md)。

Guard 命令一览

- `hol-guard start` 显示 Guard 发现的 harness 的下一步操作。 - `hol-guard init` 作为批准检查点运行首次引导：本地仪表板、harness 发现和安装、可选的 Guard Cloud 连接以及桌面通知设置。 - `hol-guard bootstrap` 检测最佳本地 harness，启动批准中心，并在其前面安装 Guard。 - `hol-guard hermes bootstrap` 直接安装由 Guard 管理的 Hermes 覆盖包。 - `hol-guard status` 显示 Guard 当前正在监视的内容。 - `hol-guard install ` 为该 harness 创建启动器垫片。 - `hol-guard update` 在当前环境中更新已安装的 `hol-guard` 包。 - `hol-guard run --dry-run` 在您信任它之前记录一次当前状态。 - `hol-guard run ` 在启动前审查更改，并在需要时将会话交由批准中心处理。 - `hol-guard approvals` 列出待处理的批准或从终端解决它们。 - `hol-guard receipts` 显示本地批准和阻止历史记录。

Harness 批准策略

- `claude-code` Guard 优先使用 Claude 钩子，当 shell 无法提示时，再使用本地批准中心。 - `copilot` Guard 可以包装 `copilot` CLI，检测 `~/.copilot/config.json`、`~/.copilot/mcp-config.json`、工作区 `.vscode/mcp.json`，并为文档化的 `preToolUse` 和 `postToolUse` 事件安装由 Guard 管理的 Copilot 钩子线路。 Guard 不会将 VS Code Copilot 内联权限表本身视为 Guard 拦截的证据；当前的证据应来自 Guard 钩子响应、Guard 收据或明确回答 Guard 引出问题的 MCP 客户端。 - `codex` 当交互式 CLI 或 Codex 应用可以回答 MCP 引出问题时，Guard 会在同一个 Codex 聊天中进行内联询问，仅对 `codex exec` 或任何其他无响应的会话回退到本地批准中心。当 Guard 具有正确的 Codex 线程绑定时，在浏览器中批准或阻止会使用 HOL Guard 品牌的延续副本恢复同一个 Codex 线程。实时的应用服务器会话在原位继续，而无头 `codex exec` 会话通过 `codex exec resume` 恢复，并带有精确的被阻止命令上下文。如果会话无法识别，Guard 会明确告知并告诉您手动下一步操作，而不是假装它已恢复。 - `cursor` Guard 尊重 Cursor 的原生工具批准，并专注于启动前的制品信任。 - `opencode` Guard 编写包级别的策略，而 OpenCode 为受管 MCP 工具保持原生的一次、总是或拒绝提示。 - `hermes` Guard 安装一个由 Guard 管理的 Hermes 覆盖包，通过 Guard 代理路由 MCP 服务器，并对阻止的请求优先使用原生或中心传递。 - `gemini` Guard 扫描扩展，对于被阻止的更改回退到本地批准中心。

## Guard：保护级别 HOL Guard 是 AI Harness 的防病毒软件。它在您的文件被更改或网络被访问之前拦截每个工具操作，然后在毫秒内决定是允许还是阻止。 使用 `hol-guard settings set security-level ` 选择保护级别： | 级别 | 适合谁 | 阻止什么 | | :--- | :--- | :--- | | **Gentle** | 希望最小干扰的团队；经验丰富的用户 | 仅高置信度的密钥和明确的外泄 | | **Balanced** | 大多数用户（默认） | 密钥、Shell 外泄、提示注入、供应链钩子 | | **Strict** | 注重安全的团队 | 以上所有内容加上低置信度信号和不受信任的提示 | | **Paranoid** | 高安全性环境 | 以上所有内容加上任何未识别的 MCP 服务器操作 | 如果您不确定，请从 **Balanced** 开始。您可以在审查第一周的收据后升级到 **Strict**。 ## Guard：故障排除 ### 为什么我的命令被暂停了？ Guard 暂停了一个命令，因为一个或多个检测器触发了。要查看具体是什么触发了： ``` hol-guard receipts # review recent decisions hol-guard doctor # run a probe and see which detectors are active hol-guard doctor --perf # include per-detector timing ``` 如果该阻止看起来像是误报，您可以从收据视图或从 `http://localhost:6174` 的仪表板批准它。 ### 如何清除批准？ 从终端： ``` hol-guard approvals # list pending approvals hol-guard approvals clear # clear all pending approvals (prompts for confirmation) ``` 从仪表板：打开 `http://localhost:6174`，转到**批准中心**，然后使用**清除所有**按钮。在移除任何批准之前，系统会要求您确认。 ## Guard：建议同步隐私 Guard 的建议数据库更新是可选的，并且是仅拉取的。当您运行 `hol-guard advisories sync` 时，Guard 会从 `advisories.hol.org` 获取签名的建议列表。在同步期间，不会将任何本地文件路径、harness 配置、收据数据或工作区标识符发送到任何服务器。 建议同步需要一个 HOL Guard Cloud 账户。如果您尚未登录，同步将被跳过，Guard 继续使用本地捆绑的建议数据库。运行 `hol-guard login` 以连接免费账户。 ## 扫描器快速入门 ``` pipx install plugin-scanner plugin-scanner lint . plugin-scanner verify . ``` ``` # GitHub Actions PR 门控 - name: AI plugin quality gate uses: hashgraph-online/ai-plugin-scanner-action@v1 with: plugin_dir: "." fail_on_severity: high min_score: 80 ``` 何时添加 `plugin-scanner`： - 您发布插件、技能或市场包 - 您想要在发布前设置 CI 门控 - 您需要 SARIF、验证有效负载或提交制品 如果您的仓库使用像 `.agents/plugins/marketplace.json` 这样的 Codex 市场根目录，请保持 `plugin_dir: "."`。扫描器将自动发现本地的 `./plugins/...` 条目，扫描每个本地插件清单，并跳过远程市场条目，而不是将仓库根目录视为单个插件。 ## 需要更多细节？ - 贡献者设置：跳转到 [开发](#development) - 本地 Guard 文档：[docs/guard/get-started.md](docs/guard/get-started.md) - GitHub Action 文档：[hashgraph-online/ai-plugin-scanner-action](https://github.com/hashgraph-online/ai-plugin-scanner-action) - 注册表和信任参考：继续阅读下面

扫描器参考：信任评分、安装、生态系统和 CLI 命令

## 信任评分如何工作 扫描器现在在质量等级之外输出明确的信任来源： - 捆绑技能直接使用已发布的 HCS-28 基线适配器 ID、权重和分母规则 - MCP 配置信任在本地使用相同的 HCS 风格的适配器、权重和贡献模式模式 - 顶级 Codex 插件信任在本地使用相同的 HCS 风格的适配器、权重和贡献模式模式 当前本地规范： - [技能信任本地草案](docs/trust/skill-trust-local.md) - [MCP 信任草案](docs/trust/mcp-trust-draft.md) - [Codex 插件信任草案](docs/trust/plugin-trust-draft.md) 这使得质量等级和信任评分保持分离。像 `SECURITY.md` 这样的信号仍然可见，但它们的权重现在是一个命名的适配器权重，而不是原始类别分数的推断副作用。 ## 贡献者快速入门 ``` git clone https://github.com/hashgraph-online/hol-guard.git cd hol-guard uv sync --extra dev --extra cisco pytest -q ``` 当您需要不含 Cisco MCP 额外内容的精简基线路径时，请使用 `uv sync --extra dev --python 3.10`。 ## 安装所需软件包 ### 精简基线安装 Guard 包： ``` pip install hol-guard ``` 扫描器包： ``` pip install plugin-scanner ``` 精简基线保持 Python 3.10 支持完整，并始终包含已发货的 `cisco-ai-skill-scanner` 集成。 ### 完整 Cisco 覆盖 当您希望在基线技能扫描器之外获得静态 MCP 覆盖时，请在 Python 3.11+ 上安装 Cisco 额外内容： ``` pip install "hol-guard[cisco]" ``` ``` pip install "plugin-scanner[cisco]" ``` `cisco-ai-mcp-scanner` 保留在可选的 `cisco` 额外中，因为它仅支持 Python 3.11+，并且比精简基线所需的安装面更重。Cisco 目前在扫描器安装面上支持修补过的 `litellm==1.83.10` 发布版本，因此本仓库保持该 Cisco 兼容的固定版本以获得完整覆盖。 在 Guard 表面上，Cisco 额外为 `hol-guard scan`、`hol-guard preflight` 和 `hol-guard explain ` 添加可选的离线证据。使用 `--cisco-mode {auto,on,off}` 来控制本地制品扫描的消费者模式证据路径。在本次迭代中，`hol-guard run` 和 Guard 运行时提示/文件读取保护仍然是原生的 Guard 行为。 当 Hermes 或 OpenClaw 库存运行显式启用这些扫描器时，Guard 库存快照也可以携带 Cisco MCP 和技能扫描器状态。云证据模型记录扫描器源、状态、已编辑的发现文本、持续时间、映射的制品 ID 和风险组件元数据，而不存储原始本地路径或密钥。 在本次迭代中，Guard 不添加 Cisco AIBOM 运行时集成。如果 AIBOM 支持稍后返回，它应保留在证据或导出表面上，而不是 Guard 阻止或批准逻辑中。 ### Cisco 包状态 感谢 [Cisco AI Defense](https://github.com/cisco-ai-defense) 开源以下软件包。 | 包 | 在此仓库中的状态 | 备注 | | :--- | :--- | :--- | | `cisco-ai-skill-scanner` | 默认包含 | 包含在精简基线安装中。 | | `cisco-ai-mcp-scanner` | 通过 `[cisco]` 提供 | 推荐用于 Python 3.11+ 上的完整 Cisco 覆盖，包括仓库控制的 CI 和 Docker。 | | `cisco-ai-a2a-scanner` | 已推迟 | 需要实时的 A2A 端点，在本次迭代中未添加。 | | `cisco-aibom` | 已推迟 | 在本次迭代中没有 Guard 运行时集成。稍后仅在证据或导出工作流中重新考虑。 | 如果您希望在本地开发期间将两个工具放在一个 shell 中： ``` pipx install hol-guard pipx install plugin-scanner ``` 容器优先的环境可以使用发布的镜像。仓库控制的镜像在 Python 3.12 上安装了一个派生自锁的 Cisco 依赖集，因此容器默认具有完整的静态 Cisco 覆盖。 ``` docker run --rm \ -v "$PWD:/workspace" \ ghcr.io/hashgraph-online/hol-guard: \ scan /workspace --format text ``` 按包划分的命令名称： ``` hol-guard start plugin-scanner verify . ``` ## 生态系统支持 | 生态系统 | 检测面 | | :--- | :--- | | Codex | `.codex-plugin/plugin.json`, `marketplace.json`, `.agents/plugins/marketplace.json` | | Claude Code | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` | | Gemini CLI | `gemini-extension.json`, `commands/**/*.toml` | | OpenCode | `opencode.json`, `opencode.jsonc`, `.opencode/commands`, `.opencode/plugins` | 使用 `--ecosystem auto`（默认）扫描仓库中所有检测到的包，或显式选择单个生态系统。 ## 扫描器检查什么 `plugin-scanner` 支持完整的质量套件： - `scan` 用于全面表面安全和发布分析 - `lint` 用于基于规则的创作反馈 - `verify` 用于运行时和安装表面就绪检查 - `submit` 用于制品支持的提交门控 - `doctor` 用于有针对性的诊断和故障排除捆绑包 扫描器仅评估插件实际暴露的表面，然后根据适用的检查规范化最终分数。插件不会因未提供的可选表面而获得奖励或惩罚。 | 类别 | 最大分数 | 覆盖范围 | | :--- | :--- | :--- | | 清单验证 | 31 | `plugin.json`、必填字段、semver、kebab-case、推荐元数据、接口元数据、接口链接和资产、安全声明的路径 | | 安全 | 36 | `SECURITY.md`、`LICENSE`、硬编码密钥检测、危险 MCP 命令、MCP 传输加固、有风险的批准默认值、Cisco MCP 扫描状态、升级的 MCP 发现、MCP 可分析性 | | 操作安全 | 20 | SHA 固定的 GitHub Actions、`write-all`、特权不受信任的检出模式、Dependabot、依赖锁文件 | | 最佳实践 | 15 | `README.md`、技能目录、`SKILL.md` 前端数据、已提交的 `.env`、`.codexignore` | | 市场 | 15 | `.agents/plugins/marketplace.json` 有效性、旧版 `marketplace.json` 兼容性、策略字段、安全源路径 | | 技能安全 | 15 | Cisco 集成状态、升级的技能发现、可分析性 | | 代码质量 | 10 | `eval`、`new Function`、shell 注入模式 | ## CLI 用法 ``` # 扫描插件目录 plugin-scanner scan ./my-plugin # 自动检测仓库内所有支持的生态系统（默认） plugin-scanner scan ./plugins-repo --ecosystem auto # 仅扫描 Claude 包表面 plugin-scanner scan ./plugins-repo --ecosystem claude # 列出支持的生态系统 plugin-scanner --list-ecosystems # 输出 JSON plugin-scanner scan ./my-plugin --format json # 为 GitHub code scanning 编写 SARIF 报告 plugin-scanner scan ./my-plugin --format sarif --output plugin-scanner.sarif # 发现高严重性或以上问题时 CI 失败 plugin-scanner scan ./my-plugin --fail-on-severity high # 要求 Cisco 技能扫描并采用严格策略 plugin-scanner scan ./my-plugin --cisco-skill-scan on --cisco-policy strict # 要求可选的 Cisco MCP 静态分析 plugin-scanner scan ./my-plugin --cisco-mcp-scan on ``` 仅当需要与旧版自动化兼容时才使用裸露的 `plugin-scanner ./my-plugin` 形式。新的脚本和文档应 优先使用显式子命令，以便 `scan`、`lint`、`verify`、`submit` 和 `doctor` 具有可预测的帮助、标志和输出。 | 需求 | 命令 | 输出约定 | | :--- | :--- | :--- | | 人类可读的发布摘要 | `plugin-scanner scan ./my-plugin` | 首先是终端摘要，使用 `--format` 时可选 JSON/Markdown/SARIF | | 规则级别的创作反馈 | `plugin-scanner lint ./my-plugin` | 默认是人类可读的发现，使用 `--format json` 时为 JSON | | 运行时就绪细节 | `plugin-scanner verify ./my-plugin` | 默认是人类可读的通过/失败，使用 `--format json` 时为 JSON | | 可发布的质量制品 | `plugin-scanner submit ./my-plugin --attest dist/plugin-quality.json` | 为一个插件目录编写一个制品 | | 故障排除捆绑包 | `plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip` | 诊断 JSON 和捆绑制品 | ## 质量套件命令 ``` # 摘要扫描（旧版形式仍有效） plugin-scanner scan ./my-plugin --format json --profile public-marketplace # 从市场根目录扫描多插件仓库 plugin-scanner scan . --format json # 规则导向的 lint（可选机械修复） 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 . --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 ```

高级参考：规范、Action 发布、自动化和示例

## Codex 规范对齐 扫描器更紧密地遵循当前的 Codex 插件打包约定： - 本地清单路径应使用 `./` 前缀 - `.agents/plugins/marketplace.json` 是首选的市场清单位置 - 仍然支持兼容模式下的根目录 `marketplace.json` - `interface` 元数据不再需要未记录的 `type` 字段 - `verify` 在探测声明的能力之前执行 MCP 初始化握手 `lint --fix` 保留或添加文档化的 `./` 前缀，而不是删除它们。 对于仓库范围的市场，`scan`、`lint`、`verify` 和 `doctor` 可以直接针对仓库根目录。`submit` 仍然是有意的单插件，因此生成的制品指向一个具体的插件包。 ## 配置 + 基线示例 ``` # .plugin-scanner.toml [scanner] profile = "public-marketplace" baseline_file = "baseline.txt" ignore_paths = ["tests/*", "fixtures/*"] [rules] disabled = ["README_MISSING"] severity_overrides = { CODEXIGNORE_MISSING = "low" } ``` ## 示例输出 ``` 🔗 Plugin Scanner v2.0.0 Scanning: ./my-plugin ── Manifest Validation (31/31) ── ✅ plugin.json exists +4 ✅ Valid JSON +4 ✅ Required fields present +5 ✅ Version follows semver +3 ✅ Name is kebab-case +2 ✅ Recommended metadata present +4 ✅ Interface metadata complete if declared +3 ✅ Interface links and assets valid if declared +3 ✅ Declared paths are safe +3 ── Security (16/16) ── ✅ SECURITY.md found +3 ✅ LICENSE found +3 ✅ No hardcoded secrets +7 ✅ No dangerous MCP commands +0 ✅ MCP remote transports are hardened +0 ✅ No approval bypass defaults +3 ── Operational Security (0/0) ── ✅ Third-party GitHub Actions pinned to SHAs +0 ✅ No write-all GitHub Actions permissions +0 ✅ No privileged untrusted checkout patterns +0 ✅ Dependabot configured for automation surfaces +0 ✅ Dependency manifests have lockfiles +0 ── Skill Security (15/15) ── ✅ Cisco skill scan completed +3 ✅ No elevated Cisco skill findings +8 ✅ Skills analyzable +4 Findings: critical:0, high:0, medium:0, low:0, info:0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Final Score: 100/100 (A - Excellent) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ## 报告格式 | 格式 | 用例 | | :--- | :--- | | `text` | 人类可读的终端摘要，包含类别总数和发现 | | `json` | 用于工具和仪表板的结构化集成和发现 | | `markdown` | 拉取请求、问题或审查就绪摘要 | | `sarif` | GitHub 代码扫描上传和安全自动化 | ## 扫描器信号 扫描器当前检测或验证： - 硬编码密钥，如 AWS 密钥、GitHub 令牌、OpenAI 密钥、Slack 令牌、GitLab 令牌，以及通用的密码或令牌模式 - 危险的 MCP 命令模式，如 `rm -rf`、`sudo`、`curl|sh`、`wget|sh`、`eval`、`exec` 以及 PowerShell 或 `cmd /c` shell - 不安全的 MCP 远程端点，包括非 HTTPS 端点和非环回 HTTP 传输 - 在发货的插件配置或文档中有风险的 Codex 默认值，如批准绕过和无限制的沙箱默认值 - `interface` 元数据、HTTPS 链接和声明资产路径中的可发布性问题 - 工作流加固缺陷，包括未固定的第三方操作、`write-all`、特权检出模式、缺少 Dependabot 和缺少锁文件 - 当安装了可选集成时，由 Cisco `skill-scanner` 提出的技能级别问题 - 当安装了可选的 `cisco` 额外时，由 Cisco `mcp-scanner` 提出的静态 MCP 发现 ## CI 和自动化 将扫描器添加到插件仓库 CI 作业中： ``` permissions: contents: read security-events: write jobs: scan-plugin: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: hashgraph-online/ai-plugin-scanner-action@v1 with: plugin_dir: "." mode: scan profile: public-marketplace min_score: 80 fail_on_severity: high format: sarif upload_sarif: true ``` 对于多插件仓库，只要仓库具有包含本地 `./plugins/...` 条目的 `.agents/plugins/marketplace.json`，同一工作流可以继续指向 `plugin_dir: "."`。 对于此仓库中的仓库控制验证，以完整覆盖为目标的 Linux 作业在 Python 3.12 上安装 `cisco` 额外，而基线矩阵明确保持 Python 3.10 兼容性。 本地预提交风格的钩子： ``` repos: - repo: local hooks: - id: plugin-scanner name: Plugin Scanner entry: plugin-scanner language: system types: [directory] pass_filenames: false args: ["./"] ``` ## GitHub Action 市场 Action 位于专用仓库 [hashgraph-online/ai-plugin-scanner-action](https://github.com/hashgraph-online/ai-plugin-scanner-action) 中。 此仓库不再打包本地 Action 捆绑包。请使用独立的 Action 仓库获取 `action.yml`、发行说明和 Action 特定的文档。旧版别名 [hashgraph-online/hol-codex-plugin-scanner-action](https://github.com/hashgraph-online/hol-codex-plugin-scanner-action) 对现有工作流仍然可用。 当您在自己的作业中运行扫描器而不是打包的 Action 时，请在 Python 3.11+ 上安装 `plugin-scanner[cisco]` 并设置 `CISCO_MCP_SCAN=auto` 或 `CISCO_MCP_SCAN=on` 以获得完整的 Cisco MCP 覆盖。 ### 插件作者提交流程 该 Action 也可以处理提交受理。插件仓库可以将扫描器连接到 CI 中，以便通过的扫描在 [awesome-codex-plugins](https://github.com/hashgraph-online/awesome-codex-plugins) 中打开或复用提交问题。 它还输出自动化的机器友好输出： - `score`、`grade`、`grade_label`、`max_severity` 和 `findings_total` 作为 GitHub Action 输出 - 默认在作业摘要中提供简洁的 markdown 摘要 - 可选的机器可读的注册表有效负载文件，用于下游注册表、徽标或 awesome-list 自动化 预期路径是： 1. 将扫描器 Action 添加到插件 CI。 2. 要求 `min_score: 80` 和严重性门控，如 `fail_on_severity: high`。 3. 使用在 `hashgraph-online/awesome-codex-plugins` 上具有 `issues:write` 权限的令牌启用提交模式。 4. 当插件清除阈值时，Action 会打开或复用一个提交问题。 5. 问题正文包含机器可读的注册表有效负载数据，因此注册表自动化可以摄取相同的提交事件。 示例： ``` permissions: contents: read jobs: scan-plugin: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - name: Scan and submit if eligible id: scan uses: hashgraph-online/ai-plugin-scanner-action@v1 with: plugin_dir: "." min_score: 80 fail_on_severity: high submission_enabled: true submission_score_threshold: 80 submission_token: ${{ secrets.AWESOME_CODEX_PLUGINS_TOKEN }} - name: Print submission issue if: steps.scan.outputs.submission_performed == 'true' run: echo "${{ steps.scan.outputs.submission_issue_urls }}" ``` 当 `submission_enabled: true` 时需要 `submission_token`。此流程是幂等的。如果插件仓库已经提交，Action 将通过匹配现有问题正文中的精确隐藏插件 URL 标记来复用现有的打开问题，而不是打开重复的问题。 ### 插件生态系统自动化的注册表有效负载 如果您希望将相同的扫描提供给注册表、徽标管道或另一个插件生态系统自动化步骤，请直接从 Action 请求注册表有效负载文件： ``` permissions: contents: read jobs: scan-plugin: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - name: Scan plugin id: scan uses: hashgraph-online/ai-plugin-scanner-action@v1 with: plugin_dir: "." format: sarif output: ai-plugin-scanner.sarif registry_payload_output: ai-plugin-registry-payload.json - name: Show trust signals run: | echo "Score: ${{ steps.scan.outputs.score }}" echo "Grade: ${{ steps.scan.outputs.grade_label }}" echo "Max severity: ${{ steps.scan.outputs.max_severity }}" - name: Upload registry payload uses: actions/upload-artifact@v6 with: name: ai-plugin-registry-payload path: ${{ steps.scan.outputs.registry_payload_path }} ``` 注册表有效负载镜像 HOL 生态系统自动化使用的提交数据，因此一次扫描可以驱动代码扫描、审查摘要、awesome-list 受理和注册表信任摄取。 ## 开发 ``` pip install -e ".[dev,cisco]" ruff check src tests ruff format --check src pytest -q python -m build ``` 当您需要不含 Cisco MCP 额外内容的精简基线路径时，请使用 `pip install -e ".[dev]"` 或 `uv sync --extra dev --python 3.10`。 ## 仓库工作流 - Python `3.10` 到 `3.13` 的矩阵 CI - 通过 `publish.yml` 工作流发布包 - 用于仓库加固可见性的 OpenSSF 记分卡自动化 ## 安全 有关披露和响应政策，请参见 [SECURITY.md](./SECURITY.md)。 ## 贡献 贡献指南位于 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 维护者 由 HOL 维护。 ## 示例：HOL 注册表代理插件 [HOL 注册表代理 Codex 插件](https://github.com/hashgraph-online/registry-broker-codex-plugin) 在 Codex 插件和 [HOL 通用注册表](https://hol.org/registry/plugins) 之间架起了桥梁，在 Hedera 上提供代理发现、信任信号和验证身份。 [](https://hol.org/registry/plugins/hol%2Fregistry-broker-codex-plugin) HOL 注册表评分：**信任 80** / **审查 83** / **执行 74** ``` 🔗 Plugin Scanner v2.0.0 Scanning: ./registry-broker-codex-plugin ── Manifest Validation (31/31) ── ✅ plugin.json exists +4 ✅ Valid JSON +4 ✅ Required fields present +5 ✅ Version follows semver +3 ✅ Name is kebab-case +2 ✅ Recommended metadata present +4 ✅ Interface metadata complete if declared +3 ✅ Interface links and assets valid if declared +3 ✅ Declared paths are safe +3 ── Security (24/24) ── ✅ SECURITY.md found +3 ✅ LICENSE found +3 ✅ No hardcoded secrets +7 ✅ No dangerous MCP commands +3 ✅ MCP remote transports are hardened +3 ✅ No approval bypass defaults +5 ── Operational Security (20/20) ── ✅ Third-party GitHub Actions pinned to SHAs +5 ✅ No write-all GitHub Actions permissions +5 ✅ No privileged untrusted checkout patterns +3 ✅ Dependabot configured for automation surfaces +4 ✅ Dependency manifests have lockfiles +3 ── Best Practices (15/15) ── ✅ README.md found +5 ✅ Skills directory present +3 ✅ SKILL.md frontmatter valid +4 ✅ No committed .env +2 ✅ .codexignore found +1 ── Marketplace (15/15) ── ✅ marketplace.json valid +5 ✅ Policy fields present +5 ✅ Marketplace sources are safe +5 ── Skill Security (15/15) ── ✅ Cisco skill scan completed +3 ✅ No elevated Cisco skill findings +8 ✅ Skills analyzable +4 ── Code Quality (10/10) ── ✅ No eval or Function constructor +5 ✅ No shell injection patterns +5 Findings: critical:0, high:0, medium:0, low:0, info:0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Final Score: 130/130 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` 通过扫描器获得高分的插件是列入 [HOL 插件注册表](https://hol.org/registry/plugins) 的候选者。

## 资源 - [HOL 插件注册表](https://hol.org/registry/plugins) - [HOL 标准文档](https://hol.org/docs/standards) - [OpenAI Codex 插件文档](https://developers.openai.com/codex/plugins) - [模型上下文协议文档](https://modelcontextprotocol.io) - [Cisco AI 技能扫描器](https://pypi.org/project/cisco-ai-skill-scanner/) - [Cisco AI MCP 扫描器](https://pypi.org/project/cisco-ai-mcp-scanner/) - [HOL GitHub 组织](https://github.com/hashgraph-online) ## 许可证 Apache-2.0

标签：AI安全, AI工具保护, AI环境保护, Chat Copilot, Docker, HOL Guard, Plugin Scanner, PyPI, Python, 代理保护, 代码安全, 代码防护, 安全扫描, 安全防御评估, 工具运行前保护, 开发工具安全, 开发者代理, 开发者安全, 插件扫描, 无后门, 时序注入, 本地安全, 漏洞枚举, 环境安全, 结构化查询, 网络安全, 自动化安全, 请求拦截, 软件供应链安全, 远程方法调用, 逆向工具, 防护系统, 防病毒, 隐私保护