swayamiitb/SAAS_-AI

## 它是什么 一个 **OSINT**（开源情报）智能体，它能够**导航**公开可用的数据源， 构建一个包含其所发现的实体和关系的**活的知识图谱**，并将结果渲染 为用于分析的**交互式 3D 图谱**。 将智能体指向你被授权研究的目标——你拥有的域名、你正在评估的组织、 公开的代码库足迹。看着基础设施自动映射成图：域名解析到 IP、证书 绑定到组织、公开的代码库链接到贡献者。然后查询图谱——*“显示在 2 跳 内连接到该主机的所有内容”*——并看着子图谱高亮显示，同时智能体 解释这些关系。切换到 2D 以进行精确的链接分析。 ## 查看运行效果 智能体**每轮执行一个推理步骤**：读取请求，调用最小集合的 provider， 将发现的实体归档到图谱中，然后回答。 ## 工作原理 一个单一的**编排智能体**（LangGraph + `qwen3:14b`）将每一轮路由到 正确的**上下文 provider**。每个 provider 都是一个子智能体，它拥有一个 数据源并将其怪异之处与编排器隔离。图谱（Neo4j）*就是*记忆——它随着 每次调查而增长，因此知识可以在不同会话之间积累。 ## ✨ 核心亮点 | | | |:---|:---| | 🧠 **设计上本地优先** | 推理模型（`qwen3:14b`，<31B 参数）通过 Ollama 在你的硬件上运行——无需云端调用，没有 API 账单，数据不离开你的网络。 | | 🕸️ **图谱*就是*记忆** | 每个发现都成为一个节点；每个观察到的关系都成为一条边。Neo4j 跨会话持久化存储它们。 | | 🎯 **导航，而非摄入** | 就像编码智能体使用 `ls` 和 `grep` 一样，智能体只向每个数据源查询它确切需要的内容——没有批量抓取。 | | 🔒 **单一写入面安全** | 只有一个工具（`update_graph`）可以更改数据库。一个经过 schema 验证的写入器会拒绝词汇表之外的任何内容。 | | 🔬 **封闭且经过验证的 schema** | 节点标签和边类型是在写入时强制执行的固定词汇表——拼写错误永远不会静默创建一个不可见的节点。 | | 🌐 **四个 OSINT 数据 provider** | Domain/DNS/WHOIS/SSL · Web (SearXNG + Trafilatura) · GitHub 公开 API——默认均无需密钥。 | | 🎨 **双模式可视化** | 沉浸式的 `react-force-graph-3d` 视图**加上**精确的 `Cytoscape.js` 2D 视图，支持实时切换。 | ## 🧱 技术栈 | 层级 | 选择 | 原因 | |---|---|---| | **Agent 编排** | LangGraph + FastAPI | 开放、有状态、通过 SSE 流式传输 token | | **推理模型** | 通过 Ollama 的 `qwen3:14b` | 本地，<31B 参数，原生支持 tool-calling | | **Embeddings** | 通过 Ollama 的 `bge-m3` | 多语言，8K 上下文，语义节点搜索 | | **知识图谱** | Neo4j Community 5.x | 专为图构建的数据库，支持丰富的 Cypher 查询 | | **Web 研究** | SearXNG + Trafilatura | 自托管的元搜索引擎 + 干净的页面提取 | | **数据收集** | dnspython · python-whois · cryptography · PyGithub | 完全开源，无需密钥 | | **前端** | Next.js 14 · react-force-graph-3d · Cytoscape.js | 3D 探索 + 实用的 2D 分析 | | **基础设施** | Docker Compose (5 个服务) | 一条命令启动整个平台 |

🏗️ 架构原则——工程决策

- **每轮一个推理步骤。** 编排器读取请求，调用最小集合的 provider， 然后回答。没有无界的规划循环，没有不受控的扇出——成本和延迟可预测。 - **Provider 隔离。** 每个数据源都是一个子智能体，它处理其 API 的 怪异之处（分页、超时、响应结构）。编排器的上下文永远不会看到 那些混乱——只有干净的 `query_` / `update_graph` 工具。 - **读写分离。** 收集 provider 严格只读。图谱 provider 是唯一的 写入者，且其写入在接触数据库之前必须通过经过 pydantic 验证的计划。 - **封闭词汇表。** 添加节点/边类型是对单一事实来源 （`graph_schema.py`）的经过深思熟虑和审查的更改——而这不是 LLM 在运行时可以凭空发明的东西。 - **优雅降级。** 每个 provider 都会自我报告健康状况并干净地失败。 智能体会告诉你某个源不可用，而不是伪造数据。

## 📊 部署状态 ``` git clone https://github.com/swayamiitb/SAAS_-AI.git cd SAAS_-AI cp .env.example .env ./scripts/setup.sh # seeds config + SearXNG settings docker compose up -d # Neo4j · Ollama · SearXNG · API · Web ./scripts/ollama_pull.sh # qwen3:14b + bge-m3 (a few GB) open http://localhost:3000 # the analysis console ``` **已验证：** 所有后端检查均通过（ruff、mypy、48 个单元测试、8 个架构 不变量），并且数据 provider 已针对实时公开数据进行了测试。 | 服务 | URL | 用途 | |---|---|---| | 🖥️ **分析控制台** | http://localhost:3000 | 3D/2D 图谱 + 流式聊天 | | ⚙️ **API** | http://localhost:8000/docs | FastAPI Swagger 文档 | | 🕸️ **Neo4j Browser** | http://localhost:7474 | 浏览原始图谱（用户名 `neo4j` / 密码来自 `.env`） | | 🧠 **Ollama** | http://localhost:11434 | 本地模型 runtime | | 🔍 **SearXNG** | http://localhost:8080 | 自托管元搜索 |

🔧 不使用 Docker 运行后端

``` python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e ".[dev]" # 在某处运行 Neo4j + Ollama；将 .env 指向它们。 cd backend PYTHONPATH=. uvicorn app.main:app --reload # API on :8000 PYTHONPATH=. python -m saas_ai chat # …or the CLI ``` 前端需要 Node 20：`cd frontend && npm install && npm run dev`。

## 🕸️ 知识图谱 一个**封闭的词汇表**保持图谱整洁，并使可视化图例保持稳定。 **节点** — `Domain` · `Subdomain` · `IPAddress` · `Organization` · `Person` · `Email` · `GitHubUser` · `GitHubRepo` · `WebPage` · `Certificate` · `Tag` **边** — `RESOLVES_TO` · `SUBDOMAIN_OF` · `REGISTERED_BY` · `HAS_CERTIFICATE` · `OWNS` · `MEMBER_OF` · `AUTHORED` · `LINKS_TO` · `MENTIONED_ON` · `EXTRACTED_FROM` · `TAGGED` 每个节点都包含 `source`、`confidence` (0.0–1.0)、`first_seen`、`last_seen`。 完整 schema 见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。 ## 🛠️ CLI ``` python -m saas_ai chat # interactive analysis chat python -m saas_ai providers # show provider status python -m saas_ai graph-stats # node / edge counts python -m saas_ai clear-graph # wipe the graph (prompts for confirm) python -m saas_ai pull-models # print the model-pull command ``` ## ✅ 质量与评估 ``` python -m evals wiring # 8 structural checks — must always be green python -m pytest backend/tests -q ``` | 层级 | 断言内容 | |---|---| | **架构不变量** | 单一写入面 · 封闭图谱词汇表 · 严格的计划验证 · provider 协议结构 · 完整的 API 面 | | **单元测试** | 词汇表标准化 · provider 契约 · 图谱写入器计划验证 | | **行为/评判** | 智能体路由、往返交互、优雅降级、注入抵抗（需要实时运行栈） | 完整方法论见 [`docs/EVALS.md`](docs/EVALS.md)。 ## 📁 项目布局 ``` SAAS_-AI/ ├── compose.yaml # 5-service stack ├── backend/ │ ├── saas_ai/ # the agent — settings, instructions, orchestrator │ │ ├── agent.py # LangGraph ReAct orchestrator + streaming │ │ ├── graph_schema.py # closed node/edge vocabulary + Neo4j read/write │ │ ├── graph_writer.py # LLM plan → schema-validated → apply │ │ ├── contexts.py # env-driven provider registry │ │ └── providers/ # graph · web · domain · github + base contract │ ├── app/ # FastAPI routes (chat, graph, ingest, providers) │ ├── evals/ # architecture invariants + behavioral harness │ └── tests/ # pytest unit tests ├── frontend/ # Next.js: Graph3D, Graph2D, ChatPanel, inspector └── docs/ # SETUP · ARCHITECTURE · PROVIDERS · EVALS ``` ## ⚖️ 负责任及授权使用 OSINT 仅处理**公开可用的开源信息**。SAAS AI **不执行主动扫描、不 进行身份验证、也不访问私有数据**——它只读取已经公开的内容。它适用于： - **防御性安全** ——在你拥有或被授权评估的基础设施上进行攻击面映射和资产清查。 - **威胁情报** ——丰富和关联公开的指标。 - **尽职调查与研究** ——了解一个组织的公开足迹。 - **教育** ——学习基于图的 OSINT 分析和本地 AI agent。 **仅在你被授权研究的系统和数据上使用它。** 尊重每个数据源的 服务条款和所有适用法律。作者不对滥用行为负责。 ## 📄 许可证 **MIT。** 每个组件都是开源的。每个模型都是开放权重的且在本地运行。

标签：AI风险缓解, ESC4, GitHub, LangGraph, Neo4j, OSINT, 实时处理, 情报分析, 版权保护, 网络诊断, 误配置预防, 逆向工具