sayan9168/nexus-osint

## 📑 目录 - [概述](#-overview) - [核心功能](#-key-features) - [架构](#-architecture) - [技术栈](#-tech-stack) - [快速开始](#-quick-start) - [项目结构](#-project-structure) - [API 参考](#-api-reference) - [AI Agent](#-ai-recon-agent) - [3D 图谱 UI](#-3d-graph-ui) - [Transforms](#-transforms) - [配置](#-configuration) - [开发](#-development) - [路线图](#-roadmap) - [贡献](#-contributing) - [License](#-license) - [作者](#-author) ## 🔍 概述 **NEXUS-OSINT** 是一个生产级的、AI 原生的开源情报 (OSINT) 与 3D 链路分析平台。它使安全研究人员、威胁分析师和调查人员能够： - **自主调查**目标，使用 AI 驱动的 OSINT 工作流 - **可视化复杂关系**，在交互式的 3D WebGL 图谱中（支持 100,000+ 节点） - **发现隐藏的关联**，利用语义向量搜索在不同实体间进行分析 - **异步执行 OSINT transforms**（DNS, WHOIS, VirusTotal 以及自定义 transform） - **实时接收更新**，当 AI agent 发现新实体时通过 WebSocket 进行推送 ## ✨ 核心功能 | 功能 | 描述 | |---------|-------------| | 🤖 **自主 AI Agent** | 基于 LangGraph 的 agent，能够根据图谱上下文决定运行哪些 OSINT transforms | | 🌐 **3D 图谱可视化** | 基于 WebGL 的力导向图谱，以 60 FPS 的速度渲染 100K+ 节点 | | ⚡ **实时流处理** | 基于 WebSocket 的实时图谱更新，在发现实体时即时呈现 | | 🔗 **语义关联** | 向量嵌入 (Qdrant) 用于发现不同类型实体之间的隐藏关联 | | 🔄 **异步 Transform 引擎** | Celery + Redis 任务队列，实现非阻塞的 OSINT 数据收集 | | 📊 **内存图谱数据库** | Memgraph (Cypher) 用于超高速的节点/关系查询 | | 🛡️ **威胁情报** | 集成 VirusTotal，用于声誉检查和 IOC 发现 | | 🏗️ **生产级架构** | Docker 编排，速率限制，重试逻辑，结构化日志 | ## 🏗 架构 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ NEXUS-OSINT Platform │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ WebSocket ┌──────────────────────────────┐ │ │ │ Next.js 3D │◄────────────────►│ FastAPI Backend │ │ │ │ Frontend │ REST API │ ┌────────────────────────┐ │ │ │ │ (WebGL) │◄────────────────►│ │ /api/v1/graph │ │ │ │ │ Port:3001 │ │ │ /api/v1/entities │ │ │ │ └──────────────┘ │ │ /api/v1/transforms │ │ │ │ │ │ /api/v1/agent │ │ │ │ │ │ /ws/graph (WebSocket) │ │ │ │ │ └────────────────────────┘ │ │ │ └──────┬───────────┬───────────┘ │ │ │ │ │ │ ┌────────────┘ └────────┐ │ │ ▼ ▼ │ │ ┌──────────────────────────────────┐ ┌─────────────────────┐ │ │ │ Memgraph (Graph DB) │ │ Qdrant (Vector) │ │ │ │ In-Memory Cypher │ │ Semantic Search │ │ │ │ Port: 7687 │ │ Port: 6333 │ │ │ └──────────────────────────────────┘ └─────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ Celery Workers + Redis Broker │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────────┐ │ │ │ │ │DNS │ │WHOIS │ │VirusTotal│ │ Custom │ │ │ │ │ │Transform│ │Transform│ │Transform │ │ Transforms │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ AI Recon Agent (LangGraph) │ │ │ │ Plan (LLM) → Execute Tools → Correlate (Vector) → Report │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ## 🛠 技术栈 | 层级 | 技术 | |-------|-----------| | **Backend** | Python 3.11+, FastAPI (AsyncIO), Pydantic v2 | | **图数据库** | Memgraph 2.18 (In-Memory Cypher) | | **向量数据库** | Qdrant 1.9 (语义搜索与身份匹配) | | **任务队列** | Celery 5.4 + Redis 7.2 | | **AI Agent** | LangGraph + LangChain + LLM (Qwen / Claude) | | **Frontend** | Next.js 14, TypeScript, Tailwind CSS | | **3D 渲染** | 3d-force-graph (WebGL / Three.js) | | **状态管理** | Zustand | | **编排** | Docker & Docker Compose | | **日志** | structlog (结构化 JSON 日志) | ## 🚀 快速开始 ### 前置条件 - Docker & Docker Compose v2.20+ - 8GB+ 内存 (Memgraph 基于内存运行) - (可选) 用于本地 LLM 推理的 Ollama ### 1. 克隆仓库 ``` git clone https://github.com/sayan9168/nexus-osint.git cd nexus-osint ``` ### 2. 配置环境 ``` cp .env.example .env ``` 编辑 `.env` 文件，填入你的 API 密钥： ``` VIRUSTOTAL_API_KEY=your_vt_key_here LLM_API_KEY=your_llm_key_here LLM_BASE_URL=http://localhost:11434/v1 LLM_MODEL=qwen2.5:72b ``` ### 3. 构建并启动 ``` # 构建所有容器 docker compose build --no-cache # 启动所有服务 docker compose up -d ``` ### 4. 访问平台 | 服务 | URL | |---------|-----| | 🌐 **3D 图谱控制面板** | http://localhost:3001 | | 🔌 **Backend API** | http://localhost:8000 | | 📖 **API 文档 (Swagger)** | http://localhost:8000/docs | | 🤖 **AI Agent 服务** | http://localhost:8001 | | 🗄️ **Memgraph Lab** | http://localhost:3000 | | 📐 **Qdrant 控制面板** | http://localhost:6333/dashboard | ### 5. 验证安装 ``` # 健康检查 curl http://localhost:8000/health # 运行 DNS transform curl -X POST http://localhost:8000/api/v1/transforms/execute \ -H "Content-Type: application/json" \ -d '{"transform_name": "dns_resolution", "entity_type": "Domain", "entity_value": "example.com"}' # 触发 AI 调查 curl -X POST http://localhost:8000/api/v1/agent/investigate \ -H "Content-Type: application/json" \ -d '{"target": "suspicious-domain.com", "goal": "Identify all associated infrastructure"}' ``` ## 📁 项目结构 ``` nexus-osint/ ├── docker-compose.yml # Service orchestration ├── .env.example # Environment template ├── Makefile # Build/run shortcuts ├── README.md ├── LICENSE ├── .gitignore │ ├── backend/ # FastAPI + Transforms + Workers │ ├── main.py # App entry point │ ├── config.py # Centralized settings │ ├── db/ # Memgraph + Qdrant clients │ ├── transforms/ # OSINT transform engine │ ├── api/ # REST + WebSocket routes │ └── workers/ # Celery task definitions │ ├── agent/ # AI Recon Agent (LangGraph) │ ├── recon_agent.py # Main agent workflow │ ├── tools.py # LLM tool definitions │ ├── state.py # LangGraph state schema │ ├── correlation.py # Semantic correlation engine │ └── prompts.py # System prompts │ ├── frontend/ # Next.js 3D Dashboard │ └── src/ │ ├── components/ # Graph3D, Sidebar, AgentPanel │ ├── hooks/ # useWebSocket, useGraphData │ ├── store/ # Zustand state │ └── lib/ # API client, types │ └── docker/ # Init scripts & configs ├── memgraph/init.cypher ├── redis/redis.conf └── nginx/nginx.conf ``` ## 📡 API 参考 ### 图谱端点 | 方法 | 端点 | 描述 | |--------|----------|-------------| | `GET` | `/api/v1/graph/full` | 获取完整图谱（节点 + 边） | | `GET` | `/api/v1/graph/neighbors` | 按深度获取实体的相邻节点 | | `GET` | `/api/v1/graph/summary` | 图谱统计摘要 | | `POST` | `/api/v1/graph/nodes` | 创建新节点 | | `POST` | `/api/v1/graph/edges` | 创建新边 | | `POST` | `/api/v1/graph/query` | 执行原生 Cypher 查询 | | `POST` | `/api/v1/graph/correlate` | 语义关联搜索 | | `DELETE` | `/api/v1/graph/nodes/{id}` | 删除节点及关系 | ### 实体端点 | 方法 | 端点 | 描述 | |--------|----------|-------------| | `GET` | `/api/v1/entities/` | 列出实体（分页） | | `GET` | `/api/v1/entities/{id}` | 获取单个实体 | | `POST` | `/api/v1/entities/` | 创建实体 | | `PUT` | `/api/v1/entities/{id}` | 更新实体 | | `DELETE` | `/api/v1/entities/{id}` | 删除实体 | | `POST` | `/api/v1/entities/search` | 全文搜索 | ### Transform 端点 | 方法 | 端点 | 描述 | |--------|----------|-------------| | `GET` | `/api/v1/transforms/` | 列出可用的 transforms | | `POST` | `/api/v1/transforms/execute` | 执行 transform（同步/异步） | | `GET` | `/api/v1/transforms/status/{id}` | 检查异步任务状态 | ### Agent 端点 | 方法 | 端点 | 描述 | |--------|----------|-------------| | `POST` | `/api/v1/agent/investigate` | 启动 AI 调查 | | `GET` | `/api/v1/agent/health` | Agent 服务健康状态 | ### WebSocket | 端点 | 描述 | |----------|-------------| | `ws://host:8000/ws/graph` | 实时图谱更新流 | ## 🤖 AI 侦察 Agent 自主调查 agent 使用 **LangGraph** 来编排工具调用循环： ``` ┌────────┐ ┌───────────────┐ ┌─────────────┐ ┌────────┐ │ PLAN │────►│ EXECUTE TOOLS │────►│ CORRELATE │────►│ REPORT │ │ (LLM) │◄────│ (OSINT) │◄────│ (Vector) │ │ │ └────────┘ └───────────────┘ └─────────────┘ └────────┘ ``` **可用工具：** - `run_dns_resolution` — DNS 记录发现 - `run_whois_lookup` — 域名归属情报 - `run_virustotal_lookup` — 威胁声誉与 IOC 提取 - `query_graph_neighbors` — 知识图谱遍历 - `find_semantic_correlations` — 通过嵌入发现隐藏关联 - `get_investigation_summary` — 当前状态概览 ## 🌐 3D 图谱 UI 前端使用 **WebGL** (Three.js) 渲染交互式的 3D 力导向图谱： - **100,000+ 节点**借助 GPU 加速以 60 FPS 渲染 - 按类型对实体进行**颜色编码**（Domain, IP, Email, Hash, Wallet, Person 等） - 沿着边流动的**动画粒子**，用于显示关系方向 - **点击检查**任意节点以查看完整元数据 - AI agent 发现实体时，通过 WebSocket **实时更新** - **筛选面板**用于切换实体类型的可见性 - **AI Agent 面板**用于启动调查并查看报告 ## 🔄 Transforms | Transform | 输入 | 输出 | 描述 | |-----------|-------|--------|-------------| | `dns_resolution` | Domain | IP, Domain, Email | 解析 A, AAAA, MX, NS, TXT 记录 | | `whois_lookup` | Domain | Domain, Email, Person | 获取注册数据 | | `virustotal_lookup` | Domain/IP/Hash | IP, Domain, Hash, Email | 威胁情报与 IOCs | 可以通过扩展 `BaseTransform` 来添加**自定义 transforms**： ``` from transforms.base import BaseTransform from db.schemas import NodeLabel, TransformResult class MyCustomTransform(BaseTransform): name = "my_transform" description = "Does something useful" input_type = NodeLabel.DOMAIN output_types = [NodeLabel.IP] async def execute(self, entity_value, parameters=None): # Your logic here return TransformResult( transform_name=self.name, status="success", new_nodes=[...], new_edges=[...], ) ``` ## ⚙️ 配置 所有配置均通过环境变量进行管理（参见 `.env.example`）： | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `MEMGRAPH_HOST` | `localhost` | Memgraph 服务器主机 | | `MEMGRAPH_PORT` | `7687` | Memgraph Bolt 端口 | | `REDIS_URL` | `redis://localhost:6379/0` | Redis 连接 | | `QDRANT_HOST` | `localhost` | Qdrant 服务器主机 | | `QDRANT_PORT` | `6333` | Qdrant HTTP 端口 | | `VIRUSTOTAL_API_KEY` | — | VirusTotal API 密钥 | | `LLM_API_KEY` | — | LLM 提供商 API 密钥 | | `LLM_BASE_URL` | `http://localhost:11434/v1` | LLM 端点 | | `LLM_MODEL` | `qwen2.5:72b` | 模型标识符 | ## 💻 开发 ### 本地开发（不使用 Docker） ``` # Backend cd backend python -m venv venv && source venv/bin/activate pip install -r requirements.txt uvicorn main:app --reload --port 8000 # Celery Worker celery -A workers.celery_app worker --loglevel=info # Agent cd agent pip install -r requirements.txt python recon_agent.py # Frontend cd frontend npm install npm run dev ``` ### 运行测试 ``` cd backend pytest tests/ -v --cov=. cd frontend npm run lint ``` ### Makefile 命令 ``` make up # Start all services make down # Stop all services make build # Rebuild containers make logs # Tail all logs make clean # Full cleanup (volumes + images) make restart # Restart all ``` ## 🗺 路线图 - [ ] Shodan / Censys 集成 transforms - [ ] 区块链浏览器 transforms (Etherscan, Blockchain.com) - [ ] 暗网论坛爬虫（基于 Tor） - [ ] 多用户身份验证 (JWT + RBAC) - [ ] 图谱导出 (GraphML, GEXF, JSON) - [ ] 用于时间分析的 timeline 视图 - [ ] 协作调查会话 - [ ] 面向社区 transforms 的插件市场 - [ ] 用于云端部署的 Kubernetes Helm chart - [ ] 移动端响应式图谱查看器 ### 提交规范 ``` feat: New feature fix: Bug fix docs: Documentation update refactor: Code refactoring test: Adding tests chore: Maintenance tasks ``` ## 📜 License 该项目基于 **Sayanox License v1.1** 授权。 有关完整的条款和条件，请参阅 [LICENSE](./LICENSE) 文件。 ## 👤 作者 ```

标签：ESC4, OSINT, Python, 关联分析, 图数据分析, 安全调查, 实时处理, 搜索引擎查询, 无后门, 请求拦截