## 📖 目录 - [关于](#-about) - [问题陈述](#-problem-statement) - [功能](#-features) - [技术栈](#️-tech-stack) - [快速开始](#-getting-started) - [API 文档](#-api-documentation) - [架构](#-architecture) - [部署](#-deployment) - [故障排除](#-troubleshooting) - [贡献](#-contributing) - [许可证](#-license) - [联系方式](#-contact) ## 🎯 关于 OAuthSentry 是一个生产就绪的安全代理，可针对实时的 IOC 威胁情报，持续扫描您组织的 OAuth 应用程序、第三方 AI 集成和 npm 依赖项。对于高风险发现，系统会自动提交 Linear 工单并发送 Slack 实时警报。专为防范供应链攻击和受损 AI 工具集成的安全团队而构建。 ## ⚠️ 问题陈述 在 2026 年 4 月发生的 Vercel/Context.ai 事件中，一个受损的 OAuth 应用程序借此侵入了员工的 Google Workspace 帐户，此后安全团队需要对以下内容进行持续监控： - 拥有过度权限的 OAuth 应用程序 - 具有 admin 权限的第三方 AI 集成 - 恶意的 npm 包（域名拼写抢注、后门） - 供应商信任变更和已废弃的项目 ## ✨ 功能 | 功能 | 描述 | |---------|-------------| | **🔍 AI 驱动扫描** | 使用 GPT-4o-mini 扫描 OAuth 应用程序、npm 包和 SaaS 工具 | | **📊 风险评分** | 结合 IOC 匹配和详细推理的 0–100 分制评分 | | **🎫 Linear 集成** | 为关键发现自动提交工单 | | **💬 Slack 警报** | 带有可操作修复步骤的丰富 Block Kit 消息 | | **⏰ 定时扫描** | 持久化存储在 Upstash Redis 中的 24/7 全天候监控 | | **📡 实时威胁情报** | 来自 NVD、OSV 和 GitHub Security Advisories 的实时情报 | | **📄 PDF 导出** | 包含执行摘要的综合报告 | | **🌓 深色/浅色模式** | 带有主题切换的精美 UI | | **🧪 演示模式** | 无需 API 调用即可立即加载真实的扫描发现 | | **⚡ 实时流式传输** | 扫描结果的 NDJSON 流式传输 | ## 🛠️ 技术栈 ### 前端 - **框架**：Next.js 16 App Router - **样式**：Tailwind CSS v4 - **UI 组件**：shadcn/ui - **类型安全**：TypeScript ### 后端与 AI - **AI SDK**：Vercel AI SDK 6 - **模型**：OpenAI GPT-4o-mini（通过 AI Gateway） - **工作流**：Vercel Workflow Development Kit (WDK) - **存储**：Upstash Redis - **API**：REST 与 GraphQL ### 集成 - **Linear**：用于提交工单的 GraphQL API - **Slack**：用于发送警报的 Incoming Webhooks - **威胁情报**：NVD、OSV、GitHub Security Advisories ### 部署 - **托管**：Vercel - **定时任务**：Vercel Cron Jobs ## 🚀 快速开始 ### 前置条件 - Node.js 18+ - pnpm 或 npm - Vercel 帐户（用于部署） - OpenAI API 密钥（通过 Vercel AI Gateway） ### 安装 1. **克隆仓库** git clone https://github.com/Hayredin950/oauthsentry.git cd oauthsentry 2. **安装依赖** pnpm install # 或 npm install 3. **配置环境变量** 创建一个 `.env.local` 文件： # 必填 — Vercel AI Gateway AI_GATEWAY_API_KEY=your_vercel_ai_gateway_key # 选填 — Linear 集成 LINEAR_API_KEY=your_linear_api_key # 选填 — Slack 集成 SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL # 定时扫描必填 — Upstash Redis KV_REST_API_URL=your_upstash_redis_url KV_REST_API_TOKEN=your_upstash_redis_token # 选填 — 警报中链接的应用 URL NEXT_PUBLIC_APP_URL=https://your-deployment.vercel.app 4. **运行开发服务器** pnpm dev # 或 npm run dev 5. **打开应用程序** 导航至 [http://localhost:3000](http://localhost:3000) ## 📚 API 文档 完整的 API 文档请访问：[https://oauthsentry-phi.vercel.app/api-docs](https://oauthsentry-phi.vercel.app/api-docs) ### 核心 Endpoint | 方法 | 路径 | 用途 | |--------|------|---------| | `POST` | `/api/scan` | AI 驱动的流式扫描 (NDJSON) | | `GET` | `/api/threat-feed` | 实时威胁情报 | | `POST` | `/api/actions/file-ticket` | 创建 Linear Issue | | `POST` | `/api/actions/send-alert` | 发送 Slack 警报 | | `GET/POST/PUT/DELETE` | `/api/scheduled-scans` | 管理扫描计划 | ## 🏗️ 架构 ### 数据流 ``` User clicks "Run Scan" ↓ POST /api/scan with asset list ↓ AI analyzes each asset against IOC feeds + advisories (streaming) ↓ RiskFinding[] streamed to dashboard in real-time ↓ User clicks "File ticket" → POST /api/actions/file-ticket ↓ Linear issue created via GraphQL API ↓ User clicks "Send alert" → POST /api/actions/send-alert ↓ Rich Block Kit message posted to Slack webhook ``` ### 项目结构 ``` oauthsentry/ ├── app/ │ ├── layout.tsx # Root layout + ThemeProvider │ ├── page.tsx # Main dashboard │ ├── globals.css # Tailwind v4 + design tokens │ ├── api-docs/page.tsx # API documentation │ └── api/ │ ├── scan/route.ts # AI scan agent │ ├── threat-feed/route.ts # Threat intel feed │ ├── actions/ │ │ ├── file-ticket/ │ │ └── send-alert/ │ ├── scheduled-scans/ │ └── workflow/ ├── components/ │ ├── ui/ # shadcn/ui components │ ├── hero.tsx │ ├── risk-scanner.tsx │ ├── risk-results-table.tsx │ └── ... ├── lib/ │ ├── types.ts │ ├── linear-client.ts │ ├── risk-knowledge.ts │ └── ... ├── public/ ├── package.json ├── tsconfig.json └── vercel.json ``` ## 🚀 部署 ### 部署到 Vercel 1. **通过 Vercel CLI 部署** vercel 2. 在 Vercel Project Settings → Environment Variables 中**设置环境变量**。 3. **必要集成**：通过 Vercel Marketplace 添加 **Upstash for Redis** 以启用定时扫描。 `vercel.json` 中包含一个 Cron 任务，每 15 分钟触发一次 `/api/scheduled-scans/execute` 以运行到期的计划任务。 ## 🔧 故障排除 | 问题 | 解决方案 | |-------|----------| | 扫描未运行 | 验证是否设置了 `AI_GATEWAY_API_KEY` | | Linear 工单未创建 | 在 Settings 或环境变量中检查 Linear API 密钥 | | Slack 警报未发送 | 确保已配置 Slack Webhook URL | | 威胁情报为空 | 外部 API 可能受到速率限制 — 已启用自动重试 | | 定时扫描失败 | 确认 Upstash Redis 集成是否处于活跃状态 | | 构建错误 | 在本地运行 `pnpm build` 以调试 TypeScript 问题 | ## 📄 许可证 基于 MIT 许可证分发。请查看 `LICENSE` 获取更多信息。 ## 📬 联系方式 **Hayredin** - [hayredin.950@gmail.com](mailto:hayredin.950@gmail.com) 项目链接：[https://github.com/Hayredin950/oauthsentry](https://github.com/Hayredin950/oauthsentry) 在线演示：[https://oauthsentry-phi.vercel.app](https://oauthsentry-phi.vercel.app)

标签：威胁情报, 开发者工具, 文档安全, 第三方风险管理, 自动化告警, 自动化攻击