tiger-eye

pgvector 原生威胁情报 enrichment 服务

从 [tiger2go](https://github.com/miketigerblue/tiger2go) 摄入器数据库读取 OSINT 条目，通过 RAG 上下文运行基于 LLM 的分析，并存储带有向量嵌入的增强结果——全部在 Postgres 中完成。 属于 tiger 生态系统：**tiger2go**（摄入器）→ **tiger-eye**（增强器）→ **snow-tiger**（导出器）。 ## 架构 ``` ┌──────────────────────────────┐ ┌──────────────────────────────────────┐ │ TIGERFETCH │ │ TIGEREYE │ │ (Go ingestor) │ │ (enrichment service) │ ├──────────────────────────────┤ ├──────────────────────────────────────┤ │ │ │ │ │ RSS / Atom Feeds │ │ Enrichment Loop (async) │ │ │ │ │ │ │ │ ▼ │ │ ▼ │ │ archive │───────▶│ Read unprocessed entries │ │ current │ net │ │ │ │ cve_enriched │───────▶│ RAG retrieval (pgvector) │ │ epss_daily │ │ │ │ │ │ │ ▼ │ │ │ │ LLM analysis (OpenAI) │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ Persist analysis + embedding │ │ │ │ (single transaction) │ │ │ │ │ │ │ │ Internal API (:8080) │ │ │ │ • /health │ │ │ │ • /internal/search/text │ │ │ │ • /internal/search/vector │ │ │ │ • /internal/node/{id} │ │ │ │ • /metrics │ └──────────────────────────────┘ └──────────────────────────────────────┘ ``` ## 功能特性 - **增强管线**——通过指数退避与信号量限制并发，批量处理条目并通过 LLM 分析 - **RAG 上下文**——pgvector 余弦距离检索将相似历史分析注入 LLM 提示词，支持 Token 预算与距离阈值 - **NVD 上下文查询**——从文本提取 CVE ID 并从 `cve_enriched` 表获取实时的 CVSS/EPSS 分数 - **ATT&CK 标准化**——260 项查找表在后期处理中自动填充 MITRE ATT&CK 技术 ID - **结构化输出**——每次分析包含 18 个情报字段：威胁类型、严重度、置信度、IOC、TTP、角色方、恶意软件家族、地理、区域、CVE、工具、建议动作 - **三支柱可观测性**——structlog JSON 日志、13 项 Prometheus 指标、OpenTelemetry 分布式追踪 - **Grafana 仪表板**——16 面板的预配置仪表板（管线健康、延迟百分位、RAG 命中率、威胁分布） - **自定义迁移运行器**——SHA-256 校验和、干运行模式、状态报告 ## API 端点 | 方法 | 路径 | 描述 | |--------|------|-------------| | `GET` | `/health` | 活跃性探测（含数据库检查、循环状态、连续失败计数） | | `POST` | `/internal/search/text` | 基于自然语言的语义搜索 | | `POST` | `/internal/search/vector` | 基于嵌入向量的最近邻搜索 | | `GET` | `/internal/node/{id}` | 按 UUID 获取分析结果 | | `GET` | `/metrics` | Prometheus 抓取端点 | | `GET` | `/docs` | Swagger UI | ## 快速启动 ``` # 确保 tiger2go 栈正在运行 cd ~/tiger2go && docker compose up -d # 启动 tiger-eye（加入 tiger2go_net） cd ~/tiger-eye && docker compose up -d # 检查健康状况 curl http://localhost:8080/health ``` ## 配置 将 `.env.example` 复制为 `.env` 并设置 OpenAI API 密钥。其他默认值均指向 tiger2go Postgres 容器。 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `DATABASE_URL` | `postgresql+asyncpg://...tiger2go_postgres:5432/tiger2go` | 异步 Postgres 连接字符串 | | `OPENAI_API_KEY` | *(必需)* | 用于 LLM 与嵌入的 OpenAI API 密钥 | | `EMBEDDING_MODEL` | `text-embedding-3-small` | OpenAI 嵌入模型 | | `EMBEDDING_DIMENSIONS` | `1536` | 向量维度 | | `ENRICH_INTERVAL` | `60` | 增强周期之间的秒数 | | `ENRICH_BATCH_SIZE` | `20` | 每周期处理的条目数 | | `LOG_LEVEL` | `INFO` | 日志级别 | | `LOG_JSON` | `true` | JSON 结构化日志（开发时设为 false） | | `OTEL_EXPORTER_OTLP_ENDPOINT` | *(可选)* | OpenTelemetry OTLP gRPC 端点 | ## 开发 ``` python -m venv venv source venv/bin/activate pip install -r requirements.txt cp .env.example .env # 使用您的 OPENAI_API_KEY 编辑 .env python -m tiger_eye.main ``` ### 运行测试 ``` # 单元 + API 测试（无需数据库） pytest tests/test_analysis.py tests/test_api.py -v # 集成测试（需要 DATABASE_URL 指向 pgvector Postgres） DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/tiger2go pytest tests/test_integration.py -v # 通过 Docker 运行完整套件 docker compose -f docker-compose.test.yml up --build --abort-on-container-exit ``` ### 迁移 ``` # 应用待处理的迁移 python -m tiger_eye.migrate # 检查状态 python -m tiger_eye.migrate --status # 预览而不应用 python -m tiger_eye.migrate --dry-run ``` ## 测试 共 37 个测试，覆盖三层： | 层级 | 文件 | 测试数 | 覆盖内容 | |-------|------|-------|----------------| | 单元 | `test_analysis.py` | 22 | 标准化边界情况：威胁类型、严重度、置信度钳制、IOC 包装、TTP 自动填充、JSON 解析 | | API | `test_api.py` | 8 | 健康（200/503）、节点查询（400/404/200）、文本搜索、向量搜索、输入验证 | | 集成 | `test_integration.py` | 7 | 真实 Postgres+pgvector：数据库连接、模式验证、ORM 往返、级联删除、HNSW 向量搜索、迁移 | 集成测试在无 `DATABASE_URL` 时自动跳过，并在 CI 中通过 `docker-compose.test.yml` 连接真实 pgvector。 ## CI/CD 包含 8 个作业的 5 阶段流水线（`.github/workflows/ci.yml`）： | 阶段 | 作业 | |-------|------| | 1（快速，并行） | Lint（ruff + mypy）、SAST（bandit + semgrep）、依赖审计（pip-audit）、密钥扫描（gitleaks） | | 2 | 单元测试（pytest + 覆盖率） | | 3 | 集成测试（pgvector 服务容器） | | 4 | 容器扫描（Trivy 漏洞扫描 + SBOM 生成） | | 5 | DAST（对运行中容器执行 ZAP 基线扫描） | 额外项：每周 CodeQL 定时任务、Dependabot（pip/docker/github-actions）、预提交钩子（ruff、bandit、detect-secrets、gitleaks、禁止提交到 main）。 ## 可观测性 | 支柱 | 技术 | 细节 | |--------|-----------|--------| | **日志** | structlog | JSON 输出到 stdout，可配置级别，抑制嘈杂日志器 | | **指标** | prometheus_client | `/metrics` 提供 13 项指标——增强速率、失败阶段、LLM/嵌入延迟直方图、RAG 命中率 | | **追踪** | OpenTelemetry | OTLP gRPC 导出，自动注入 FastAPI 与 SQLAlchemy，批量与搜索的手动 Span | | **仪表板** | Grafana | 16 面预配置 JSON 仪表板——概述、管线、延迟（p50/p95/p99）、RAG | | **健康** | FastAPI | `GET /health` 包含活跃 DB 探测、循环状态、连续失败计数 |

## 项目结构 ``` tiger-eye/ ├── tiger_eye/ │ ├── main.py # FastAPI app + enrichment loop │ ├── analysis.py # LLM pipeline, prompt, normaliser, TTP lookup │ ├── rag.py # pgvector semantic search (RAG retrieval) │ ├── embedding.py # OpenAI embedding wrapper with retries │ ├── database.py # SQLAlchemy ORM (5 models), async sessions │ ├── config.py # pydantic-settings configuration │ ├── metrics.py # Prometheus metric definitions │ ├── logging_config.py # structlog JSON configuration │ ├── tracing.py # OpenTelemetry initialisation │ └── migrate.py # Custom migration runner CLI ├── migrations/ │ ├── 001_analysis_pgvector.sql # Schema + HNSW index │ └── 002_backfill_ttp_ids.sql # Historical TTP ID backfill ├── grafana/dashboards/ │ └── tiger-eye.json # 16-panel Grafana dashboard ├── tests/ │ ├── test_analysis.py # 22 unit tests │ ├── test_api.py # 8 API tests │ └── test_integration.py # 7 integration tests ├── docker-compose.yml # Production (joins tiger2go_net) ├── docker-compose.test.yml # Integration test harness ├── Dockerfile ├── pyproject.toml # ruff, mypy, pytest, bandit config ├── requirements.txt ├── SYSTEM_DESIGN.md # 1000+ line architecture document └── SECURITY.md # Vulnerability disclosure policy ``` ## 文档 - **[SYSTEM_DESIGN.md](SYSTEM_DESIGN.md)**——完整的架构规范，含 C1/C2/C3 图、故障模式矩阵、性能特征和实时系统快照 - **[SECURITY.md](SECURITY.md)**——漏洞披露策略（security@tigerblue.tech，48 小时确认 SLA，30 天修复 SLA） ## 许可证 [MIT](LICENSE)

标签：Atom Feeds, CI, DLL 劫持, enrichment service, ESC4, Go, LLM, OSINT, pgvector, PostgreSQL, Python, RAG, RSS, Ruby工具, SEO, Snow Tiger, tiger2go, tiger ecosystem, Unmanaged PE, 向量嵌入, 向量数据库, 大语言模型, 威胁情报, 开发者工具, 开源框架, 异步处理, 情报增强, 持续集成, 搜索引擎优化, 无后门, 逆向工具