# HFish-SecOps-Brain

**Repository Path**: nwb/hfish-sec-ops-brain

## Basic Information

- **Project Name**: HFish-SecOps-Brain
- **Description**: 本项目旨在基于 HFish 蜜罐平台打造一个完整的企业级 SecOps Brain（安全运营大脑）。项目的最终目标是涵盖从诱捕感知、数据汇聚、智能分析（AI/大模型介入）到自动化响应（SOAR）的闭环安全体系。

- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-06-09
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HFish SecOps Brain

HFish 攻击数据采集、富化、AI研判、SOAR 多剧本执行和 Web 可视化平台。

## 主链路

```
hfish_puller.py  →  hfish_attack_enricher.py  →  hfish_script_decision.py  →  hfish_script_execution.py
       ↓                        ↓                            ↓                            ↓
  Raw 文档(ES)          Enriched 文档(ES)            决策 JSON(本地)              执行结果(ES + 本地)
```

SOAR 执行支持双模式：
- **SSH 模式**（默认）：`soar_execution_runtime.py` 通过 SSH 连接目标节点执行 shell 命令
- **Agent 模式**：`soar_agent_server.py` 运行在目标节点，接收 `POST /execute` 执行 workflow

```mermaid
graph LR
    Execution[SOAR 执行引擎] -->|SSH| Target[目标节点]
    Execution -->|HTTP POST /execute| Agent[soar_agent_server]
    Agent -->|GET /health| HealthCheck
    Agent -->|POST /verify| Verify
    Agent -->|POST /cleanup| Cleanup
```

- `run_pipeline.py`：一键串联 `pull → enrich → decide → execute`
- `hfish_web.py`：一键启动前后端 Web 平台

## 快速开始

```powershell
# 安装依赖
pip install -r requirements.txt

# 采集攻击数据
python hfish_puller.py

# 富化原始攻击文档
python hfish_attack_enricher.py --days 7

# 生成 SOAR 决策
python hfish_script_decision.py

# 执行最新决策（SSH 模式 - 默认）
python hfish_script_execution.py

# 一键串联全链路
python run_pipeline.py

# 启动 Web 平台
python hfish_web.py
```

### Agent 模式部署

```powershell
# 1. 一键部署 agent 到目标节点（systemd + ufw + 健康检查）
python test_agent/deploy_soar_agent.py --host 192.168.75.136 --user root

# 2. config.json 中 target 设 executor_type: agent
# 3. 执行脚本不变，自动走 agent 路径
python hfish_script_execution.py
```

## 项目结构

```
HFish_SecOps/
├── hfish_puller.py               # 攻击数据采集 (HFish API → Raw ES)
├── hfish_attack_enricher.py      # 富化引擎 (Raw → Enriched ES)
├── hfish_script_decision.py      # SOAR 决策 (Enriched → 决策 JSON)
├── hfish_script_execution.py     # SOAR 执行 (决策 → 执行结果)
├── run_pipeline.py               # 全流程编排
├── hfish_web.py                  # Web 平台一键启动
├── soar_execution_runtime.py     # 执行核心运行时
├── soar_execution_store.py       # 执行结果 ES 持久化
├── config.json / config.example.json  # 配置文件
├── requirements.txt              # Python 依赖
│
├── api-server/                   # FastAPI 后端
│   ├── main.py                   # 启动入口
│   ├── routers/                  # API 路由 (attacks/attackers/soar/settings/dashboard)
│   └── services/                 # ES / MySQL 数据服务
│
├── web-platform/                 # React 前端
│   └── src/
│       ├── pages/                # 页面 (Dashboard/Attackers/Attacks/SoarHistory/SoarPending/Settings)
│       ├── components/           # 组件 (SoarExecutionDetailView / HighThreatNotifier)
│       ├── services/api.ts       # API 封装
│       └── types/index.ts        # TypeScript 类型定义
│
├── soar_agent_server.py          # 持久化 Agent HTTP 服务（/health /execute /verify /cleanup）
│
├── soar_core/                    # SOAR 工作流引擎
│   ├── engine.py                 # 零外部依赖工作流引擎
│   ├── apps/                     # 插件 (es/linux/http/helloworld)
│   │   └── linux/main/run.py     # 双执行路径: SSH (paramiko) | Agent (HTTP POST /execute)
│   ├── workflows/                # 剧本 JSON（6 个真实逻辑, 1 个测试 echo）
│   │   ├── attack_response.json            # iptables DROP 封禁IP + ES 历史查询
│   │   ├── kill_malicious_process.json     # ss -tnp 查进程 + kill
│   │   ├── disable_malicious_account.json  # last -i 查账户 + passwd -l 锁定
│   │   ├── high_threat_alert.json          # HTTP Webhook 推送告警
│   │   ├── dns_sinkhole.json               # dnsmasq 恶意域名 sinkhole 配置
│   │   ├── pcap_capture.json               # tcpdump 留存攻击流量证据
│   │   └── hello_world.json                # HelloWorld 引擎连通性测试(echo)
│   └── ai-agent/SKILL.md         # AI 剧本生成技能
│
├── test_agent/                   # 自动化测试
│   ├── run_tests.py              # 全自动测试编排: 攻击→管道→验证→清理→HTML报告
│   ├── deploy_soar_agent.py      # 一键 SSH 部署 soar_agent_server.py + systemd + ufw + 健康检查
│   ├── conf.yaml.example         # 测试配置模板
│   ├── AGENTS.md                 # Agent 测试执行指南
│   └── attack/                   # 10 个攻击脚本 (sqlmap/hydra/nmap/curl/dig)
│
├── ELK/                          # ELK 部署配置
│   ├── elasticsearch.yml         # ES 配置
│   ├── logstash.conf             # Logstash pipeline (Kafka → ES)
│   └── ...
│
├── docs/                         # 文档
│   ├── 数据结构解释.md            # 各阶段 JSON 数据结构
│   ├── 系统架构设计.md            # 架构图 + AI 三层模型
│   ├── 问题与未来方向.md          # 问题/扩展/清理分类
│   └── ...
│
├── soar_data/                    # 决策/执行 JSON 输出目录
└── hfish_data/                   # 本地文件输出目录
```

## 配置字段说明

### `hfish` — HFish 连接

| 字段 | 类型 | 说明 |
|------|------|------|
| `base_url` | string | HFish 管理平台地址 |
| `api_key` | string | HFish API 密钥 |
| `timeout` | int | API 请求超时秒数 |

### `pipeline` — 数据管道

| 字段 | 类型 | 说明 |
|------|------|------|
| `use_kafka_pipeline` | bool | 是否走 Kafka 缓冲（`true`=Kafka, `false`=直连 ES） |
| `enabled_outputs` | string[] | 启用的输出通道，可选：`local_file` / `elasticsearch` / `mysql` / `sqlite` |
| `mysql.host/port/user/password/database` | — | MySQL 连接参数 |
| `kafka.bootstrap_servers` | string[] | Kafka broker 地址列表 |
| `kafka.topic_prefix` | string | Kafka topic 前缀 |
| `elasticsearch.hosts` | string[] | ES 节点地址列表 |

### `soar` — SOAR 引擎

| 字段 | 类型 | 默认值 | 说明 |
|------|------|------|------|
| `silent_logs` | bool | `false` | `true` 时静默执行引擎日志（不打印节点耗时等） |
| `process_batch` | int | `50` | 决策单批次最大处理条数 |
| `default_pretty_json` | bool | `true` | 决策/执行输出 JSON 是否格式化缩进 |
| `auto_input_latest_decision` | bool | `true` | 执行脚本是否自动读取最新的决策 JSON 文件 |
| `required_field` | string | `"attack_ip"` | 决策必选字段，缺少该字段的文档跳过 |
| `enable_ai_decision` | bool | `false` | 是否启用 AI 决策（`false` 时仅用规则） |
| `ai_decision_timeout` | int | `60` | 单次 AI 决策请求超时秒数 |
| `ai_decision_concurrency` | int | `0` | AI 决策并发上限，0=自适应（`min(ceil(N/10), 10)`），手动值直接取用 |
| `ai_min_confidence` | float | `0.7` | AI 决策最低置信度，低于此值走 `ai_fallback_mode` |
| `ai_fallback_mode` | string | `"rule"` | AI 决策失败/低置信度时的回退策略：`"rule"` 或 `"manual"` |
| `ai_history_size` | int | `100` | AI 决策时提供的 ES 历史文档条数上限 |
| `ai_history_window_minutes` | int | `1440` | AI 决策时查询 ES 历史的时间窗（分钟） |
| `ai_recent_window_minutes` | int | `30` | AI 决策时"近期"定义（分钟），用于统计近期攻击频率 |
| `workflow_priority` | string[] | `[]` | workflow key 优先级列表，影响候选集排序 |
| `alert_webhook_url` | string | — | 高危攻击告警通知剧本的 Webhook 推送地址 |
| `targets` | object[] | — | 执行目标列表，每个 target 指定主机和该主机启用的 workflow |

> **自适应并发说明**：当 `ai_decision_concurrency` / `enrich_concurrency` 设为 `0` 时，系统按 `min(ceil(处理条数/10), 10)` 自动计算并发数。
> **剧本并行执行**：`hfish_script_execution.py` 按 `min(cpu_count()//2, 5)` 并行执行多个剧本，无需配置项。

`targets` 结构：

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `name` | string | — | 目标节点名称 |
| `host` | string | — | SSH 目标主机 IP |
| `port` | int | `22` | SSH 端口 |
| `user` | string | — | SSH 用户名 |
| `password` | string | — | SSH 密码 |
| `executor_type` | string | `"ssh"` | 执行模式：`"ssh"` 或 `"agent"` |
| `agent_url` | string | `""` | Agent 模式时 agent 地址（如 `http://192.168.75.136:18080`） |
| `token` | string | `""` | Agent Bearer token（可选） |
| `workflows` | string[] | `[]` | 该 target 启用的 workflow 名称列表 |

**SSH 模式示例：**
```json
{
  "name": "client002",
  "host": "192.168.75.136",
  "port": 22,
  "user": "ssh-user",
  "password": "ssh-password",
  "executor_type": "ssh",
  "workflows": ["封禁IP+历史查询"]
}
```

**Agent 模式示例：**
```json
{
  "name": "client002",
  "host": "192.168.75.136",
  "executor_type": "agent",
  "agent_url": "http://192.168.75.136:18080",
  "token": "",
  "workflows": ["封禁IP+历史查询"]
}
```

### `ai` — AI 服务

| 字段 | 类型 | 默认值 | 说明 |
|------|------|------|------|
| `provider` | string | `"deepseek"` | AI 服务商标识 |
| `base_url` | string | — | API 基础地址 |
| `api_key` | string | — | API 密钥 |
| `model` | string | `"deepseek-chat"` | 模型名称 |
| `timeout` | int | `60` | AI 请求超时秒数（富化和 AI 决策共用） |
| `enrich_concurrency` | int | `0` | 富化阶段并发上限，0=自适应（`min(ceil(N/10), 10)`），手动值直接取用 |
| `max_tokens` | int | `0` | AI 响应最大 token 数，0=不传该参数由模型自行决定 |

## SOAR 剧本

| 剧本 | 文件 | 执行方式 | 验证方法 | 清理方式 | 适用场景 |
|------|------|---------|---------|---------|----------|
| 封禁IP | `attack_response.json` | `iptables -A INPUT -s <ip> -j DROP` | `iptables -C INPUT -s <ip> -j DROP` | 删除 DROP 规则 | 高威胁持续攻击、爆破、漏洞利用 |
| 结束恶意进程 | `kill_malicious_process.json` | `ss -tnp` 查进程 → kill | `ss -tnp \| grep <ip>` 确认已清除 | 无（过程式清理） | 检测到入侵后清除恶意连接 |
| 禁用恶意账户 | `disable_malicious_account.json` | `last -i` 查账户 → `passwd -l` 锁定 | `passwd -S <acct> \| grep ^L` | `usermod -U` 解锁 | SSH暴力破解、异常登录 |
| 高危攻击告警 | `high_threat_alert.json` | HTTP Webhook POST 推送 | 接收端核验（`WEBHOOK_REMOTE_VERIFICATION_REQUIRED`） | 无（无副作用） | 需要立即通知的高危事件 |
| DNS黑洞 | `dns_sinkhole.json` | dnsmasq sinkhole 配置写入 | `grep <ip>.sinkhole /etc/dnsmasq.d/sinkhole.conf` | 删除对应行 + reload dnsmasq | 阻断C2通信、恶意软件回连 |
| 抓包取证 | `pcap_capture.json` | tcpdump 留存流量到 `/var/evidence/` | `find /var/evidence -name "<ip>_*.pcap"` | PCAP 文件保留（证据不删除） | 高威胁攻击留存证据和行为分析 |
| HelloWorld | `hello_world.json` | `echo` 测试 | `echo hello_world ok` | `echo cleanup ok` | 引擎连通性测试 |

> **证据保留策略**：PCAP 文件、告警日志等证据文件永久保留。iptables 规则、dnsmasq 配置、账户锁定等副作用在验证后通过对应清理命令清除。

## AI研判 + 人工研判

- **AI研判**：AI 分析富化后的攻击特征，自动从匹配的剧本候选集中选择应执行的剧本分支
- **人工研判**：当 AI 置信度不足时，自动转为 `pending_manual_review` 状态，前端"SOAR 待处理"页展示 AI 研判结果供安全分析师手动决策
- **研判流程**：Enrichment → Decision（AI研判选择剧本）→ 低置信度转人工 → 人工选择剧本 → Execution

## 数据流

| 阶段 | 输入 | 输出 |
|------|------|------|
| Pull | HFish API | `hfish-attack-raw-*`（ES） + `attacker_profiles`（MySQL） |
| Enrich | `hfish-attack-raw-*` | `hfish-attack-enriched-*`（ES） |
| Decide | `hfish-attack-enriched-*` | `soar_data/decision_*.json` + `soar_es_tracker`（MySQL 去重） |
| Execute | `soar_data/decision_*.json` | `soar_data/execution_*.json` + `hfish-soar-execution-*`（ES） |

完整 JSON 结构见 [数据结构解释](./docs/数据结构解释.md)。

## 硬编码字段

以下字段已硬编码在脚本中，不再通过 `config.json` 或 Web Settings 页面修改：

| 类别 | 硬编码值 |
|------|------|
| 索引 | `hfish-attack-raw-*` / `hfish-attack-enriched-*` / `hfish-soar-execution-*` |
| 输出 | 目录 `./soar_data`，前缀 `decision_` / `execution_`，时间格式 `YYYYMMDD_HHmmSS` |
| 富化阈值 | `long_token_threshold=120`, `max_url/body/auth_info/header_value_length`, `max_header_count=12` |
| 低价值过滤 | 固定的 `exact_paths` / `path_prefixes` / `suffixes` / `internal_source_ips` 集合 |
| 剧本并行 | `min(cpu_count()//2, 5)` — 不可配置，后端自动计算 |

> **自适应并发**：`ai_decision_concurrency` / `enrich_concurrency` 配置值 `0` 时触发，非硬编码。

## Web

- 前端：`web-platform`（React + TypeScript）
- 后端：`api-server`（FastAPI）
- 启动：`python hfish_web.py`
- 前端高危通知：`HighThreatNotifier` 组件每 30 秒轮询最近 5 分钟的高危攻击并推送浏览器通知

Settings 页面仅展示 `config.json` 中 `soar` 和 `ai` 段的可配置字段。

## 自动化测试

```powershell
# 1. 创建配置文件
cp test_agent/conf.yaml.example test_agent/conf.yaml
# 编辑 conf.yaml，填写 Kali 攻击机 IP、蜜罐目标、SOAR 节点信息

# 2. 运行全量测试（攻击 → 管道 → 验证 → 清理 → HTML 报告）
python test_agent/run_tests.py

# 3. 打开 HTML 报告
# test_agent/results/report_*.html
```

CLI 参数: `--scripts 01,03` 指定脚本, `--skip-attack` 跳过攻击, `--skip-pipeline` 跳过管道, `--pipeline-timeout 900` 加长超时。

测试模块特性：
- **双执行路径**：`conf.yaml` 中 `soar_nodes.executor_type` 设为 `ssh` 或 `agent`，自动匹配验证方式
- **Agent 验证**：通过 `GET /health` + `POST /verify` + `POST /cleanup` 接口完成节点验证与清理
- **SSH 验证**：直接 SSH 到目标节点执行自定义 `checks` 命令
- **fail2ban 管理**：自动添加/移除验证源 IP 到 fail2ban 白名单，避免误封
- **ES 等待循环**：管道跑完后轮询 ES 等待原始文档落地（Kafka 管道场景）
- **临时配置**：`build_test_config()` 自动创建 temp config（batch=1, concurrency=1），测试完后自动清理
- **HTML 报告**：深色主题，含攻击/管道/决策/执行/验证 5 个模块

详细步骤见 [总体测试流程](./docs/总体测试流程.md)。

## 文档

- [数据结构解释](./docs/数据结构解释.md) — 各阶段 JSON 数据格式
- [系统架构设计](./docs/系统架构设计.md) — 系统架构图 + AI 三层模型
- [问题与未来方向](./docs/问题与未来方向.md) — 问题/扩展/清理/安全漏洞分类
- [总体测试流程](./docs/总体测试流程.md) — 管线测试步骤
- [SOAR 修改说明](./docs/修改说明/soar修改说明.md) — 历次 SOAR 变更记录（已归档）