uplift-labs/safeguard

# Safeguard AI 编码安全网。保护您的会话免受破坏性操作、凭证泄露、提示注入、无限循环和错误被静默吞噬的威胁。 纯 Bash 核心。宿主适配器将 Claude Code、Codex 和 OpenCode 的钩子协议转换为相同的核心契约。 ## 快速入门 ``` # 安装到你的项目（使用 Codex hooks） bash install.sh --target /path/to/repo --with-codex # 安装到你的项目（使用 Claude Code hooks） bash install.sh --target /path/to/repo --with-claude-code # 安装到你的项目（使用 OpenCode plugins） bash install.sh --target /path/to/repo --with-opencode # 安装所有 adapters bash install.sh --target /path/to/repo --with-codex --with-claude-code --with-opencode # 来自 GitHub 的单行命令，main 分支最新版（可能包含未发布的更改） bash <(curl -sSL https://raw.githubusercontent.com/uplift-labs/safeguard/main/remote-install.sh) --with-codex # 固定 v1.0.0 版本（Claude Code adapter） bash <(curl -sSL https://raw.githubusercontent.com/uplift-labs/safeguard/v1.0.0/remote-install.sh) --with-claude-code ``` ## 防护内容 | 防护项 | 威胁 | 操作 | |-------|--------|--------| | **damage-control** | 破坏性 shell 命令（`rm -rf /`、`DROP TABLE`、`terraform destroy`、`vault kv destroy`、`helm uninstall`、`rsync --delete` 等 40 多种模式） | 阻止或询问 | | **sensitive-file-guard** | 写入凭证文件（`.env`、`.ssh/*`、`*.pem`、`*.tfstate`） | 阻止 | | **input-sanitizer** | 正在读取的文件中的提示注入模式 | 警告 | | **loop-detector** | 同一命令重复 25 次以上（AI 陷入死循环） | 阻止 | | **error-suppression-scanner** | 被静默吞噬的错误（`except: pass`、`.unwrap()`、空 catch） | 阻止 | | **no-push-to-main** | 未经审查直接 `git push` 到 main/master 分支 | 带差异上下文询问 | ## 架构 双层设计：工具无关核心 + 特定宿主适配器。 ``` Your Project .uplift/safeguard/ core/ <-- tool-agnostic guards + multiplexer cmd/safeguard-run.sh (single entry point) guards/*.sh (6 independent guards) lib/json-field.sh (shared JSON parser) adapter/ <-- Claude Code hooks (thin translators) hooks/pre-bash.sh, pre-edit.sh, pre-read.sh, post-bash.sh adapter-codex/ <-- Codex hooks (thin translators) hooks/pre-bash.sh, pre-apply-patch.sh, permission-request.sh, post-bash.sh adapter-opencode/ <-- OpenCode plugins (server + TUI bridge) plugins/safeguard-server.js, safeguard-tui.js, bridge.js ``` **核心** 通过 stdin 接收 JSON，发出带标签的文本（`BLOCK:`、`ASK:`、`WARN:` 或空）。 **适配器** 在宿主工具的格式与核心的文本协议之间进行转换。 添加新宿主（Cursor、Windsurf 等）只需编写一个轻量级适配器，核心代码零改动。 ## 配置 Safeguard 运行时配置仅使用环境变量。适配器安装程序可能会更新宿主的钩子配置文件。 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `SAFEGUARD_DISABLED` | 未设置 | 设为 `1` 以禁用所有防护 | | `SAFEGUARD_DISABLE_DAMAGE_CONTROL` | 未设置 | 设为 `1` 以禁用特定防护 | | `SAFEGUARD_DISABLE_SENSITIVE_FILE` | 未设置 | （每种防护采用相同模式） | | `SAFEGUARD_LOOP_THRESHOLD` | 25 / 30 | 循环检测阈值 | | `SAFEGUARD_OPENCODE_BASH` | `bash` | OpenCode 适配器使用的 Bash 可执行文件 | | `SAFEGUARD_OPENCODE_ROOT` | 自动检测 | 针对 OpenCode 适配器的 Safeguard 安装根目录覆盖 | | `SAFEGUARD_OPENCODE_CORE_TIMEOUT_MS` | 10000 | OpenCode 适配器核心子进程超时时间 | | `SAFEGUARD_OPENCODE_ASK_TIMEOUT_MS` | 60000 | OpenCode 适配器审批对话框超时时间 | | `CI` | 未设置 | 设为 `true` 跳过所有防护 | ## 安装 ``` bash install.sh [--target ] [--with-codex] [--with-claude-code] [--with-opencode] ``` - `--target`：目标 Git 仓库的路径（默认值：当前目录） - `--with-codex`：同时安装 Codex 适配器钩子，合并到 `.codex/hooks.json`，并在 `.codex/config.toml` 中启用 `codex_hooks = true` - `--with-claude-code`：同时安装 Claude Code 适配器钩子，并合并到 `.claude/settings.json` - `--with-opencode`：同时安装 OpenCode server/TUI 插件，并在 `.opencode/tui.json` 中启用 TUI 桥接 - 幂等操作：重新运行会原地更新文件 - Safeguard 旨在被提交到仓库，以便在工作树中也能使用钩子 涉及合并宿主 JSON 配置的适配器安装需要 `python3`。仅核心安装仅需 Bash/Git。 ## Codex 说明 Codex 钩子通过项目本地的 `.codex/hooks.json` 启用，外加： ``` [features] codex_hooks = true ``` 项目 `.codex/` 层必须被 Codex 信任，才能加载仓库本地钩子。 Codex 目前支持来自 `PreToolUse` 的硬拒绝，但 `PreToolUse` 中的 `ask` 决策会被解析并导致 Fail-open（开放失败）。为安全起见，Safeguard 默认将核心的 `ASK:` 结果映射为 Codex 拒绝。设置 `SAFEGUARD_CODEX_ASK_MODE=warn` 可将这些结果降级为模型可见的警告。 Codex 文件编辑通常以 `apply_patch` 的形式呈现，因此 Codex 适配器会在调用现有的 `pre-edit` 防护之前解析补丁路径和新增行。这涵盖了敏感文件保护和错误吞噬扫描，而无需更改核心防护契约。 ## OpenCode 说明 OpenCode 的强制执行在 `tool.execute.before` 中进行，因此 `BLOCK:` 和已批准的 `ASK:` 决策会在工具主体执行前生效。`WARN:` 结果会在工具调用后展示，并尽可能存储在工具元数据中。 OpenCode 服务端插件无法直接打开任意的 TUI 对话框，因此适配器附带了一个配对的 TUI 插件。`ASK:` 决策使用该桥接来展示一次性允许/阻止对话框；如果桥接不可用或超时，Safeguard 会为了安全而执行 Fail-closed（闭合失败）。 OpenCode 插件以 ESM 默认导出插件对象的形式安装。在 Windows 上，适配器在回退到 `bash` 之前会自动检测 Git Bash/MSYS Bash；在需要时设置 `SAFEGUARD_OPENCODE_BASH` 以覆盖可执行文件。 OpenCode 的 `apply_patch` 编辑会在调用其他适配器使用的相同 `pre-edit` 防护之前，按路径和新增行进行解析。 ## 测试 ``` bash tests/run.sh # all tests (fixtures + unit) bash tests/run.sh fixtures # fixture tests only bash tests/run.sh unit # unit tests only bash tests/run.sh damage-control # single guard ``` ## 平台支持 - **Windows (Git Bash / MSYS2)：** 完全支持 - **Linux / macOS / WSL：** 支持 ## 为什么是 Bash？ - 除了 Bash/Git 外，核心没有其他运行时依赖 - 按照 Claude Code 的惯例，防护钩子均为 bash 脚本 - 跨 6 个防护项和多路复用器的核心表面积小 - 无需编译即可跨所有平台移植 ## 相关 - [worktree-sandbox](https://github.com/uplift-labs/worktree-sandbox) — AI 编码会话的工作树隔离（互补产品） ## 许可证 MIT

标签：AI代码生成安全, AI安全防护, AI编程助手, CI/CD安全, CISA项目, Claude Code适配器, Codex适配器, DevSecOps, Git分支保护, Llama, OpenCode插件, ProjectDiscovery, Shell安全, Streamlit, 上游代理, 人工智能安全, 代码安全审计, 凭据泄露防护, 合规性, 命令注入防御, 失败开放设计, 安全中间件, 安全策略执行, 安全网, 安全防护工具, 应用安全, 敏感文件保护, 数据保护, 数据可视化, 无限循环检测, 沙盒防护, 研发安全, 破坏性操作拦截, 终端安全, 网络安全研究, 自定义脚本, 访问控制, 错误吞没检测, 零依赖, 零日漏洞检测