dgenio/vibeguard

# VibeGuard **氛围编码软件的护栏。** [](https://github.com/dgenio/vibeguard/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) ## 问题所在 人工智能编程工具让开发者能在数小时内完成过去需要数天的工作。这确实很棒。但是，不加审视地接受大型 AI 生成的代码差异，会产生传统安全工具无法捕捉的新型故障模式： - **意外提交的密钥** — API 密钥、令牌和数据库 URL 通过 AI 生成的配置文件混入其中 - **包发布泄露** — 源代码映射、`.env` 文件和测试夹具最终出现在 npm/PyPI 包中 - **依赖供应链风险** — AI 代理引入 git URL、拼写错误的包或宽泛的版本范围 - **安全控制绕过** — AI 注释掉认证检查或禁用 SSL 验证以"使程序运行" - **未经测试的风险代码变更** — 涉及认证、加密和数据库写入的巨大代码差异，且测试覆盖率为零 - **AI 痕迹** — 占位符凭证、`# TODO: implement real auth` 和 `信任所有证书` ## VibeGuard 为何存在 VibeGuard **不是**又一个 AI 包装器、SAST 扫描器或依赖检查器。 它是一个**快速、确定性的合并前安全关卡**，专为 AI 辅助编程（"氛围编码"）的故障模式而设计。它可在几秒钟内离线运行，无需 API 密钥。 可以将其视为介于"AI 生成了此代码差异"和"此代码差异进入生产环境"之间的检查点。 ## 它能捕获什么 | 类别 | 示例 | |---|---| | 🔑 **密钥** | AWS 密钥、GitHub 令牌、OpenAI 密钥、数据库 URL、私钥、`.env` 文件 | | 🗺️ **源代码映射** | `dist/` 中的 `.map` 文件、包中的 `sourceMappingURL`、发布映射的 npm 包 | | 📦 **打包泄露** | npm/PyPI 包中的 `.env`、`tests/`、`.github/`、源代码映射 | | 🔗 **依赖风险** | git/URL 依赖、拼写错误的包、未固定的版本（严格模式） | | ⚠️ **风险代码模式** | `eval/exec`、`shell=True`、`JWT verify=False`、CORS 通配符、`pickle.loads`、SQL 拼接 | | 🧪 **缺失测试** | 源代码更改但无对应的测试更改 | | 🤖 **AI 痕迹** | 占位符凭证、禁用的认证、信任所有证书、TODO 存根、临时绕过 | ## 快速开始 ``` pip install vibeguard-gate ``` 或从源代码安装： ``` git clone https://github.com/dgenio/vibeguard cd vibeguard pip install -e ".[dev]" ``` 初始化配置文件： ``` vibeguard init ``` 扫描目录： ``` vibeguard scan --path . ``` 为你的 CI 设置关卡（如果发现阻断性问题则退出码为 1）： ``` vibeguard gate --diff --fail-on high ``` ## 30 秒内试用 此仓库附带了两个故意存在漏洞的示例包，包含伪造的 密钥，因此你无需将 VibeGuard 指向任何敏感内容即可看到一组 真实且有意义的结果： ``` git clone https://github.com/dgenio/vibeguard cd vibeguard pip install -e . vibeguard scan --path examples/vulnerable-node-package ``` 你应该会看到大约 16 个发现，涵盖密钥、源映射泄露、打包泄露、风险模式和 AI 痕迹——所有这些都不会触及网络或调用任何外部服务。尝试 `examples/vulnerable-python-package` 获取 Python 风格的版本。 要将 VibeGuard 用作 CI 关卡（在发现阻断性问题时退出非零码）： ``` vibeguard gate --path examples/vulnerable-python-package --fail-on medium ``` 无需 API 密钥，无遥测，无网络调用。 想要看起来像真实 PR 而非"厨房水槽"式的演示变更？请查看 [`examples/pr-scenarios/`](examples/pr-scenarios) — 六个自包含的场景（禁用 TLS 以通过测试、临时认证绕过、打包泄露、提交的代理记忆、git URL 依赖、风险数据库写入），每个场景都附有确切的命令、预期发现和修复方法。 ## CLI 参考 ### `vibeguard init` 创建一个具有合理默认值的 `vibeguard.yaml` 配置文件。 ``` vibeguard init vibeguard init --path /path/to/repo ``` ### `vibeguard scan` 扫描仓库并打印发现结果。**总是退出码 0**（仅供参考）。 ``` vibeguard scan vibeguard scan --path . vibeguard scan --diff # only changed files (requires git) vibeguard scan --json # machine-readable output vibeguard scan --markdown # for PR comments vibeguard scan --verbose # detailed descriptions vibeguard scan --fail-on medium # set threshold (informational only) ``` ### `vibeguard gate` 与 `scan` 相同，但当发现数量达到或超过阈值时**退出码 1**。 ``` vibeguard gate --path . --fail-on high vibeguard gate --diff --fail-on medium ``` ### `vibeguard publish-check` 模拟 `npm publish` 或 `python -m build`，并在发布到注册表之前，根据已发布文件集中的发现设置关卡。 ``` vibeguard publish-check --path . vibeguard publish-check --ecosystem npm --manifest-out publish-manifest.json vibeguard publish-check --ecosystem python-sdist --fail-on medium ``` 完整指南、发现 ID 和 GitHub Actions 发布关卡模板，请参阅 [docs/pre-publish.md](docs/pre-publish.md)。 ### `vibeguard explain ` 打印某个发现的详细解释和修复指南。 ``` vibeguard explain SEC-ENV vibeguard explain MAP-DIST vibeguard explain TEST-MISSING ``` ## 示例输出 以下是此仓库上运行 `vibeguard scan --path examples/vulnerable-node-package` 的实际输出（如果规则变更，使用相同命令重新生成）： ``` VibeGuard Findings ┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Sev ┃ Rule ┃ Path ┃ Title ┃ ┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ ☠ CRITICAL │ secrets │ src/server.js:12 │ GitHub Token detected │ │ ✗ HIGH │ secrets │ .env │ Sensitive file committed: .env │ │ ✗ HIGH │ sourcemaps │ package.json │ package.json 'files' includes source maps │ │ ✗ HIGH │ packaging │ package.json │ npm package may publish Environment files (.env) │ │ ✗ HIGH │ packaging │ package.json │ npm package may publish Source map files │ │ ✗ HIGH │ dependencies │ package.json │ URL/git/path dependency: axios │ │ ✗ HIGH │ ai_footprints │ src/server.js:14 │ AI footprint: Security disabled in code │ │ ✗ HIGH │ ai_footprints │ src/server.js:31 │ AI footprint: Trust-all certificates │ │ ✗ HIGH │ auth │ src/server.js:16 │ Auth: Auth bypass TODO/FIXME/HACK comment │ │ ⚠ MEDIUM │ packaging │ .npmignore:8 │ Overly broad .npmignore negation: '!*' │ │ ⚠ MEDIUM │ risky_diff │ src/server.js:9 │ Risk-sensitive area changed: CORS configuration │ │ ⚠ MEDIUM │ risky_diff │ src/server.js:27 │ Risk-sensitive area changed: eval() or exec() usag │ │ ⚠ MEDIUM │ risky_diff │ src/server.js:32 │ Risk-sensitive area changed: Environment variable │ │ ⚠ MEDIUM │ ai_footprints │ src/server.js:17 │ AI footprint: Temporary security bypass or mock │ │ ↓ LOW │ packaging │ package.json │ package.json runs `prepare` at publish time │ │ ℹ INFO │ ai_footprints │ src/server.js:11 │ AI footprint: AI-generated code comment │ └────────────┴────────────────┴──────────────────────┴────────────────────────────────────────────────────┘ Scanned 5 file(s) • 16 finding(s) | critical: 1 high: 8 medium: 5 low: 1 info: 1 • policy: balanced ``` `vibeguard scan` 总是退出码 `0`（仅供参考）。`vibeguard gate` 运行相同的检查，但当发现数量达到或超过 `--fail-on` 设定的阈值时，退出码为 `1`： ``` vibeguard gate --path examples/vulnerable-node-package --fail-on high echo "exit: $?" # exit: 1 ``` ## 策略级别 | 策略 | 描述 | |---|---| | `relaxed` | 仅阻断性和高危发现 | | `balanced` | 高危 + 中危发现（默认） | | `strict` | 所有发现；未固定的依赖和缺失的测试会被提升等级 | 在 `vibeguard.yaml` 中设置： ``` policy: strict fail_on: medium ``` 或在命令行中覆盖： ``` vibeguard gate --fail-on medium ``` ## 配置 运行 `vibeguard init` 创建 `vibeguard.yaml`： ``` policy: balanced fail_on: high ignore: paths: - .git/ - node_modules/ - .venv/ - dist/ - build/ findings: [] # suppress specific finding IDs secrets: enabled: true min_entropy: 3.5 sourcemaps: enabled: true packaging: enabled: true dependencies: enabled: true # `risky_patterns:` tunes the `risky_diff` rule — the YAML section name and # the rule id differ for historical reasons. Use `vibeguard rules explain # ` to look up the config section for any rule. risky_patterns: enabled: true tests: enabled: true ai_footprints: enabled: true ``` ## GitHub Actions 使用方法 添加到你的拉取请求工作流： ``` name: VibeGuard on: [pull_request] jobs: vibeguard: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-python@v5 with: python-version: "3.11" - run: pip install vibeguard-gate - run: vibeguard gate --diff --fail-on high ``` 用于本地开发（发布到 PyPI 之前）： ``` - run: pip install -e . - run: vibeguard gate --fail-on high ``` ## 规则快速参考 VibeGuard 内置 **13 条确定性规则**。每条规则会生成一个或多个 稳定的发现 ID，你可以用 `vibeguard explain ` 查看详情， 通过 `vibeguard.yaml` 抑制，或通过 `severity_overrides` 重映射。 | 规则 | 默认严重等级 | 检测内容 | |-------------------|------------------|---------------------------------------------------------------------------------------------------| | `secrets` | 高 | AWS 密钥、GitHub/OpenAI/Slack/Stripe 令牌、私钥、Bearer 令牌、硬编码密码、包含凭证的数据库 URL、已提交的 `.env` 文件。 | | `sourcemaps` | 高 | `dist/`/`build/` 中的 `.map` 文件、`sourceMappingURL` 注释、`package.json` 中包含源映射的 `files` 条目。 | | `packaging` | 中 | npm/PyPI 清单文件会发布 `.env`、测试、源映射、构建配置；宽泛的 `MANIFEST.in` 嫁接、`.npmignore` 否定项。 | | `dependencies` | 高 | git/URL/路径依赖、拼写错误启发式、宽泛版本范围、锁文件漂移、注册表变更。 | | `risky_diff` | 中 | 对风险敏感区域的更改（认证、加密、eval/exec、shell、网络、数据库写入、支付、CORS、JWT、证书）加上差异宽度/大小信号。 | | `auth` | 高 | 被注释掉的认证、JWT `alg=none`、硬编码管理员密码、`verify=False`、允许所有中间件、返回 `True`/`nil` 的认证函数。 | | `sql` | 高 | f-string / 拼接 / 模板字面量 / `fmt.Sprintf` 等可能存在注入风险的 SQL 构造方式。 | | `ai_footprints` | 中 | AI 生成注释、占位符凭证、信任所有证书、CORS 通配符、临时绕过、跳过验证、臆造的 TODO。 | | `agent_memory` | 高 | 意外提交的代理产物：SQLite 记忆数据库、JSONL 日志、转录记录、工具跟踪、隐藏的记忆目录。 | | `ci_docker` | 高 | 风险的 Dockerfile 和 GitHub Actions：特权容器、`latest` 标签、curl-pipe-bash、`pull_request_target`、宽泛权限、密钥回显、未版本控制的 Actions。 | | `iac` | 高 | Terraform：IAM 通配符、开放安全组、公共 S3、未加密资源。Kubernetes：特权容器、hostPath、root 用户、无 TLS、允许所有策略。 | | `go_rules` | 高 | Go 特定风险：TLS 绕过、shell 注入、CORS 通配符、通过 `Sprintf` 的 SQL、硬编码令牌、认证绕过注释、不安全的文件删除。 | | `tests` | 低 | 源代码文件已更改，但无任何对应的测试文件更改。 | 对于任何特定发现（例如 `vibeguard explain SEC-GITHUBTOKEN`），运行 `vibeguard explain ` 获取完整的修复指南。 `risky_diff` 本质上是一个**风险信号**，而非漏洞声明——它表示"人工请关注此处"，而非"此处可被利用"。 ## VibeGuard 是/不是什么 **是：** - 一个确定性的、离线的合并前安全关卡，针对 AI 辅助编程大规模产生的各类错误。 - 一道快速的第一道防线——在典型的仓库上通常以个位数秒运行，适用于预提交钩子和 PR 关卡。 - 一个**无需 API 密钥、无网络调用、无遥测**，且不依赖任何 LLM 的工具。 **不是：** - 完整的 SAST 替代品（深度语义分析请使用 Semgrep、CodeQL、Bandit、ESLint 安全插件）。 - 针对已泄露凭证的密钥扫描替代品（针对完整 git 历史请使用 truffleHog 或 gitleaks）。 - 依赖漏洞扫描器（CVE 覆盖请使用 Dependabot、pip-audit、npm audit、Snyk）。 - 人工代码审查的替代品。 - 对代码安全或生产就绪的保证。 ### VibeGuard 与其他工具的定位 | 工具类别 | 擅长领域 | 对 AI 生成代码差异可能遗漏之处 | |-----------------------------------|------------------------------------------|------------------------------------------------------------| | **VibeGuard** | AI 编程故障模式的合并前关卡（新文件中的密钥、打包泄露、"信任所有证书"、注释掉的认证、风险差异信号）。 | 深度数据流分析、CVE 查询、历史泄露扫描。 | | 密钥扫描器 (gitleaks, truffleHog) | 广泛的模式覆盖；可扫描完整 git 历史。 | 即将被提交的 `.env` 文件；已暂存但尚未推送的新代码中的密钥。 | | SAST (Semgrep, CodeQL, Bandit) | 深度数据流分析；社区规则包。 | "AI 痕迹"模式（`# TODO: real auth`、`verify=False`、CORS 通配符）和打包清单卫生。 | | 依赖扫描器 (Dependabot, pip-audit, npm audit, Snyk) | 已知 CVE；传递漏洞覆盖。 | git/URL 依赖、拼写错误启发式、AI 提交引入的锁文件漂移。 | | 代码检查工具 (ruff, eslint) | 风格 + 简单正确性。 | 任何与安全相关的内容。 | 其意图是**补充**这些工具，而非替代。典型的 CI 流水线会将 VibeGuard 与上述每类工具中的一种一起运行。 有关更详细的按工具分类的指南——何时使用 VibeGuard 何时不使用，以及推荐的分层 CI 流水线——请参阅[工具比较指南](docs/comparison.md)。 ### 速度与误报 VibeGuard 附带了一份可重现的[基准测试与评估报告](docs/benchmark.md)： 合成仓库的扫描吞吐量、跨 Node/Python/Go/Terraform 测试套件的检测，以及在干净代码上的**零阻断性误报**基线。你可以通过 `make bench` 和 `make bench-scenarios` 自行运行。 ## 生态系统 VibeGuard 是**完全独立的**。它不依赖任何外部服务、API 或兄弟项目进行运行时操作，并且从不回传数据。它唯一需要的是你指向它的差异或目录。 它被设计为通过标准、常规的接口——进程退出码、JSON 和 SARIF 报告以及编辑器诊断——*融入*更广泛的工具链，这样下游工具可以使用其发现，而无需与 VibeGuard 内部耦合。将这些输出视为集成接口：VibeGuard 完成其工作不需要任何下游组件，采用 VibeGuard 也绝不会强制你使用任何其他工具。 ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解本地设置、测试命令、分支和提交约定以及如何添加新规则。 有关安全漏洞披露，请参阅 [SECURITY.md](SECURITY.md) — 请勿就漏洞提交公开 Issue。 提交错误、功能请求、规则请求或误报？请使用 [Issue 表单](https://github.com/dgenio/vibeguard/issues/new/choose)。 - **[docs/rules.md](docs/rules.md)** — 自动生成的规则参考（运行 `make docs` 重新生成）。 - **[docs/how-to-add-a-rule.md](docs/how-to-add-a-rule.md)** — 添加内置规则的分步指南。 - **[docs/plugin-api.md](docs/plugin-api.md)** — 用于在自己的包中发布规则的公共插件 API。 - **[docs/policy-packs.md](docs/policy-packs.md)** — 内置策略包（`oss-library`、`web-app`、`strict-ci`）以及针对单体仓库的源测试映射。 - **[docs/pre-commit.md](docs/pre-commit.md)** — 通过 [pre-commit](https://pre-commit.com) 框架在本地运行 VibeGuard。 - **[docs/docker.md](docs/docker.md)** — 在任何 CI 环境中将 VibeGuard 作为容器运行。 ## 许可证 Apache 2.0 — 详见 [LICENSE](LICENSE)。

标签：AI代码安全, DevSecOps, Python, TLS抓取, 上游代理, 代码审查, 代码差异分析, 供应链风险, 依赖项安全, 包发布安全, 安全检查, 安全门控, 开源框架, 持续集成, 数据隔离, 无后门, 源代码扫描, 秘密管理, 结构化查询, 自动化安全, 软件安全, 逆向工具, 配置漂移, 预合并检查