husinn-abd/VibeAudit

# VibeAudit [](https://github.com/husinn-abd/VibeAudit/actions/workflows/ci.yml) [](https://github.com/husinn-abd/VibeAudit/actions/workflows/pages.yml) [](./CHANGELOG.md) [](./LICENSE) [](https://husinn-abd.github.io/VibeAudit/) VibeAudit 是一个面向现代仓库的本地优先安全审计控制台。它帮助开发者和审计员扫描代码、规范化审计发现、强制执行 policy 验证门槛、保留证据哈希，并默认不上传源代码即可准备 ISO/IEC 27001 审计支持材料。 [打开实时 dashboard](https://husinn-abd.github.io/VibeAudit/) | [阅读实施阶段](./docs/IMPLEMENTATION_PHASES.md) | [配置环境](./docs/ENVIRONMENT.md) | [查阅 VibeAudit 标准](./docs/VIBEAUDIT_STANDARD.md) | [查看更新日志](./CHANGELOG.md) | [查阅安全策略](./SECURITY.md)  截图取自在本地运行的真实 `apps/web` dashboard。示例数据为注入的演示数据，但界面、选择状态、policy 面板、证据面板和报告控件均由应用程序渲染。 ## 为什么选择 VibeAudit 安全扫描器非常有用，但它们的输出结果往往散落在 CLI 日志、SARIF 上传、CI 失败记录、PDF 报告以及基于电子表格的风险登记表中。VibeAudit 将这些信号整合为一个可审查的工作流： - 从本地 runner 运行 Semgrep、Gitleaks 和 Trivy。 - 将审计发现统一规范化为稳定的模型。 - 在存储、生成报告或交由 AI 处理之前对机密信息进行脱敏。 - 应用可导致 CI 失败的 policy 验证门槛。 - 追踪证据哈希、扫描器元数据以及 ISO 控制措施映射。 - 导出面向开发者、管理层、Markdown、JSON、SARIF 以及证据导向的报告。 ## 适用人群 - 希望在推送代码前进行快速本地安全检查的开发者。 - 需要跨项目保持证据一致性的安全团队。 - 需要可追溯扫描器元数据和控制措施映射的审计员。 - 希望拥有可读的公开安全态势的开源项目维护者。 - 希望在不默认发送完整源代码的前提下获得 AI 辅助的 AI 重度应用团队。 ## 目前已实现的功能 | 领域 | 状态 | | --- | --- | | 公开 dashboard | 已部署于 GitHub Pages | | Dashboard UI | 现代化的指挥中心界面，包含过滤器、已选证据、扫描器流程、ISO 及导出状态 | | Monorepo 基础架构 | `apps/*`, `packages/*`, 文档, CI, Pages 工作流 | | Runner CLI | 模拟扫描、JSON 输出、SARIF 输出、Markdown 输出、Docker 扫描器包装器 | | 核心模型 | 严重性映射、指纹识别、policy 评估、报告 | | 机密安全性 | 脱敏处理、证据哈希、API token 哈希辅助工具 | | ISO-lite | A.8.8, A.8.25, A.8.28, A.8.29 支持映射 | | API | MVP 导入、项目、审计发现、风险接受、HTML 和 Markdown 报告 endpoint | VibeAudit 目前处于预发布阶段。dashboard 当前使用演示数据，同时正在对接 API 和持久化存储。 ## 产品流程 1. **本地扫描**：使用 runner 针对文件夹或 git URL 进行扫描。 2. **规范化**：将 Semgrep、Gitleaks 和 Trivy 的输出结果统一规范化为单一审计发现模型。 3. **脱敏与哈希**：在证据被存储、展示或导出之前，对其进行脱敏和哈希处理。 4. **评估 policy**：使用 `securerepo.policy.yml` 进行评估，包含 `fail_on` 规则和必需的扫描器。 5. **在 dashboard 中审查**：查看严重性过滤器、扫描器过滤器、选定审计发现的证据、扫描器运行元数据以及 ISO-lite 映射。 6. **接受风险或导出**：基于同一份扫描数据，导出 HTML、PDF、Markdown、JSON 和 SARIF 报告。 7. **在需要时中断 CI**：使用 runner 的退出代码：`0` 表示通过，`1` 表示 policy 验证失败，`2` 表示扫描器/运行时错误，`3` 表示无效的输入/配置。 ## 从 PowerShell 快速访问 在任何 PowerShell 提示符（包括您的 Windows 主目录）下复制并粘贴此代码块。如果需要，它会克隆仓库；如果已存在，则会对其进行更新，然后运行内置的快速启动脚本。 ``` $repo = Join-Path $env:USERPROFILE "VibeAudit" if (-not (Get-Command git -ErrorAction SilentlyContinue)) { throw "Git is required. Install Git for Windows, reopen PowerShell, then run this block again." } git --version if ($LASTEXITCODE -ne 0) { throw "Git is required. Install Git for Windows, reopen PowerShell, then run this block again." } if (Test-Path (Join-Path $repo ".git")) { Set-Location $repo git pull --ff-only if ($LASTEXITCODE -ne 0) { throw "git pull failed. Commit/stash local changes or reclone the repo, then run this block again." } } else { if (Test-Path $repo) { throw "$repo already exists but is not a git repo. Move it or choose another folder." } git clone https://github.com/husinn-abd/VibeAudit.git $repo if ($LASTEXITCODE -ne 0) { throw "git clone failed. Check internet access and GitHub access, then run this block again." } Set-Location $repo } powershell -ExecutionPolicy Bypass -File .\scripts\quickstart.ps1 ``` 该脚本会在安装依赖项之前检查 Git、Node.js、Corepack、pnpm、可选的 Docker 可用性以及仓库根目录。接着，它会在需要时根据 `.env.example` 创建 `.env` 文件，并运行安装、类型检查、测试、生产环境构建以及一次模拟扫描。如果任何依赖项安装或验证步骤失败，它会打印出接下来应尝试的准确修复方法。 模拟扫描会生成以下文件： - `artifacts/mock-report.json` - `artifacts/mock-report.sarif` - `artifacts/mock-report.md` 如果仓库已经被克隆到了其他地方，请进入该文件夹并运行相同的脚本： ``` Set-Location "D:\0Documents\Documents\SecureRepo-Auditor" powershell -ExecutionPolicy Bypass -File .\scripts\quickstart.ps1 ``` 如果只想在安装包之前检查机器依赖项： ``` powershell -ExecutionPolicy Bypass -File .\scripts\quickstart.ps1 -CheckOnly ``` 要保存一份机器可读的设置报告： ``` powershell -ExecutionPolicy Bypass -File .\scripts\quickstart.ps1 -CheckOnly -DoctorReport artifacts\quickstart-doctor.json ``` ## 环境设置 提交的 `.env.example` 文件是安全的模板。真实的 `.env` 文件会被 git 忽略。 ``` Copy-Item .env.example .env ``` 此处提供可选的应用特定覆盖模板： - `apps/api/.env.example` - `apps/runner/.env.example` - `apps/web/.env.example` 完整详情：[docs/ENVIRONMENT.md](./docs/ENVIRONMENT.md)。 ### 为什么旧命令会失败 这个错误： ``` ERR_PNPM_NO_PKG_MANIFEST No package.json found in C:\Users\HusinAbdullah ``` 意味着 pnpm 是在您的 Windows 主目录下运行的，而不是在 VibeAudit 仓库中运行。请通过以下命令确认您是否处于正确的文件夹中： ``` Test-Path .\package.json ``` 在运行 `corepack pnpm install`、`corepack pnpm test` 或 `corepack pnpm build` 之前，它必须输出 `True`。建议的修复方法是使用上述基于克隆的快速访问代码块，因为它在运行检查之前总是会先进入仓库。 ## 手动快速启动 安装依赖项、运行测试并构建所有内容： ``` cp .env.example .env corepack pnpm install corepack pnpm typecheck corepack pnpm test corepack pnpm build corepack pnpm --filter @vibeaudit/runner scan:mock:demo ``` 在本地运行 dashboard： ``` corepack pnpm --filter @vibeaudit/web dev ``` 打开： ``` http://localhost:5173 ``` 运行一次确定性的模拟扫描： ``` corepack pnpm --filter @vibeaudit/runner scan:mock:demo ``` 该演示会写入 `artifacts/mock-report.json`、`artifacts/mock-report.sarif` 和 `artifacts/mock-report.md`， 然后在确认预期的 policy 失败后以代码 `0` 退出。 要实现 CI policy 验证门槛行为，请使用原始命令： ``` corepack pnpm --filter @vibeaudit/runner scan:mock ``` 原始的模拟扫描会故意返回退出代码 `1`，因为示例 policy 在遇到高级和严重级别的审计发现时会判定为失败。 ## 真实扫描器模式 真实的扫描过程会针对 V1 所需的扫描器集合使用 Docker 镜像： - 用于 SAST 的 Semgrep。 - 用于已提交机密信息的 Gitleaks。 - 用于依赖项和文件系统漏洞的 Trivy。 ``` corepack pnpm --filter @vibeaudit/runner exec tsx src/index.ts scan . \ --output artifacts/vibeaudit-report.json \ --sarif artifacts/vibeaudit-report.sarif \ --markdown artifacts/vibeaudit-report.md ``` VibeAudit 在运行扫描器容器时会以只读方式挂载本地源代码。 ## Policy 示例 创建 `securerepo.policy.yml`： ``` schema_version: 1 required_scanners: - semgrep - gitleaks - trivy fail_on: high ignored_rules: [] accepted_risk_max_days: 90 ai_privacy_mode: disabled ``` Policy 评估是确定性的，并由 CLI、API 导入和 dashboard 视图共同使用。 ## 架构 ``` apps/ api/ REST API, project scope, imports, findings, report endpoints runner/ Local CLI scanner orchestrator web/ Dashboard deployed to GitHub Pages packages/ core/ Finding schema, normalization, SARIF, policy engine, reports iso/ Lightweight ISO/IEC 27001 mappings security/ Redaction, hashing, token helpers, audit hash primitives docs/ Architecture, deployment, implementation phases, repo patterns, standards ``` 默认的导入 payload 包含规范化后的审计发现、扫描器元数据、policy 输出、证据哈希以及脱敏后的代码片段。完整的源代码并不属于默认的导入契约。 读取或写入作用域数据的 API 调用必须通过 `x-organization-id` 包含明确的组织上下文；项目路由也会在路径中携带 `projectId`。 扫描报告导出可通过项目作用域的 API 路由获取： - `GET /v1/projects/:projectId/scans/:scanId/reports/html` - `GET /v1/projects/:projectId/scans/:scanId/reports/markdown` - `GET /v1/projects/:projectId/scans/:scanId/reports/json` - `GET /v1/projects/:projectId/scans/:scanId/reports/sarif` ## 当前路线图 1. 将 dashboard 对接到 API，取代演示数据。 2. 通过 Prisma 和 SQLite 持久化导入的数据以供本地使用。 3. 添加适配 Postgres 的部署路径。 4. 基于同一报告模型添加 PDF 报告生成功能。 5. 添加严格的本地 AI 辅助功能，用于解释审计发现。 6. 添加扫描器基准测试夹具，用于回归测试。 暂缓实施的企业级功能包括 SSO、GitHub App、GitLab App、多 runner 集群、签名发布管道以及完整的 ISMS 生命周期工作流。 ## 安全与合规性说明 VibeAudit 旨在帮助收集和组织技术证据。它不能为组织进行认证、取代 ISMS，也无法单凭自身证明符合 ISO/IEC 27001 标准。 在对敏感仓库使用 VibeAudit 之前，请阅读 [SECURITY.md](./SECURITY.md)。 ## 贡献 欢迎提交 Issue 和 pull request。请确保改动范围聚焦，针对扫描器或 policy 行为更新测试，并且切勿在测试夹具中添加真实的机密信息。 从这里开始： - [贡献指南](./CONTRIBUTING.md) - [架构说明](./docs/ARCHITECTURE.md) - [部署说明](./docs/DEPLOYMENT.md)

标签：DevSecOps, MITM代理, 上游代理, 安全合规, 网络代理, 自动化攻击, 请求拦截, 静态应用安全测试