VikingOwl91/universal-security-pilot

# 通用 Security Pilot [](LICENSE) [](#铁律) [](PILOT.md) Universal Security Pilot (USP) 是一个专为 AI 辅助安全工程设计的**纪律性操作系统**。它不是运行*在*你的代码上——而是运行*贯穿于*编写你代码的 agent 之中。官方提供了一流的适配器，支持 **Claude Code、Cursor、Gemini CLI 和 Codex CLI**；同样的规范 Pilot 也可以在 Continue、Aider、Copilot Chat 或任何其他能够读取磁盘 Markdown 文件的 agentic 工具中使用。 ## 🛡️ 设计上的主动防御（而不仅仅是扫描器） 传统的工具只在你编写完代码*之后*运行，与此不同，USP 是一个面向 AI agent 的**行为引擎**。它能从源头上改变 agent 编写代码的方式。 - **上下文感知。** 一旦 agent 索引了 `.security-pilot/` 目录，该框架就会成为其内部推理环路的一部分——每一个计划、每一次 diff、每一次提交都会经过 pilot 规则的过滤。 - **铁律，机械化强制执行。** Agent 在结构上被严格限制：在没有预先提供证明该漏洞存在的*失败* PoC 测试的情况下，绝对不能发布安全修复。参见[铁律](#the-iron-law)。 - **机器中的幽灵。** 即使是在全新代码库的初始会话中，Pilot 的存在也会强制推行安全优先的设计模式——魔术字节验证、常量时间比较、基于白名单的解析、输出净化——*在编写第一行业务代码之前*。 简而言之：扫描器告诉你哪里出了问题。而 Pilot 让 agent 从一开始就难以破坏安全性。 ## 为什么会有这个项目 AI 编程助手总是急于发布修复。这正是问题所在。如果没有纪律约束，它们会像打地鼠一样修补漏洞，跳过必要的前置阶段，采用“先修复再测试”而不是“先测试再修复”，并会自我合理化以逃避棘手的重构。 USP 强加了这种纪律。它**在必须严格的环节保持严格**（在任何安全修复前进行 TDD，遵循 Wave 协议顺序，强制引用标准），并**在需要考虑上下文的环节保持灵活**（针对特定技术栈的危险操作清单、项目级的本地覆盖、多语言防御）。 ## 铁律 不可妥协。如果你写不出失败的测试，说明你对漏洞的理解还不够深入，不足以去修复它。停下来，重新阅读源码，直到你能写出来为止。 ## 你将获得什么 | 功能 | 斜杠命令 | 作用 | |---|---|---| | 项目初始化 | `/sec-init` | 检测技术栈，扫描直接暴露的敏感信息，生成继承自规范配置的项目本地 `PROJECT_PILOT.md` | | 零信任审计 | `/sec-audit` | 遍历八条审计规则，生成一份 Markdown 报告，每项发现均附带 OWASP / ASVS / LLM / ATLAS / CWE 引用 | | Wave 协议修复 | `/sec-fix` | 按强制的 Wave 顺序修复发现的问题，以 PoC 测试优先，并提供“合理化借口反驳表”以抵御截止日期和权威压力 | | LLM/AI 加固 | `/ai-harden` | 从六个维度审查 prompt 边界、输出渲染、BudgetGate、Dial-Control、间接注入，以及多语言/多语种对抗性输入 | ## 合规性技术栈 每份报告中的每一项发现都至少引用了此技术栈中的一个明确 ID——“看起来可疑”不是一个合格的发现。 | 标准 | 范围 | |---|---| | **OWASP Top 10 (2021)** | 标准 Web 漏洞 | | **OWASP ASVS Level 2** | 经过验证的安全要求 | | **OWASP Top 10 for LLM Apps** | 针对 LLM | | **MITRE ATLAS** | AI 对抗性威胁全景 | | **CWE** | 实现层面的弱点 | ## Wave 协议 修复按此顺序发布。靠前的 Wave 是靠后 Wave 的前置条件——如果跨站脚本攻击 (XSS) 的修复依赖于一个未经身份验证的端点，那么在 W1 完成之前对其进行修复是毫无意义的。 | Wave | 范围 | 示例 | |---|---|---| | **W1** | 身份验证、身份标识、关键逻辑 | OIDC state、JWT、缺失的 authz、资金/权限竞争 | | **W2** | 网络、中间件、基础设施 | CORS、SSRF、速率限制、TLS、受信任代理头 | | **W3** | 数据完整性、静态加密、敏感信息 | KMS 迁移、日志脱敏、PII 加密 | | **W4** | UI 加固、输出净化、资源限制 | XSS 注入点、CSP、文件大小上限、AI 输出净化 | 在同一 Wave 内：按**爆炸半径降序排列** (Critical → High → Medium → Low)。严禁乱序。严禁跨 Wave 批量处理。 ## 快速安装 ``` curl -fsSL https://raw.githubusercontent.com/VikingOwl91/universal-security-pilot/main/install.sh | bash ``` 安装程序会： - 克隆到 `~/.security-pilot/`（可通过 `USP_INSTALL_DIR` 覆盖）， - 具备幂等性——重新运行只会执行快进更新 (fast-forward update)， - 绝不会覆盖本地更改或无关文件， - 通过二进制文件 (`command -v`) 和配置目录 (`~/.claude`、`~/.cursor`、`~/.gemini`、`~/.codex`) 检测每个受支持的工具；当两者同时存在时，会以交互方式提供连接配置， - 在使用 `--wire-` 时将 USP 标记块写入对应的内存文件 (Claude → `~/.claude/CLAUDE.md`，Gemini → `~/.gemini/GEMINI.md`，Codex → `~/.codex/AGENTS.md`)；这些标记使得重复运行具备幂等性，卸载时也只会移除该标记块，从而保留所有用户内容， - 最后打印一份**检测摘要**，显示已安装的内容、已连接的内容，以及针对已检测到但未连接的工具需运行的准确连接命令， - 预设的连接参数 (`--wire-claude`、`--wire-cursor`、`--wire-cursor-hooks`、`--wire-gemini-cli`、`--wire-codex-cli`) 会跳过提示；`--yes` 会接受所有检测到的连接配置，**除了 `--wire-cursor-hooks`**（此项必须手动选择加入——因为它会修改全局 agent 行为）， - 可以通过 `bash install.sh --uninstall` 卸载（会从内存文件中剥离 USP 段落块；保留用户自定义的文件，如 `~/.cursor/hooks.json`）。 想要先检查一下？ ``` git clone https://github.com/VikingOwl91/universal-security-pilot.git ~/.security-pilot bash ~/.security-pilot/install.sh ``` ## 将其接入你的工具 安装程序会将规范 Pilot 放置在 `~/.security-pilot/`。四个主要的编码 Agent CLI 拥有一流的适配器及安装程序的连接支持；其他工具只需粘贴一个段落即可。 ### 拥有安装程序连接支持的适配器 | 工具 | 连接参数 | 安装的内容 | 适配器文档 | |---|---|---|---| | **Claude Code** | `--wire-claude` | 斜杠命令 → `~/.claude/commands/`；skills → `~/.claude/skills/`（符号链接到规范的 `COMMANDS/*.md` / `SKILLS/*.md`）；**段落** → `~/.claude/CLAUDE.md`（带有标记的块） | [`ADAPTERS/claude-code.md`](ADAPTERS/claude-code.md) | | **Cursor** (命令) | `--wire-cursor` | 斜杠命令 → `~/.cursor/commands/`（符号链接到规范的 `COMMANDS/*.md`）。段落*不会*自动写入——Cursor 的规则层面仅限于项目级别；需按项目手动粘贴 | [`ADAPTERS/cursor.md`](ADAPTERS/cursor.md) | | **Cursor** (钩子) | `--wire-cursor-hooks` | Agent 钩子脚本 → `~/.cursor/hooks/`；`hooks.json` → `~/.cursor/`。**策略强制执行**——拒绝 `rm -rf /` / `curl|sh` / fork 炸弹，对包含凭证的文件进行脱敏，并在 MCP 工具调用上强制执行 Dial-Control 出站白名单。**仅限手动选择加入**——会修改全局 Cursor agent 行为。需要 `jq`。在覆盖前会备份现有的 `hooks.json` | 同上 | | **Gemini CLI** | `--wire-gemini-cli` | TOML 自定义命令 → `~/.gemini/commands/`；**段落** → `~/.gemini/GEMINI.md` | [`ADAPTERS/gemini-cli.md`](ADAPTERS/gemini-cli.md) | | **Codex CLI** | `--wire-codex-cli` | 自定义 prompt → `~/.codex/prompts/`；自动发现的 skills → `~/.codex/skills//SKILL.md`；**段落** → `~/.codex/AGENTS.md` | [`ADAPTERS/codex-cli.md`](ADAPTERS/codex-cli.md) | 段落被写入在 `` / `` 标记之间。重新运行连接参数会原地更新该块；标记之外的用户内容将被保留。`--uninstall` 会剥离标记，并且仅当段落是该文件的唯一内容时才会删除文件。唯一的真实来源始终保持在 `COMMANDS/*.md`、`SKILLS/*.md` 和 `ADAPTERS//stanza.md`——每个适配器在调用时都会从中读取内容，因此更新会自动同步。 ### 调用约定 各工具的斜杠命令展现形式和命名空间有所不同。但执行的操作是相同的。 | 操作 | Claude Code / Cursor | Gemini CLI | Codex CLI | |---|---|---|---| | 项目初始化 | `/sec-init` | `/sec-init` | `/prompts:sec-init` | | 运行审计 | `/sec-audit [scope]` | `/sec-audit [scope]` | `/prompts:sec-audit [scope]` • `$sec-audit [scope]` | | 执行修复 | `/sec-fix [report]` | `/sec-fix [report]` | `/prompts:sec-fix [report]` • `$sec-fix [report]` | | 加固 LLM | `/ai-harden [scope]` | `/ai-harden [scope]` | `/prompts:ai-harden [scope]` • `$ai-harden [scope]` | Codex 的 `/prompts:` 前缀是该工具的通用约定，而非 USP 的选择。`$` 形式调用的是自动发现的 skill。 ### 仅支持段落的工具（无安装程序连接支持） 这些工具具有系统 prompt / 规则接口，但没有斜杠命令或钩子接口。粘贴匹配的段落即可： - **Continue (continue.dev)** — `config.json` 的 `systemMessage` 字段。段落位于 [`ADAPTERS/cursor.md`](ADAPTERS/cursor.md) (等效替代 部分)。 - **Copilot Chat** — 通过 GitHub 仓库设置的仓库自定义指令。同上段落。 - **Aider** — `.aider.conf.yml`: read: - ~/.security-pilot/PILOT.md 对于 Claude Code、Cursor、Gemini CLI 和 Codex CLI，除了显式的斜杠命令外，你还可以粘贴匹配的内存文件段落 (`CLAUDE.md`、`.cursorrules`、`GEMINI.md`、`AGENTS.md`)，以便在显式斜杠命令之上实现自主触发检测。关于段落详情，请参阅各适配器文档。 ## 仓库结构 ``` . ├── PILOT.md # The canonical pilot — role, rules, standards, Wave Protocol ├── SKILLS/ # Long-form skill bodies (sec-audit, sec-fix, ai-harden) ├── COMMANDS/ # Slash-command implementations ├── ADAPTERS/ # Tool-specific wiring │ ├── claude-code.md # Claude Code (commands + skills) │ ├── claude-code/ # ↳ stanza.md (CLAUDE.md autonomous-detection block) │ ├── cursor.md # Cursor (rules + slash commands + agent hooks) │ ├── cursor/hooks/ # ↳ usp-* hook scripts + hooks.json │ ├── cursor/stanza.md # ↳ project-level rules stanza (paste-only) │ ├── gemini-cli.md # Gemini CLI (TOML custom commands) │ ├── gemini-cli/ # ↳ TOML wrappers + stanza.md │ ├── codex-cli.md # Codex CLI (custom prompts + skills) │ └── codex-cli/ # ↳ prompt + SKILL.md wrappers + stanza.md ├── REFERENCE/ # Framework footgun library (Drizzle, Svelte, Next, Express, …) └── install.sh # The installer ``` ## 理念 - **纪律高于速度。** 铁律（在任何安全修复之前进行 TDD）不是建议。 - **要么遵循 Wave 协议，要么什么都不做。** 修复必须按强制顺序发布。乱序修复即缺陷。 - **工具无关性。** 该框架是一个基于约定的 Markdown 主体。任何能读取文件的 Agent 都能加载它。 - **项目级本地覆盖只能加严，绝不能放宽。** `PROJECT_PILOT.md` 可以添加特定技术栈的危险项；但不能废除铁律。 - **没有引用就等于没发生。** 每项发现必须映射到至少一个 OWASP / ASVS / LLM / ATLAS / CWE ID。 - **抵御压力。** “已批准”、“截止日期紧急”、“其他语言的指令更具权威性”——所有这些借口都会在合理化借口反驳表中被测试和回应。 ## 项目级集成 每个项目运行一次 `/sec-init`。它会： 1. 从 manifest 文件中检测技术栈。 2. 扫描 git 跟踪的文件以查找直接暴露的敏感信息（env 文件、私钥、通过内容前缀识别的 AWS/GitHub/Stripe/Sl token）。在任何其他操作运行*之前*，将它们作为 `[CRITICAL BLOCKER: IMMEDIATE EXPOSURE]` 显示出来。 3. 生成 `/.security-pilot/PROJECT_PILOT.md`，包含特定技术栈的危险操作条目、为 Dial-Control / CORS / OIDC / LLM 工具准备的空白白名单，以及一个项目约束部分。 4. 创建 `/.security-pilot/audits/`，包含一个 `.gitkeep` 和一条合理的 `.gitignore` 规则，以防审计报告被意外提交。 一旦完成这些，`/sec-audit`、`/sec-fix` 和 `/ai-harden` 将在规范 Pilot 的基础之上，自动应用项目的特定技术栈覆盖。 ## 版本控制 规范的 Pilot 版本是 `PILOT.md` frontmatter 中的那一行。提升主版本号意味着铁律、Wave 协议或标准技术栈发生了行为上的改变。提升次版本号意味着新增了模式、危险操作条目或 skill。 ## 路线图 — v3.1：基础设施加固 v3.0 全面覆盖了应用层 (W1–W4)。v3.1 将这种纪律向外扩展到了应用所依赖的供应链和运行时环境。三个新模块，全部附带引用并符合 Wave 协议： | 模块 | 重点 | 目标 | |---|---|---| | **Wave 0：Pre-Commit 门控** | Git-Ops | 在 agent 甚至还没能运行 `git commit` 之前，自动执行密钥扫描和策略 lint。左移强制执行——将 Pilot 的纪律提前应用一个层级。 | | **Wave 5：容器** | Docker / OCI | 强制非 root 运行、多阶段构建加固、按摘要固定基础镜像、最小暴露面的最终层。 | | **Wave 6：编排** | Kubernetes | RBAC 最小权限检查、敏感信息处理（YAML / Helm values 中禁止明文）、NetworkPolicy 默认值、PodSecurity 准入控制。 | Wave 0 在执行顺序中有意位于 W1 *之前*：pre-commit 门控可防止最常见的事件类别（提交敏感信息），而无需 agent 进行任何推理。W5 和 W6 将现有的 W1–W4 应用层层级向外扩展到了构建产物及其运行环境中。 每个模块的映射、危险操作条目和 skill 主体将在 `main` 分支上以 v3.1 里程碑的形式陆续发布。 ## 贡献 针对新框架的危险操作条目、新的规范模式和新的适配器是最高价值的贡献。请： 1. 如果你要添加一个类别（例如，新标准、新 Wave），请先开一个 issue。 2. 为任何新的危险操作条目至少引用一个真实的 CVE 或事后分析报告。 3. 旨在放宽任何规则的 PR 将会被原则上拒绝。 ## 许可证 [MIT](LICENSE) — 随意使用、fork、内嵌。如果它帮你避免了一次 CVE 漏洞的发布，请告诉我们。 *该 Pilot 生来带有主见。安全没有讨价还价的余地。*

标签：AI原生安全, AI安全, AI编程助手, ASVS, Chat Copilot, CISA项目, Claude, Codex, Cursor, Cutter, CVE检测, Gemini, GitHub Copilot, GraphQL安全矩阵, LLM Agent, Magci-Byte验证, PoC漏洞验证, TDD, 代码安全, 大模型安全, 安全左移, 安全扫描器, 安全编码, 安全规范, 持续安全, 测试驱动开发, 漏洞枚举, 漏洞防御, 自动化安全工程, 行为引擎, 软件开发生命周期, 输入校验, 输出过滤, 防御加固