vietk5/NIRO_agent
GitHub: vietk5/NIRO_agent
基于 LLM 与 PI 框架的自动化网络安全事件响应编排系统，通过多阶段 Pipeline 实现告警分析、威胁侦察、MITRE 映射与响应处置。
Stars: 0 | Forks: 0
# NIRO-PI — 网络事件响应编排器
使用 LLM 的自动化网络安全事件分析与响应系统。
基于 **PI framework** 运行
## 快速开始
### 1. 安装
```
pip install -r requirements.txt
```
### 2. 配置 API key
在根目录创建 `.env` 文件（仓库中暂不提供 `.env.example`）。`get_llm_client()` 会根据存在的 key 自动选择 backend — 优先使用 Anthropic：
```
# 使用 Claude（如果同时有两个 key 则优先使用）
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-5 # optional, đây là default
# 或者使用 OpenAI-compatible（OpenAI, DeepSeek, ...）
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.deepseek.com # optional, default là api.openai.com/v1
OPENAI_MODEL=deepseek-chat # optional, default là gpt-4o
```
### 3. 添加数据到 data/input/
```
data/input/
├── alerts/ ← Đặt file JSON alert từ IDS/SIEM vào đây
├── logs/ ← Đặt auth.log, firewall.log, syslog.log vào đây
└── pcap/ ← Đặt file PCAP vào đây (optional)
```
### 4. 通过 PI skills 运行
在 `niro-pi/` 目录下打开 Claude Code，输入：
| 命令 | 功能 |
|------|-----------|
| `/run-pipeline` | 通过完整 pipeline 处理 `data/input/alerts/` 中的告警 |
| `/analyze-logs` | 分析来自 `data/input/logs/` 的日志，寻找攻击证据 |
| `/run-batch` | 批量处理所有告警 |
| `/triage-alert` | 快速对一个告警进行分类 |
## Pipeline 架构
```
Alert → Stage 0: Triage (serial, 20s timeout)
↓ (action != close_fp)
Stage 1: Scatter × 3 (parallel, 30s timeout mỗi task)
├── 1A Recon (AbuseIPDB + VirusTotal + port scan + whois — LLM tool-loop)
├── 1B Log Collection (data/input/logs/ → auth/fw/syslog, rule-based)
└── 1C PCAP Analysis (scapy / metadata fallback, rule-based)
↓
Stage 2: Scatter × 2 (parallel, 60s timeout mỗi task)
├── 2A ML Classifier (LLM phân loại + MITRE_KB containment playbook)
└── 2B MITRE Mapper (RandomForest/cosine similarity + IsolationForest anomaly check)
↓
Stage 2C: Orchestrator + Investigator Subagents (sequential, 120s timeout)
├── So sánh 2A vs 2B → AGREE (xác nhận) hay CONFLICT (cần giải quyết)
├── spawn_subagent() → bruteforce / ddos / portscan / general investigator
└── finalize_investigation() → verdict cuối cùng (ưu tiên cao nhất)
↓
Stage 3A: Response (conditional — human approval cho block_ip/isolate_host)
Stage 3B: Report (always runs → reports/ + results/ folder)
```
整个 pipeline 均在 **`pipeline.yaml`** 中声明，可以直接在此修改（开启/关闭特定 stage 或 agent，切换 parallel ↔ sequential 模式，设置每个 stage 的 timeout）。
## 环境变量
| 变量 | 默认值 (代码中) | 说明 |
|------|----------|---------|
| `ANTHROPIC_API_KEY` | — | 使用 Claude backend，如果存在则优先使用 |
| `ANTHROPIC_MODEL` | `claude-sonnet-4-5` | Claude 模型 |
| `OPENAI_API_KEY` | — | 如果没有 ANTHROPIC_API_KEY，则使用 OpenAI-compatible backend (OpenAI, DeepSeek, ...) |
| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | 修改为 `https://api.deepseek.com` 以使用 DeepSeek |
| `OPENAI_MODEL` | `gpt-4o` | 如果使用 DeepSeek，请修改为 `deepseek-chat` |
| `STAGE1_TIMEOUT_SEC` | `30` | Stage 1 的超时时间（秒） |
| `STAGE2_TIMEOUT_SEC` | `60` | Stage 2 的超时时间（秒） |
| `APPROVAL_TIMEOUT_SEC` | `120` | 人工审批超时时间 |
| `NIRO_AUTO_APPROVE` | `0` | 设为 `1` 以自动批准（实验室模式） |
## 人工审批
当响应代理需要封锁 IP 或隔离主机时：
1. 写入 `logs/pending_approval.json` — 包含需要批准的操作
2. 等待用户创建包含 `APPROVED` 或 `REJECTED` 内容的 `logs/approval_response.txt`
3. 超时 → 操作将被跳过
**实验室模式**（跳过审批）：`NIRO_AUTO_APPROVE=1 python3 scripts/full_pipeline.py ...`
## 直接运行（不通过 PI）
```
# 来自 file 的单个 alert
PYTHONIOENCODING=utf-8 python3 scripts/full_pipeline.py --alert data/input/alerts/bruteforce.json --save
# Auto approve + quiet
NIRO_AUTO_APPROVE=1 PYTHONIOENCODING=utf-8 python3 scripts/full_pipeline.py --alert data/input/alerts/bruteforce.json --save --quiet
# 在 approve 后 resume（仅重新运行 Stage 3A+3B，使用 state cache）
PYTHONIOENCODING=utf-8 python3 scripts/full_pipeline.py --alert data/input/alerts/bruteforce.json --save --resume
# Batch（多个 alerts 并行）
PYTHONIOENCODING=utf-8 python3 scripts/batch_parallel.py --dir data/input/alerts/ --max-concurrent 3
```
## 输出
- **报告**：`reports/{ip}_{timestamp}_incident.md` — Markdown IR 报告（使用 `--save` 时生成）
- **Pipeline 结果**：`results/{ip}_{timestamp}_pipeline.json` — 原始输出，可用作未来的训练数据
- **审计日志**：`logs/audit.jsonl` — 防篡改的操作执行链条
- **Pipeline 缓存**：`logs/pipeline_cache/{alert_id}.json` — Stage 3A 之前的状态，用于 `--resume`
- **审批**：`logs/pending_approval.json` — 待执行的操作（如果有）
## 重要文件
- `scripts/full_pipeline.py` — 入口点，使用 asyncio scatter/gather 汇总全部 6 个 stage
- `src/agents/ml_classifier.py` — Stage 2A：LLM 分类 + 查询 `MITRE_KB` 获取遏制步骤
- `src/agents/mitre_mapper.py` — Stage 2B：RandomForest/cosine similarity → MITRE ATT&CK + IsolationForest 异常检测
- `src/agents/orchestrator_agent.py` — Stage 2C：Orchestrator LLM 协调 Investigator 子代理
- `src/agents/investigators/` — 4 个 investigator 子代理 (bruteforce, ddos, portscan, general)
- `src/agents/response_agent.py` — Stage 3A：human-in-the-loop 审批
- `src/agents/log_collector.py` — Stage 1B：从 `data/input/logs/` 读取
- `scripts/train_sklearn.py` / `scripts/train_isolation.py` — 为 Stage 2B 训练模型（参见 `data/training/README.md`）
- `pipeline.yaml` — 开启/关闭 stage、agent，切换 parallel/sequential，设置 timeout
- `.pi/chains/niro_pipeline_chain.md` — PI chain 定义（完整描述了 6 个 stage）
- `.pi/skills/` — 4 个 PI skills：run-pipeline, analyze-logs, run-batch, triage-alert
## 目录结构
```
niro-pi/
├── .pi/
│ ├── agents/ ← PI agent docs (1 file mô tả mỗi agent)
│ ├── chains/ ← Pipeline chain config (niro_pipeline_chain.md)
│ ├── prompts/ ← LLM system prompts
│ └── skills/ ← PI skills (run-pipeline, analyze-logs, run-batch, triage-alert)
├── src/
│ ├── agents/ ← Python agent implementations (kể cả investigators/)
│ ├── tools/ ← Network + threat-intel + response tools
│ └── utils/ ← Logger, safety, agent_loop (LLM tool-call loop), pipeline_config
├── scripts/ ← full_pipeline.py, batch_parallel.py, các script train_*.py
├── data/
│ ├── input/ ← ĐẶT DỮ LIỆU THỰC TẾ VÀO ĐÂY (alerts/ logs/ pcap/)
│ └── training/ ← labeled.jsonl + sklearn_model.pkl + isolation_model.pkl
├── logs/ ← Runtime logs, pipeline_cache/, approval files
├── reports/ ← Generated IR reports (.md)
├── results/ ← Raw pipeline JSON (nguồn dữ liệu training)
├── pipeline.yaml ← Config bật/tắt stage + parallel/sequential
└── requirements.txt
```
标签：Petitpotam, Python, 安全运营, 库, 应急响应, 扫描框架, 无后门, 自动化编排, 计算机取证, 逆向工具