pritpatel2412/CodeGuard

# CodeGuard 面向 Pull/Merge Request 的自动化安全与代码质量审查平台，提供 AI 分析、可选的 AI 修复、自定义策略执行以及面向开发者的分流 UI。 ## CodeGuard 的功能 CodeGuard 连接代码仓库，接收 webhook 事件，分析代码变更，存储审查结果，并在仪表盘中展示可操作的审查输出。 核心成果： - 检测 PR/MR 变更中的安全、Bug、性能和可维护性风险。 - 通过 `.codeguard.yml` 执行特定于组织的规则。 - 生成带有安全检查的、可选的 AI 辅助修复 PR/MR。 - 提供污点传播视图，用于展示跨文件风险路径和语义流。 - 追踪审查历史、风险趋势，并提供可下载的报告。 ## 功能覆盖 ### 1) AI 审查流水线 - 使用 GPT-4o 进行 diff 分析，并生成带有类型/经过验证的审查响应。 - 分类发现问题（`bug`、`security`、`performance`、`readability`、`maintainability`）。 - 为每次审查生成风险评分和摘要。 - 将评论发布到源代码控制系统，并在仪表盘级别记录历史。 ### 2) 策略即提示词 (`.codeguard.yml`) - 在 PR head SHA 处从仓库根目录获取 `.codeguard.yml`。 - YAML 解析 + 严格的 schema 验证（`js-yaml` + `zod`）。 - 将验证后的策略规则注入到专门的 GPT-4o 策略执行提示词中。 - 持久化策略定义以及每次审查中的策略违规记录。 - UI 支持： - 审查详情中的策略标签页 - 仓库页面上的策略查看器和执行开关 - 新增 API： - `GET /api/policy/:repositoryId` - `GET /api/policy/violations/:reviewId` - `PUT /api/policy/:repositoryId/toggle` 规范文档：[docs/codeguard-yml-spec.md](docs/codeguard-yml-spec.md) ### 3) 跨文件污点分析 - 针对变更代码范围进行图构建和污点路径传播。 - 可选的 AI 增强，用于提供解释/修复上下文。 - 持久化图和路径产物，并提供专用的 API 端点。 - UI 支持： - 污点路径标签页 - 语义图标签页 ### 4) AI 自动修复工作流 - 从可操作的审查评论中触发修复。 - 获取文件上下文，生成完整文件的修复，并创建分支和 PR/MR。 - 包含针对敏感文件系列的安全拦截机制。 - 在 UI 中展示进度流程，并提供指向已创建 PR/MR 的链接。 ### 5) 开发者用户体验增强 - 安全修复指示器徽章（基于图标，无 emoji）。 - 审查页面高级过滤： - 风险 - 状态 - 平台 - 审查类型（安全修复 vs 常规审查） - 排序 + 重置过滤器 - 更新了法律页面，包含了与平台行为一致的详细条款/隐私说明。 - 设置页面重构，具备更好的可靠性： - 基于查询的加载 - 脏状态追踪 - 重置/保存控件 - 更清晰的 webhook/安全指导 ## 已实施的安全加固 CodeGuard 现在包含了更强的生产环境安全防护： - 在生产环境中强制执行会话密钥（需要 `SESSION_SECRET`，并具有最小长度策略）。 - 净化 `/api/user` 响应（不暴露 token）。 - 对改变状态的 API 路由进行 CSRF 保护（具有定义的豁免）。 - 在处理仓库 webhook 时，强制进行 GitHub webhook 签名验证。 - 对 webhook 负载进行仓库身份检查。 - 针对敏感键对 API 响应日志进行脱敏处理。 - 在生产环境中通过 `APP_ORIGIN` 白名单进行更严格的 CORS 处理。 - 收紧生产环境 CSP（特别是移除了 `unsafe-eval`）。 - 在前端安全处理 PR/MR 链接的外部 URL。 - 在 UI 中掩码 webhook 密钥（提供明确的显示/复制流程）。 - 事件响应指南和安全的 env 模板： - [.env.example](.env.example) - [docs/SECURITY_INCIDENT_RESPONSE.md](docs/SECURITY_INCIDENT_RESPONSE.md) ## 技术栈 | 层级 | 技术 | | :--- | :--- | | 前端 | React 18, Vite, TypeScript, TanStack Query, Tailwind, Radix UI, Framer Motion | | 后端 | Node.js, Express, Passport (GitHub OAuth), Socket.io | | AI | OpenAI GPT-4o | | 数据库 | PostgreSQL, Drizzle ORM, Drizzle Kit | | 集成 | GitHub Webhooks/API，部分支持 GitLab 工作流 | | 可视化 | Recharts, XYFlow, Dagre | ## 项目结构 | 路径 | 用途 | | :--- | :--- | | `client/` | 前端应用（仪表盘、审查、设置、策略/污点视图） | | `server/` | API 路由、身份验证、集成、AI 编排、污点 + 策略引擎 | | `shared/` | 共享 schema/类型 (Drizzle + Zod) | | `api/` | Serverless 入口配置 | | `script/`, `scripts/` | 构建和实用工具脚本 | | `docs/` | 产品/文档规范（包括 `.codeguard.yml` 规范和事件响应） | ## 快速开始 ### 前置条件 - Node.js 20+ - PostgreSQL 数据库 - OpenAI API key - GitHub OAuth app 凭据 ### 环境配置 使用 [.env.example](.env.example) 作为您的基准配置。 本地最少需要的变量： ``` DATABASE_URL=postgresql://user:pass@localhost:5432/codeguard OPENAI_API_KEY=... GITHUB_CLIENT_ID=... GITHUB_CLIENT_SECRET=... GITHUB_CALLBACK_URL=http://localhost:5000/auth/github/callback SESSION_SECRET=your_long_random_secret_min_32_chars APP_ORIGIN=http://localhost:5000 ``` 可选配置： ``` TAINT_ENGINE_ENABLED=true ENABLE_DEBUG_GITHUB_AUTH=false ``` ### 安装并运行 ``` npm install npm run db:push npm run dev ``` ### 构建并启动 ``` npm run build npm run start ``` ## 部署检查清单 在发布到生产环境之前： 1. 设置强 `SESSION_SECRET` 和有效的 `APP_ORIGIN`。 2. 轮换任何之前暴露的密钥/token。 3. 确保已配置仓库 webhook 密钥。 4. 运行类型检查：`npm run check`。 5. 验证 webhook 签名验证失败会被拒绝。 6. 验证 `/api/user` 不会暴露 token 字段。 7. 确保 CI 工作流处于激活状态（`.github/workflows/ci.yml`）。 ## CI 与质量门禁 当前的 CI 工作流包括： - 安装依赖项 - 类型检查 - 依赖项审计（高危及以上） 路径：[.github/workflows/ci.yml](.github/workflows/ci.yml) ## 关于 GitLab 的说明 GitHub webhook 流程是主要的生产路径。代码中包含了用于部分修复流程的 GitLab 辅助逻辑，而 webhook 功能的对齐仍在不断完善中。 ## 发布说明 ### 最新版本 (2026-04) #### 安全与策略版本 - 通过仓库 `.codeguard.yml` 添加了策略即提示词支持： - YAML 加载/验证 - 将规则注入 GPT 策略执行 - 策略违规持久化和 API - 仓库策略查看器和审查级别的策略标签页 UI - 添加了跨文件污点分析流水线集成和 UI： - 污点路径标签页 - 语义图可视化标签页 - 改进了审查体验： - 安全修复指示器徽章（基于图标） - 高级审查过滤（风险/状态/平台/类型/排序/重置） - 关键审查界面使用无 emoji 的专业标签 - 完成了部署前的强化检查： - 对修改状态的 API 路由进行 CSRF 保护 - 严格的 webhook 签名和仓库身份检查 - 净化后的 `/api/user` 响应模型 - 敏感日志脱敏 - 生产环境 CORS 白名单 + 更严格的 CSP 策略 - 针对已创建的 PR/MR 链接进行安全的外部 URL 验证 - UI 中掩码 webhook 密钥，并提供明确的显示/复制流程 - 升级了法律和设置内容： - 详细的条款和隐私页面，与当前平台行为保持一致 - 设置页面可靠性改进（基于查询的加载、脏状态追踪、重置/保存控件） - 添加了运营准备就绪的产物： - `.env.example` - `docs/SECURITY_INCIDENT_RESPONSE.md` - 位于 `.github/workflows/ci.yml` 的基准 CI 工作流 ### 早期版本 - 初始平台发布：AI 驱动的 PR 审查流水线、仪表盘、仓库管理和风险追踪基础。

标签：AI代码分析, DevSecOps, GitHub集成, MITM代理, 上游代理, 代码安全, 代码质量审查, 测试用例, 漏洞枚举, 自动化攻击, 静态应用安全测试