buddhsen-tripathi/openvscan

# OpenVScan OpenVScan 是一款基于 Web 的漏洞扫描器，它将开源安全工具与 AI 辅助分析相结合，以实现更快、更可靠的预生产安全测试。它**完全运行在 Cloudflare 上** —— 使用了 Workers、Containers、D1、R2 和 Queues。 ## 架构 | 层级 | 技术栈 | 职责 | |------|-------|------------------| | **Web Worker** (`web/`) | TanStack Start, React 19, Tailwind 4, Cloudflare Workers | UI、Better-auth、服务器函数（项目/扫描 CRUD）、队列生产者、导出 | | **Scanner Worker** (`workers/`) | Cloudflare Worker + Container, Queues | 消费扫描作业，在 container 中运行 Trivy，将扫描结果写入 D1，并将产出物写入 R2 | | **数据库** | Cloudflare **D1** (SQLite, Drizzle ORM) | 用户、会话、项目、扫描、发现结果、日志 | | **对象存储** | Cloudflare **R2** | 原始扫描器输出产出物 | | **队列** | Cloudflare **Queues** | 将扫描调度与执行解耦 | **没有单独的 API 服务器、Redis 或 Postgres** —— Web Worker 通过 TanStack Start 服务器函数管理数据访问，消费者 Worker 驱动扫描器 container。 ## 快速开始 ``` # Clone 和 install git clone https://github.com/Buddhsen-tripathi/openvscan.git cd openvscan pnpm install # 认证并 provision Cloudflare 资源（仅限首次） pnpm --filter openvscan-web exec wrangler login pnpm --filter openvscan-web exec wrangler d1 create openvscan pnpm --filter openvscan-web exec wrangler r2 bucket create openvscan-artifacts pnpm --filter openvscan-web exec wrangler queues create openvscan-scans # → 将打印出的 D1 database_id 复制到 web/wrangler.jsonc 和 workers/wrangler.jsonc 中 # 将 schema 应用到本地 D1，然后启动 web app pnpm db:migrate:local pnpm dev:web ``` Web 应用运行在 http://localhost:3000。 ### 环境配置 绑定（D1、R2、Queue）位于 `wrangler.jsonc` 中，而不是 `.env`。在 `web/.dev.vars` 中提供本地开发所需的密钥： ``` BETTER_AUTH_SECRET="generate-a-random-32-char-secret" BETTER_AUTH_URL=http://localhost:3000 VITE_APP_URL=http://localhost:3000 ``` 使用 `openssl rand -base64 32` 生成密钥。 ### GitHub 集成 OpenVScan 通过 **GitHub App**（仓库访问权限、push webhook、PR 评论）和 OAuth 客户端（用于“使用 GitHub 继续”登录）连接到 GitHub。GitHub 功能是可选的 —— 如果不启用，手动项目扫描仍然可以正常工作。 **1. 注册 GitHub App**（Settings → Developer settings → GitHub Apps → New）： | 设置 | 值 | |---------|-------| | Webhook URL | `https:///api/github/webhook` | | Setup URL (callback) | `https:///api/github/setup`（勾选 "Redirect on update"） | | Webhook secret | 一个随机字符串（作为 `GITHUB_WEBHOOK_SECRET`） | | Permissions | **Contents:** read, **Pull requests:** read & write, **Metadata:** read | | Subscribe to events | **Push**, **Pull request**, **Installation**, **Installation repositories** | 为 App 生成一个私钥（会下载一个 `.pem` 文件）。该 App 的 **App ID**、**slug**（来自其公开页面 URL）、**Client ID/secret** 以及私钥将用于填充下方的密钥。 **2. 提供密钥。** 在本地，复制 `web/.dev.vars.example` → `web/.dev.vars` 和 `workers/.dev.vars.example` → `workers/.dev.vars` 并填写内容。在生产环境中： ``` # Web Worker for s in GITHUB_APP_ID GITHUB_APP_SLUG GITHUB_APP_PRIVATE_KEY GITHUB_WEBHOOK_SECRET \ GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET; do pnpm --filter openvscan-web exec wrangler secret put "$s" done # Scanner Worker for s in GITHUB_APP_ID GITHUB_APP_PRIVATE_KEY APP_URL; do pnpm --filter openvscan-workers exec wrangler secret put "$s" done ``` **3. 使用它。** 登录 → **Repositories** → 将 App 安装到你想要的 repo 上 → 连接一个 repo → 将其触发器设置为 **Automatic**，并可选择性配置分支过滤。在匹配的 push 发生时，OpenVScan 会扫描该 repo，并且（当分支有打开的 PR 时）发布一条发现结果摘要评论。 对于本地 webhook 测试，使用隧道（例如 [smee.io](https://smee.io) 或 `cloudflared tunnel`）将 GitHub 的请求转发到你的开发服务器，并指向 `localhost:3000/api/github/webhook`。 ### 首次运行 1. 访问 http://localhost:3000/signup 并创建一个账户。 2. 从仪表板创建一个项目。 3. 从项目页面启动扫描（目标 = 一个 repo URL、container image 或路径）。 4. 打开扫描详情页面以查看状态、发现结果、日志和导出内容。 ## 功能 ### 当前功能 - ✅ 邮箱/密码**和 GitHub**身份验证（基于 D1 的 Better-auth） - ✅ 多租户项目管理 - ✅ **GitHub App 集成**：连接 repo，在 push 时自动扫描，将发现结果发布到 PR - ✅ 使用 Trivy 进行异步漏洞扫描（依赖项、container image、repo） - ✅ 按严重程度分组的发现结果及修复指南 - ✅ 扫描执行日志和状态轮询 - ✅ 扫描取消（基于数据库标志） - ✅ 导出 JSON 和 SARIF 格式 - ✅ 原始扫描器产出物存储在 R2 中 ### 计划中 - 🔜 额外的扫描器（Nmap、Semgrep、OWASP ZAP） - 🔜 消费者 Worker 中的 AI 辅助分诊 - 🔜 行内 PR 审查评论（逐行）+ Checks API - 🔜 支持 GitLab - 🔜 定时扫描和基线 - 🔜 团队协作 ## 仓库结构 ``` openvscan/ ├── web/ # TanStack Start app on Cloudflare Workers │ ├── src/routes/ # routes incl. api/auth/$ and api/scans.$id.export │ ├── components/ # auth/, dashboard/, homepage/, ui/ │ ├── lib/ # auth.ts, db.ts, server.ts (server functions), api.ts │ └── wrangler.jsonc # bindings: DB (D1), ARTIFACTS (R2), SCAN_QUEUE ├── workers/ # Cloudflare consumer Worker (openvscan-scanner) │ ├── src/index.ts # ScannerContainer + queue() handler │ ├── container/ # Dockerfile (node + Trivy) + server.mjs │ └── wrangler.jsonc # queue consumer + D1 + R2 + Container bindings ├── packages/ │ ├── db/ # Drizzle SQLite schema for D1 + migrations │ └── types/ # Shared TypeScript types & enums └── package.json # Root scripts ``` ## 开发 ### 前置条件 - Node.js 22.12+ - pnpm 8+ - 一个 Cloudflare 账户（使用 Workers Paid 以运行扫描器 container） - Docker（仅用于构建/运行扫描器 container） ### 命令 ``` # 开发 pnpm dev:web # web Worker (local D1/R2/Queue via vite plugin) pnpm --filter openvscan-workers dev # scanner Worker (needs Docker) # Build pnpm prebuild # build shared packages pnpm build # build the web Worker # Database (D1) pnpm db:generate # generate SQLite migrations from the schema pnpm db:migrate:local # apply to local D1 pnpm db:migrate # apply to remote D1 ``` ## 部署 所有内容都部署到 Cloudflare。 ``` # 1. 将 migrations 应用到远程 D1 pnpm db:migrate # 2. 部署 scanner Worker（包含 build 和 push container image — 需要 Docker） pnpm --filter openvscan-workers deploy # 3. 部署 web Worker pnpm deploy # 4. 在 web Worker 上设置 production secrets pnpm --filter openvscan-web exec wrangler secret put BETTER_AUTH_SECRET # 同时将 BETTER_AUTH_URL / VITE_APP_URL 设置为已部署的 origin，然后重新 deploy ``` ## 文档 - **[AGENTS.MD](AGENTS.MD)** — 面向 AI agent 的架构上下文 - **[CONTRIBUTING.md](CONTRIBUTING.md)** — 贡献指南 - **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — 社区标准 ## 许可证 仅根据 GNU Affero General Public License v3.0 获得许可。详情请参阅 [LICENSE](LICENSE)。 ## 致谢 OpenVScan 构建在受信赖的开源安全工具之上： - [Trivy](https://github.com/aquasecurity/trivy) — container、文件系统及 repository 扫描 - [OWASP ZAP](https://www.zaproxy.org/) — DAST 扫描（计划中） - [Nmap](https://nmap.org/) — 网络扫描（计划中） - [Semgrep](https://semgrep.dev/) — 静态分析（计划中） **由 [Buddhsen Tripathi](https://github.com/Buddhsen-tripathi) 制作** 如有疑问或需要支持，请[提交一个 issue](https://github.com/Buddhsen-tripathi/openvscan/issues)。

标签：AI应用开发, Cloudflare, MITRE ATT&CK, React, Serverless, Syscalls, Web安全, 加密, 安全测试, 攻击性安全, 漏洞扫描器, 程序员工具, 自动化攻击, 蓝队分析, 请求拦截