ashpb07/LA-IDRS
GitHub: ashpb07/LA-IDRS
一款面向小规模网络的轻量级自治入侵检测与响应系统，结合实时流量监控、蜜罐诱骗与自动化封锁，提供可解释的威胁防御能力。
Stars: 1 | Forks: 2
# NetSentinel — LA-IDRS
**轻量级自治入侵检测与响应系统**
一款专为小规模环境设计的即插即用、具备自我防御能力的网络入侵检测系统。它在数据包级别监控流量，结合基于规则和行为的分析来检测入侵，并在解释其做出的每一个决策的同时自主应对威胁。
## 适用场景
- 小型企业
- 高校实验室与研究环境
- 家庭与个人网络
## 功能特性
| 特性 | 描述 |
|---|---|
| 实时数据包捕获 | C + libpcap，极低的数据包处理开销 |
| 特征检测 | 端口扫描、SYN flood、暴力破解（基于 JSON 的规则） |
| 行为检测 | EMA 偏差评分、端口多样性异常、协议不匹配 |
| 自适应基线 | 24小时被动观察阶段，支持按网络设定阈值 |
| 风险评分 | 加权累计评分，包含三级响应机制 |
| 微型蜜罐诱捕 | 动态伪造监听器——任何接触均触发即时拦截 |
| 因果攻击图 | 以 JSON 格式存储的每个攻击者事件链，并在仪表板中渲染 |
| XAI 封锁报告 | 为每次自动拦截操作提供结构化解释 |
| 自动解封 | 基于 TTL 的定时 IP 释放（默认为 1 小时） |
| P2P 威胁情报 | 向对等节点匿名广播 Gossip（默认关闭，需手动开启） |
| REST API | 基于 FastAPI，提供实时引擎状态 |
| 仪表板 | 单页 HTML/JS，每 5 秒自动刷新 |
## 风险评分表
| 评分 | 操作 |
|---|---|
| 0 - 30 | 仅记录日志 |
| 31 - 70 | 通过 API 和仪表板发出告警 |
| 71 - 100 | 通过 iptables 自动拦截 |
| 蜜罐接触 | 无论评分多少，立即拦截 |
## 架构
```
NIC
|
v
Packet Engine (C / libpcap)
| raw packet_meta_t structs over UNIX socket
v
Detection Engine (Python)
|-- BaselineLearner 24-hour passive observation phase
|-- EMATracker Per-IP exponential moving average
|-- SignatureEngine JSON rule evaluation
|-- BehaviorEngine Anomaly scoring against baseline
|-- RiskScorer Cumulative weighted score per IP
|
v
DecisionEngine
|-- score 31-70 --> Alert via API
|-- scan detected --> HoneypotManager (spawn fake listeners)
| |
| +-- contact --> instant block
|-- score 71+ --> IPBlocker (iptables)
|-- AttackGraphBuilder.finalize()
|-- AttackGraphStore.save()
|-- XAIReportGenerator.generate()
|-- GossipNode.broadcast() [if P2P enabled]
|
v
FastAPI --> Dashboard
--> P2P Peer Nodes (opt-in)
```
## 技术栈
| 层级 | 技术 |
|---|---|
| 数据包捕获 | C, libpcap |
| 检测引擎 | Python |
| 基线引擎 | Python, numpy |
| 攻击图引擎 | Python, networkx |
| 诱骗层 | Python, socket |
| XAI 报告生成器 | Python |
| 响应引擎 | Python, Bash |
| 防火墙控制 | iptables |
| API | FastAPI, uvicorn |
| 仪表板 | HTML, CSS, JavaScript |
| P2P 威胁情报 | Python, asyncio |
| 操作系统 | Linux |
## 快速开始
环境要求：Linux、Python 3.11+、GCC、libpcap-dev、iptables、root 权限。
```
git clone https://github.com/your-username/netsentinel-laidrs.git
cd netsentinel-laidrs
chmod +x scripts/setup.sh
sudo ./scripts/setup.sh
sudo ./scripts/run.sh
```
首次运行时，系统将进入 24 小时的基线学习阶段。在此阶段不会执行任何拦截操作。如果仅为了测试想跳过此阶段，请在 `.env` 中设置 `NS_SKIP_BASELINE=true`。
## 配置说明
将 `.env.example` 复制为 `.env`，并在运行前进行编辑：
```
cp .env.example .env
```
| 变量 | 默认值 | 描述 |
|---|---|---|
| `NS_IFACE` | `eth0` | 监控的网络接口 |
| `NS_BASELINE_SEC` | `86400` | 基线学习时长（以秒为单位） |
| `NS_SKIP_BASELINE` | `false` | 跳过基线阶段（仅供测试） |
| `NS_API_HOST` | `0.0.0.0` | API 绑定地址 |
| `NS_API_PORT` | `8000` | API 端口 |
| `NS_LOG_LEVEL` | `INFO` | DEBUG / INFO / WARNING / ERROR |
| `NS_BAN_TTL_SEC` | `3600` | 被拦截 IP 自动解封前的秒数 |
| `NS_HP_PORTS` | `5` | 每次扫描事件开启的蜜罐端口数 |
| `NS_P2P` | `false` | 启用 P2P 威胁情报共享 |
| `NS_P2P_PORT` | `9999` | Gossip 监听端口 |
| `NS_P2P_PEERS` | _(空)_ | 对等节点 IP 的逗号分隔列表 |
## API 端点
基础 URL：`http://:8000/api/v1`
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | `/status` | 系统状态、基线进度、拦截计数 |
| GET | `/alerts` | 所有被追踪 IP 的风险评分与事件 |
| GET | `/alerts/{ip}` | 单个 IP 的完整告警详情 |
| GET | `/blocks` | 当前被拦截的 IP |
| DELETE | `/blocks/{ip}` | 手动解封某个 IP |
| GET | `/graphs` | 所有已记录的攻击图 |
| GET | `/graphs/{id}` | 根据 ID 获取单个攻击图 |
| GET | `/honeypots` | 蜜罐接触次数 |
| GET | `/honeypots/contacts` | 近期的蜜罐接触记录 |
| GET | `/reports` | 所有 XAI 拦截报告 |
| GET | `/reports/{ip}` | 某个 IP 最近一次的拦截报告 |
交互式 API 文档可在 `http://:8000/docs` 查看。
## 仪表板
启动系统后，在浏览器中打开 `http://localhost:8000`。
仪表板每 5 秒自动刷新一次，并显示以下内容：
- 系统状态与基线学习进度
- 包含各 IP 风险评分的实时告警表
- 带有手动解封选项的被拦截 IP 列表
- 展示每个攻击者事件因果链的攻击图时间轴
- 包含各项原因细分的 XAI 拦截报告
## 示例：nmap 扫描响应
攻击者执行：
```
nmap -sS
```
NetSentinel 响应序列：
1. 数据包引擎检测到跨多个端口的 SYN 数据包
2. 特征引擎触发 PORT_SCAN_001 规则——评分 +35
3. 行为引擎检测到偏离基线的速率异常——评分 +20
4. 决策引擎针对源 IP 触发蜜罐生成
5. 攻击者连接到蜜罐端口——评分设为 100，瞬间拦截
6. iptables 规则被添加到 NETSENTINEL_BLOCK 链中
7. 攻击图定型：`[TCP 端口扫描] --> [数据包速率异常] --> [蜜罐接触] --> [拦截]`
8. 生成 XAI 报告并推送到 API
9. 仪表板显示带有因果上下文的完整告警
10. 将匿名特征广播给对等节点（如果启用了 P2P）
## XAI 拦截报告格式
```
{
"ip": "192.168.1.45",
"blocked_at": "2025-06-01T14:32:10Z",
"risk_score": 87,
"reasons": [
"TCP Port Scan: 24 unique ports in 5 seconds",
"Packet Rate Anomaly: 4.2 standard deviations above baseline",
"Honeypot Contact: connected to port 31337"
],
"honeypot_contacts": 1,
"attack_graph_id": "graph_192_168_1_45_1748784730"
}
```
## Docker
```
cd docker
docker-compose up --build
```
该容器使用 `network_mode: host`，并且需要 `NET_ADMIN` 和 `NET_RAW` 权限才能进行数据包捕获和访问 iptables。
## 测试
```
source .venv/bin/activate
pytest tests/ -v
```
测试覆盖率包括：检测引擎、EMA 基线、风险评分、攻击图构建器、XAI 报告生成器、P2P 数据清洗器和诱骗层。
## 项目结构
```
netsentinel-laidrs/
├── packet_engine/ C layer — libpcap packet capture
│ ├── src/ capture.c, parser.c, emitter.c, main.c
│ ├── include/ capture.h, parser.h, emitter.h
│ └── Makefile
├── detection_engine/ Core detection pipeline
│ ├── core/ detector, signature, behavior, scorer, decision
│ ├── baseline/ learner, ema, profile
│ ├── rules/ port_scan.json, syn_flood.json, brute_force.json
│ ├── state/ ip_state, cache
│ └── utils/ logger, parser
├── attack_graph/ Causal event graph builder and store
├── deception/ Micro-honeypot spawner
├── xai/ Explainable block report generator
├── response_engine/ iptables blocker, unblocker, scheduler
├── p2p/ Gossip-based threat intelligence sharing
├── api/ FastAPI routes, services, schemas
├── dashboard/ Static HTML/CSS/JS dashboard
├── comms/ UNIX socket server and IPC protocol spec
├── orchestrator/ Startup runner, process supervisor, config loader
├── tests/ pytest test suite
├── docs/ Architecture notes
├── scripts/ setup.sh, run.sh, cleanup.sh
├── docker/ Dockerfile, docker-compose.yml
├── requirements.txt
├── .env.example
└── main.py
```
## 清理
```
sudo ./scripts/cleanup.sh # flush iptables rules, remove socket
sudo ./scripts/cleanup.sh --purge # also delete all logs and database files
```
## 路线图
| 版本 | 特性 | 状态 |
|---|---|---|
| v1.0 | 数据包捕获、特征检测、iptables 拦截 | 完成 |
| v1.1 | 自适应基线引擎 | 已规划 |
| v1.2 | 微型蜜罐诱骗层 | 已规划 |
| v1.3 | 因果攻击图引擎 | 已规划 |
| v1.4 | XAI 拦截报告 | 已规划 |
| v2.0 | 联邦 P2P 威胁情报 | 研究中 |
| v2.1 | SDN 集成 | 研究中 |
| v2.2 | 分布式检测节点 | 研究中 |
## 免责声明
本项目仅用于教育目的和小规模部署。它不能替代企业级的 IDS 解决方案。诱骗层和自动拦截功能只能部署在您自己拥有，或获得明确书面授权保护的网络上。在第三方网络上未经授权使用可能会违反相关法律法规。
## 许可证
MIT License
## 作者
Anish G Prabhu — [github.com/ashpb07](https://github.com/ashpb07)
Hithansh Arekere — [github.com/hithansharekere-debug](https://github.com/hithansharekere-debug)
标签：AV绕过, C, FastAPI, Python, 入侵检测与防御系统, 威胁情报, 开发者工具, 插件系统, 无后门, 网络流量分析, 网络测绘, 蜜罐技术, 计算机取证, 请求拦截, 逆向工具, 配置错误, 防御绕过