SUDARSHANCHAUDHARI/RepoGuardAI

# RepoGuardAI [](https://github.com/SUDARSHANCHAUDHARI/RepoGuardAI/actions/workflows/ci.yml) [](LICENSE) [](package.json) [](https://pnpm.io) [](tsconfig.json) RepoGuardAI 能够检查任何软件仓库，运行你已经安装的任何安全和依赖扫描器**以及其自带的确定性扫描器**，并生成精确的、证据驱动的指令，引导 coding agent 审查代码中的 bug、安全漏洞、API 安全问题、缺失的速率限制、依赖风险、配置问题以及缺失的测试。 它**不**绑定任何 AI 提供商。确定性工作在本地运行；推理过程则委托给运行所生成指令的任何 agent 执行。 ## 目录 - [为什么](#why) - [设计：确定性优先，AI 辅助](#design-deterministic-first-ai-second) - [流水线](#the-pipeline) - [功能](#features) - [要求](#requirements) - [安装](#install) - [快速开始](#quick-start) - [命令参考](#command-reference) - [输出布局](#output-layout) - [Finding schema](#finding-schema) - [配置](#configuration) - [扫描内容](#what-gets-scanned) - [支持的 agent](#supported-agents) - [CI / SARIF 集成](#ci--sarif-integration) - [GitHub 日常安全](#daily-github-security) - [仓库布局](#repository-layout) - [开发](#development) - [安全保证](#safety-guarantees) - [局限性](#limitations) - [路线图](#roadmap) - [许可证](#license) ## 为什么 将 LLM 指向整个仓库并要求“找出 bug”是不可靠的：它会产生幻觉虚构出 finding，漏掉工具本该捕获的问题，而且每次运行给你的结果都不一样。RepoGuardAI 通过拆分工作解决了这个问题： - **确定性工具**执行客观检查（secret、依赖项规范、路由清单、config 标志、headers、CVE）——结果可重复，无幻觉。 - **AI agent** 做工具做不到的事情：架构、业务逻辑、授权、代码流程，并使用具体的 `file:line` 证据**验证或驳回**每一条线索。 最终结果是，无论你运行哪个 agent，流程都是一致且可审计的。 ## 设计：确定性优先，AI 辅助 ``` Automated scanners → Collected evidence → AI code review → Finding validation → Final report ``` 每一个 finding 都必须携带代码证据（`file:line`）。内置扫描器**绝不**输出 `confirmed` —— 它们只呈现 `potential` / `manual-verification` 级别的线索，供 agent 去证明或驳回。 ## 流水线 1. **Discovery** — 语言、框架、包管理器、API/测试框架、数据库、集成、CI、Docker/基础设施、身份验证和配置文件，以及一份尽力的 API 路由清单。 → `discovery.json` 2. **Evidence** — 外部扫描器（安装后）+ 六个内置扫描器，与丰富的 API 清单相结合。 → `evidence.json` 3. **Instructions** — 从 prompt 库和 YAML 规则包组装针对特定 agent 的 playbook，注入 discovery + evidence 上下文。 → `instructions/-instructions.md` 4. **AI review** — agent 验证线索，发现扫描器遗漏的问题，并写入 `findings.json`。 5. **Validation & report** — 确定性的阈值通过检查，然后生成 Markdown、JSON 和 SARIF 报告。 → `reports/audit-report.{md,json,sarif}` ## 功能 - 🔌 **提供商中立** — 兼容 Codex、Claude Code、Cursor、Gemini CLI，或任何能够读取文件的 agent。 - 🧰 **9 个外部扫描器**，受可用性控制 — gitleaks、semgrep、trivy、osv-scanner、npm/pnpm audit、pip-audit、govulncheck、cargo-audit。绝不自动安装；不可用的会被跳过，而非致命错误。 - 🔎 **6 个内置确定性扫描器** — secrets、dependencies、routes、permissions、configuration、security-headers。零外部依赖。 - 📋 **15 个 YAML 规则包**，涵盖安全、API 和质量。 - 🧭 **API 清单**，带有诚实的控制检测（当控制不可见时显示 `?` —— 绝不产生虚假声明）。 - 🧱 **Zod 验证**的产物 + JSON Schema 镜像。 - 📄 **Markdown + JSON + SARIF** 报告（可将 SARIF 上传至 GitHub 代码扫描）。 - ⏱️ **GitHub 日常安全** — 可复用的 Semgrep、OSV、Gitleaks、SARIF、issue、Dependabot 和 CodeQL 自动化，使用最小权限作业。 - 🛡️ **默认只读** — 绝不修改受审计的仓库。 - ✅ **严格的 TypeScript**，60 个测试，支持在 Node 18/20/22 上运行 CI。 ## 要求 - Node.js ≥ 18 - pnpm 外部扫描器是**可选的**，并在运行时进行检测 —— 安装其中任何一个以增加覆盖范围： [gitleaks](https://github.com/gitleaks/gitleaks) · [semgrep](https://semgrep.dev/) · [trivy](https://github.com/aquasecurity/trivy) · [osv-scanner](https://github.com/google/osv-scanner) · `npm audit` · `pnpm audit` · [pip-audit](https://github.com/pypa/pip-audit) · [govulncheck](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck) · [cargo-audit](https://github.com/rustsec/rustsec)。 ## 安装 ``` git clone https://github.com/SUDARSHANCHAUDHARI/RepoGuardAI.git cd RepoGuardAI pnpm install pnpm build pnpm link --global # optional: expose the `repoguard` binary globally ``` 在开发期间无需构建即可运行： ``` pnpm dev -- discover ../some-repo # tsx src/cli.ts discover ../some-repo ``` ## 快速开始 ``` # 针对目标 repo 的完整 pipeline repoguard audit /path/to/target-repo # 将你的 agent 指向生成的 instructions，例如在 Claude Code 中打开： # /path/to/target-repo/repoguard-results/instructions/claude-instructions.md # agent 会验证 findings 并写入 repoguard-results/findings.json # 然后进行 finalize： repoguard validate /path/to/target-repo repoguard report /path/to/target-repo ``` ## 命令参考 | 命令 | 描述 | | --- | --- | | `repoguard init [repo]` | 创建输出工作区和起始模板 `repoguard.config.yaml`。 | | `repoguard discover ` | 检测技术栈、API、配置；写入 `discovery.json`。 | | `repoguard scan [--security] [--api]` | 运行外部 + 内置扫描器；写入 `evidence.json`。 | | `repoguard instructions --agent ` | 为 `codex`、`claude`、`cursor`、`gemini` 或 `generic` 生成指令。 | | `repoguard audit [--security] [--api]` | 完整的流水线：discover → evidence → instructions → report。 | | `repoguard validate [repo]` | 确定性检查过程，重新分类低置信度的 potential（< `minimumConfidence`）。 | | `repoguard report [repo]` | 从现有的产物重新构建 `audit-report.{md,json,sarif}`。 | | `repoguard fix [repo]` | 为单个 finding 生成修复计划（除非启用 `mode.modifyFiles`，否则绝不编辑代码）。 | **范围标志：** `--security` 将运行限制为安全 + 依赖 + 配置检查；`--api` 将其限制为 API 安全 + 速率限制检查。两者都仅针对该次运行覆盖 `audit.*` 开关。 ### 示例 ``` repoguard init repoguard discover . repoguard scan . --security repoguard instructions . --agent codex repoguard audit ../my-api --api repoguard fix RG-AUTH-001 ../my-api ``` ## 批量 / 项目组合脚本 位于 [`scripts/`](scripts/) 中的辅助脚本可以一次性在多个仓库上运行 RepoGuard。 通过 `REPOGUARD_ROOT`（默认为当前目录）将它们指向包含你仓库的目录（或类别文件夹）： ``` # 审计目录下的每个 repo，将 repoguard-results/ 写入其中 REPOGUARD_ROOT=~/code ./scripts/portfolio-audit.sh # 安全的、范围内的 dependency 刷新（pnpm update + dedupe）+ audit delta REPOGUARD_ROOT=~/code ./scripts/dependency-sweep.sh --criticals # AI 深度运行：让 Claude Code 将 seed findings 验证写入 findings.json # （仅限于 read + write-file 工具，按 repo 设定 $ 预算上限） cd some-repo && ./scripts/claude-deep-pass.sh ``` 这些是围绕核心 `repoguard` CLI 的可选便捷包装器。 ## 输出布局 ``` repoguard-results/ ├── discovery.json # detected stack + raw API endpoints ├── evidence.json # external + in-house scanner output + API inventory + seed findings ├── findings.json # seeded from evidence; the agent overwrites this ├── scans/ │ ├── scan-report.json │ └── .stdout.txt / .stderr.txt ├── instructions/ │ ├── codex-instructions.md │ ├── claude-instructions.md │ ├── cursor-instructions.md │ ├── gemini-instructions.md │ └── generic-instructions.md ├── reports/ │ ├── audit-report.md │ ├── audit-report.json │ └── audit-report.sarif └── fixes/ └── .md # from `repoguard fix` ``` ## Finding schema Agent 会写入 `repoguard-results/findings.json`： ``` { "repository": "/path/to/target-repo", "generatedAt": "2026-07-12T00:00:00.000Z", "findings": [ { "id": "RG-AUTH-001", "title": "Login endpoint has no rate limiting", "severity": "high", "category": "api-security", "status": "confirmed", "confidence": 95, "file": "src/routes/auth.ts", "line": 42, "endpoint": "POST /api/login", "description": "The login endpoint accepts unlimited authentication attempts.", "evidence": "No rate-limit middleware is applied to the route or router.", "impact": "An attacker can perform credential-stuffing or brute-force attacks.", "triggerCondition": "Repeated POST /api/login requests from one client.", "reproduction": ["Send repeated invalid logins", "Observe no throttling"], "recommendedFix": "Apply a distributed limiter keyed on account + client IP." } ] } ``` | 字段 | 值 | | --- | --- | | `severity` | `critical` · `high` · `medium` · `low` · `informational` | | `status` | `confirmed` · `potential` · `manual-verification` · `rejected` | | `category` | `bug` · `security` · `api-security` · `authentication` · `authorization` · `rate-limiting` · `dependency` · `configuration` · `secrets` · `test-coverage` · `other` | | `id` | `RG--`，例如 `RG-AUTH-001` | 使用 Zod (`src/schemas.ts`) 进行验证，并在 [`schemas/finding.schema.json`](schemas/finding.schema.json) 中镜像为 JSON Schema。无效的 `findings.json` 将被忽略并发出警告，而不会破坏报告。 ## 配置 在目标仓库中使用可选的 `repoguard.config.yaml`。所有键均为可选；请参阅 [`repoguard.config.example.yaml`](repoguard.config.example.yaml) 和 [`schemas/config.schema.json`](schemas/config.schema.json)。 ``` project: name: auto repository: . audit: # per-area toggles bugs: true security: true apiSecurity: true rateLimiting: true dependencies: true configuration: true tests: true mode: modifyFiles: false # RepoGuard never edits files unless this is true validateFindings: true minimumConfidence: 75 # `validate` reclassifies potentials below this exclude: [node_modules, dist, build, coverage, vendor, .git] report: formats: [markdown, json, sarif] outputDirectory: repoguard-results scanners: disabled: [] # e.g. [semgrep, trivy] timeoutMs: 120000 discovery: maxFiles: 200000 maxEndpointScanFiles: 5000 ``` ## 扫描内容 **内置扫描器**（`scanners/`，无外部依赖）： | 扫描器 | 检查内容 | | --- | --- | | `secrets` | 已提交的 API key、token、私钥（具备占位符感知能力）。 | | `dependencies` | 浮动版本（`*`/`latest`），缺失的 lockfile。 | | `routes` | API 路由清单 + 缺少可见身份验证/限制的敏感 endpoint。 | | `permissions` | 代码中完全缺失任何授权/所有权检查。 | | `configuration` | TLS 验证关闭、通配符 CORS、debug 模式、不安全的 cookie。 | | `security-headers` | Node HTTP 应用中缺失的 helmet / HTTP 安全 headers。 | **规则包**（`rules/`），汇总进 agent 指令中： - `security/` — 身份验证、授权、注入、secret、文件上传、敏感数据 - `api/` — 速率限制（包括绕过向量）、请求限制、分页、CORS、错误响应 - `quality/` — bug、竞态条件、错误处理、测试覆盖率 ## 支持的 agent `codex` · `claude` · `cursor` · `gemini` · `generic`。每一个都有定制的 adapter（`adapters/`）以及共享的 prompt 库和规则包。 | Agent | 读取内容 | | --- | --- | | **Codex** | `AGENTS.md`, `CODEX.md`, `repoguard-results/instructions/codex-instructions.md` | | **Claude Code** | `CLAUDE.md`, `AGENTS.md`, `repoguard-results/instructions/claude-instructions.md` | | **其他** | `repoguard instructions --agent generic` → 一个合并的 prompt | ## CI / SARIF 集成 `audit-report.sarif` 是 SARIF 2.1.0 格式 —— 将其上传到 GitHub 代码扫描： ``` - run: npx repoguard audit . - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: repoguard-results/reports/audit-report.sarif ``` 此仓库自身的 CI (`.github/workflows/ci.yml`) 运行一个 Node 18 兼容性作业，包含类型检查、测试、构建和已提交 Action 的验证。同一分支上被取代的运行将被取消。 ## GitHub 日常安全 RepoGuardAI 包含一个打包的 Node 24 Action 和一个可重用的安全工作流。它不会安排对自身的扫描；目标仓库可以选择自己的时间表和触发器。该工作流以只读权限运行目标代码，在应用 `--fail-on` 之前保留报告，并在受信任的作业中隔离 SARIF/issue 写入。Dependabot 会开启可供审查的依赖 PR；RepoGuardAI 不会自动合并它们或重写应用程序代码。 有关公共/私有调用方、权限、版本固定、故障排除和网站试点，请参阅 [GitHub 安全自动化](docs/github-actions.md)。 ## 仓库布局 ``` prompts/ reusable review steps (system-audit, bug, api-security, rate-limiting, …) rules/ declarative YAML rule packs (security/, api/, quality/) adapters/ per-agent operating instructions (codex, claude-code, cursor, gemini-cli, generic) scanners/ in-house deterministic scanners + shared util schemas/ JSON Schema mirrors of finding / audit / config templates/ report, finding, and remediation-plan templates src/ cli, discovery, scanner-runner, evidence-collector, agent-instructions, report-generator, schemas, types, config tests/ vitest suites ``` ## 开发 ``` pnpm typecheck # tsc --noEmit (strict) pnpm test # vitest run (36 tests) pnpm build # tsup -> dist/ ``` 在不触及无关代码的情况下扩展设计： - **外部扫描器** → 在 `src/scanner-runner.ts` 中添加到 `SCANNERS`。 - **内置扫描器** → 在 `scanners/index.ts` 中添加到 `INTERNAL_SCANNERS`。 - **Agent** → 在 `adapters/` 中添加一个 adapter，并在 `src/agent-instructions.ts` 中接入 `ADAPTER_FILE`。 - **数据结构** → 首先在 `src/schemas.ts` 中更改 Zod schema，然后再更改代码。 ## 安全保证 - 绝不修改受审计的仓库（只读；除非启用了 `mode.modifyFiles`，否则 `fix` 只编写计划，不修改代码）。 - 绝不自动安装扫描器。 - 跳过不可用/已用/不适用的扫描器，且不会导致运行失败。 - 将其自身的输出目录排除在扫描之外（无自我污染）。 - 内置扫描器绝不输出 `confirmed` —— 仅输出可验证的线索。 - 指令禁止在没有代码证据的情况下声称漏洞已确认，并要求明确区分 Confirmed / Potential / Manual-verification / Rejected。 ## 局限性 - 仅限静态分析；目标应用绝不执行。 - API 发现和控制检测是对常见 Node 模式的词法扫描 —— 其他框架或动态构建的路由可能会被遗漏，并且仅当控制点在路由行上可见时才标记为存在（否则 `?` = 需手动验证）。 - 访问控制、租户隔离和业务逻辑深度取决于驱动的 agent。 - 一份没有问题的报告并不能证明仓库是安全的 —— 请参阅 [SECURITY.md](SECURITY.md)。 ## 路线图 - ✅ 解析外部扫描器的 JSON（semgrep、gitleaks、npm/pnpm audit、osv-scanner、trivy）为结构化的种子 finding。 - ✅ 打包的 GitHub Action + `--fail-on ` 退出控制门。 - ✅ 可重用的安全工作流、每周的 Dependabot 以及脱敏的 issue 同步。 - 针对 Python / Go / Rust / Java 框架的路由提取器（目前仅支持 Node）。 - 无需更改代码即可通过配置声明的自定义扫描器。 - 针对拉取请求的仅差异审计模式。 ## 许可证 [MIT](LICENSE) © 2026 Sudarshan Chaudhari (SudarshanTechLabs)