subkoks/blackterminal-security

BlackTerminal Security

发现漏洞。安全交付。

一个 skill + agent 包，赋予 AI 编程代理高级应用安全工程师的直觉。
停止交付典型的安全漏洞——开始交付生产级的安全代码。

## 为什么需要这个项目 AI 编程代理能编写出功能正常的代码，但它们总是不断交付同样典型的安全漏洞——SQL injection、XSS、IDOR、硬编码密钥、Server Actions 缺失身份验证、公开的 S3 存储桶、使用 `pull_request_target` 配合拉取分支代码。这些是过去十五年里一直占据 CVE 头条的安全缺陷。 **BlackTerminal Security 解决了这个问题。** 它是一套检测模式、漏洞分类、威胁建模规范以及一个专门的 auditor agent，旨在教会你的 AI 队友**像高级安全工程师一样思考**——寻找信任边界、将输入与 sink 匹配、检查每条状态变更路径上的权限、将每一个密钥都视为已泄露、默认采取失败封闭（fail closed）策略。 ### 它能捕获的漏洞类型 - **Injection** — SQLi、NoSQLi、命令注入、代码注入、模板注入、XSS、LDAP、XPath - **访问控制失效（Broken Access Control）** — IDOR、BOLA、BOPLA、身份验证缺失、批量赋值、Server Action 授权缺陷、`x-middleware-subrequest` 绕过类 - **加密失败** — MD5/SHA1、使用 `Math.random()` 生成 token、ECB 模式、硬编码密钥、JWT `alg: none`、HS256/RS256 混淆、使用 `===` 进行 HMAC 比较 - **SSRF** — 包括私有 IP / 云元数据 / `file://` / TOCTOU - **路径穿越** — 无前缀检查的 `path.join`、使用原始输入的 `send_file` - **不安全的反序列化** — `pickle.loads`、`yaml.load`、`ObjectInputStream`、`vm2` - **硬编码密钥** — AWS、GitHub、Stripe、OpenAI、Anthropic、Slack、JWTs、私钥（超过 25 种模式） - **云配置错误** — 公开的 S3、IAM `*:*`、`0.0.0.0/0:22`、IMDSv1、未启用加密 - **容器 / k8s** — `privileged: true`、`runAsUser: 0`、`hostNetwork`、挂载 `/var/run/docker.sock`、`image:latest` - **CI/CD** — `pull_request_target` + 拉取分支代码、可变的 Action 标签（CVE-2025-30066 类）、通过 PR 标题进行 shell 注入 - **身份验证缺陷** — 存储在 localStorage 中的 JWT、无 MFA、登录缺失速率限制、可预测的重置 token - **开放重定向** — `//evil.com` 绕过类 - **Markdown 数据泄露** — 由密钥构造的图片 URL（EchoLeak 类） - **LLM 特有漏洞** — 输出至 eval、过度代理、系统 prompt 中包含密钥 ## 包含哪些内容 | 组件 | 类型 | 作用 | |-----------|------|-------------| | **`blackterminal-security`** | Skill | 核心安全规范——当你的代理读取、写入或审查代码时自动加载。包含五项规范、威胁建模检查清单、检测速查表。 | | **`security-audit`** | Skill | 斜杠命令审查。扫描文件/目录/PR/代码库以查找漏洞，返回按严重程度排序的报告并附带 CWE/OWASP 映射。 | | **`security-auditor`** | Agent | 只读的高级安全工程师子代理。无法写入、编辑或删除。使用 OWASP Top 10 + CWE Top 25 + 威胁模型审查每一个文件。 | | **`scan.sh`** | Script | 用于 pre-commit / CI 的快速离线正则表达式扫描。兼容 macOS bash 3.2。 | ### 参考文档 该 skill 附带八份深入的参考文档（约 50 页的专家级内容）： - **vulnerability-taxonomies.md** — OWASP Top 10 (2021)、API Top 10 (2023)、Mobile Top 10 (2024)、LLM Top 10 (2025)、CWE Top 25 (2024)、CISA KEV 常见漏洞类、DBIR 主要攻击向量 - **language-patterns.md** — JS/TS、Python、Go、Rust、Java/Spring、Ruby/Rails、PHP——包含漏洞代码与修复代码对，按 ORM 分类的 SQLi 参考 - **frontend-patterns.md** — React、Next.js（Server Actions、middleware、hydration）、Vue、Svelte、浏览器特定问题 - **infrastructure-patterns.md** — AWS、GCP、Azure、Docker、Kubernetes、Terraform、GitHub Actions、GitLab CI - **secrets-patterns.md** — 针对超过 25 种密钥类型的正则表达式目录 - **case-studies.md** — Log4Shell、Spring4Shell、MOVEit、XZ 后门、Polyfill.io、Snowflake、Ivanti、regreSSHion、Next.js CVE-2025-29927、tj-actions 供应链、近期的 agent CVE - **tooling.md** — Semgrep、CodeQL、Snyk、Trivy、Gitleaks、OSV、govulncheck、Brakeman、Checkov、kube-bench、MobSF - **threat-modeling.md** — 完整的 10 问威胁建模规范 ## 安装说明 此代码库是唯一的事实来源。`install.sh` 会将 skill 和 agent 软链接到所有受支持的编辑器中，因此在此处执行 `git pull` 即可到处更新它们——没有副本，没有版本偏移。 ``` git clone https://github.com/subkoks/blackterminal-security.git cd blackterminal-security ./install.sh # detect installed editors, symlink skills + agent ./install.sh --dry-run # preview actions ./install.sh --with-hooks # also install the pre-commit scan hook in this repo ./install.sh --uninstall # remove all symlinks ``` 它将仅为机器上存在的编辑器进行配置连接： | 目标平台 | 路径 | |--------|------| | Cursor（标准源） | `~/.cursor/skills/blackterminal-security`、`~/.cursor/skills/security-audit` | | Claude Code（skills） | `~/.claude/skills/*` → Cursor 标准源 | | Claude Code（agent） | `~/.claude/agents/security-auditor.md` | | Windsurf | `~/.codeium/windsurf/skills/*` | | `~/.agents` 镜像 | `~/.agents/skills/*` | Codex / Copilot 直接使用 `SKILL.md` —— 只需将它们的指令文件指向此代码库即可。 ### 手动安装 / 项目级别 ``` mkdir -p .claude/skills .claude/agents cp -r skills/blackterminal-security .claude/skills/ cp -r skills/security-audit .claude/skills/ cp agents/security-auditor.md .claude/agents/ ``` ## 工作原理 ### 五大规范 安装后，当你的代理读取、写入或审查代码时，`blackterminal-security` skill 就会被激活。你的代理现在会像资深专家一样思考： 1. **寻找信任边界** —— 不受信任的数据进入受信任代码的每一个地方。 2. **将输入与 sink 匹配** —— 每一个 `(source, sink)` 对都是一个潜在的漏洞。 3. **对每条改变状态的路径进行身份验证** —— 身份验证 + 授权（检查所有权，而不仅仅是角色）+ 输入验证。 4. **假设密钥已经泄露** —— 将轮换作为默认计划，并为此做好准备。 5. **失败封闭、大声记录日志、缩小影响范围** —— 默认拒绝、脱敏错误信息、审计日志、网络/IAM 隔离。 ### 10 问威胁模型 在宣布代码“安全”之前： 1. 信任边界——数据在哪里跨越？ 2. AuthN/AuthZ——是否在服务端并检查了所有权？ 3. 输入验证——是否在边界处使用了 schema？ 4. 输出编码——上下文是否正确？ 5. 密钥——存储安全并执行了轮换吗？ 6. 失败模式——失败时是否采取封闭策略？ 7. 影响范围——如果被攻破会波及什么？ 8. 供应链——是否锁定版本并经过审计？ 9. 日志记录——是否捕获了安全事件？PII 是否脱敏？ 10. 重放保护——是否实现了幂等性、nonce、CSRF、速率限制？ 如果任何一个回答是“我不知道”——该代码就**没有**通过审查。 ### 审查模式 ``` > /security-audit src/api/users.ts > /security-audit https://github.com/owner/repo/pull/123 > /security-audit ./terraform/ > /security-audit "all server actions in this app" ``` `security-auditor` agent 将遍历目标，应用全部 20 个审查类别，并生成一份按严重程度排序的报告，包含： - **文件:行号** —— 确切位置 - **类别** —— 漏洞类别 - **CWE / OWASP** —— 规范 ID - **代码** —— 原样呈现的漏洞代码片段 - **漏洞利用场景** —— 具体而非泛泛而谈 - **修复方案** —— 补丁后的代码 - **参考** —— 指向 CWE、OWASP 和 BlackTerminal Security 参考的链接 ### 快速离线扫描 ``` ./scripts/scan.sh ./src # exit 0 clean, 1 findings, 2 usage ``` 将其用作 pre-commit 的门禁（`./install.sh --with_hooks`）或在 CI 中使用——参见 `.github/workflows/security-scan.yml`。 ## 何时使用 如果你的代理符合以下情况，请安装此工具： - 编写任何生产环境代码 - 审查 PR 或 diff - 生成基础设施即代码（Terraform、Kubernetes、Dockerfiles） - 修改 CI/CD 配置（GitHub Actions、GitLab CI） - 重构身份验证 / 授权 / 支付代码 - 在任何代码路径中处理用户输入 - 编写 Server Actions、RPC handler、API endpoint - 接触任何包含 `eval`、`exec`、`query`、`fetch`、`redirect`、文件路径或密钥的代码 如果你的代理只编写纯函数和单元测试，你可能不需要这个。**除此之外的其他人都需要。** ## 项目布局 ``` blackterminal-security/ ├── .claude-plugin/ │ └── plugin.json ├── .github/ │ └── workflows/ │ └── security-scan.yml ├── skills/ │ ├── blackterminal-security/ │ │ ├── SKILL.md │ │ └── references/ │ │ ├── vulnerability-taxonomies.md │ │ ├── language-patterns.md │ │ ├── frontend-patterns.md │ │ ├── infrastructure-patterns.md │ │ ├── secrets-patterns.md │ │ ├── case-studies.md │ │ ├── tooling.md │ │ └── threat-modeling.md │ └── security-audit/ │ └── SKILL.md ├── agents/ │ └── security-auditor.md ├── hooks/ │ └── pre-commit ├── scripts/ │ └── scan.sh └── install.sh ``` ## 兼容性 使用受 30 多种 AI 编程工具支持的标准 **SKILL.md / agent** 包格式。 | 工具 | Skills | 子 Agent | 备注 | |------|--------|----------|-------| | Claude Code | ✅ | ✅ | 全面支持 skill + agent | | Cursor | ✅ | — | `~/.cursor/skills/` | | Windsurf | ✅ | — | `~/.codeium/windsurf/skills/` | | OpenAI Codex | ✅ | — | Skill 格式 | | Gemini CLI | ✅ | — | Skill 格式 | | Cline / Roo Code | ✅ | — | Skill 格式 | | GitHub Copilot | ✅ | — | 通过 `.github/copilot-instructions.md` 引用 | | Continue.dev | ✅ | — | Skill 格式 | | Goose | ✅ | — | Skill 格式 | ## 它不能做什么 - **它不是 SAST 工具。** 它是一种*思考*技能。请将其与 Semgrep / CodeQL / Snyk / Trivy 搭配使用——该 skill 知道如何调用它们并整合输出。 - **它不是绝对的保证。** 安全是分层实现的。此 skill 能让你的代理表现得更好；但不能保证你的代码绝对无法攻破。 - **不能取代人工审查。** 在高风险流程（支付、身份验证、加密、IAM）中尤其如此。 - **它不是运行时防御。** 它捕获的是代码编写阶段的问题。WAF、沙箱和可观测性由其他层面的工具负责。 它是你技术栈中的一层。请将它与其他层级结合使用：CI 中的 SAST、依赖扫描、密钥扫描、容器扫描、IaC 扫描、DAST、运行时可观测性，以及针对高风险变更的人工安全审查。 ## 权威参考 此 skill 综合了以下来源的指导： - [OWASP Top 10 (2021)](https://owasp.org/Top10/) - [OWASP API 安全 Top 10 (2023)](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) - [OWASP 移动应用 Top 10 (2024)](https://owasp.org/www-project-mobile-top-10/) - [OWASP LLM Top 10 (2025)](https://genai.owasp.org/llm-top-10/) - [CWE Top 25 (2024)](https://cwe.mitre.org/top25/archive/2024/2024_cwe_top25.html) - [CISA 已知被利用漏洞](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) - [Verizon DBIR](https://www.verizon.com/business/resources/reports/dbir/) - [NIST NVD](https://nvd.nist.gov/) - [CIS Benchmarks](https://www.cisecurity.org/cis-benchmarks/) - [NSA/CISA Kubernetes 加固指南 v1.2](https://media.defense.gov/2022/Aug/29/2003066362/-1/-1/0/CTR_KUBERNETES_HARDENING_GUIDANCE_1.2_20220829.PDF) - [GitHub Actions 安全加固](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) - [OWASP 速查表系列](https://cheatsheetseries.owasp.org/) ## 许可证 MIT。详见 [许可证](LICENSE)。 *BlackTerminal Security。发现漏洞。安全交付。*

标签：AI编程助手, DevSecOps, 上游代理, 代码安全审计, 安全开发生命周期, 应用安全, 错误基检测, 静态代码分析