hsvibeguard/vibeguard-cli

# VibeGuard CLI [](https://pypi.org/project/vibeguard-cli/) [](https://pypi.org/project/vibeguard-cli/) [](https://opensource.org/licenses/MIT) [](https://github.com/hsvibeguard/vibeguard-cli/actions/workflows/ci.yml) [](https://github.com/hsvibeguard/vibeguard-cli)

**本地仓库统一安全扫描器调度器。** 使用一条命令运行 **Semgrep、Bandit、Checkov、Gitleaks、Trivy & TruffleHog**，自动检测每个仓库的生态系统扫描器，获得一个标准化分数、去重结果、SARIF 格式用于 GitHub 代码扫描，以及 AI 驱动的修复建议。 ## 功能 - **一条命令**：使用 `vibeguard scan .` 运行多个安全扫描器 - **标准化输出**：所有扫描器的统一发现方案 - **分数和等级**：获取安全分数（0-100）和字母等级 - **多种输出格式**：终端、JSON、SARIF、HTML 报告 - **徽章生成器**：在您的 README 中嵌入安全徽章 - **CI 友好**：自动化和阈值检查的退出代码 ## 安装 ### 从 PyPI（推荐） ``` pip install vibeguard-cli ``` ### 从源码 ``` git clone https://github.com/hsvibeguard/vibeguard-cli.git cd vibeguard-cli pip install -e ".[dev]" ``` ### 验证安装 ``` vibeguard --version vibeguard doctor ``` ## 快速入门 ``` # 检查您的环境 vibeguard doctor # 在您的项目中初始化 vibeguard init # 运行安全扫描 vibeguard scan . # 为 GitHub Code Scanning 生成 SARIF vibeguard scan . --output sarif > results.sarif # 生成 HTML 报告 vibeguard scan . --output html > report.html # 生成徽章 vibeguard scan . --badge badge.svg ``` ## 在 CI/CD 中使用 ### GitHub Action（推荐） 一步安装 VibeGuard + 固定扫描器集并上传发现到您的仓库安全标签页： ``` # .github/workflows/security.yml name: Security on: [push, pull_request] permissions: contents: read security-events: write # required for SARIF upload jobs: vibeguard: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: hsvibeguard/vibeguard-cli@v1 with: scanners: broad # core | broad | full threshold: 70 # fail the build below this score (0 = never fail) ``` ### pre-commit 钩子 ``` # .pre-commit-config.yaml repos: - repo: https://github.com/hsvibeguard/vibeguard-cli rev: v1.1.9 hooks: - id: vibeguard additional_dependencies: ["semgrep", "bandit", "checkov"] ``` ### Docker 镜像中包含了预安装的扫描器，无需安装步骤： ``` docker run --rm -v "$(pwd):/repo" ghcr.io/hsvibeguard/vibeguard-cli ``` ## VibeGuard 不是什么 - **不是一个新的扫描器**。它调度现有的、经过实战检验的工具（Semgrep、Trivy、Gitleaks、Bandit、Checkov、TruffleHog）——它不重新发明检测。 - **不是替代专业工具**。需要深入的 SAST 调优？直接运行 Semgrep。VibeGuard 的价值在于统一、去重和评分——而不是超越专家。 - **不是安全保证**。通过分数意味着“配置的扫描器没有发现”，并不意味着“安全”。安全不是一个单一的数字。 - **不是您的代码的云服务**。扫描在本地/您的 CI 中运行——您的源代码永远不会离开您的机器。 ## VibeGuard 与自行运行扫描器的比较 您完全可以直接运行 Semgrep、Trivy、Gitleaks 等——VibeGuard 只移除了粘合工作： | | 分别运行 | VibeGuard | |---|---|---| | 安装和配置 | 6 个工具，6 个配置 | 一个命令/一个 Action | | 输出 | 6 种格式 | 一个标准化的方案 | | 重复发现 | 手动 | 在扫描器之间去重 | | 优先级 | 每个工具的严重性 | 一个 0–100 分数 + 等级 | | CI 阻塞 | 自己连接 | 一个 `threshold:` | | 安全标签页 | 上传每个 SARIF | 一个 SARIF | 如果您只使用单个扫描器，您可能不需要 VibeGuard——价值在于运行多个扫描器时。 ## 命令 | 命令 | 描述 | 等级 | |---------|-------------|------| | `vibeguard doctor` | 检查环境和扫描器可用性 | 免费 | | `vibeguard init` | 在目录中初始化 VibeGuard | 免费 | | `vibeguard scan [路径]` | 在代码库上运行安全扫描器 | 免费 | | `vibeguard report [路径]` | 从缓存的扫描生成报告 | 免费 | | `vibeguard fix [id]` | 为 LLM 生成复制粘贴提示 | 免费 | | `vibeguard baseline` | 管理回归检测的基线 | 免费 | | `vibeguard patch [id]` | 通过 LLM 生成统一差异（BYOK）| 专业 | | `vibeguard apply ` | 使用 git 安全检查应用补丁 | 专业 | | `vibeguard live ` | 对运行中的应用进行 DAST 扫描 | 实验 | ## 输出格式 VibeGuard 支持多种输出格式： | 格式 | 标志 | 描述 | |--------|------|-------------| | 终端 | `--output terminal` | 丰富的终端输出（默认）| | json | `--output json` | JSON 扫描结果 | | sarif | `--output sarif` | 用于 GitHub 代码扫描的 SARIF 2.1.0 | | html | `--output html` | 独立的 HTML 报告 | ### 生成徽章 ``` vibeguard scan . --badge badge.svg ``` 嵌入到 README 中： ```  ``` ## 扫描器包 ### 核心包（默认） - Semgrep（多语言 SAST） - Gitleaks（秘密检测） - Trivy（依赖项/容器/IaC） - Bandit（Python SAST） - TruffleHog v3（秘密检测） ### 生态系统包（自动检测） - npm-audit（JavaScript/Node.js） - pip-audit（Python） - cargo-audit（Rust） ### 区分包 - Checkov（基础设施即代码） - Dockle（容器最佳实践） - Nuclei（DAST 模板） ## 评分 - **基础**：100 分 - **扣除**：关键（-20）、高（-10）、中（-5）、低（-2） - **类别上限**：每个类别最多 50 分 - **等级**：A+（≥95）、A（≥85）、B（≥70）、C（≥50）、D（≥30）、F（<30） ## 退出代码 对于 CI/CD 集成： | 代码 | 含义 | |------|---------| | 0 | 成功，没有发现 | | 1 | 成功，发现发现 | | 2 | 扫描错误（部分扫描） | | 3 | 没有缓存的扫描（报告命令） | | 4 | 配置错误 | | 5 | 无效路径 | | 10 | 分数低于阈值 | ### CI 集成 见上面的 [在 CI/CD 中使用](#use-in-cicd)，包括 GitHub Action、pre-commit 钩子和 Docker 镜像。注意：在 `--ci` 模式下，VibeGuard 只运行已安装的扫描器（用于确定性的构建），这就是为什么 Action 为您安装了一个固定的扫描器集。 ### 阈值强制执行 ``` # 如果分数低于 80 则以代码 10 退出 vibeguard scan . --threshold 80 ``` ## 专业功能（BYOK） VibeGuard 专业功能使用您自己的 LLM API 密钥（自带密钥）： ``` # 配置您的 API 密钥（本地加密） vibeguard keys set openai sk-... # 为发现生成补丁 vibeguard patch # 安全应用补丁 vibeguard apply .vibeguard/patches/.patch ``` 支持的提供商：OpenAI、Anthropic、Google、Azure、Mistral、Groq ## 已知限制 - **CI 模式只运行已安装的扫描器**。`--ci` 是确定的并且不会自动安装工具。GitHub Action 为您安装了一个固定的扫描器集，但原始的 `vibeguard scan . --ci` 只运行已经存在的工具。 - **分数是启发式的**。它是一个分类/门控辅助工具（按严重性扣除），而不是校准的风险模型——用于趋势和阈值，而不是作为绝对判断。 - **覆盖率因语言而异**。Semgrep 很广泛；一些扫描器是特定于生态系统的（gosec 用于 Go，pip-audit 用于 Python，cargo-audit 用于 Rust）。 - **第一次 CI 运行较慢**（安装 + 二进制下载）。缓存 `~/.vibeguard/bin` 以加快后续运行。 - **分类保守**。测试固定、供应商或临时路径中的发现可能会自动抑制——使用 `--no-default-ignore` 来查看所有内容。 ## 贡献 欢迎贡献！见 **[CONTRIBUTING.md](CONTRIBUTING.md)** ——添加扫描器通常是一个小的清单 + 解析器。对于安全问题，见 **[SECURITY.md](SECURITY.md)**。 ## 许可证 MIT - 详见 [LICENSE](LICENSE)。

标签：AI修复建议, GitHub Advanced Security, Python, SARIF, 二进制发布, 初始化, 反取证, 安全加固, 安全可观测性, 安全合规, 安全响应, 安全扫描, 安全漏洞, 安全评估, 安全评分, 开源工具, 徽章生成, 扫描, 无后门, 时序注入, 正则表达式, 源代码管理, 版本控制, 环境诊断, 统一输出格式, 网络代理, 逆向工具, 集成开发环境