ESSAKKI-RAJA/THREATWEAVE-Enterprise-Cyber-Risk-Intelligence-Platform

## 概述 现代企业信任数以百计的第三方供应商——云提供商、SaaS 工具、支付处理商和开源库——却对这些关系引入的网络风险缺乏足够的可见性。单个被攻破的供应商就可能引发全面的组织违规事件。 **THREATWEAVE** 解决了这个问题。它是一个企业级、AI 增强的网络风险情报平台，能够： - **融合被动 OSINT 信号**——TLS 证书图谱、暴露的端口和 CVE、恶意软件信誉、泄露的凭证、暗网提及——形成统一的供应商风险画像 - **使用交互式图谱引擎映射 N 度供应链依赖关系**，揭示隐藏的爆炸半径 - **生成可供 CISO 使用的 AI 叙述报告**，将原始技术信号转化为适合董事会的语言 - **提供与您监控的供应商生态系统直接关联的实时威胁警报** - **使用 ARIMA、Prophet 和 LSTM 时间序列模型预测风险轨迹** **适用人群？** - 需要执行级风险可见性的首席信息安全官 (CISO) - 负责进行供应商风险评估和威胁调查的 SOC 团队 - 管理数百个供应商关系的第三方风险管理 (TPRM) 项目 - 构建内部威胁情报工具的安全工程师 **核心差异化优势：** | 功能 | THREATWEAVE | 传统 TPRM 工具 | |---|---|---| | 实时 OSINT 融合 | ✅ 持续监控 | ❌ 定期问卷调查 | | AI 叙述生成 | ✅ 自动化 | ❌ 人工分析师报告 | | 交互式供应链图谱 | ✅ N 度映射 | ❌ 仅限第一方 | | 风险预测 (ML) | ✅ ARIMA + Prophet + LSTM | ❌ 静态评分 | | 支持自托管 | ✅ Docker / K8s 就绪 | ❌ 供应商锁定的 SaaS | ## 核心功能 ### 🔍 OSINT 信号融合引擎 持续从以下来源聚合被动情报： - **crt.sh** — TLS 证书子域名枚举和颁发者图谱 - **Shodan InternetDB** — 暴露的端口、服务、banners 和 CVE 关联 - **VirusTotal** — 文件哈希信誉、恶意软件家族分类 - **AlienVault OTX** — 威胁指标源 (IP、域名、哈希) - **GreyNoise** — 互联网背景噪音过滤和大规模扫描归因 - **GitHub** — 公共存储库中的凭证泄露和密钥检测 - **AbuseIPDB** — IP 信誉评分和滥用报告 所有信号都会经过标准化、去重和加权，为每个供应商域生成综合的 **风险评分 (0–100)**。 ### 🕸️ 交互式供应链图谱 基于 `@xyflow/react` (React Flow) 构建，该图谱引擎能够： - 映射第一方、第二方和第三方供应商关系 (N 度) - 可视化**爆炸半径**——“如果该供应商被攻破，我会损失什么？” - 支持缩放、平移、展开/折叠以及供应商详细信息下钻 - 突出显示将供应商与已知威胁行为者联系起来的共享基础设施（TLS 颁发者、ASN 块、CDN 提供商） ### 🤖 AI 叙述生成 使用服务端 LLM 集成（兼容 OpenAI），THREATWEAVE 会自动生成： - 关于供应商风险发现的通俗英文执行摘要 - 每个供应商的按严重性排名的指标叙述 - 用于分析师交接的调查简报 - 可导出的报告部分（PDF/Markdown） ### 📊 风险预测（ML 后端） Python FastAPI 后端提供时间序列预测： - **ARIMA** — 用于短期趋势的经典统计预测 - **Facebook Prophet** — 用于中期风险预测的季节性分解 - **LSTM (TensorFlow)** — 用于处理复杂、非线性模式的深度学习 - 供应商风险历史记录存储在 Supabase 中，并通过 `/forecast/arima` endpoint 提供 ### 🚨 实时警报系统 - 与受监控的供应商事件绑定的实时警报 - 可配置的严重性阈值（危急、高、中、低） - 批量管理（分配、抑制、升级） - 通过 Webhook 发送至 Slack、Teams、PagerDuty ### 🔬 调查案例管理 完整的案例生命周期管理： - 基于时间线的证据收集 - MITRE ATT&CK 技术标签 - 保管链跟踪 - 附件工件和分析师任务分配 ### 🏢 企业级身份验证与多租户 - 使用 **Clerk** 进行企业级身份验证（SSO、SAML、WebAuthn、SCIM） - 基于组织的工作空间隔离 - 基于角色的访问控制（CISO、SOC 经理、分析师、查看者） - 保留 90 天的审计日志 ## 系统架构 ``` flowchart TD subgraph Client["Client Layer"] BROWSER["Browser / SSR"] LANDING["Landing Page\n/index.tsx"] DASH["Mission Control\n/dashboard"] VENDOR["Vendor Intel\n/vendors/:domain"] ALERTS["Alert Center\n/alerts"] INV["Investigations\n/investigations"] GRAPH["Supply Chain Graph\n@xyflow/react"] end subgraph Frontend["Frontend — TanStack Start + Nitro (Vercel)"] SSR["SSR / Hydration\nserver.ts + start.ts"] ROUTER["TanStack Router\nFile-based routing"] RQ["TanStack Query\nData fetching + cache"] CLERK_FE["Clerk\nAuth provider"] SUPA_CLIENT["Supabase Client\nRLS-enforced queries"] end subgraph Backend["Forecasting Backend — FastAPI (Render)"] FORECAST_API["Forecast API\n/forecast/arima"] ARIMA["ARIMA\nstatsmodels"] PROPHET["Prophet\nFacebook Prophet"] LSTM["LSTM\nTensorFlow / Keras"] FEAT_STORE["Feature Store\nfeature_store.py"] MODEL_REG["Model Registry\nmodel_registry.py"] end subgraph Database["Data Layer — Supabase"] PG["PostgreSQL\nRow-Level Security"] REALTIME["Realtime\nWebSocket subscriptions"] AUTH_SB["Supabase Auth\n(bridge to Clerk)"] STORAGE["Supabase Storage\nReport artifacts"] end subgraph OSINT["OSINT Connectors — Server Functions"] CRTSH["crt.sh\nCertificate graph"] SHODAN["Shodan InternetDB\nPorts + CVEs"] VT["VirusTotal\nMalware reputation"] GN["GreyNoise\nNoise filtering"] OTX["AlienVault OTX\nThreat indicators"] GITHUB_CON["GitHub\nLeak detection"] ABUSE["AbuseIPDB\nIP reputation"] end subgraph External["External Services"] OPENAI["OpenAI API\nNarrative generation"] CLERK_SVC["Clerk.com\nSSO + SCIM"] end BROWSER --> LANDING BROWSER --> DASH BROWSER --> VENDOR BROWSER --> ALERTS BROWSER --> INV Client --> Frontend CLERK_FE --> CLERK_SVC RQ --> SUPA_CLIENT SUPA_CLIENT --> PG PG --> REALTIME SSR -->|Server Functions| OSINT SSR -->|Server Functions| OPENAI SSR --> FORECAST_API FORECAST_API --> ARIMA FORECAST_API --> PROPHET FORECAST_API --> LSTM FEAT_STORE --> PG MODEL_REG --> PG ``` ## 技术栈 ### 前端 | 类别 | 技术 | 版本 | 用途 | |---|---|---|---| | 框架 | TanStack Start | 1.167 | 具有基于文件路由的全栈 React SSR | | 路由 | TanStack Router | 1.168 | 类型安全的基于文件路由，SSR 流式传输 | | 服务器 | Nitro | 3.0-beta | 通用服务器，Vercel 部署预设 | | 语言 | TypeScript | 5.8 | 跨所有层的类型安全开发 | | 样式 | Tailwind CSS | 4.2 | 实用优先，零配置暗黑模式 | | 认证 | Clerk | 1.4 | 企业 SSO、SAML、WebAuthn、SCIM | | 数据库客户端 | Supabase JS | 2.108 | 带有 RLS + Realtime 的 PostgreSQL | | 数据获取 | TanStack Query | 5.83 | 带有乐观更新的服务器状态管理 | | 图谱可视化 | @xyflow/react | 12.11 | 交互式供应链依赖图谱 | | 图表 | Recharts | 2.15 | 风险趋势图表和执行仪表板 | | UI 组件 | Radix UI | 最新 | 无障碍的无头 UI 基础组件 | | 图标 | Lucide React | 0.575 | 一致的图标系统 | | 通知 | Sonner | 2.0 | 通知系统 | | 命令面板 | cmdk | 1.1 | 全局搜索 (CTRL+K) | | 虚拟化 | TanStack Virtual | 3.14 | 高性能供应商列表渲染 | ### 后端（预测服务） | 类别 | 技术 | 版本 | 用途 | |---|---|---|---| | 框架 | FastAPI | 最新 | 高性能异步 REST API | | 服务器 | Uvicorn | 最新 | ASGI 服务器 | | 预测 | statsmodels | 最新 | ARIMA 时间序列模型 | | 预测 | Prophet | 最新 | 季节性分解预测 | | ML | TensorFlow / Keras | 最新 | LSTM 深度学习模型 | | 数据 | Pandas + NumPy | 最新 | 数据处理和特征工程 | | 数据库 | psycopg2-binary | 最新 | PostgreSQL 驱动程序 | | 配置 | python-dotenv | 最新 | 环境变量管理 | ### 基础设施 | 类别 | 技术 | 用途 | |---|---|---| | 数据库 | Supabase (PostgreSQL) | 带有 RLS、Realtime、Auth 的主数据存储 | | 前端托管 | Vercel | 通过 Nitro vercel 预设进行边缘优化的 SSR | | 后端托管 | Render | Python FastAPI 预测服务 | | 容器化 | Docker + Compose | 本地开发和自托管 | | CI/CD | GitHub Actions | 构建、测试、lint、类型检查流水线 | ## 仓库结构 ``` THREATWEAVE/ ├── frontend/ # TanStack Start SSR application │ ├── src/ │ │ ├── api/ # Server function API layer │ │ │ ├── activities.api.ts # Activity log server functions │ │ │ ├── forecast.api.ts # Forecasting backend proxy │ │ │ ├── intelligence.api.ts # Threat intelligence queries │ │ │ ├── investigations.api.ts # Case management CRUD │ │ │ ├── settings.api.ts # Org settings read/write │ │ │ └── vendor.api.ts # Vendor CRUD + scan triggers │ │ ├── components/ # Shared UI components │ │ │ └── ui/ # shadcn/ui primitives │ │ ├── integrations/ │ │ │ └── supabase/ │ │ │ ├── auth-middleware.ts # Clerk JWT verification middleware │ │ │ ├── mock-db.ts # E2E test mock database │ │ │ └── types.ts # Generated Supabase types │ │ ├── lib/ │ │ │ ├── connectors/ # OSINT data source connectors │ │ │ │ ├── base.connector.ts # Abstract base with rate limiting │ │ │ │ ├── crtsh.connector.ts # crt.sh certificate graph │ │ │ │ ├── github.connector.ts# GitHub leak detection │ │ │ │ ├── shodan.connector.ts# Shodan port/CVE enrichment │ │ │ │ ├── threatfeeds.connector.ts # OTX, AbuseIPDB, GreyNoise │ │ │ │ └── virustotal.connector.ts # VirusTotal reputation │ │ │ ├── intelligence/ # Threat intelligence processing │ │ │ ├── analytics/ # Risk scoring analytics │ │ │ ├── scan.functions.ts # Orchestrated OSINT scan pipeline │ │ │ ├── threats.functions.ts # Threat signature generation │ │ │ ├── narrative.functions.ts # AI narrative generation │ │ │ ├── vendor-intelligence.functions.ts # Vendor enrichment │ │ │ ├── supplyChainDepth.functions.ts # Nth-party graph builder │ │ │ ├── osint-types.ts # Shared TypeScript types │ │ │ ├── rate-limit.ts # Exponential backoff + circuit breaker │ │ │ └── health.functions.ts # Connector health checks │ │ ├── routes/ │ │ │ ├── __root.tsx # Root layout + Clerk + QueryClient │ │ │ ├── index.tsx # Enterprise landing page │ │ │ ├── login.tsx # Clerk SignIn │ │ │ ├── sign-up.tsx # Clerk SignUp → Onboarding │ │ │ ├── auth.callback.tsx # Clerk OAuth callback handler │ │ │ └── _authenticated/ # Protected routes (Clerk guard) │ │ │ ├── route.tsx # Authenticated layout wrapper │ │ │ ├── onboarding.tsx # Workspace setup wizard │ │ │ ├── dashboard.tsx # Executive Mission Control │ │ │ ├── vendors.$domain.tsx# Vendor deep-dive intelligence │ │ │ ├── alerts.tsx # Live alert management │ │ │ ├── investigations.tsx # Case management │ │ │ ├── intelligence.tsx # Global threat intelligence │ │ │ ├── supply-chain.tsx # Interactive dependency graph │ │ │ ├── threats.tsx # Threat feed browser │ │ │ └── settings.tsx # Enterprise control center │ │ ├── server/ # Nitro server handlers │ │ ├── routeTree.gen.ts # Auto-generated route manifest │ │ ├── router.tsx # Router configuration │ │ └── server.ts # SSR entry + error wrapper │ ├── tests/ │ │ └── e2e/ # Playwright E2E test suite │ │ ├── verification.spec.ts # Platform verification tests │ │ ├── vendor-lifecycle.spec.ts# Vendor CRUD lifecycle │ │ └── workflow.spec.ts # Full user workflow tests │ ├── Dockerfile # Frontend container definition │ ├── vite.config.ts # Vite + TanStack Start + Nitro config │ ├── playwright.config.ts # E2E test configuration │ └── package.json │ ├── backend/ # Python FastAPI forecasting service │ ├── app/ │ │ ├── api/v1/ │ │ │ ├── vendors.py # Vendor data endpoints │ │ │ ├── alerts.py # Alert endpoints │ │ │ ├── threats.py # Threat intel endpoints │ │ │ ├── investigations.py # Case management endpoints │ │ │ ├── analytics.py # Analytics aggregations │ │ │ └── settings.py # Settings CRUD │ │ ├── core/ # Core config + dependencies │ │ ├── main.py # FastAPI app + route registration │ │ ├── feature_store.py # ML feature engineering pipeline │ │ └── model_registry.py # ARIMA/Prophet/LSTM model management │ ├── Dockerfile # Backend container definition │ └── requirements.txt │ ├── docs/ # Extended documentation ├── scripts/ # Utility and automation scripts ├── .github/ │ ├── workflows/ # GitHub Actions CI/CD │ └── ISSUE_TEMPLATE/ # Standardized issue templates ├── docker-compose.yml # Full-stack local development ├── render.yaml # Render.com deployment manifest ├── vercel.json # Vercel deployment configuration └── README.md ``` ## 快速开始 ### 前置条件 | 要求 | 版本 | 备注 | |---|---|---| | Node.js | ≥ 22.x | 推荐 LTS | | npm | ≥ 10.x | 随 Node 提供 | | Python | ≥ 3.11 | 用于预测后端 | | Docker Desktop | 最新 | 用于容器化设置 | ### 1. 克隆仓库 ``` git clone https://github.com/ESSAKKI-RAJA/THREATWEAVE.git cd THREATWEAVE ``` ### 2. 前端设置 ``` cd frontend npm install cp .env.example .env ``` 使用您的凭证编辑 `.env`（参见[环境变量](#environment-variables)）。 ### 3. 后端设置 ``` cd backend python -m venv .venv # Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate pip install -r requirements.txt cp .env.example .env ``` ### 4. 在开发模式下运行 **终端 1 — 前端：** ``` cd frontend npm run dev # → http://localhost:8080 ``` **终端 2 — 预测后端：** ``` cd backend uvicorn app.main:app --reload --port 8000 # → http://localhost:8000 # → Swagger UI: http://localhost:8000/docs ``` ### 5. Docker Compose（全栈） ``` # 从 repo 根目录 cp .env.example .env # Fill in secrets docker compose up --build # → Frontend: http://localhost:3000 # → Backend: http://localhost:8000 ``` ### 6. 运行测试 ``` # Frontend 单元测试 cd frontend && npm test # Frontend E2E 测试（需要运行服务器） npm run test:e2e # TypeScript 类型检查 npx tsc --noEmit # Lint npm run lint ``` ## 安装

Windows (PowerShell)

``` # 通过 winget 安装 Node.js winget install OpenJS.NodeJS.LTS # 安装 Python winget install Python.Python.3.11 # Clone 并设置 git clone https://github.com/ESSAKKI-RAJA/THREATWEAVE.git cd THREATWEAVE\frontend npm install cd ..\backend python -m venv .venv .venv\Scripts\Activate.ps1 pip install -r requirements.txt ```

macOS (Homebrew)

``` brew install node python@3.11 git clone https://github.com/ESSAKKI-RAJA/THREATWEAVE.git cd THREATWEAVE/frontend && npm install cd ../backend && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt ```

Linux (Ubuntu/Debian)

``` curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs python3.11 python3.11-venv git clone https://github.com/ESSAKKI-RAJA/THREATWEAVE.git cd THREATWEAVE/frontend && npm install cd ../backend && python3.11 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt ```

Docker

``` # 单个服务 docker build -t threatweave-frontend ./frontend docker run -p 3000:3000 --env-file .env threatweave-frontend docker build -t threatweave-backend ./backend docker run -p 8000:8000 --env-file .env threatweave-backend # 全栈（推荐） docker compose up --build ```

## 环境变量 ### 前端 (`frontend/.env`) | 变量 | 描述 | 必需 | 示例 | |---|---|---|---| | `VITE_CLERK_PUBLISHABLE_KEY` | 用于客户端身份验证的 Clerk 公钥 | ✅ | `pk_live_...` | | `CLERK_SECRET_KEY` | 用于服务端 JWT 验证的 Clerk 密钥 | ✅ | `sk_live_...` | | `VITE_SUPABASE_URL` | Supabase 项目 URL | ✅ | `https://xxxx.supabase.co` | | `VITE_SUPABASE_PUBLISHABLE_KEY` | Supabase anon 密钥（客户端安全） | ✅ | `eyJ...` | | `SUPABASE_URL` | 用于服务器函数的 Supabase URL | ✅ | `https://xxxx.supabase.co` | | `SUPABASE_SERVICE_ROLE_KEY` | Supabase 服务角色密钥（仅限服务器，机密） | ✅ | `eyJ...` | | `VITE_AUTH_MODE` | 身份验证模式：`enterprise` 或 `public` | ✅ | `enterprise` | | `VITE_BYPASS_AUTH` | 仅在本地 E2E 测试中跳过身份验证 | ❌ | `false` | | `FORECAST_SERVICE_URL` | 指向 Python 预测后端的 URL | ✅ | `https://api.render.com` | | `SHODAN_API_KEY` | 用于端口/CVE 充实的 Shodan API 密钥 | ❌ | `abc123...` | | `VIRUSTOTAL_API_KEY` | 用于恶意软件信誉的 VirusTotal API 密钥 | ❌ | `abc123...` | | `ABUSEIPDB_API_KEY` | 用于 IP 信誉的 AbuseIPDB API 密钥 | ❌ | `abc123...` | | `GREYNOISE_API_KEY` | 用于噪音过滤的 GreyNoise API 密钥 | ❌ | `abc123...` | | `GITHUB_TOKEN` | 用于凭证泄露检测的 GitHub PAT | ❌ | `ghp_...` | | `OTX_API_KEY` | AlienVault OTX API 密钥 | ❌ | `abc123...` | | `OPENAI_API_KEY | 用于叙述生成的 OpenAI API 密钥 | ❌ | `sk-...` | | `NODE_ENV` | 运行时环境 | ✅ | `production` | ### 后端 (`backend/.env`) | 变量 | 描述 | 必需 | |---|---|---| | `DATABASE_URL` | PostgreSQL 连接字符串 | ✅ | | `SUPABASE_SERVICE_ROLE_KEY` | 用于数据库访问的 Supabase 服务角色 | ✅ | ## 可用脚本 ### 前端 | 命令 | 描述 | |---|---| | `npm run dev` | 在端口 8080 启动带有 HMR 的 Vite 开发服务器 | | `npm run build` | 使用 Nitro vercel 预设进行生产环境构建 → `.vercel/output/` | | `npm run build:dev` | 开发构建（未压缩，对调试 SSR 有用） | | `npm run preview` | 在本地预览生产环境构建 | | `npm run lint` | 对所有 TypeScript/TSX 文件运行 ESLint | | `npm run format` | 使用 Prettier 自动格式化 | | `npm test` | 运行 Vitest 单元测试 | | `npm run test:unit` | 运行 Vitest 单元测试（显式） | | `npm run test:e2e` | 运行 Playwright E2E 测试套件 | ### 后端 | 命令 | 描述 | |---|---| | `uvicorn app.main:app --reload` | 启动带有热重载的 FastAPI 开发服务器 | | `uvicorn app.main:app --host 0.0.0.0 --port 8000` | 生产服务器 | | `pytest` | 运行所有 Python 测试 | ## API 文档 预测后端在 `http://localhost:8000` 暴露了一个 RESTful API。交互式文档可在 `/docs` (Swagger UI) 和 `/redoc` (ReDoc) 查阅。 ### 身份验证 所有后端 endpoint 都需要 `SUPABASE_SERVICE_ROLE_KEY` bearer token 才能进行服务器到服务器的调用： ``` Authorization: Bearer ``` ### 核心 Endpoints #### `POST /forecast/arima` 为供应商生成 ARIMA 风险评分预测。 **请求：** ``` { "vendor_id": "uuid-of-vendor", "periods": 30 } ``` **响应：** ``` { "vendor_id": "uuid-of-vendor", "forecast": [ { "period": 1, "predicted_risk": 72.4, "confidence_lower": 65.1, "confidence_upper": 79.7 }, { "period": 2, "predicted_risk": 73.8, "confidence_lower": 65.9, "confidence_upper": 81.7 } ], "model": "ARIMA(2,1,2)", "aic": 284.3, "generated_at": "2026-01-15T10:30:00Z" } ``` #### `GET /api/v1/vendors` 列出所有受监控的供应商及其当前风险评分。 #### `GET /api/v1/alerts` 检索活动的威胁警报。 #### `GET /api/v1/threats` 浏览威胁情报源。 #### `GET /api/v1/investigations` 列出活动和已关闭的调查案例。 #### `GET /api/v1/analytics` 聚合风险指标和趋势数据。 #### `GET /api/v1/settings` 检索组织集成设置。 #### `PUT /api/v1/settings` 更新组织集成 API 密钥和配置。 #### `GET /health` 健康检查 endpoint。返回 `{ "status": "healthy" }`。 ### 错误代码 | 代码 | 含义 | |---|---| | `400` | 错误请求 — 参数无效 | | `401` | 未授权 — 缺少或无效的身份验证 token | | `403` | 禁止访问 — 权限不足 | | `404` | 资源未找到 | | `422` | 验证错误 — 请求体 schema 不匹配 | | `429` | 超出速率限制 | | `500` | 内部服务器错误 | ## 安全 ### 身份验证架构 - **Clerk** 负责处理所有面向用户的身份验证（登录、注册、SSO、MFA、WebAuthn） - 身份验证成功后，Clerk 会颁发一个 **JWT**，通过 `@clerk/backend` 的 `verifyToken()` 在每个 TanStack Start 服务器函数中进行服务端验证 - [`auth-middleware.ts`](frontend/src/integrations/supabase/auth-middleware.ts) 中的 `requireSupabaseAuth` middleware 在每个受保护的服务器函数上强制执行此操作 - `BYPASS_AUTH` 在 `NODE_ENV=production` 中被**硬性阻断**——它专属于测试基础设施标志 ### 授权 - **Supabase 行级安全性 (RLS)** 在数据库级别实施数据隔离——用户只能访问属于其组织的数据 - 基于角色的访问通过 Clerk 组织角色（CISO、SOC 经理、分析师、查看者）强制执行 ### 密钥管理 - 所有密钥均为环境变量——绝不硬编码 - 服务端密钥（`SUPABASE_SERVICE_ROLE_KEY`、`CLERK_SECRET_KEY`）仅在 Nitro 服务器函数中访问，绝不打包到客户端 JavaScript 中 - 带有 `VITE_*` 前缀的变量对客户端是安全的（仅限 anon 密钥） ### OWASP Top 10 缓解措施 | 风险 | 缓解措施 | |---|---| | 注入 | 通过 Supabase JS 客户端进行参数化查询；无原生 SQL | | 失效的身份验证 | 带有 JWT RS256、短生命周期 token、刷新轮换的 Clerk | | XSS | React 的 JSX 转义；通过 Nitro 提供 CSP headers | | CSRF | SameSite cookies；Clerk 会话 token | | 不安全的直接对象引用 | Supabase RLS；所有查询范围限定为经过验证的用户组织 | | 安全配置错误 | `BYPASS_AUTH` 在生产环境中被阻止 | | 速率限制 | OSINT 连接器中的指数退避；`rate-limit.ts` | ### 漏洞报告 有关我们的负责任披露政策，请参见 [SECURITY.md](SECURITY.md)。 ## 性能 - **流式 SSR** — TanStack Start + Nitro 从服务器流式传输 HTML，在 Vercel Edge 上不到 1 秒内实现首次内容绘制 (FCP) - **TanStack Query** — 根据查询类型配置 `staleTime` 进行智能缓存；消除冗余的 OSINT API 调用 - **TanStack Virtual** — `useVirtualizer` 仅渲染供应商表中的可见行，以 60fps 的速度支持数千个供应商 - **代码分割** — 每个路由都是一个单独的 Nitro bundle chunk；用户只下载他们需要的内容 - **延迟 OSINT 扫描** — 扫描通过服务器函数按需触发，不会阻塞页面加载 - **速率限制** — `rate-limit.ts` 实现了令牌桶 + 带有抖动的指数退避，以避免对 OSINT API 造成惊群效应 - **断路器** — `CircuitBreakerOpenError` 防止在 OSINT 提供商降级时发生级联故障 ## 测试 ### 单元测试 ``` cd frontend && npm run test:unit ``` 位于 `frontend/src/lib/__tests__/`。涵盖： - `scan.functions.ts` — OSINT 扫描编排逻辑 - OSINT 连接器响应标准化 - 风险评分计算工具 ### 端到端测试 ``` cd frontend && npm run test:e2e ``` 位于 `frontend/tests/e2e/`。套件包括： - `verification.spec.ts` — 平台范围的冒烟测试 - `vendor-lifecycle.spec.ts` — 添加 → 扫描 → 查看 → 删除供应商流程 - `workflow.spec.ts` — 完整的分析师工作流（扫描 → 警报 → 调查） **测试基础设施：** - `VITE_BYPASS_AUTH=true` + 模拟的 Supabase 客户端允许 E2E 测试在无活动 Clerk 凭证的情况下运行 - `BYPASS_AUTH` 专属于非生产环境变量，在 `NODE_ENV=production` 中被阻止 ### 类型检查 ``` cd frontend && npx tsc --noEmit ``` ### Linting ``` cd frontend && npm run lint ``` ## CI/CD ``` # .github/workflows/ci.yml（推荐） name: CI on: push: branches: [main, develop] pull_request: branches: [main] jobs: frontend: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: { node-version: '22', cache: 'npm', cache-dependency-path: frontend/package-lock.json } - run: npm ci working-directory: frontend - run: npm run lint working-directory: frontend - run: npx tsc --noEmit working-directory: frontend - run: npm test working-directory: frontend - run: npm run build working-directory: frontend backend: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: { python-version: '3.11' } - run: pip install -r requirements.txt working-directory: backend - run: pytest working-directory: backend ``` **质量门禁** — 对 `main` 的 PR 必须通过： 1. TypeScript 编译 (`tsc --noEmit`) 2. ESLint 零错误 3. 所有 Vitest 单元测试 4. 生产构建 (`npm run build`) ## 部署 ### Vercel（前端 — 推荐） 1. 将您的 GitHub 存储库连接到 Vercel 2. 将 **Root Directory** 设置为 `frontend` **或者** 依赖位于仓库根目录的 `vercel.json` 3. 在 Vercel Dashboard → Settings → Environment Variables 中设置所有必需的[环境变量](#environment-variables) 4. Vercel 会自动检测 Nitro `vercel` 预设并使用 `.vercel/output/` **`vercel.json`（仓库根目录）：** ``` { "framework": null, "buildCommand": "npm install --prefix frontend && npm run build --prefix frontend", "outputDirectory": "frontend/.vercel/output", "installCommand": "echo 'skip root install'" } ``` ### Render（后端 — 推荐） 定义在 [`render.yaml`](render.yaml) 中： ``` services: - type: web name: threatweave-backend env: python buildCommand: cd backend && pip install -r requirements.txt startCommand: cd backend && uvicorn app.main:app --host 0.0.0.0 --port $PORT ``` 在 Render dashboard 中设置 `DATABASE_URL` 和 `SUPABASE_SERVICE_ROLE_KEY`。 ### Docker Compose（自托管） ``` cp .env.example .env # 填写所有必需的 secrets docker compose up --build -d ``` ### Railway ``` railway login railway link railway up --detach # 通过 railway.app dashboard 设置环境变量 ``` ## 监控 - **Vercel Analytics** — 在 Vercel 仪表板中内置的 Web Vitals 监控 - **Supabase Logs** — 在 Supabase 仪表板中可见的数据库查询日志和 RLS 策略违规 - **FastAPI `/health`** — 用于正常运行时间监控（UptimeRobot、Better Uptime）的轻量级健康检查 endpoint - **错误捕获** — `error-capture.ts` 和 `lovable-error-reporting.ts` 捕获并报告客户端错误 - **审计日志** — 所有管理操作都会在 Settings 控制台中记录时间戳、用户 ID 和操作详细信息 ## 贡献 请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 获取完整的贡献指南。 **快速摘要：** ``` # 1. Fork 并 clone git clone https://github.com//THREATWEAVE.git # 2. 创建 feature branch git checkout -b feat/my-new-feature # 3. 进行更改，运行测试 npm run lint && npx tsc --noEmit && npm test # 4. 使用 conventional commits 进行 commit git commit -m "feat(dashboard): add MITRE heatmap widget" # 5. Push 并创建 Pull Request git push origin feat/my-new-feature ``` ## 路线图 ### v2.0 — 当前版本 ✅ - [x] 企业登陆页面和工作空间引导 - [x] 带有爆炸半径可视化的交互式供应链图谱 - [x] OSINT 信号融合（6 个数据源） - [x] AI 叙述生成 - [x] 风险预测后端（ARIMA、Prophet、LSTM） - [x] 使用 `vercel.json` 进行 Vercel + Render 部署 - [x] Clerk 企业级身份验证（SSO、MFA、SCIM） ### v2.1 — 进行中 🚧 - [ ] 带有供应商搜索的全局命令面板 (CTRL+K) - [ ] 带有严重性分组的通知中心 - [ ] 仪表板上的 MITRE ATT&CK 框架热图 - [ ] 调查案例管理重新设计 - [ ] 批量警报抑制和升级 ### v2.2 — 下一步 📋 - [ ] 到 Slack、Teams、PagerDuty 的 Webhooks - [ ] PDF/DOCX 执行报告导出 - [ ] STIX/TAXII 威胁情报源摄取 - [ ] NVD CVE 充实集成 - [ ] 供应商 API 密钥轮换建议 ### v3.0 — 未来 🔮 - [ ] 具有基于使用量计费的多租户 SaaS 层级 - [ ] 用于自托管企业的 Kubernetes Helm chart - [ ] 实时协作调查 - [ ] 移动伴侣应用（React Native） - [ ] SOC SIEM 连接器（QRadar、Splunk、Elastic SIEM） ## 常见问题解答 **问：THREATWEAVE 需要付费的 API 密钥才能运行吗？** 答：不需要。所有 OSINT 连接器都是可选的。在没有 API 密钥的情况下，THREATWEAVE 使用被动的公共数据源（crt.sh、公共 VirusTotal 查询）并返回优雅的后备方案。该平台在没有付费密钥的情况下处于降级但可用的状态运行。 **问：供应商数据是否在组织之间进行了隔离？** 答：是的。Supabase 行级安全性 (RLS) 策略在数据库级别实施严格的数据隔离。每个组织只能查询其自己的供应商和警报数据。 **问：我可以自托管 THREATWEAVE 吗？** 答：可以。使用 `docker compose up --build` 获取完整的本地技术栈。该应用程序与基础设施无关——它可以在任何支持 Node.js 22 和 Python 3.11 的平台上运行。 **问：如果 OSINT 数据源不可用会怎样？** 答：每个连接器都有独立的错误处理。断路器（`CircuitBreakerOpenError`）防止单个不可用的源阻塞整个扫描。可用的源仍会返回其数据。 **问：风险预测的准确性如何？** 答：预测准确性取决于历史扫描数据的数量。每个供应商拥有 ≥ 30 个数据点时，ARIMA 可实现约 78% 的方向准确性。对于具有明显季节性模式的供应商（例如季度安全评估），建议使用 Prophet。 ## 故障排除 **Vercel 部署出现 404 错误** 确保 `vercel.json` 存在于仓库目录并指定了 `"outputDirectory": "frontend/.vercel/output"`。如果 Vercel 配置了 Root Directory = `frontend`，请移除 `vercel.json` 并依赖 Nitro 自动检测。 **`Missing VITE_CLERK_PUBLISHABLE_KEY` 错误** 如果未设置 Clerk 公钥，则此错误会出现在 `__root.tsx` 中。将 `VITE_CLERK_PUBLISHABLE_KEY=pk_live_...` 添加到您的 Vercel 环境变量或本地 `.env` 中。 **OSINT 扫描返回空结果** 检查您的 API 密钥是否在 Settings → Connectors & API 中正确设置。使用 `/health` 处的连接器健康 endpoint 验证 API 密钥的有效性。 **`routeTree.gen.ts` 中的 TypeScript 错误** 该文件是自动生成的。在添加新的路由文件后，运行 `npx tsr generate` (TanStack Router CLI) 重新生成它。 **预测后端返回 500** 确保后端 `.env` 中的 `DATABASE_URL` 指向活动的 PostgreSQL 实例。ARIMA 模型要求每个供应商至少有 10 个历史风险评分数据点。 ## 致谢 - [TanStack](https://tanstack.com) — Router、Query、Virtual、Start - [Vercel](https://vercel.com) — 托管和边缘基础设施 - [Supabase](https://supabase.com) — 开源 Firebase 替代方案 - [Clerk](https://clerk.com) — 企业级身份验证 - [React Flow / xyflow](https://reactflow.dev) — 图谱可视化 - [Radix UI](https://radix-ui.com) — 无障碍 UI 基础组件 - [FastAPI](https://fastapi.tiangolo.com) — Python API 框架 - [Prophet](https://facebook.github.io/prophet/) — 时间序列预测 ## 作者 **Essakki Raja T** — 首席工程师与架构师 [](https://github.com/ESSAKKI-RAJA) ## 许可证 该项目基于 **MIT License** 授权 — 详见 [LICENSE](LICENSE)。 ## 引用 ``` @software{threatweave2026, author = {Essakki Raja T}, title = {THREATWEAVE: Enterprise Supply Chain Cyber Risk Intelligence Platform}, year = {2026}, url = {https://github.com/ESSAKKI-RAJA/THREATWEAVE}, version = {2.0.0} } ```

**带有目的地构建。精准部署。** [报告 Bug](https://github.com/ESSAKKI-RAJA/THREATWEAVE/issues/new?template=bug_report.yml) · [请求功能](https://github.com/ESSAKKI-RAJA/THREATWEAVE/issues/new?template=feature_request.yml) · [阅读文档](docs/) · [安全政策](SECURITY.md) *© 2026 THREATWEAVE。MIT Licensed。*

标签：GitHub, 企业安全, 威胁情报, 实时处理, 密码管理, 开发者工具, 测试用例, 漏洞分析, 网络安全, 网络资产管理, 自定义脚本, 请求拦截, 路径探测, 逆向工具, 隐私保护