wellwelwel/blue-spec
GitHub: wellwelwel/blue-spec
Blue Spec 是一个让 AI agent 自动检测代码安全风险、制定并逐条应用防御修复方案的安全驱动加固工具包。
Stars: 10 | Forks: 0
# 🌊 Blue Spec：安全驱动的加固
[]()
**Blue Spec** 帮助你的 AI agent 让项目变得更加安全。你只需将其指向你的代码，agent 就能弄清楚你的系统实际做了什么，然后指导你完成对它至关重要的安全工作。
- **Blue Spec** 适用于**任何编程语言**的项目，并支持 **37 个 agent** ✨
## 目录
- 🌱 [**开始使用**](#get-started)
- [**安装**](#install)
- [**命令**](#commands)
- 🧠 [**可用技能**](#available-skills)
- 🎓 [**示例**](#examples)
- 🤖 [**支持的 Agent**](#supported-agents)
- 📦 [**环境要求**](#requirements)
- 🖖 [**致谢**](#acknowledgements)
- 🧑⚖️ [**许可证**](#license)
## 开始使用
### 安装
```
npx -y blue-spec@latest init
```
- **Blue Spec** 底层运行在 **Node.js** 上，你可以使用任何你想要的语言 🃏
### 命令
一旦在你的项目中设置好 **Blue Spec**，你的 **AI** agent 就会解锁一系列斜杠命令：
| # | 命令 | 为你执行的操作 | 建议的最低投入程度 |
| --- | ------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| 1 | `/bluespec.charter` | 设定你的项目安全规则，为你提供建议或根据你的描述进行塑造_（可选）_。 | 中等 |
| 2 | `/bluespec.detect` | 读取你的代码，梳理系统的功能以及风险所在。 | 高或更高（投入程度越高，结果越好） |
| 3 | `/bluespec.plan` | 将 detect 发现的问题转化为防御计划，并为每个发现提供修复方案。 | 高 |
| 4 | `/bluespec.harden` | 将计划中的修复方案安全地、逐一应用到你的代码中。 | 高 |
| 5 | `/bluespec.verify` | 验证每个已应用的修复方案是否有效，并关闭已确认有效的修复。 | 中等 |
#### 附加命令
| 命令 | 为你执行的操作 |
| ------------------ | ----------------------------------------------------- |
| `/bluespec.repair` | 修复 **Blue Spec** 的内部追踪。 |
| `/bluespec.skills` | 按需加载安全_子_技能。 |
| `/bluespec.list` | 按名称列出 **Blue Spec** 正在追踪的所有发现。 |
## 可用技能
_子_技能是专注于特定领域的安全知识模块，各阶段会根据项目的范围按需自动加载。你也可以自己运行它们（包括在与 **Blue Spec** 无关的 prompt 中），以便在开发的同时兼顾安全性：
| _子_技能 | 路径 | 侧重点 |
| ------------ | -------------------------------- | -------------------------------------------------------- |
| `regex` | `.bluespec/skills/regex.md` | **ReDoS：** 在特定输入下会引发指数级耗时爆炸的正则表达式。 |
| `javascript` | `.bluespec/skills/javascript.md` | **语言级风险：** RCE、prototype pollution 等。 |
| `browser` | `.bluespec/skills/browser.md` | **客户端风险：** DOM XSS、origin、storage 等。 |
直接使用自由格式的 prompt，通过 **Python** 生成安全 **RegExp** 集合的示例：
```
@.bluespec/skills/regex.md
Create a collection of regular expressions in @src/utils/regex.py to validate emails and usernames.
```
这将会使用一个 hook 对每个 **RegExp** 进行 **ReDoS** 测试，保留安全的表达式，并生成类似于以下的内容：
```
import re
EMAIL = re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")
USERNAME = re.compile(r"^[a-zA-Z0-9_]{3,20}$")
def is_email(value: str) -> bool:
return EMAIL.match(value) is not None
def is_username(value: str) -> bool:
return USERNAME.match(value) is not None
```
试试看：[**devina.io/redos-checker**](https://devina.io/redos-checker)
## 示例
### `/bluespec.charter`
🧬 设定规则，或者让 **Blue Spec** 为你定义。
```
# 不带输入使用它，让 Blue Spec 提供建议
/bluespec.charter
```
```
# 或者描述它
/bluespec.charter My project is an online store that sells video games. Customers add products to a cart and pay by credit card or bank slip. They can see their orders and the status of each one.
```
接着，**Blue Spec** 会分析出这对安全性意味着什么，例如：
- 一个包含订单的购物车意味着存在一个**数据库**：
- 例如，`"数据存储在哪里？"`、`"谁可以访问它？"`、`"是否会泄露？"`。
- 客户能够查看自己的订单意味着存在某种**登录或访问控制**：
- 例如，`"一个客户能否访问另一个客户的订单？"`、`"会话是否受到保护？"`。
- 接收银行卡和银行汇款支付意味着**涉及资金和敏感数据**：
- 例如，`"是否存储了银行卡数据？"`、`"支付是否经过验证？"`。
基于此，**Blue Spec** 会为项目构建一套量身定制的安全规则，你可以随时对其进行审查和调整。
### `/bluespec.detect`
🔬 找出你的系统究竟在做什么，以及风险隐藏在哪里。
```
# 不带输入使用它，让 Blue Spec 扫描整个项目
/bluespec.detect
```
```
# 将其指向特定文件或文件夹
/bluespec.detect src/routes/ src/auth.ts
```
```
# 或者描述你想要检查的内容
/bluespec.detect make sure customer data is never exposed
```
接着，**Blue Spec** 会读取代码并映射其实际发现，例如：
- **文件上传**，系统接受用户上传的文件：
- _重要性：_ 伪装成图片的文件可能隐藏恶意代码。
- _证据：_ POST /upload 处理程序信任客户端发送的 MIME 类型，而没有检查文件的真实类型。
- **登录与会话**，用户通过登录访问其账户：
- _重要性：_ 薄弱的会话处理会让一个账户被另一个账户接管。
- _证据：_ 会话发放逻辑中，发放的会话没有设置过期时间。
从这里开始，你将获得一张清晰的系统功能及风险所在位置的映射图，为后续步骤的执行做好准备。
### `/bluespec.plan`
🛡️ 将 detect 发现的问题转化为防御计划：针对每个发现，制定需要应用的修复方案。
```
# 不带输入使用它，为 detect 映射到的每个发现计划修复
/bluespec.plan
```
```
# 将其指向 detect 已经覆盖的特定文件或文件夹
/bluespec.plan src/routes/upload.ts
```
```
# 或者描述一个需要重点关注的问题
/bluespec.plan where sensitive data could leak
```
此阶段在 detect 之后继续。detect 已经发现了系统的功能以及每项功能携带的风险，因此计划不会重复这些风险，而是决定如何应对它们。它仅基于 `/bluespec.detect` 已经映射的内容进行工作，因此请先运行 detect。每一项计划中的修复都会指向 detect 的一项发现，例如：
- **文件上传**（优先级：**严重**）
- _遵循原则：_ III. 所有输入在被验证之前都是不可信的。
- _修复：_ 检查文件的真实类型和大小，在保存时重命名，并将上传内容存储在无法作为代码执行的位置。
从这里开始，你将得到一个按优先级排序的修复列表，每一项都与一个发现绑定，随时准备在下一阶段中应用。
### `/bluespec.harden`
🔧 将计划中的修复方案安全地、逐一应用到你的代码中。
```
# 不带输入使用它以应用 plan 生成的每个修复，优先处理最高优先级
/bluespec.harden
```
```
# 将其指向 plan 已经覆盖的特定修复或文件
/bluespec.harden src/routes/upload.ts
```
```
# 或者按优先级应用：Critical、High、Medium 和/或 Low
/bluespec.harden Critical and High
```
计划已经决定了每一项修复方案，因此 harden 只需应用它即可。由于这是唯一直接接触你代码的阶段，它的操作非常谨慎：它会向你展示每一处更改并事先询问，每次只应用一个修复方案，以便每一次更改都易于审查，并且绝不会为了强行应用修复而削弱现有的安全控制。例如，针对文件上传的修复：
- **文件上传**（状态：**已应用**）
- _更改内容：_ 检查文件的真实类型和大小，拒绝任何意外内容，在保存时重命名，并将其存储在无法作为代码执行的地方。
- _更改位置：_ `handleUpload` 函数，以及它调用的存储 helper。
如果某个修复无法完全应用，harden 会在确保安全的前提下尽可能完成，并将其余部分标记为 **Partial** 或 **Blocked**，保持其开启状态。已应用并不意味着已被证明有效，这正是 verify 阶段的职责所在。
### `/bluespec.verify`
⚖️ 通过阅读代码并将其与 harden 记录的内容进行对比，验证每个已应用的修复是否有效，然后关闭确认有效的修复。
```
# 不带输入使用它以验证每个已应用的控制，优先处理最高优先级
/bluespec.verify
```
```
# 将其指向 harden 已经应用的特定控制或文件
/bluespec.verify src/routes/upload.ts
```
```
# 或者按优先级验证：Critical、High、Medium 和/或 Low
/bluespec.verify Critical and High
```
它会读取 harden 记录的每一处代码位置，并确认其是否真正符合声明，证明就来源于这种对抗，即代码与记录的比对。每个控制措施都会得出三种结论之一：**✅ 风险已消除**、**❌ 风险未消除**，或 **❓ 无法从代码判断**（当仅从代码中无法看到证据时）。在你的确认下，被证明已消除的风险将退出链条，例如：
- **文件上传**（结论：**✅ 风险已消除**）
- _如何证明：_ 阅读了上传处理程序，看到它会从文件内容检测真实文件类型，强制执行大小限制，并拒绝任何其他内容，完全符合记录的声明。
- _证据：_ `handleUpload` 函数，该函数从内容中检测真实的文件类型。
如果风险未消除（**❌ 风险未消除**），verify 会明确指出这一点，并将你送回 `/bluespec.harden`，因为该修复仍处于开启状态。
### `/bluespec.skills`
按需加载专注的安全_子_技能，并针对你的代码运行 🧠
```
# 按名称运行子技能
/bluespec.skills regex
```
```
# 查看可用的内容
/bluespec.skills
```
### `/bluespec.repair`
🧰 当重命名或移动文件导致链条混乱时，修复链条。
```
# 它不需要输入：它总是修复整个链条
/bluespec.repair
```
在重构后重命名发现或移动文件时，某个阶段可能会失去对它的追踪，从而丢失仍然重要的工作。Repair 通过读取所有 artifact 和你当前的代码来修复此问题，找到每个条目现在所在的位置，并一次性重写整个链条。
## 支持的 Agent
通过传递其 key 来选择你的 agent，例如 `npx -y blue-spec@latest init 标签：GitHub Advanced Security, MITM代理, SOC Prime, 人工智能, 安全加固, 开发工具, 暗色界面, 用户模式Hook绕过, 自动化攻击, 防御加固, 防御工作流