PhoenixKnight-in/Vantablack

# Vantablack — 威胁情报平台 ## 目录 - [概述](#overview) - [架构](#architecture) - [功能](#features) - [技术栈](#tech-stack) - [快速开始](#getting-started) - [前置条件](#prerequisites) - [环境变量](#environment-variables) - [Docker Compose（推荐）](#docker-compose-recommended) - [本地开发](#local-development) - [API 参考](#api-reference) - [Webhook 集成](#webhook-integration) - [数据流](#data-flow) - [测试](#testing) - [CI/CD 流水线](#cicd-pipeline) - [项目结构](#project-structure) ## 概述 Vantablack 是一个全栈安全运营中心（SOC）平台，可持续从多个开源威胁情报源摄取**失陷标示（IOC）**，通过第三方 API 进行富化，计算综合风险评分，并通过实时仪表盘向分析师展示可操作的告警。 该平台专为可靠性而构建：每个 IOC 都会经过确定性的评分流水线，每次告警状态变更都会被审计日志记录，并且每个出站通知都通过高可用的 webhook worker 传递。 ## 架构 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Vantablack Platform │ │ │ │ ┌──────────────┐ ┌──────────────────────────────────────────┐ │ │ │ Frontend │ │ Backend (FastAPI) │ │ │ │ React + TS │◄──►│ │ │ │ │ Vite + TQ │ │ ┌──────────┐ ┌────────────────────┐ │ │ │ └──────────────┘ │ │ REST │ │ APScheduler │ │ │ │ │ │ API │ │ (feed ingestion) │ │ │ │ ┌──────────────┐ │ │ /api/v1 │ └────────┬───────────┘ │ │ │ │ Nginx / │ │ └────┬─────┘ │ │ │ │ │ Docker │◄──►│ │ │ │ │ │ └──────────────┘ │ ┌────▼─────────────────▼───────────┐ │ │ │ │ │ SQLAlchemy ORM (async) │ │ │ │ External Feeds: │ └────────────────┬─────────────────┘ │ │ │ ┌─────────────┐ │ │ │ │ │ │ AlienVault │──► │ ┌────────────────▼─────────────────┐ │ │ │ │ URLhaus │──► │ │ PostgreSQL 16 │ │ │ │ │ MalwareBazaar──► │ └──────────────────────────────────┘ │ │ │ │ CISA KEV │──► │ │ │ │ └─────────────┘ │ ┌──────────────────────────────────┐ │ │ │ │ │ Redis (webhook job queue) │ │ │ │ Enrichment APIs: │ └──────────────────────────────────┘ │ │ │ ┌─────────────┐ │ │ │ │ │ VirusTotal │◄──► │ ┌──────────────────────────────────┐ │ │ │ │ AbuseIPDB │◄──► │ │ Webhook Worker (asyncio loop) │ │ │ │ │ Shodan │◄──► │ └──────────────────────────────────┘ │ │ │ └─────────────┘ └──────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` ## 功能 ### 🔍 IOC 管理 - **多源摄取** — 按可配置的定时任务从 AlienVault OTX、URLhaus、MalwareBazaar 和 CISA KEV 拉取 IOC - **自动去重** — 基于 `(value, ioc_type)` 复合键执行 upsert；现有记录会累加出现次数 - **手动创建 IOC** — 分析师可通过 UI 或 API 提交自定义标示 - **全文搜索** — 按值、类型、标签或严重程度搜索 IOC - **STIX 2.1 导出** — 将任何 IOC 下载为符合标准的 STIX 2.1 包 ### 📊 风险评分引擎 综合评分（0–100）由以下信号计算得出： | 信号 | 权重 | |---|---| | 情报源命中频率 | 30% | | VirusTotal 检出率 | 25% | | 时间衰减 | 15% | | Shodan 开放端口 | 10% | | 恶意软件家族标签 | 10% | | CISA KEV 收录 | 10% | ### 🚨 告警与分发 - 当评分超过阈值时，在摄取 IOC 时自动生成告警 - 分析师可以**确认**（可附带备注）、**升级**或**分配**告警 - 支持按严重程度、确认状态和日期范围进行全面过滤 - 提供基于游标分页的 API 导航 ### 🔔 Webhooks - **管理后台 UI** — 用于管理 webhook 的现代仪表盘，具有事件选择器实时创建、密钥可见性切换、活动 endpoint 列表和传递协议卡片等功能 - **实时事件推送** — 注册 HTTPS endpoint 以接收即时事件通知 - 支持的事件：`alert.created`、`alert.acknowledged`、`alert.escalated` - 通过 `X-Vantablack-Signature` 标头进行 **HMAC-SHA256 请求签名**，用于 payload 验证 - 带有重试逻辑的**后台异步 worker**（3 次指数退避） ### 📡 威胁情报源健康度 - 每个情报源的实时状态仪表盘 - 跟踪上次轮询时间、错误数和 IOC 摄取数 ### 🛡️ 安全 - JWT 认证（access + refresh token 对） - 基于角色的访问控制：`ADMIN` / `ANALYST` / `READONLY` - 密码策略强制执行（最少 8 个字符，包含大写字母、数字、特殊字符） - 记录每个分析师操作的完整审计日志 - BGP 封禁缓解 — 通过 API 部署防火墙规则 ## 技术栈 | 层级 | 技术 | |---|---| | **后端框架** | FastAPI 0.111 | | **数据库** | PostgreSQL 16 + SQLAlchemy 2.0 (async) | | **数据库迁移** | Alembic | | **缓存 / 队列** | Redis 7 | | **调度器** | APScheduler 3.10 | | **认证** | python-jose (JWT) + passlib (bcrypt) | | **HTTP 客户端** | httpx (async) | | **监控指标** | Prometheus + prometheus-fastapi-instrumentator | | **前端框架** | React 18 + Vite 5 | | **前端状态** | TanStack Query (React Query) v5 | | **前端语言** | TypeScript | | **前端样式** | Tailwind CSS | | **容器** | Docker + Docker Compose | | **CI/CD** | GitHub Actions | | **测试** | pytest + pytest-asyncio + httpx | ## 部署 本平台已配置部署，目前运行在 **Render** 上。 ### 已部署的服务 | 服务 | URL | |---|---| | **前端仪表盘** | [https://vantablack-frontend.onrender.com](https://vantablack-frontend.onrender.com) | | **后端 API** | [https://vantablack-backend.onrender.com](https://vantablack-backend.onrender.com) | | **API 文档**（仅限非生产环境） | [https://vantablack-backend.onrender.com/docs](https://vantablack-backend.onrender.com/docs) | | **Prometheus 指标** | [https://vantablack-backend.onrender.com/metrics](https://vantablack-backend.onrender.com/metrics) | ### 基础设施与编排 项目仓库包含一个用于自动化部署的 `render.yaml` 文件： - **FastAPI Web 服务**（在 `/backend` 中配置了 Docker 上下文） - **React 静态站点**（从 `/frontend/vantablack` 构建至 `/dist`） - **Redis 实例**（用作 webhook 队列的键值存储） - **PostgreSQL 数据库**（Render 上的托管集群） ## API 参考 所有 endpoint 的前缀均为 `/api/v1`。交互式文档位于 `/docs`（仅限非生产环境）。 ### 认证 | 方法 | 路径 | 描述 | |---|---|---| | `POST` | `/auth/register` | 注册新的分析师账户 | | `POST` | `/auth/login` | 获取 access + refresh token 对 | | `POST` | `/auth/refresh` | 使用 refresh token 轮换 token | | `GET` | `/auth/me` | 获取当前已认证的用户 | ### IOCs | 方法 | 路径 | 描述 | |---|---|---| | `GET` | `/iocs/` | 列出 IOC，支持过滤和分页 | | `POST` | `/iocs/` | 创建手动 IOC | | `GET` | `/iocs/{id}` | 获取包含富化信息和告警的完整 IOC 详情 | | `POST` | `/iocs/search` | 跨 IOC 值的全文搜索 | | `GET` | `/iocs/{id}/stix` | 将 IOC 导出为 STIX 2.1 包 | #### 查询参数 — `GET /iocs/` | 参数 | 类型 | 描述 | |---|---|---| | `severity` | `CRITICAL\|HIGH\|MEDIUM\|LOW\|INFO` | 按严重程度过滤 | | `ioc_type` | `ip\|domain\|hash\|url\|email\|cve` | 按标示类型过滤 | | `is_active` | `bool` | 按活跃状态过滤 | | `order` | `asc\|desc` | 排序方向（按分数） | | `page` | `int` | 页码（从 1 开始） | | `page_size` | `int` | 每页结果数（最多 100） | ### 告警 | 方法 | 路径 | 描述 | |---|---|---| | `GET` | `/alerts/` | 列出告警，支持过滤和分页 | | `POST` | `/alerts/{id}/acknowledge` | 确认告警（可选备注） | | `POST` | `/alerts/{id}/escalate` | 升级告警 | | `PATCH` | `/alerts/{id}/assign` | 将告警分配给当前用户 | ### Webhooks | 方法 | 路径 | 描述 | |---|---|---| | `GET` | `/webhooks/` | 列出所有已注册的 webhook 订阅 | | `POST` | `/webhooks/` | 注册新的 webhook endpoint | | `DELETE` | `/webhooks/{id}` | 删除 webhook 订阅 | #### 创建 Webhook — 请求体 ``` { "url": "https://your-server.io/hooks/vantablack", "secret_token": "optional-hmac-secret", "events": ["alert.created", "alert.acknowledged", "alert.escalated"] } ``` ### 情报源 | 方法 | 路径 | 描述 | |---|---|---| | `GET` | `/feeds/` | 列出所有已配置的情报源及其健康状态 | | `POST` | `/feeds/{name}/trigger` | 手动触发情报源摄取运行 | ### 管理（仅限 ADMIN 角色） | 方法 | 路径 | 描述 | |---|---|---| | `GET` | `/admin/users` | 列出所有已注册的用户 | | `GET` | `/admin/audit-logs` | 获取系统审计记录 | ### 其他 | 方法 | 路径 | 描述 | |---|---|---| | `GET` | `/health` | 健康检查 endpoint | | `GET` | `/metrics` | Prometheus 指标 endpoint | | `POST` | `/mitigation/bgp-block` | 为标示部署 BGP 封禁规则 | | `GET` | `/enrichment/{id}` | 获取 IOC 的富化数据 | ## Webhook 集成 当订阅的事件发生时，Vantablack 会向您注册的 endpoint 发送 HTTP POST 请求。 ### 事件 Payload 格式 ``` { "event" : "alert.created", "timestamp": "2026-06-23T18:00:00Z", "data" : { "alert_id" : "uuid-here", "ioc_value" : "185.112.156.72", "severity" : "CRITICAL", "message" : "High-confidence C2 indicator detected" } } ``` ### 验证签名 当配置了 `secret_token` 时，每个请求都会包含： ``` X-Vantablack-Signature: sha256= ``` 在 Python 中进行验证： ``` import hashlib, hmac def verify_signature(body: bytes, secret: str, signature_header: str) -> bool: expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature_header) ``` ### 重试策略 传递失败（非 2xx 响应或超时 > 10秒）最多将重试 **3 次**，并采用指数退避： | 尝试 | 延迟 | |---|---| | 第 1 次重试 | 30 秒 | | 第 2 次重试 | 5 分钟 | | 第 3 次重试 | 30 分钟 | ## 数据流 ``` External Feed │ ▼ Ingestion Connector (OTX / URLhaus / MalwareBazaar / CISA KEV) │ ▼ IOC Upsert (deduplicated by value + type) │ ├──► Enrichment Service (VirusTotal, AbuseIPDB, Shodan) │ │ │ ▼ │ Enrichment records stored │ ├──► Scoring Service (weighted composite 0–100) │ └──► Alert Generation (if score ≥ threshold) │ ├──► Analyst Dashboard (real-time via polling) │ └──► Webhook Worker → registered endpoints ``` ## 测试 测试套件涵盖了认证、IOC CRUD、告警生命周期和 webhook 管理。 ``` cd backend # 运行带有 coverage 的所有测试 pytest --cov=app --cov-report=term-missing # 运行特定 module pytest tests/test_alerts.py -v # 以 verbose 输出运行 pytest -v --tb=short ``` ### 测试架构 - **会话级事件循环** — 所有测试共享一个 asyncio 循环，以防止 Starlette 的 `BaseHTTPMiddleware` 任务组冲突。 - **表删除** — 每个测试均通过按照外键依赖顺序（先子表）执行针对性的 `DELETE` 语句来获得干净的数据库状态。这避免了 `TRUNCATE` 的排他访问锁争用。 - **会话隔离** — 防止死锁和 asyncpg 的“Future attached to a different loop”错误： - HTTP 客户端不会覆盖 `get_db`；应用程序像在生产环境中一样，为每个请求使用自己独立的会话。 - User fixture 和直接 DB 辅助操作（例如，告警创建）在它们各自的执行范围内，在本地打开和关闭自己独立的连接。 - **NullPool 引擎** — 防止跨协程的连接重用。 ### 覆盖率 | 模块 | 覆盖率 | |---|---| | 认证 | ≥ 90% | | IOC endpoint | ≥ 85% | | 告警 endpoint | ≥ 85% | | Webhook endpoint | ≥ 80 | ## CI/CD 流水线 GitHub Actions 流水线（`.github/workflows/ci.yml`）会在每次推送到 `main` 和 `features/**` 分支时运行： ``` ┌──────────────────┐ ┌──────────────────┐ ┌─────────────────────┐ │ backend-lint │ │ backend-test │ │ frontend-lint-build│ │ │ │ │ │ │ │ ruff check . │ │ PostgreSQL 16 │ │ npm run lint │ │ │ │ Redis 7 │ │ npm run build │ │ │ │ alembic upgrade │ │ │ │ │ │ pytest --cov │ │ │ └──────────────────┘ └──────────────────┘ └─────────────────────┘ │ ▼ ┌──────────────────┐ │ docker-build │ │ (dry run) │ │ │ │ Backend image │ │ Frontend image │ └──────────────────┘ ``` 覆盖率报告将作为工作流制品（`html-coverage-report`）上传。 ## 项目结构 ``` Vantablack/ ├── .github/ │ └── workflows/ │ └── ci.yml # GitHub Actions CI pipeline │ ├── backend/ │ ├── app/ │ │ ├── api/ │ │ │ └── v1/ │ │ │ ├── endpoints/ # Route handlers (auth, iocs, alerts, …) │ │ │ ├── dependencies/ # FastAPI Depends (auth, db) │ │ │ └── router.py # Main API router │ │ ├── core/ │ │ │ ├── config.py # Pydantic settings │ │ │ ├── security.py # JWT + password hashing │ │ │ ├── middleware.py # Request-ID middleware │ │ │ └── logger.py # Structured logging │ │ ├── db/ │ │ │ ├── session.py # Async engine + session factory │ │ │ └── base.py # SQLAlchemy declarative base │ │ ├── models/ # ORM models (IOC, Alert, User, …) │ │ ├── schemas/ # Pydantic request/response schemas │ │ ├── repositories/ # Data-access layer │ │ ├── services/ # Business logic (scoring, enrichment, webhooks) │ │ ├── ingestion/ # Feed connectors (OTX, URLhaus, …) │ │ └── main.py # FastAPI app factory + lifespan │ ├── alembic/ # Database migration scripts │ ├── tests/ │ │ ├── conftest.py # Session loop, fixtures, DB setup │ │ ├── test_auth.py │ │ ├── test_alerts.py │ │ ├── test_iocs.py │ │ ├── test_webhooks.py │ │ └── test_metrics.py │ ├── Dockerfile │ ├── requirements.txt │ └── pytest.ini │ ├── frontend/ │ └── vantablack/ │ ├── src/ │ │ ├── api/ # Axios API modules (alerts, iocs, webhooks, …) │ │ ├── components/ # Shared UI components (Sidebar, Header, …) │ │ ├── hooks/ # React Query hooks │ │ ├── pages/ # Full-page views (WebhooksPage, LoginPage) │ │ ├── utils/ # Adapters, formatters │ │ ├── types.ts # Shared TypeScript types │ │ └── App.tsx # Root component + tab router │ ├── Dockerfile │ ├── vite.config.ts │ └── package.json │ └── docker-compose.yml # Full stack orchestration ``` ## 许可证 本项目仅用于教育和个人作品集展示目的。

为安全运营中心（SOC）用 ❤️ 构建

标签：AV绕过, FastAPI, PostgreSQL, React, Syscalls, 妥协指标, 威胁情报, 安全运营中心, 开发者工具, 搜索引擎查询, 测试用例, 网络映射, 自定义请求头, 请求拦截