marco-scheffler/vibesafe

## 为什么选择 vibesafe？ 纯文本的安全指南只能*提供建议* —— 它从未真正进行过检查。vibesafe 是 替代方案：一个**能够运行真实扫描器**的技能，将标准化且按优先级排序的发现反馈给 你的 agent —— 然后只在得到你批准的情况下帮助你修复它们。 它同时以两种方式工作：在你编写代码时**引导**安全模式，并按需使用 gitleaks、semgrep、trivy 以及 npm/pip/osv 咨询数据库进行**审计** —— 每一个结果都会合并 为一份按严重程度排序的报告。 ## 核心特性 - 🔑 **真正的机密信息检测** — gitleaks + trivy，带有**脱敏的**值和一个 `committed` 标志，可以 指出已经存在于 git 历史记录中的机密信息 - 📦 **存在漏洞的依赖** — 跨生态系统的 `npm audit` · `pip-audit` · `osv-scanner` - 🐛 **代码 (SAST)** — semgrep 安全规则集（注入、XSS、`eval`、弱加密算法 等） - 🐳 **IaC 与容器** — 使用 trivy 检测 Docker/Terraform 配置错误及许可证风险 - 🧩 **统一报告** — 将每个扫描器的结果标准化为单一的、排序过的 `report.json` / `report.md` - 🪶 **零依赖核心** — 编排器仅使用 Python **标准库**；缺失的工具会优雅降级 - 🔒 **本地优先** — 扫描引擎在你的机器上运行；只有依赖的*名称*会发送到咨询 API - ⚙️ **两种安装方式** — 作为 Claude Code 插件，或者直接克隆到任何 agent 的 skills 目录中 ## 环境要求 - **Python 3.8+** — 编排器（`scripts/scan.py`）**仅使用标准库**，不需要 `pip install`。 - 用于实现全面覆盖的**可选扫描器**（详见[扫描器](#scanners)）。即使没有它们，vibesafe 仍然 会运行所有可用的工具，并在报告中显示覆盖范围的差距。 ## 安装 ### Claude Code — 作为插件（推荐） ``` /plugin marketplace add marco-scheffler/vibesafe /plugin install vibesafe@vibesafe-marketplace ``` ### Claude Code — 作为克隆的技能 ``` git clone https://github.com/marco-scheffler/vibesafe.git ~/.claude/skills/vibesafe ``` ### 其他 agents 思路相同 —— 克隆到 agent 的 skills 目录（全局），或者针对单个项目克隆到项目本地的 `./skills/`： | Agent | 全局 skills 目录 | |---|---| | Claude Code | `~/.claude/skills/vibesafe` | | Cursor | `~/.cursor/skills/vibesafe` | | Codex | `~/.agents/skills/vibesafe` | | GitHub Copilot | `~/.copilot/skills/vibesafe` | | Antigravity (Gemini) | `~/.gemini/antigravity/skills/vibesafe` | 无论哪种方式，重启你的 agent，然后只需问：*“scan <project> for security issues.”* ## 扫描器 编排器会在可用时运行每个工具（已安装的二进制文件，或针对 Python 工具使用临时的 `uvx`/`pipx run`），否则会跳过并附带安装提示。一次性完整设置： ``` brew install gitleaks trivy osv-scanner # native binaries pip install pip-audit # usually already present # semgrep 无需安装 — vibesafe 通过 `uvx` 运行它 ``` | 类别 | 工具 | 安装方式 | |---|---|---| | 机密信息 | gitleaks | `brew install gitleaks` | | 依赖 | npm audit / pip-audit / osv-scanner | 内置 / `pip install pip-audit` / `brew install osv-scanner` | | 代码 (SAST) | semgrep | `uvx semgrep` (自动) / `brew install semgrep` | | IaC / 容器 / 许可证 | trivy (回退: checkov) | `brew install trivy` | ## 用法 - 当你编写或修改 Web 应用代码时，**指导**会自动触发。 - **按需审计** — 要求 agent（*“scan this project”*），或者直接运行扫描器： ``` python3 ~/.claude/skills/vibesafe/scripts/scan.py ``` 它将 `report.json` + `report.md` 写入临时目录并打印路径。常用参数： `--only secrets,deps,sast,iac,license` · `--timeout ` · `--out-dir `。 ## 自动化（CI / pre-commit） vibesafe 对 CI 和 pre-commit 非常友好。退出码是**可选的** —— 普通的运行总是以 `0` 退出； `--fail-on ` 会将发现的问题转化为构建门禁。 **GitHub Action** — 该仓库提供了一个组合操作（安装你需要的引擎；缺失的引擎会 优雅降级）： ``` - uses: marco-scheffler/vibesafe@v1.6.0 with: path: . fail-on: high ``` **pre-commit**（`.pre-commit-config.yaml`）— 扫描**暂存区（staged）**的更改，遇到 `high` 及以上级别时失败： ``` repos: - repo: https://github.com/marco-scheffler/vibesafe rev: v1.6.0 hooks: - id: vibesafe ``` **现有代码库** — 使用 `--update-baseline` 冻结当前的发现，然后通过 `--baseline vibesafe-baseline.json` 仅显示*新*问题；通过 `.vibesafeignore` 抑制已接受的问题；使用 `--staged` / `--diff ` 将快速扫描范围限定在更改过的文件。完整参考： [`references/automation.md`](references/automation.md)。 ## 工作原理与隐私 扫描引擎完全在**本地**运行 —— 你的**源代码不会被上传**。依赖扫描器仅 将**包名 + 版本号**发送到咨询 API（npm registry、PyPI、OSV）；semgrep 会下载 规则集，trivy 会下载漏洞数据库（缓存在本地）。没有付费数据源，也没有 AI 服务。 完整详情和数据源矩阵：[`references/tools.md`](references/tools.md)。 机密信息的发现绝不会包含原始机密值（设计上已脱敏），并带有一个 `committed` 标志 —— `true` 表示该机密存在于被 git 跟踪的文件中（在历史记录中 → 轮换**并**清除）。 ## 文档 - 安全编码指南：[`references/secure-coding.md`](references/secure-coding.md) - 设计规范：[`docs/specs/2026-06-13-vibesafe-skill-design.md`](docs/specs/2026-06-13-vibesafe-skill-design.md) - 实施计划：[`docs/plans/2026-06-13-vibesafe.md`](docs/plans/2026-06-13-vibesafe.md) ## 测试 ``` bash tests/run-tests.sh ``` ## 许可证 MIT — 详见 [`LICENSE`](LICENSE)。灵感来源于开源项目 [VibeSec-Skill](https://github.com/BehiSecc/VibeSec-Skill) (Apache-2.0)；这里的所有内容均为原创。

标签：AI编程助手, Claude插件, Python, 依赖审计, 安全扫描, 无后门, 时序注入, 逆向工具, 静态应用安全测试