Codex Guard

codex-guard 是 Codex 的敏感行为拦截插件。它通过 UserPromptSubmit、PreToolUse、PermissionRequest 和 PostToolUse hooks 检查提示词、Shell、文件修改、MCP 与其他本地工具调用，并输出 Codex 支持的拒绝决策。审计日志只记录规则 ID、目标、决策和 HMAC 指纹，不写入命中的 原始秘密。

默认策略处于 enforce 模式：高风险和中风险行为会被拒绝；中风险行为可使用绑定 会话与规则的一次性例外 token。解析失败、策略不可用、审计 key 不可用或审计写入 失败时保持 fail-closed。

安装插件

支持 Codex CLI 和 ChatGPT 桌面端中的 Codex，运行平台为 macOS/Linux 的 amd64 或 arm64。仓库已包含对应运行时，不需要安装 Go，也不需要修改 /etc：

codex plugin marketplace add https://github.com/qhyuTT/codex-guard.git --ref main
codex

进入 Codex 后运行 /plugins，选择 Codex Guard，安装并启用，然后开启一个新会话。 首次启用插件 hooks 时，Codex 会要求检查并信任 hook 定义。这是普通插件的完整安装 流程；IDE 扩展目前不支持插件。

更新插件 marketplace：

codex plugin marketplace upgrade codex-guard-marketplace

运行时位于 artifacts/，对应哈希记录在 SHA256SUMS。

关闭或卸载插件

临时关闭 Codex Guard：

1. 在 Codex 中运行 /plugins。
2. 打开 Installed，选中 Codex Guard。
3. 按 Space 将插件切换为关闭状态。
4. 结束当前会话并开启新会话，确保本会话已加载的 hooks 不再继续使用。

彻底卸载插件：在 /plugins 的 Installed 页面打开 Codex Guard，选择 Uninstall，然后开启新会话。

不再需要这个 GitHub marketplace 时，先卸载插件，再执行：

codex plugin marketplace list
codex plugin marketplace remove codex-guard-marketplace

第一条命令用于确认 marketplace 名称；如果显示的名称不同，将第二条命令的最后一个 参数替换为实际名称。仅移除 marketplace 来源不能替代卸载已经安装的插件。

企业 managed hooks 不能通过 /plugins 关闭，应使用后文的企业卸载流程。

开发与测试

要求 Go 1.23 或更高版本。

make check
make build
make artifacts
./bin/codex-guard policy validate --file policies/default.json

make build 生成两个程序：终端运行时使用 bin/codex-guard；离线管理员工作站使用 bin/codex-guard-admin。运行时命令如下：

codex-guard hook --policy POLICY.json [--audit EVENTS.jsonl] [--audit-key-file KEY]
codex-guard policy validate --file POLICY.json
codex-guard self-test --policy POLICY.json [--audit EVENTS.jsonl] [--audit-key-file KEY]
codex-guard version

例外签发

签发密钥只能在隔离的管理员工作站或组织密钥服务中生成和保存，私钥不得部署到 Codex 终端、插件包、策略仓库或日志采集器：

./bin/codex-guard-admin keygen \
  --public-out ./exception-public.key \
  --private-out /secure/offline/exception-private.key

./bin/codex-guard-admin issue \
  --private-key /secure/offline/exception-private.key \
  --user alice --device laptop.example.com --session SESSION_ID \
  --rules pii.cn-id --ttl 15m

默认策略将 exception_public_key 和 exception_state_dir 留空，因此例外功能默认 关闭。启用时，只把公钥内容写入终端策略的 exception_public_key，并为 exception_state_dir 配置受管的持久目录。签发结果通过组织批准的短时秘密通道交付， 运行时优先以 CODEX_GUARD_EXCEPTION_TOKEN 提供，避免 token 出现在进程参数中；token 绑定操作系统用户、设备主机名、Codex session、规则集合和有效期，并按 nonce 一次性 消费。当前一次性状态是本机文件；它假设终端用户不能删除或回滚该目录。需要对抗已 控制终端时，应把消费状态放到受保护的本机代理或远程审批服务。

企业强制部署（可选）

以下步骤不是普通插件安装所必需的。只有需要让用户无法禁用 hooks、强制网络白名单 和集中审计时，才使用企业部署。

安装器固定使用 /opt/codex-guard、/etc/codex-guard、/etc/codex 和 /var/log/codex-guard，与 deploy/requirements.toml 一致。默认只预览；必须显式传入 --apply 才会写入。

先创建独立运行组，并把允许运行 Codex 的用户加入该组：

# Linux
sudo groupadd --system codex-guard
sudo usermod -aG codex-guard "$USER"

# macOS
sudo dseditgroup -o create codex-guard
sudo dseditgroup -o edit -a "$USER" -t user codex-guard

重新登录以刷新组成员关系，然后安装：

make build
sudo ./deploy/install.sh --binary "$PWD/bin/codex-guard"
sudo ./deploy/install.sh --apply --binary "$PWD/bin/codex-guard"

安装器会备份被替换的受管文件，并将清单写入 /var/lib/codex-guard/install-manifest.tsv。卸载同样默认只预览；它会校验当前文件 哈希，拒绝覆盖安装后被管理员修改的文件，并恢复备份版本：

sudo ./deploy/uninstall.sh
sudo ./deploy/uninstall.sh --apply

审计日志和 HMAC key 不会被卸载器删除。先按组织保留策略归档，再由管理员明确处理。 可用 --root /absolute/staging/root 在临时根目录中测试安装；非 root staging 时同时 指定当前 --owner 和 --group。完整的 systemd、launchd 和 MDM 步骤见 部署说明。

策略与审计

• policies/default.json 定义模式、域名、MCP allowlist、敏感 路径和内容规则。先用 policy validate 验证后再发布。
• /etc/codex/requirements.toml 强制启用 managed hooks、忽略用户/项目/plugin hooks、禁用 hosted WebSearch 和浏览器类能力，并把实验性网络 allowlist 限制到 api.openai.com。实验性网络字段必须在实际部署的 Codex 版本上先做小范围验证。
• /var/log/codex-guard/events.jsonl 预创建为 root:codex-guard、模式 0620；组成员 可追加但不能读取。独立采集器应以 root 读取并尽快转发 SIEM。
• /etc/codex-guard/audit.hmac 必须能被 hook 进程读取。共享运行组成员因此也能读取 key，HMAC 只能防止无 key 的事后篡改，不能对抗已控制终端或该组成员。高保证部署 应将审计写入独立的本机代理或硬件/系统密钥存储。

安全边界

Codex Guard 是纵深防御中的本地 guardrail，不是完整的防泄漏边界：

• 它不能证明 API 中转站没有保存、复制或转卖正常发送的对话。敏感工作负载应直连 可信端点或企业自有网关。
• PostToolUse 只能阻止结果继续进入后续上下文，不能撤销工具已经产生的副作用； 外传必须在 PreToolUse 或主机网络层提前拒绝。
• hosted tools（例如 WebSearch）不经过本地 function-tool hook 路径，少数专用工具 也可能选择绕过默认 hook 路径。本仓库的 requirements 禁用已知相关能力，但仍需 EDR、防火墙、DNS/代理 allowlist 和进程树监控。
• UserPromptSubmit 只扫描 hook 提供的 prompt 字段，并不等价于检查客户端最终组装 的完整 API 请求；系统上下文、附件、IDE 自动上下文和未来新增的数据路径仍需可信 网关与独立 DLP 覆盖。
• 同一事件的多个匹配 command hooks 会并发启动，一个 hook 不能阻止另一个先启动。 allow_managed_hooks_only = true 用于排除用户、项目、会话和 plugin hooks。
• 插件包中的 hooks 属于非托管 hooks，用户可以不信任或禁用；生产强制执行依赖 managed requirements，而不是插件安装本身。
• launchd/systemd 健康检查只能告警，不能保证 Codex 启动前策略有效。需要强启动门禁 时，应由 MDM/EDR 或企业启动器先运行 self-test，失败则不启动客户端。

依据当前 OpenAI 官方文档：

• Codex Hooks
• Managed configuration
• Agent approvals & security

部署前应对组织实际使用的 Codex 客户端版本做兼容性验证；受管字段和实验性网络配置 可能随版本变化。