hol-guard

背景：AI Agent 时代的安全危机

2025 年起，Claude Code、OpenAI Codex、Cursor、Gemini 等 AI 编程工具迅速普及，它们能直接读写文件、执行 Shell 命令、调用 MCP 服务器——权限之大，堪比一个不知疲倦的超级程序员。但硬币的另一面是：如果这些工具本身被恶意污染，后果远比传统软件攻击更严重。

一个典型的攻击场景：攻击者发布了一个含有恶意依赖的 AI 插件，开发者将其安装到 Claude Code 或 OpenCode 中，AI 会在完全不知情的情况下将后门写入生产代码、窃取 API 密钥、甚至横向渗透整个开发环境。这种攻击不依赖任何用户交互，AI 本身就是攻击的载体。

HOL Guard（全称 Human Operated Layer Guard）正是为解决这一新威胁而生的开源项目，由 HOL（Human Operated Layer）组织维护，定位是「AI 编程工具的杀毒软件」。

项目起源与核心定位

HOL Guard 的诞生气息可追溯到 AI Agent 安全这一新兴领域。根据项目文档，它最早支持 OpenAI Codex，随后迅速扩展到 Claude Code、Cursor、Gemini、OpenCode、Pi、ZCode 等主流 AI 编程工具。2026 年 3 月创建至今（不到 3 个月），已积累了 372 颗 GitHub Stars，45 个 open issues，显示出活跃的开源社区参与度。

项目采用双包策略：

• hol-guard：面向终端用户的运行时保护工具，在 AI 工具执行操作前进行拦截和审批
• plugin-scanner：面向插件/技能开发者的 CI 质量门禁工具，扫描插件安全性、质量合规性和供应链完整性

核心功能：三层防护体系

第一层：运行时拦截（hol-guard）

hol-guard 是整个项目的旗舰产品，核心工作流程是**「工具执行前拦截 → 风险评估 → 用户审批 → 放行/阻断」**。

pipx install hol-guard
hol-guard init       # 首次引导设置
hol-guard bootstrap  # 自动检测本地 harness 并安装防护
hol-guard start      # 查看当前防护状态

启动后，Guard 会在本地 localhost:6174 开启一个 Web Dashboard（审批中心），用户可以在浏览器中查看被拦截的操作并做出决策。

多工具适配是 HOL Guard 的一大技术亮点。由于不同 AI 工具的扩展机制差异巨大（Claude Code 用 hooks、Codex 用 MCP elicitations、Copilot 用 VS Code MCP 配置、Pi 用自定义 extension 协议），Guard 为每种工具实现了专门的适配器。例如针对 Claude Code，Guard 优先使用原生 hooks，当 shell 无法内联提示时降级到本地审批中心；针对 Codex，Guard 能在浏览器内直接注入 MCP 审批 UI，恢复被阻断的 Codex 线程。

四档安全级别让用户可以根据实际需求调整防护严格程度：

• Gentle（温和）：仅拦截高置信度的密钥泄露和明显数据外传
• Balanced（均衡，默认）：覆盖密钥泄露、Shell 外传、提示词注入、供应链钩子
• Strict（严格）：在均衡基础上增加低置信度异常检测
• Paranoid（偏执）：上述全部 + 任何未知 MCP 服务器操作

第二层：插件安全扫描（plugin-scanner）

plugin-scanner 是面向插件开发者和 CI 管道的质量门禁工具，支持扫描 Codex 插件、Claude 技能、MCP 服务器、Gemini CLI 扩展等多种生态。

pipx install plugin-scanner
plugin-scanner scan ./my-plugin

扫描维度覆盖 7 大类，最高 142 分的质量评分体系：

• 清单验证（31分）：plugin.json 格式、必填字段、语义化版本、推荐元数据
• 安全扫描（36分）：SECURITY.md、LICENSE、硬编码密钥、危险 MCP 命令、MCP 传输加固
• 运维安全（20分）：GitHub Actions SHA 固定、write-all 权限检查、特权 checkout 模式
• 最佳实践（15分）：README.md 存在性、skills 目录规范、SKILL.md frontmatter
• 市场合规（15分）：marketplace.json 有效性、旧版兼容性、策略字段
• 技能安全（15分）：Cisco 技能扫描集成、权限提升发现
• 代码质量（10分）：eval/new Function 检测、Shell 注入模式识别

Cisco 集成是 plugin-scanner 的重要差异化能力。通过可选的 cisco-ai-skill-scanner 和 cisco-ai-mcp-scanner，扫描器可以检测 AI 技能中的权限提升、安全漏洞和可分析性问题。这一能力通过 uv 依赖组隔离，避免与主包产生依赖冲突。

第三层：供应链安全（supply-chain）

hol-guard supply-chain scan 可以对项目依赖进行供应链审计，hol-guard supply-chain explain <package>@<version> 可以解释特定包的来源和风险。

架构设计：模块化与多生态适配

HOL Guard 的代码库结构清晰，主要分为两个核心模块：

codex_plugin_scanner/：Scanner 工具的主体代码，包含：

• checks/：各类检查器（安全、最佳实践、代码质量、清单、生态系统）
• ecosystems/：多生态检测器（Codex、Claude Code、Gemini、OpenCode），自动发现项目中的插件清单文件
• rules/：规则注册和规格定义
• cli.py：plugin-scanner 命令行入口

guard/：Guard 运行时主体，包含：

• approval_gate.py：审批闸门核心逻辑
• store_*.py：多类型持久化存储（策略、审批、证据、回执、OAuth、威胁情报）
• adapters/：各 AI 工具的适配层
• policy/：策略引擎
• daemon/：本地守护进程
• runtime/：运行时检测逻辑

技术栈方面，项目纯 Python 实现，依赖 rich（终端美化）、cryptography（加密）、keyring（安全存储）、requests（HTTP）、cisco-ai-skill-scanner（技能扫描）。开发规范严格使用 ruff 进行 lint，basedpyright 进行类型检查。

争议与局限

尽管 HOL Guard 设计精巧，但它也面临一些现实挑战：

适配成本高：不同 AI 工具的版本迭代频繁，每个新版本都可能改变扩展机制或 MCP 协议。Guard 需要持续跟进所有主流工具的 API 变化，维护成本不容忽视。

性能开销：hol-guard 作为 AI 工具的中间拦截层，每次工具调用都经过 Guard 的检测逻辑，在 Strict 或 Paranoid 模式下可能会有可感知的延迟。

误报问题：初次部署时，Guard 会对许多正常的开发操作发出警报，用户需要花时间训练信任基线。在 Security.md 中，官方也承认存在误报可能，建议从 Balanced 模式开始，逐步适应。

平台锁定：Guard 主要针对特定生态的工具（Codex、Claude Code、Copilot 等），对非主流 AI 编程工具的支持需要额外的适配工作。

行业意义与增长趋势

HOL Guard 项目的出现标志着 AI 安全从理论走向工程实践的里程碑。随着 AI Agent 概念的爆发式普及，「AI 工具本身是否可信」这个问题正变得日益紧迫。传统安全工具无法理解 AI Agent 的行为语义，而 HOL Guard 通过 MCP 协议级别的拦截、提示词注入检测和供应链扫描，第一次将 AI 编程工具纳入系统性的安全防护体系。

项目创建不到 3 个月就获得 372 Stars，且保持着极高的 commit 频率（最近一次 push 为 2026-06-26），说明市场对这类工具有强烈需求。随着 AI Coding 工具的持续普及，HOL Guard 有望成为 AI 开发安全领域的标准配置工具。