carvalhocaio/trespass

# Trespass Trespass 会连接到你的 GitHub 账户，通过 GitHub API 下载仓库内容，并运行四个分析层： 1. **机密信息检测** — 使用 regex + entropy 模式检测 API key、token、PEM key 和常见的凭据前缀 2. **依赖审计** — 查询 [OSV.dev](https://osv.dev) 获取 `package.json` 和 `requirements.txt` 中已知的 CVE 3. **SAST 模式** — 检测 SQL injection、`eval()`、command injection、XSS vector、弱密码学和 LLM prompt injection 模式 4. **LLM 审查** _(可选)_ — 将标记的代码片段发送到你自己的模型（OpenAI、Anthropic 或 Google）以获取详细的发现结果和修复建议 扫描结果会按每次扫描进行持久化存储，并通过具有按严重程度细分和可展开代码片段的暗色主题 UI 展示。 ## 功能 - GitHub OAuth 登录（Better-Auth） - 使用 AES-256-GCM 对 GitHub PAT 和 LLM API key 进行加密存储 - “即发即忘”的后台扫描 — HTTP 请求不会被阻塞 - 包含状态跟踪（`queued → running → done | error`）的每次扫描结果历史记录 - 扫描期间的终端风格进度面板 — 实时步骤跟踪（依赖审计 → 文件树 → 代码扫描 → LLM 审查），包含计数和状态图标 - 结果页面上的重新扫描按钮 — 为相同的 repo 启动新的扫描并导航到最新的结果 - 可以直接从任何发现结果中打开 GitHub Issue — 自动预填标题、严重程度、代码片段和修复建议 - LLM 审查可平滑降级：如果未配置 API key，扫描仍会运行三个静态层 - UI 页脚中的语义化版本控制徽章 ## 技术栈 - **Frontend**：Nuxt 4 · Vue 3 · shadcn-vue · Tailwind CSS v4 - **Backend**：Hono · Node.js - **Database**：PostgreSQL（在 [Neon](https://neon.tech) 上测试过） · Drizzle ORM - **Auth**：带有 GitHub OAuth 的 Better-Auth - **Monorepo**：pnpm workspaces · Turborepo - **Linting**：Biome（ultracite 规则集） ## 前置条件 - Node.js 22+ - pnpm 11+ - PostgreSQL 15+（或 Neon 连接字符串） - 一个 GitHub OAuth App（Client ID + Secret） ## 安装说明 ``` git clone cd trespass pnpm install ``` 复制并填写环境变量文件： ``` cp apps/server/.env.example apps/server/.env cp apps/web/.env.example apps/web/.env ``` 推送数据库 schema： ``` pnpm db:push ``` 启动开发服务器： ``` pnpm dev ``` - Frontend：http://localhost:3001 - API：http://localhost:3000 ## 配置 ### `apps/server/.env` | 变量 | 描述 | 必需 | |---|---|---| | `DATABASE_URL` | PostgreSQL 连接字符串 | 是 | | `BETTER_AUTH_SECRET` | 用于 session 签名的 32+ 字符密钥 | 是 | | `BETTER_AUTH_URL` | API 服务器的公共 URL | 是 | | `GITHUB_CLIENT_ID` | GitHub OAuth App 的 client ID | 是 | | `GITHUB_CLIENT_SECRET` | GitHub OAuth App 的 client secret | 是 | | `SECRET_ENCRYPTION_KEY` | 用于 AES-256-GCM 的 64 位十六进制密钥 | 是 | 生成一个 `SECRET_ENCRYPTION_KEY`： ``` node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" ``` ### `apps/web/.env` | 变量 | 描述 | 必需 | |---|---|---| | `NUXT_PUBLIC_SERVER_URL` | API 服务器的公共 URL | 是 | ### 创建 GitHub OAuth App 前往 **GitHub → Settings → Developer settings → OAuth Apps → New OAuth App**： - **Homepage URL**：`http://localhost:3001` - **Authorization callback URL**：`http://localhost:3000/api/auth/callback/github` ## 项目结构 ``` trespass/ ├── apps/ │ ├── web/ # Nuxt 4 frontend │ └── server/ # Hono API │ └── src/ │ ├── routes/ # repos, scans, secrets │ ├── services/ │ │ └── scanner/ # scan engine layers │ └── middleware/ ├── packages/ │ ├── auth/ # Better-Auth configuration │ ├── crypto/ # AES-256-GCM encrypt/decrypt │ ├── db/ # Drizzle schema + migrations │ ├── env/ # Validated env vars (Zod) │ └── github/ # Octokit wrapper └── tests/ # Vitest suite — unit, integration, functional, security, smoke ``` ## 脚本 | 命令 | 描述 | |---|---| | `pnpm dev` | 以 watch 模式启动所有应用 | | `pnpm build` | 构建所有应用 | | `pnpm check-types` | 跨所有包进行 TypeScript 类型检查 | | `pnpm db:push` | 将 schema 推送到数据库（无 migration 文件） | | `pnpm db:generate` | 生成 Drizzle migration 文件 | | `pnpm db:migrate` | 运行待处理的 migration | | `pnpm db:studio` | 打开 Drizzle Studio | | `pnpm test` | 运行完整的测试套件 | | `pnpm check` | Biome lint + 格式检查 | | `pnpm fix` | Biome lint + 格式自动修复 | ## 测试 ``` pnpm test # run all 108 tests across the suite ``` 测试会在每次 pull request 和推送到 main 分支时通过 GitHub Actions 自动运行。无需数据库 — 所有外部 I/O 都会被 mock。 ## 本地 PostgreSQL (Docker) ``` docker compose up -d # DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres ```

标签：LLM代码审查, MITM代理, SAST, StruQ, 机密检测, 测试用例, 盲注攻击, 自动化攻击