Csushobhit/NETRA-AI
GitHub: Csushobhit/NETRA-AI
基于多 Agent LLM 推理与无监督异常检测的 AI 驱动 SOC 平台，实现对网络日志的智能威胁检测、情报富化和可解释告警分类。
Stars: 1 | Forks: 0
# 🛡️ NETRA-AI
### *基于 AI 的网络评估与威胁识别分析*
     
## 📖 目录
- [概述](#-overview)
- [问题陈述](#-problem-statement)
- [核心功能](#-key-features)
- [系统架构](#-architecture)
- [系统流程](#-system-flow)
- [技术栈](#-tech-stack)
- [模块分解](#-module-breakdown)
- [项目截图](#-screenshots)
- [安装与设置](#️-installation--setup)
- [运行系统](#-running-the-system)
- [API 参考](#-api-reference)
- [项目结构](#-project-structure)
- [设计决策](#-design-decisions)
- [未来改进](#-future-improvements)
- [作者](#-author)
## 🚀 概述
**NETRA-AI** 是一个混合的、AI 驱动的安全运营中心 (SOC) 平台，它模拟了现实世界中的安全分析师如何检测、调查和响应网络威胁——并在每个步骤中实现了智能自动化。
它独特地将**行为异常检测**与**威胁情报富化**分离开来，采用人在回路的设计，让分析师保留对决策的最终控制权。
## 🔍 问题陈述
现代安全系统面临三个基本挑战：
| 问题 | 描述 |
|---|---|
| **告警量过大** | 系统每秒产生数千条日志——人工分析根本不可能完成 |
| **基于规则的局限性** | 静态规则无法捕捉不断演变的新的攻击模式 |
| **缺乏可解释性** | 触发的告警缺乏上下文、推理过程或可操作的指导 |
**NETRA-AI** 通过结合无监督 ML（异常检测）、多 Agent LLM 推理和经过验证的外部威胁情报来解决这三个问题。
## ✨ 核心功能
- 🔬 通过 Isolation Forest 实现的**行为异常检测**（弱信号层）
- 🤖 **多 Agent 推理 Pipeline** — 调查 Agent、决策 Agent 与解释 Agent
- 🧠 **基于向量的行为记忆** — 使用 OpenSearch 进行归一化的 k-NN 相似度检索
- 🌐 **威胁情报引擎** — Maltrail（约 20 万个 IP）+ AbuseIPDB + AlienVault OTX + VirusTotal
- 🗂️ **缓存优先的 TI 系统** — 显著减少冗余的外部 API 调用
- 🔁 **反馈学习循环** — 用户纠正被存储并反馈给 Agent 的推理过程
- 🛡️ **4 级风险分类** — `malicious` / `high_risky` / `low_risky` / `unknown`
- 🔐 **基于角色的访问控制** — 使用 Spring Security (BCrypt) 的管理员和用户角色
- 🛠️ **管理员控制面板** — 管理 TI 索引、更新 API 密钥、查看不可变的审计日志
- 📊 **OpenSearch Dashboards** — 所有系统数据的实时可视化
## 🧩 架构
### 高层系统架构
```
flowchart TB
subgraph DATA["📂 Data Layer"]
LG["🔧 Log Generator\n(Simulated Attacks)"]
OS_LOGS[("🗄️ OpenSearch\nlogs index")]
end
subgraph PIPELINE["⚙️ Processing Pipeline"]
FE["📐 Feature Engineering\n(freq · ratio · ports · time)"]
ML["🤖 Isolation Forest\n(Anomaly Score — Weak Signal)"]
end
subgraph AGENTS["🧠 Multi-Agent System"]
IA["🔍 Investigation Agent\nattack_type + reasoning"]
DA["⚖️ Decision Agent\nrisk_score + action"]
EA["📝 Explanation Agent\nhuman-readable output"]
end
subgraph MEMORY["💾 Behavioral Memory"]
MEM[("🗄️ OpenSearch\nmemory index\nk-NN Normalized Vectors")]
FB["🔄 User Feedback Loop"]
end
subgraph TI["🌐 Threat Intelligence"]
MTL["📋 Maltrail\n~200k IPs"]
CACHE[("🗄️ OpenSearch\nTI Cache Indices")]
APIS["🔌 External APIs\nAbuseIPDB · OTX · VirusTotal"]
TIA["🧬 TI Agent (LLM)\nDynamic Classification"]
end
subgraph OUTPUT["📊 Output Layer"]
FLASK["🐍 Flask API\nBackend (Port 9201)"]
SPRING["☕ Spring Boot\nFrontend Dashboard (Port 9202)"]
end
LG --> OS_LOGS
OS_LOGS --> FE
FE --> ML
ML --> IA
MEM --> IA
IA --> DA
DA --> EA
DA --> MEM
FB --> MEM
EA --> FLASK
FLASK -.->|"User triggers TI"| MTL
MTL --> CACHE
CACHE --> APIS
APIS --> TIA
TIA --> CACHE
TIA --> FLASK
FLASK --> SPRING
```
## 🔄 系统流程
### Pipeline A — 行为检测
```
sequenceDiagram
participant Gen as Log Generator
participant OS as OpenSearch (logs)
participant FE as Feature Engine
participant ML as Isolation Forest
participant Mem as Memory (k-NN)
participant Inv as Investigation Agent
participant Dec as Decision Agent
participant Exp as Explanation Agent
loop Continuous Streaming
Gen->>OS: Write log (ip, timestamp, event, port, status)
end
loop Every 2s
OS->>FE: Read new logs (timestamp-based query)
FE->>FE: Compute features per (IP × time_window)
FE->>ML: Feature vector [freq, ratio, ports, hour]
ML-->>Dec: anomaly_score (weak signal)
Mem-->>Inv: Top-3 similar past behaviors (k-NN)
FE->>Inv: Features + ML Score + Memory context
Inv-->>Dec: attack_type + reasoning
Dec-->>Exp: risk_score + action
Exp-->>OS: Persist enriched alert
end
```
### Pipeline B — 威胁情报 (用户触发)
```
flowchart LR
IP[/"🔍 Suspicious IP\n(User selects)"/]
MT{{"Maltrail\nCheck"}}
CA{{"TI Cache\nCheck"}}
API["AbuseIPDB\nOTX · VirusTotal"]
TIA["🧬 TI Agent\n(LLM — Dynamic weights)"]
OUT[/"📋 Result:\nmalicious · high_risky\nlow_risky · unknown"/]
IP --> MT
MT -->|"✅ Found"| OUT
MT -->|"❌ Miss"| CA
CA -->|"✅ Cached"| OUT
CA -->|"❌ Miss"| API
API --> TIA
TIA --> OUT
OUT -->|"Cache result"| CA
```
### 记忆与反馈循环
```
flowchart LR
A["New Alert\nFeature Vector"] --> B["Normalize\nfeature_vector\n0→1 scale"]
B --> C["k-NN Query\nOpenSearch\nmemory index"]
C --> D["Top-3 Similar\nPast Behaviors"]
D --> E["Agent Reasoning\n(enriched context)"]
E --> F["Decision\n+ Risk Score"]
F --> G["Store in\nMemory Index"]
H["User Feedback\ncorrect / incorrect"] --> I["Update Memory\nfeedback field"]
I --> C
```
## 🧱 技术栈
### 后端
| 层级 | 技术 |
|---|---|
| API 框架 | Flask (Python) |
| AI / LLM | LangChain + OpenAI GPT-4o-mini |
| ML 模型 | Scikit-learn — Isolation Forest |
| 向量搜索 | OpenSearch k-NN |
| TI APIs | AbuseIPDB, AlienVault OTX, VirusTotal |
### 前端
| 层级 | 技术 |
|---|---|
| Web 框架 | Spring Boot |
| 模板引擎 | Thymeleaf |
| 安全框架 | Spring Security (BCrypt) |
| 认证数据库 | MySQL |
### 基础设施
| 组件 | 技术 |
|---|---|
| 主数据库 | OpenSearch 2.x (Docker) |
| 数据可视化 | OpenSearch Dashboards |
| 容器化 | Docker |
## 📦 模块分解
```
mindmap
root((NETRA-AI))
Generator
log_generator
modes
writer
Ingestion
reader
tracker
Features
feature_engineer
grouping
ML
model
inference
isolation_forest.pkl
Agents
investigation_agent
decision_agent
explanation_agent
ti_agent
orchestrator
prompts
Memory
normalizer
retriever
schema
store
Threat Intel
load_maltrail
update_maltrail
checker
external_apis
scorer
Flask API
routes
pipeline_service
alert_service
ti_service
admin_service
Spring Boot
DashboardController
AdminController
SecurityConfig
AuthService
```
## 🖼️ 项目截图
### 着陆页
### 主仪表板
### 告警调查视图
### 威胁情报面板
## ⚙️ 安装与设置
### 前提条件
- Python 3.9+
- Java 17+ (用于 Spring Boot 前端)
- Maven 3.6+
- Docker Desktop
- Git
- MySQL 8.x
### 1. 克隆仓库
```
git clone https://github.com/csushobhit/NETRA-AI.git
cd netra-ai
```
### 2. 启动 OpenSearch & Dashboards
```
# OpenSearch (后端 DB)
docker run -d -p 9200:9200 ^
-e "discovery.type=single-node" ^
-e "plugins.security.disabled=true" ^
-e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=YourPassword@123" ^
-e "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" ^
opensearchproject/opensearch:2
# OpenSearch Dashboards (可选 UI)
docker run -d -p 5601:5601 ^
-e "OPENSEARCH_HOSTS=http://host.docker.internal:9200" ^
-e "DISABLE_SECURITY_DASHBOARDS_PLUGIN=true" ^
opensearchproject/opensearch-dashboards:2
```
验证 OpenSearch 是否正在运行：打开 `http://localhost:9200`
### 3. Python 环境设置
```
python -m venv venv
venv\Scripts\activate # Windows
source venv/bin/activate # Linux/Mac
pip install -r requirements.txt
```
### 4. 配置环境变量
在项目根目录创建一个 `.env` 文件：
```
OPENAI_API_KEY=sk-your-openai-key
ABUSEIPDB_API_KEY=your-abuseipdb-key
OTX_API_KEY=your-otx-key
VIRUSTOTAL_API_KEY=your-virustotal-key
```
### 5. 初始化 OpenSearch 索引
```
python -m threat_intel.db.indices
```
### 6. 加载 Maltrail 威胁数据库 (一次性)
```
# 克隆 Maltrail repo 并索引约 20 万个已知恶意 IP
python -m threat_intel.init.load_maltrail
```
### 7. 训练 ML 模型
```
# 首先生成大约 30–60 分钟的 logs，然后：
python -m scripts.train_model
```
训练后的模型将保存到 `models/isolation_forest.pkl`。
### 8. 前端 (Spring Boot)
创建 MySQL 数据库：
```
CREATE DATABASE soc_frontend;
```
配置 `soc-frontend/src/main/resources/application.properties`：
```
spring.datasource.url=jdbc:mysql://localhost:3306/soc_frontend
spring.datasource.username=root
spring.datasource.password=your-mysql-password
spring.jpa.hibernate.ddl-auto=update
server.port=9202
```
```
cd soc-frontend
mvn spring-boot:run
```
## 🚀 运行系统
打开三个终端并按顺序运行：
```
# 终端 1 — 模拟网络流量（攻击 + 正常）
python -m generator.log_generator
# 终端 2 — AI processing pipeline
python app/main.py
# 终端 3 — Web dashboard
cd soc-frontend && mvn spring-boot:run
```
| 服务 | URL | 描述 |
|---|---|---|
| 前端仪表板 | `http://localhost:9202` | 主 SOC 界面 |
| Flask 后端 API | `http://localhost:9201` | REST API |
| OpenSearch | `http://localhost:9200` | 数据库 |
| Dashboards | `http://localhost:5601` | 数据可视化 |
**默认管理员登录：** `admin` / `admin@123`
## 🔌 API 参考
### 检测与告警
| 方法 | 端点 | 描述 |
|---|---|---|
| `GET` | `/dashboard` | KPI：总数、可疑、正常、TI 恶意数量 |
| `GET` | `/alerts` | 所有已处理的告警 |
| `GET` | `/alerts?filter=suspicious` | 仅限可疑告警 |
| `GET` | `/alerts?hours=1` | 过去 N 小时内的告警 |
| `GET` | `/alerts/
     
**Sushobhit Chattaraj**
*毕业设计项目 — 计算机科学工程*
[](https://www.linkedin.com/in/sushobhit-chattaraj-410b2a253/)
[](https://github.com/csushobhit)
*设计为一个实用、可扩展且可解释的 AI-SOC 系统*
**⭐ 如果您觉得有用，请给本仓库加星！**
**⭐ 如果您觉得有用，请给本仓库加星！**
标签：AI安全, Apex, Chat Copilot, Docker, Flask, IP 地址批量处理, LangChain, NETRA-AI, Python, Spring Boot, TCP/IP协议栈, 人工智能, 威胁情报, 威胁识别架构, 安全决策, 安全系统, 安全运营中心, 安全防御评估, 开发者工具, 异常检测, 插件系统, 无后门, 智能安全分析, 机器学习, 混合架构, 用户模式Hook绕过, 网络安全, 网络安全平台, 网络日志分析, 网络映射, 网络评估, 请求拦截, 轻量级, 逆向工具, 隐私保护