giangnvh/vbsec

# vbsec — 源代码安全扫描器 一个多平台 agent skill，可执行深入的安全扫描并检测源代码中 20 多种最常见的安全漏洞。原生运行于 **Claude Code**、**OpenAI Codex CLI** 和 **Google Antigravity**。 [](https://opensource.org/licenses/MIT) [](https://docs.claude.com/claude-code) [](https://developers.openai.com/codex/skills) [](https://antigravity.google/docs/skills) ## 介绍 AI 生成的代码现在在业界的新提交中占了很大一部分。虽然现代编程助手非常擅长生成*能运行*的代码，但它们常常会发布带有典型安全陷阱的代码：硬编码的 secret、SQL injection、缺失的访问控制、弱密码哈希、JWT 误用以及配置错误的 CORS。这些错误很少在功能测试中暴露出来——它们往往是在安全事件报告中才浮现。 vbsec 将生产级别的安全审查引入到 AI 编程循环中。它作为原生的 agent skill 运行在三个平台上——在 Claude Code 中输入 `/vbs-scan-security`，在 OpenAI Codex CLI 中输入 `$vbs-scan-security`（或 `/skills`），或者直接让 Google Antigravity “scan security”——然后你就会收到一份涵盖 20 多个漏洞类别的结构化报告。它不需要外部 API 调用，不需要安装单独的工具，也不需要维护额外的基础设施。 vbsec 已经针对故意设计存在漏洞的开源训练应用（例如 OWASP Juice Shop）进行了测试——并且能够识别出与已记录的漏洞挑战相匹配的发现，涵盖 SQL injection、NoSQL injection、JWT 误用、Broken Access Control、Mass Assignment、Deserialization RCE 等。 通用规则适用于每种语言。针对 Go、PHP、TypeScript/JavaScript 和 Python 提供了专门的规则覆盖，涵盖了常见的框架：React、Vue、Angular、Express、NestJS、Next.js、Django、Flask、FastAPI、SQLAlchemy、Sequelize、Prisma 和 Mongoose。更多的语言覆盖已在路线图中。 ## 工作原理 vbsec 的设计基于一些精挑细选的决策，这使其有别于传统的模式扫描器。 - **推理优先，而非模式计数。** vbsec 不会盲目地 grep 搜索 `eval(` 或 `query(`。每一个潜在的发现都会通过阅读周围代码、追踪数据流（从 L1 不可信用户输入到 L4 可信系统数据）来验证，并确认数据在没有经过清理的情况下到达了危险的 sink。这消除了基于正则表达式的扫描器典型的误报泛滥问题。 - **基于大小的路由。** 小型扫描（≤20 个主语言文件且总计 ≤30 个文件）会在 30-60 秒内以内联方式运行。较大的扫描会自动将工作委托给并行运行的 sub-agents——每个顶级文件夹对应一个分块——并集中汇总发现。用户体验是完全相同的；只是执行策略有所变化。 - **针对大型代码库的 Sub-agent 委托。** 对于包含数百个文件的代码库，vbsec 会通过 Claude Code 的通用 agent 生成最多三个并行的 sub-agents。每个 sub-agent 独立扫描一个文件块，发现的漏洞将根据 `(file, line, rule_id)` 进行去重聚合。即使在 monorepo 中，这也能确保实际耗时保持在有界范围内。 - **语言覆盖系统。** 当 vbsec 检测到主要语言时，它会从 `rules/languages//` 加载特定语言的规则文件，这些文件会覆盖该语言的通用规则。这可以捕获特定于框架的模式：Mongoose `$where` NoSQL injection、Angular `bypassSecurityTrustHtml`、Sequelize 模板字符串 SQL、JWT algorithm confusion、在生产构建中开启 Gin debug 模式。 - **L1–L4 数据流分类。** 输入按信任级别进行分类。只有当 `x` 来源于 L1（用户控制的输入）并且在未进行参数化的情况下到达 SQL sink 时，`db.query(\`SELECT ${x}\`)` 调用才会被报告为一个发现。常量、环境变量和受信任来源的数据不会产生误报。 - **一个发现对应一条规则。** 一行同时触发 IDOR 和 Race Condition 的代码会产生两个发现——绝不会是逗号分隔的双重标签。这确保了计数的真实性、报告的可审计性，以及报告尾部的 JSON 摘要可被机器解析。 - **双语报告。** 越南语是默认语言；可通过 `lang=en` 选择英语。报告尾部的 JSON 摘要始终为标准的英文，以供 CI 和工具使用。 - **多平台。** 一套标准的规则集，三个平台变体。Claude Code 在进行大型扫描时使用并行 sub-agents；Codex 和 Antigravity 使用具有相同输出的顺序分块。一个单一的 `sync-skills.sh` 脚本可保持所有三个平台的规则定义同步。 ## 多平台支持 vbsec 从单一事实来源发布了三个变体： | 平台 | Skill 文件夹 | 安装目标 | LARGE 模式策略 | |---|---|---|---| | Claude Code | `skills/vbs-scan-security/` | `~/.claude/skills/vbs-scan-security` | 并行 sub-agents（3 个并发） | | OpenAI Codex CLI | `skills/codex/vbs-scan-security/` | `~/.agents/skills/vbs-scan-security` | 顺序分块 | | Google Antigravity | `skills/antigravity/vbs-scan-security/` | `~/.gemini/antigravity/skills/vbs-scan-security` | 顺序分块 | 这三者共享相同的 32 条规则、语言覆盖、i18n 字符串和输出格式。发现的漏洞是相同的；只是执行策略不同。在大型代码库上，顺序变体的实际耗时比 Claude Code 的并行模式慢约 3 倍，但会生成相同的 JSON 摘要和相同的 Markdown 报告。 贡献者：在 `skills/vbs-scan-security/`（标准的 Claude 文件夹）中编辑规则，然后运行 `./scripts/sync-skills.sh` 以将其同步到 Codex 和 Antigravity 变体。特定于平台的文件（`SKILL.md`、`workflows/large-review*.md`）需要手动维护。 ## 安装说明 vbsec 会自动检测你已安装的所有受支持平台，并自动配置该 skill。运行： ``` git clone https://github.com/giangnvh/vbsec ~/vbsec cd ~/vbsec ./scripts/install.sh # auto-detect, install for what's present ./scripts/install.sh --all # force install for all 3 platforms regardless ``` 检测逻辑： - **Claude Code** — PATH 中的 `claude` 二进制文件 - **OpenAI Codex CLI** — PATH 中的 `codex` 二进制文件 - **Google Antigravity** — 位于 `/Applications/Antigravity.app` 的应用（macOS）或 PATH 中的 CLI 工具 `agy`（通过 Antigravity IDE 菜单安装） Antigravity 是一个 IDE（如 VS Code），而不是 CLI。对于一个全新的 Antigravity 用户，文件夹 `~/.gemini/antigravity/skills/` 默认不存在——安装程序会为你创建它。 安装程序会将相应的 skill 文件夹符号链接到每个平台的预期位置。以后若要更新： ``` cd ~/vbsec && git pull ``` （符号链接会自动获取新版本；如有必要，请重启 CLI / IDE。） **针对单个平台的手动安装：** ``` # Claude Code ln -sfn ~/vbsec/skills/vbs-scan-security ~/.claude/skills/vbs-scan-security # OpenAI Codex CLI ln -sfn ~/vbsec/skills/codex/vbs-scan-security ~/.agents/skills/vbs-scan-security # Google Antigravity ln -sfn ~/vbsec/skills/antigravity/vbs-scan-security ~/.gemini/antigravity/skills/vbs-scan-security ``` 在每个平台上验证安装： ``` Claude Code: /vbs-scan-security Codex: $vbs-scan-security (or /skills, then pick) Antigravity: "scan security cho repo này" (auto-trigger by description) ``` 有关先决条件、故障排除和更新过程，请参阅 [docs/en/installation.md](docs/en/installation.md)。 ## 用法 默认范围是整个代码库。这是对早期版本特意做出的改变，符合团队通常要求进行安全审计的方式。 ``` /vbs-scan-security # scan entire folder (default) /vbs-scan-security uncommitted # only scan uncommitted changes /vbs-scan-security pr id 42 lang=en # scan a PR, report in English /vbs-scan-security commit within 7days # scan last 7 days of commits ``` **无需 git 即可工作。** Vibe coders 极少会在将 AI 生成的代码粘贴到文件夹之前初始化 `git`。当不存在 `.git/` 时，默认范围（`/vbs-scan-security`）会直接遍历文件系统——常见的构建/vendored 文件夹会自动排除。特定于 git 的范围（`uncommitted`、`staged`、`commit within`、`commit id`、`pr id`）仍然需要 git 代码库，并会打印一条有用的消息，要求你初始化 git 或回退到默认范围。 报告将保存到扫描文件夹内的 `vbsec-reports/scan-.md` 中，方便重新阅读、与审查者共享以及附加到修复工单中。 有关包括 `staged`、单次提交扫描以及通过 `gh` 进行 PR 扫描在内的所有选项，请参阅 [docs/en/usage.md](docs/en/usage.md)。 ## vbsec 可检测到的漏洞 | # | Rule ID | 最高严重程度 | 专门适用于 | |---|---|---|---| | 1 | `HARDCODED-SECRET` | CRITICAL | — | | 2 | `SQL-INJECTION` | CRITICAL | go, php, typescript | | 3 | `XSS` | HIGH | typescript | | 4 | `IDOR` | HIGH | — | | 5 | `SLOPSQUATTING` | CRITICAL | — | | 6 | `BRUTE-FORCE` | HIGH | — | | 7 | `MASS-ASSIGNMENT` | CRITICAL | typescript | | 8 | `INSECURE-DESERIALIZATION` | CRITICAL | go, php, typescript | | 9 | `SSRF` | HIGH | go, typescript | | 10 | `PATH-TRAVERSAL` | HIGH | — | | 11 | `CSRF` | HIGH | php, typescript | | 12 | `BROKEN-ACCESS-CONTROL` | CRITICAL | — | | 13 | `WEAK-PASSWORD-HASHING` | CRITICAL | — | | 14 | `JWT-NONE-ALGORITHM` | CRITICAL | typescript | | 15 | `CORS-MISCONFIG` | HIGH | typescript | | 16 | `UNRESTRICTED-FILE-UPLOAD` | CRITICAL | — | | 17 | `VERBOSE-ERROR-DEBUG-MODE` | HIGH | go, php, typescript | | 18 | `MISSING-RATE-LIMIT` | HIGH | — | | 19 | `RACE-CONDITION` | HIGH | — | | 20 | `OUTDATED-DEPENDENCY` | HIGH | — | | 21 | `COMMAND-INJECTION` | CRITICAL | go, php, typescript | | 22 | `SSTI` | CRITICAL | — | | 23 | `NOSQL-INJECTION` | CRITICAL | — | | 24 | `OPEN-REDIRECT` | HIGH | — | | 25 | `XXE` | CRITICAL | — | | 26 | `INSECURE-COOKIE` | HIGH | — | | 27 | `SECURITY-HEADERS` | MEDIUM | — | | 28 | `WEAK-CRYPTO` | HIGH | — | | 29 | `PROTOTYPE-POLLUTION` | HIGH | — | | 30 | `PROMPT-INJECTION` | HIGH | — | | 31 | `INSECURE-LLM-OUTPUT` | CRITICAL | — | | 32 | `IAC-MISCONFIG` | CRITICAL | — | 该列表目前包含 32 条规则，并将继续扩充。规则 30–31 涵盖了 **LLM 应用安全**（OWASP LLM Top 10），规则 32 涵盖了 **Infrastructure-as-Code / CI** 配置错误——这两者都与 AI 生成的项目日益相关。 ## 文档 - [安装](docs/en/installation.md) - [用法](docs/en/usage.md) - [完整规则目录](docs/en/rules.md) - [贡献指南](docs/en/contributing.md) - [更新日志](CHANGELOG.md) ## 路线图 - v0.1 — 通用规则集 + Go + PHP 专门化 + 双语输出 ✅ - v0.2 — TypeScript/JavaScript 专门化（Sequelize/Prisma/Mongoose、React/Vue/Angular、Express/NestJS/Next.js） ✅ - v0.3 — 默认范围更改为整个代码库、持久化报告、详尽的逐项发现解释 ✅ - v0.4 — Python 专门化（SQLAlchemy/Django ORM SQLi、pickle/yaml deserialization RCE、Werkzeug debugger、FastAPI/Flask/Django CSRF + CORS、PyJWT algorithms、subprocess shell=True） ✅ - v0.5 — 多平台支持：OpenAI Codex CLI + Google Antigravity（顺序 LARGE 模式、共享规则集、`install.sh` + `sync-skills.sh`） ✅ - v0.6（当前） — .NET/C# 专门化 · +11 条规则（SSTI、NoSQL injection、Open Redirect、XXE、Insecure Cookie、 Headers、Weak Crypto、Prototype Pollution、**LLM prompt injection + insecure output**、IaC misconfig） · SARIF 输出 · 单项发现的置信度 · `.vbsecignore` 抑制 · 实时依赖扫描器（osv-scanner/npm audit/pip-audit） · 跨分块污点追踪 ✅ — 完整详情请见 [CHANGELOG.md](CHANGELOG.md) - v0.7+ — Ruby、Java、Rust 语言覆盖 — 社区驱动 ## 免责声明 vbsec 是一个参考扫描器。它可以捕获常见的 AI 生成代码错误，但是： - 它不能替代专业的安全审计 - 它不保证 100% 的漏洞覆盖率 - 它不获取实时的 CVE 数据库（需单独运行 `npm audit` / `pip-audit` / `govulncheck`） 请将 vbsec 作为**第一道防线**使用，而不是将其视为安全的证明。 ## 许可证 基于 [MIT 许可证](LICENSE) 发布。

标签：AI编程助手, CISA项目, Claude Code, DevSecOps, DLL 劫持, StruQ, 上游代理, 代码安全审计, 大语言模型, 应用安全, 数据可视化, 日志审计, 逆向工具, 错误基检测, 静态代码分析