AnderssonEspinoza/codeward-ia

# CodeWard AI **OSS 安全审计工具** CodeWard AI 是一款面向仓库和代码片段的 OSS 安全与合规审计工具，目前处于 MVP 阶段。 其核心目标是提供可操作的发现结果和可追溯的证据，以及真实的后端架构： API + 集成的 BullMQ worker + 队列 + PostgreSQL + Redis。 ## 演示 - 在线应用：https://codeward-ia.vercel.app - API（Render Docker）：https://codeward-api-docker.onrender.com ### 演示视频 [](./public/demo.mp4) 点击图片打开视频：[public/demo.mp4](./public/demo.mp4) ### 截图 **首页**  **审计结果**  ## 核心价值 - 代码扫描输出可用于实际开发（不仅仅是视觉演示）。 - 证据按类型分类（`direct`、`heuristic`、`inferred`），避免虚假确定性。 - 异步流程配合队列和持久化，支持完整仓库分析。 - 标准导出格式（`SARIF`、`Markdown`、`JSON`），便于未来集成。 ## 技术栈 - 前端：React + Vite + Tailwind - 后端：Node.js + Express - Worker：集成在 API 进程中的 BullMQ（免费层友好模式） - 数据库：PostgreSQL - 队列：Redis - 可选解释：本地 Ollama - 认证：GitHub OAuth + 服务端会话 ## 分析状态（坦诚说明） - `direct`：由扫描器/工具确认的发现。 - `heuristic`：由本地正则规则发现的发现。 - `inferred`：通过上下文推断的架构风险。 如果实际扫描失败，UI 会显示错误。演示模式使用模拟数据，需要手动触发。 如果使用 GitHub 登录，历史记录和策略将按用户隔离。 ## MVP 当前范围 - 分析代码片段和 GitHub 仓库。 - 根据扫描器的实际覆盖范围计算健康评分和置信度评分。 - 支持通过用户（使用 GitHub OAuth）或管理员密钥（访客模式）设置策略。 - 提供历史记录、状态、导出和认证配置的端点。 ## 当前局限性（透明说明） - 不能替代企业级专业安全审计。 - 部分引擎仍基于启发式方法，可能产生误报/漏报。 - 分析深度取决于运行时 OSS 工具的可用性。 - 扫描针对免费层环境的速度/成本进行了优化，而非无限全面覆盖。 ## 当前检测能力 - 本地启发式（始终可用） - Gitleaks（如果主机已安装） - Semgrep（如果主机已安装） - OSV-Scanner（如果主机已安装） - Trivy（如果主机已安装） ## 覆盖范围矩阵（坦诚） | 领域 | 当前检测能力 | 证据类型 | | --- | --- | --- | | 硬编码密钥 | 本地正则 + Gitleaks | `heuristic` / `direct` | | 源代码 SAST | 本地正则 + Semgrep | `heuristic` / `direct` | | 依赖漏洞 | OSV-Scanner（+ 可选 Trivy） | `direct` | | 架构风险（通过 README/代码上下文） | 推断规则 | `inferred` | | 许可证 | 本地正则 + Trivy | `heuristic` / `direct` | 仓库最低覆盖所需的扫描器：`gitleaks`、`semgrep`、`osv-scanner`。 如果缺失，报告将标记覆盖不完整并降低置信度评分。 ## 推荐用例 - 技术重构或入职前的仓库初始风险评估。 - 快速检查密钥、不安全模式和依赖风险。 - 生成可共享的报告，用于团队内部技术讨论。 - 作为开源基础，用于演进自己的 DevSecOps 流程。 ## 安装 ``` pnpm install cp .env.example .env ``` ## 本地基础设施 ``` docker compose up -d ``` ## 运行 ``` pnpm run dev:full ``` 独立命令： ``` pnpm run api pnpm run worker pnpm run dev ``` 生产环境（无 watch）： ``` pnpm run start:api ``` ## GitHub OAuth（真实） 1. 在 GitHub 创建 OAuth App。 2. 配置回调 URL：`http://localhost:8787/auth/github/callback` 3. 在 `.env` 中配置： ``` GITHUB_CLIENT_ID=... GITHUB_CLIENT_SECRET=... GITHUB_CALLBACK_URL=http://localhost:8787/auth/github/callback FRONTEND_URL=http://localhost:5173 SESSION_SECRET=un-secreto-largo ``` 如果不定义 `GITHUB_CLIENT_ID` 和 `GITHUB_CLIENT_SECRET`，应用将运行在访客模式下。 ## 环境变量 - `ADMIN_KEY`：访客模式下编辑策略的可选参数（`x-admin-key`） - `SCAN_TIMEOUT_MS`：外部任务/扫描器的超时时间 - `MAX_REPO_SIZE_KB`：仓库扫描的大小限制 - `VITE_ADMIN_KEY`：UI 在本地访客模式下编辑策略使用的密钥 - `CORS_ORIGINS`：API 允许的来源 - `FRONTEND_URL`：用于 OAuth 重定向的前端 URL - `SESSION_SECRET`：会话 cookie 的密钥 - `GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET`、`GITHUB_CALLBACK_URL`：OAuth 配置 - `GITHUB_TOKEN`（可选）：可减少 GitHub API 限制 - `OLLAMA_MODEL`、`OLLAMA_URL`（可选） - `REQUIRED_SCANNERS`（可选）：必需的扫描器 CSV 列表（默认：`gitleaks,semgrep,osv-scanner`） ## 推荐部署方案：Render + Supabase（Render 免费层） 此仓库已包含 `render.yaml`，用于创建 1 个服务： - `codeward-api`（Web 服务，包含集成的 worker） 建议流程： 1. 在 Supabase 创建项目并复制 `DATABASE_URL`（连接池或直接连接）。 2. 创建 Redis（Render Redis 或 Upstash）并复制 `REDIS_URL`。 3. 在 Render，连接此仓库并使用 `render.yaml`。 4. 在 `codeward-api` 中配置： - `DATABASE_URL` - `REDIS_URL` - `SESSION_SECRET` - `ADMIN_KEY` 5. 在 `codeward-api` 中额外添加： - `FRONTEND_URL`（你的 Vercel 域名） - `CORS_ORIGINS`（包含你的 Vercel 域名） - `GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET`、`GITHUB_CALLBACK_URL`（如果使用 GitHub 登录） 如果暂时只使用访客模式，可以将 GitHub OAuth 变量留空。 ## 替代部署方案：Render（Docker，含已安装的扫描器） 如果想在生产环境中获得 `gitleaks + semgrep + osv-scanner` 的真正覆盖，请使用包含的 `Dockerfile`。 步骤： 1. 在 Render 从此仓库创建**新的 Web Service**。 2. Render 将检测到根目录的 `Dockerfile` 并进行 Docker 构建。 3. 配置变量： - `DATABASE_URL` - `REDIS_URL` - `SESSION_SECRET` - `ADMIN_KEY` - `FRONTEND_URL` - `CORS_ORIGINS` - `GITHUB_CLIENT_ID` - `GITHUB_CLIENT_SECRET` - `GITHUB_CALLBACK_URL` 4. 部署。 运行时快速验证： ``` https://TU-API.onrender.com/api/health ``` 仓库扫描后，在响应的 `meta.tools` 中检查是否包含 OSS 扫描器（`gitleaks`、`semgrep`、`osv-scanner`），或者在覆盖范围警告中查看。 ## Vercel 代理（推荐） 此仓库包含 `vercel.json`，带有重写规则以避免跨站 cookie： - `/api/*` -> `https://codeward-api.onrender.com/api/*` - `/auth/*` -> `https://codeward-api.onrender.com/auth/*` 通过这种方式，生产环境中前端使用相同来源，不依赖浏览器的第三方 cookie。 在 Vercel 中可以将 `VITE_API_URL` 留空或不定义。 如果启用此代理，使用 Vercel 域名配置 GitHub OAuth 回调： - `https://codeward-ia.vercel.app/auth/github/callback` ## 端点 - `GET /api/health` - `GET /api/me` - `GET /auth/github` - `GET /auth/github/callback` - `POST /auth/logout` - `POST /api/scans` - `GET /api/scans/:scanId` - `GET /api/scans/:scanId/export?format=json|sarif|markdown` - `GET /api/history` - `GET /api/policies` - `PUT /api/policies`（GitHub 会话或访客模式下的 `x-admin-key`） ## 导出格式 - JSON - SARIF 2.1. - Markdown ## E2E 冒烟测试（远程） ``` API_BASE_URL=https://codeward-api.onrender.com pnpm run test:e2e:remote ``` 验证真实流程：`health` -> 创建扫描 -> 轮询 -> 导出 markdown。 ## 许可证 MIT。参见 [LICENSE](./LICENSE)。 ## 社区 - 贡献指南：[CONTRIBUTING.md](./CONTRIBUTING.md) - 行为准则：[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) ## 路线图 - 改进评分的精确性和按工具追踪发现结果的能力。 - 减少许可证启发式检测中的误报。 - 扩大 E2E 测试覆盖范围，包括 OAuth 会话和多用户隔离。 - 加强 CI/CD 集成，用于仓库的持续使用。

标签：AI风险缓解, BullMQ, Dependency扫描, DevSecOps, Express, GitHub OAuth, GNU通用公共许可证, LLM评估, MITM代理, MVP产品, Node.js, Ollama, OSS安全, PostgreSQL, React, Redis, SARIF导出, SAST, Secrets扫描, Syscalls, Tailwind, Vite, 上游代理, 云安全监控, 云计算, 代码安全审计, 代码审查助手, 代码质量评分, 依赖漏洞扫描, 后端架构, 多平台, 安全合规, 安全评分, 开源安全审计, 异步任务队列, 搜索引擎查询, 正则匹配, 测试用例, 盲注攻击, 网络代理, 自定义脚本, 规则引擎, 静态分析, 静态应用安全测试