Sarthak-Purohit/NetAgent
GitHub: Sarthak-Purohit/NetAgent
NetAgent 是一个将传统网络安全工具与本地大语言模型结合的 AI 驱动安全仪表板，提供主动漏洞扫描、被动流量分析和自动化威胁解释等一体化安全运维能力。
Stars: 0 | Forks: 0
# Project NetAgent
Project NetAgent 是一个由 AI 驱动的网络安全仪表板（功能上相当于一个“盒子里的 SOC 分析师”），它支持使用本地、物理隔离的大语言模型（LLM）进行主动漏洞扫描、被动网络流量分析、实时数据包捕获以及自动化威胁解释。
## 1. 项目概述
Project NetAgent 将多个模块集成到一个统一的安全仪表板中：
1. **主动扫描模块**：使用基于 socket 的扫描来发现目标主机/网络上的开放端口、服务、banner 和漏洞。
2. **被动分析模块**：使用 Scapy 嗅探实时数据包或解析上传的 PCAP/PCAPNG 文件，标记诸如端口扫描、DDoS 和基于特征签名的威胁等异常情况。
3. **AI 威胁解释器**：与本地、物理隔离的 Ollama 实例通信，以分析扫描或警报，提供详细的解释、严重性评估和修复步骤。
4. **AI 安全 Copilot 聊天机器人**：一个交互式的多轮对话界面，可帮助安全管理员查询主机安全状况、排查漏洞并规划缓解措施。
5. **半自主 Agent 引擎**：一个多步骤威胁调查器，它将扫描器结果和基于 AI 的威胁分析串联起来，以确定是否需要进行深度扫描，提出精确的主机级修复命令（iptables 规则），并在执行前等待人类操作员的批准。
6. **React 前端（Vite）**：一个交互式 Web 仪表板，显示实时流量图表、活动警报源、主动扫描器控制器、对话式聊天机器人面板以及半自主 Agent 界面。
## 2. 前置条件
要构建并运行 NetAgent，请确保您的主机系统已安装以下组件：
- **Docker**（v20.10.0 或更高版本）
- **Docker Compose**（v2.0.0 或更高版本）
- **Ollama**（用于实现 AI 威胁解释器功能）
- **Linux 内核**：需支持 raw socket 和网络能力（容器化数据包捕获需要 `NET_ADMIN` 和 `NET_RAW`）。
## 3. 安装与设置
您可以使用以下命令序列启动整个应用程序套件：
1. **在您的主机上拉取所需的 AI 模型：**
ollama pull llama2
2. **构建并启动容器化应用程序：**
docker compose up --build -d
3. **验证服务是否正在运行：**
docker compose ps
4. **访问应用程序：**
- 打开您的 Web 浏览器并导航至 `http://localhost`（Nginx 前端）
- API 文档和后端 endpoint 可在 `http://localhost:8000` 获取
## 4. 配置指南
### Ollama 模型设置
AI 威胁解释器通过 REST API 与 Ollama 进行通信。
- 在 `docker-compose.yml` 中，后端指定了 `OLLAMA_BASE_URL=http://host.docker.internal:11434` 以便与主机的 Ollama 实例进行通信。
- 您可以通过编辑 `docker-compose.yml` 中的环境变量来配置后端行为：
- `OLLAMA_BASE_URL`：Ollama 服务的 Base URL（默认为主机网关）。
- `OLLAMA_MODEL`：要作为目标的 LLM（默认为 `llama2`。您可以使用 `llama3`、`mistral` 或任何其他通过 `ollama pull` 拉取的模型）。
- `OLLAMA_TIMEOUT`：网络请求超时时间（以秒为单位，默认：`10.0`）。
### 网络权限
被动实时数据包嗅探需要访问底层 socket API。
- `backend` 容器配置了：
cap_add:
- NET_ADMIN
- NET_RAW
- **NET_RAW** 允许 Scapy 打开 raw socket 进行数据包嗅探。
- **NET_ADMIN** 允许容器配置网络接口和路由表策略。
- 确保您的主机内核和容器运行时没有阻止这些能力（在 Linux 上默认启用）。
## 5. 使用指南
### 主动扫描
1. 从侧边栏导航至 **Scanner** 页面。
2. 输入目标 IP 地址、子网范围（例如 `192.168.1.0/24`）或域名。
3. 选择扫描配置：
- **Quick Scan**：扫描标准/常用端口。
- **Full Scan**：扫描更广泛的端口范围。
- **Targeted Scan**：扫描专门配置的端口。
4. 点击 **Start Scan**。扫描将作为后台任务运行。结果将显示在扫描历史列表中，包含开放端口、服务和潜在漏洞。
### PCAP 文件上传
1. 导航至 **Traffic** 页面。
2. 拖放或点击选择一个 `.pcap` 或 `.pcapng` 文件。
3. NetAgent 将解析该文件，执行启发式威胁规则（DDoS 和端口扫描检测），在 SQLite 数据库中记录警报，并刷新 UI 警报源。
### 实时捕获
1. 转到 **Traffic** 页面，找到 **Live Capture** 卡片。
2. 选择目标接口（`eth0`、`wlan0` 或 `lo`）。
3. 点击 **Start Capture**。NetAgent 将嗅探实时数据包，并在出现异常流量模式时引发实时警报。
4. 点击 **Stop Capture** 以终止会话。
### AI 解释器
1. 点击源或扫描历史记录中的任何活动警报。
2. 点击 **Explain Threat**。
3. NetAgent 将查询 Ollama 以生成 JSON 响应，其中包含清晰的威胁解释、自定义严重性评级和修复清单。
4. *Air-Gap 回退*：如果 Ollama 处于离线或响应缓慢状态，系统会自动回退到基于规则的离线模拟解释器，从而确保操作不中断。
### AI 安全 Copilot 聊天
1. 转到主导航中的 **🤖 AI Copilot** 标签页。
2. 输入任何网络安全问题、端口查询或缓解故障排除请求（例如，*“我该如何保护 SSH 端口 22？”*）。
3. 聊天机器人会保留对话历史记录，并查询本地 Ollama 实例以获取对话式的分步指导。
4. *回退模式*：如果 Ollama 处于离线状态，聊天机器人将进入 *离线回退模式*，为关键服务（SSH、数据库、主动扫描器）提供交互式的预配置建议。
### 半自主 Agent
1. 转到 **🤖 Autonomous Agent** 标签页。
2. 输入目标网络 IP/子网（例如 `192.168.1.15`）并选择扫描配置。
3. 点击 **Start Investigation** 以启动自主威胁狩猎循环：
* **阶段 1**：启动会话并记录目标。
* **阶段 2**：触发主动端口扫描。
* **阶段 3**：使用本地 LLM 分析扫描结果。
* **阶段 4**：如果严重程度为严重/高，则升级为深度扫描；否则继续执行。
* **阶段 5**：生成可执行的修复命令（例如 `iptables` 拒绝规则）并进入 `AWAITING APPROVAL` 状态。
4. 检查建议的操作卡片。点击 **Approve & Execute** 以应用规则（模拟的 shell 输出），或点击 **Reject** 以安全地关闭会话。
## 6. API 文档
### 主动扫描
#### `POST /api/scans`
- **目的**：在后台触发新的网络扫描。
- **请求体**：
{
"target": "192.168.1.1",
"profile": "quick"
}
- **响应** (201 Created)：
{
"id": 1,
"target": "192.168.1.1",
"profile": "quick",
"status": "running",
"created_at": "2026-06-10T08:37:00Z"
}
#### `GET /api/scans`
- **目的**：获取扫描历史摘要的时间排序列表。
- **响应** (200 OK)：扫描对象数组。
#### `GET /api/scans/{id}`
- **目的**：获取特定扫描的详细信息，包括开放端口、banner 以及发现的漏洞列表。
- **响应** (200 OK)：详细的扫描历史和结果。
### 被动警报与实时捕获
#### `GET /api/alerts`
- **目的**：获取存储在数据库中的安全警报。
- **查询参数**：
- `limit`：（可选）要获取的最大警报数。
- `severity`：（可选）按严重性筛选（`low`、`medium`、`high`、`critical`）。
- **响应** (200 OK)：生成的警报列表。
#### `POST /api/alerts/capture`
- **目的**：控制实时数据包捕获嗅探线程。
- **请求体**：
{
"action": "start",
"interface": "eth0"
}
- **响应** (200 OK)：
{
"status": "capturing",
"interface": "eth0"
}
#### `POST /api/alerts/analyze-pcap`
- **目的**：上传并解析 PCAP/PCAPNG 捕获文件以查找异常情况。
- **请求头**：`Content-Type: multipart/form-data`
- **请求体**：在表单键 `file` 下上传的二进制文件。
- **响应** (200 OK)：
{
"status": "success",
"filename": "traffic.pcap",
"alerts_generated": 2,
"alerts": [...]
}
### AI 威胁解释器
#### `POST /api/explain`
- **目的**：请求 AI 生成的描述、严重性分析以及修复步骤。
- **请求体**：
{
"source_type": "alert",
"source_id": 1
}
- **响应** (200 OK)：
{
"explanation": "检测到 SYN 扫描攻击。源主机发起了多个快速的半开 TCP 请求...",
"severity": "medium",
"remediation": "配置防火墙规则以对传入的 TCP SYN 数据包进行速率限制，拦截源 IP 地址..."
}
#### `POST /api/chat`
- **目的**：与 AI Copilot 进行对话式聊天界面交互。
- **请求体**：
{
"message": "解释端口 22 的安全性",
"history": [
{"role": "user", "content": "你好"},
{"role": "assistant", "content": "你好！今天我能为您提供什么网络安全方面的帮助？"}
]
}
- **响应** (200 OK)：
{
"response": "端口 22 托管着 SSH 服务，该服务用于安全的远程管理..."
}
### 半自主 Agent 引擎
#### `POST /api/agent/sessions`
- **目的**：在目标上启动一个新的半自主调查会话。
- **请求体**：
{
"target": "192.168.1.15",
"profile": "quick"
}
- **响应** (201 Created)：
{
"id": 1,
"target": "192.168.1.15",
"profile": "quick",
"status": "running",
"created_at": "2026-06-16T04:20:00Z",
"steps": []
}
#### `GET /api/agent/sessions`
- **目的**：列出所有调查会话及其状态。
- **响应** (200 OK)：包含活动步骤的会话对象数组。
#### `POST /api/agent/sessions/{session_id}/approve/{step_id}`
- **目的**：批准并执行建议的修复操作。
- **响应** (200 OK)：
{
"success": true,
"message": "操作已批准。正在执行修复..."
}
### 自主 Agent 流程图
```
graph TD
Start([Start Session]) --> Scan[Active Port Scan]
Scan --> AI[AI Threat Analysis]
AI --> Assess{AI Severity Assessment}
Assess -->|Critical / High| DeepScan[Deep Scan + Re-Analyze]
Assess -->|Medium / Low| Propose[Propose Remediation]
DeepScan --> Propose
Propose --> Check{Actionable?}
Check -->|No| Complete([Complete Session])
Check -->|Yes| Await[Pause & Await Approval]
Await -->|Approved| Execute[Execute iptables Remediation]
Await -->|Rejected| Close[Close Session without Action]
Execute --> Complete
Close --> Complete
```
标签：AI安全助手, AI风险缓解, C2, React, Scapy, Syscalls, 安全运营中心(SOC), 密码管理, 插件系统, 本地大语言模型, 版权保护, 网络流量分析, 请求拦截, 逆向工具, 防御绕过