# HFish-SecOps-Brain

**Repository Path**: elfbobo_admin_admin/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**: 1
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HFish SecOps Brain

基于 HFish 蜜罐平台的企业级安全运营大脑，实现从威胁数据采集、清洗存储到自动化响应的完整闭环。

## 架构概览

```mermaid
graph TB
    subgraph 数据源
        HFish[HFish 蜜罐管理端]
    end

    subgraph 采集层
        Puller[hfish_puller<br/>数据采集器]
    end

    subgraph 传输与存储
        Kafka[(Kafka<br/>消息队列)]
        Logstash[Logstash<br/>日志清洗写入]
        ES[(Elasticsearch<br/>全量日志检索)]
        MySQL[(MySQL<br/>攻击者画像)]
        LocalFile[(本地 JSON<br/>调试输出)]
    end

    subgraph SOAR 自动化响应
        Bridge[hfish_soar_bridge<br/>ES 轮询桥接]
        Engine[soar_core<br/>工作流引擎]
        Linux[SSH iptables<br/>IP 封禁]
        ESQuery[ES 历史查询]
        HTTP[HTTP 请求]
    end

    subgraph Web 可视化
        API[FastAPI<br/>api-server]
        Frontend[React + Ant Design<br/>8 页面安全运营平台]
    end

    HFish -->|REST API| Puller
    Puller -->|attack_detail| Kafka
    Puller -->|profile| MySQL
    Puller -->|raw| LocalFile
    Kafka -->|消费| Logstash
    Logstash -->|写入| ES
    ES -->|轮询新攻击| Bridge
    Bridge -->|加载 workflow| Engine
    Bridge -->|更新处理状态| MySQL
    Engine --> Linux
    Engine --> ESQuery
    Engine --> HTTP
    Frontend -->|HTTP /api/*| API
    API -->|查询| ES
    API -->|查询| MySQL
    API -->|读取| HFish
```

## 项目背景

企业安全运营中，蜜罐系统产生的威胁日志通常面临两个核心诉求：

1. **安全审计与快速检索**：需要存储全量原始攻击日志，支持多维度的搜索和关联分析。
2. **黑客画像与态势感知**：需要从海量日志中提取高价值特征（攻击 IP、账号、手法等），构建攻击者档案。

本项目围绕这两个诉求设计了一套完整的流水线：

- **攻击详情链路**：`attack_detail` channel → Kafka（Kafka 模式）或直写 ES（直连模式）。Kafka 模式下 Logstash 消费 topic `hfish_attack_detail_categorized`，将 `raw_list` split 展开并提升字段到顶层，按攻击日期索引 `hfish-YYYY.MM.DD` 写入 ES。直连模式使用相同索引和字段格式。`@timestamp` 映射为攻击时间（`create_time`），`_id` 按 `attack_ip + create_time + service_name + service_port` 去重。
- **画像数据链路**：`profile` channel → MySQL。Puller 将画像数据 upsert 到 `attacker_profiles` 表（每 IP 一行），用于攻击者分析和关联查询。
- **调试输出**：`raw` channel → LocalFile。所有原始数据均写入本地 JSON 文件，不进入 ES/Kafka。
- **自动化响应链路**：桥接脚本轮询 ES 发现新攻击，触发自研 soar_core 工作流引擎执行封禁、通知等操作。

## 前置依赖

| 组件 | 版本要求 | 用途 |
|------|----------|------|
| Python | ≥ 3.9 | 运行采集器和 SOAR 引擎 |
| Kafka | 4.x | 消息队列，削峰填谷（可选，不启用 Kafka 模式可跳过） |
| Elasticsearch | 8.x | 全文检索与攻击事件存储 |
| Logstash | 8.x | 消费 Kafka 数据，清洗后写入 ES |
| MySQL | 5.7+ | 黑客画像存储 + SOAR 去重跟踪 |
| Kibana | 8.x | ES 可视化（可选） |

Kafka 需配置双 listener（PLAINTEXT:9092 + INTERNAL:9192），详见 docs 目录下的部署指南。

## 快速开始

### 1. 安装依赖

```powershell
pip install -r requirements.txt
```

### 2. 配置

编辑 `config.json`，至少需要配置以下信息：

```json
{
    "hfish": {
        "base_url": "https://你的HFish管理端IP:4433",
        "api_key": "在HFish后台生成的API_KEY"
    },
    "pipeline": {
        "use_kafka_pipeline": true,
        "enabled_outputs": ["local_file", "elasticsearch", "mysql"],
        "kafka": {
            "bootstrap_servers": ["127.0.0.1:9092"]
        },
        "elasticsearch": {
            "hosts": ["http://localhost:9200"]
        },
        "mysql": {
            "host": "127.0.0.1",
            "user": "root",
            "password": "your_password",
            "database": "secops_brain"
        }
    },
    "soar": {
        "targets": [
            {
                "name": "honeypot-node",
                "host": "192.168.1.100",
                "port": 22,
                "user": "your_ssh_user",
                "password": "your_ssh_password",
                "workflows": ["攻击自动响应（ES查历史+条件判断）"]
            }
        ]
    }
}
```

### 3. 启动基础设施

Kafka 需要在 Windows 上原生启动，其他组件运行在 Docker 中：

```powershell
# Step 1: 启动 Kafka（保持窗口打开）
cd D:\Kafka_2.13-4.2.0
.\bin\windows\kafka-server-start.bat .\config\server.properties

# Step 2: 启动 ELK Stack（ES + Logstash + Kibana + MySQL）
cd D:\ELK
docker-compose up -d
```

### 4. 运行数据采集

```powershell
cd D:\HFish_SecOps
python hfish_puller.py
```

首次运行会拉取过去 N 天的攻击数据。控制台输出 `=== 拉取任务完成 ===` 即运行成功。攻击详情经 Kafka → Logstash 写入 ES，画像数据直存 MySQL。

验证 ES 中已有数据：

```powershell
curl -s "http://localhost:9200/hfish-*/_count"
```

返回 `count` > 0 表示链路通畅。

### 5. 启动 SOAR 自动化响应

```powershell
cd D:\HFish_SecOps
python hfish_soar_bridge.py
```

桥接脚本启动后，会定期轮询 ES 查找新攻击文档，发现后自动加载工作流并执行。默认轮询间隔 10 秒。

支持手动写入测试数据验证：

```powershell
curl -X POST "http://localhost:9200/hfish-test/_doc" -H "Content-Type: application/json" -d "{\"attack_ip\":\"8.8.8.8\",\"service_name\":\"SSH\",\"@timestamp\":\"$(Get-Date -Format 'yyyy-MM-ddTHH:mm:ssZ')\"}"
```

桥接脚本应输出类似：`→ 8.8.8.8 攻击自动响应（ES查历史+条件判断）[honeypot-node] OK`

### 6. 启动 Web 可视化

```powershell
cd D:\HFish_SecOps
python hfish_web.py
```

脚本自动安装依赖（首次）并启动 API + 前端，浏览器自动打开 `http://localhost:5173`。

打开浏览器访问 `http://localhost:5173`，即可看到安全运营平台可视化界面。

> 详细部署说明见 `docs/环境部署/Web可视化部署指南.md`。

## 组件详解

### hfish_puller.py — 数据采集器

负责从 HFish 管理端 REST API 拉取攻击数据，按 channel 分发到不同存储：

- **攻击详情**：含 `raw_list` 数组，走 `attack_detail` channel → Kafka（Kafka 模式）或 ES（直连模式）
- **攻击者画像**：按 `attack_ip` 去重合并，走 `profile` channel → MySQL
- **调试文件**：所有原始数据走 `raw` channel → 本地 JSON 文件

数据流向由 `config.json` 控制：

- `use_kafka_pipeline: true`：攻击详情推 Kafka，画像直存 MySQL，本地文件保存全部原始数据（混合模式，推荐）
- `use_kafka_pipeline: false`：攻击详情直写 ES，画像直存 MySQL，本地文件保存全部原始数据（直连模式）

### hfish_soar_bridge.py — SOAR 桥接脚本

核心职责：

1. 定时轮询 ES，查询最近 N 分钟内的新攻击文档
2. 通过 MySQL `soar_es_tracker` 表对文档 ID 做去重，确保每条攻击只触发一次
3. 根据 `config.json` 中 `soar.targets` 配置，将目标节点的 SSH 凭据注入工作流
4. 每个工作流通过 `trigger_field` 声明所关注的 ES 字段（如 `"attack_ip"`），桥接在分发时检查 doc 是否含该字段，缺失则跳过该工作流
5. 调用 soar_core 引擎执行工作流。工作流执行失败（status ≠ 0）则桥接直接退出，不重试

去重机制基于 ES 文档的 `_id`，确保同一攻击记录不会重复触发响应动作。

### soar_core — 工作流引擎

自研轻量 SOAR 引擎，零外部依赖（仅 Python 标准库 + loguru）。工作流以 JSON 文件定义，存储在 `soar_core/workflows/` 目录下。

**核心特性：**

- DAG 图执行引擎，支持条件分支（IF）、循环（FOR）
- 插件式 app 节点，通过 `soar_core/apps/` 目录下的模块扩展
- 变量系统：支持 `@(node-uuid!>field)` 引用前序节点的输出
- `trigger_field`：每个工作流的 JSON 中声明所关注的 ES 文档字段，控制桥接分发过滤
- 错误码：status 0 = 成功，status 2 = 失败（桥接退出）

**当前工作流：**

| 工作流 | 功能 |
|--------|------|
| `attack_response.json` | ES 查攻击历史 → 条件判断 → SSH iptables 封禁 |
| `hello_world.json` | 引擎测试，打印攻击 IP |

### 插件节点

| 节点 | 功能 | 依赖 |
|------|------|------|
| `linux` | SSH 远程执行命令（iptables 封禁） | paramiko |
| `es` | Elasticsearch 查询（攻击历史） | elasticsearch |
| `http` | 通用 HTTP 请求 | requests |
| `helloworld` | 引擎测试节点 | 无 |

### Web 可视化平台 — web-platform/ + api-server/

React + Ant Design 前端 + FastAPI 后端，提供 8 个功能页面：

| 页面 | 路由 | 数据源 | 功能 |
|------|------|--------|------|
| 攻击态势总览 | `/` | ES + MySQL | KPI 卡片、攻击趋势折线图、服务分布饼图、实时攻击流 |
| 攻击者列表 | `/attackers` | MySQL | IP 搜索、排序分页，点击 Drawer 查看画像 |
| SOAR 响应历史 | `/soar-history` | MySQL `soar_es_tracker` | 响应记录分页、封禁 TOP10 |
| 蜜罐节点状态 | `/nodes` | HFish API | 节点卡片（在线/离线/版本/心跳）+ 系统摘要 |
| 攻击详情钻取 | `/attacks` | ES | 多条件筛选（IP/服务/节点/归属地）、JSON 详情 Drawer |
| 系统设置 | `/settings` | `config.json` | 5 Tab 表单（HFish/ES/MySQL/SOAR/Pipeline） |
| 审计日志 | `/audit` | MySQL `audit_logs` | 操作记录分页，按类型筛选 |

**技术栈：**

| 层 | 技术 | 端口 |
|----|------|------|
| 前端 | React 18 + TypeScript + Ant Design 5 + Vite 5 | 5173 |
| 后端 | FastAPI + elasticsearch-py + pymysql | 8000 |

前端通过 Vite 代理 `/api/*` → 后端，开发和生产环境统一。

> 部署详见 `docs/环境部署/Web可视化部署指南.md`。

## 数据格式示例

### HFish API 原始返回

#### 1. 攻击来源 — `POST /api/v1/attack/ip`

```json
{
    "response_code": 0,
    "verbose_msg": "成功",
    "data": {
        "attack_ip": ["192.168.75.137", "192.168.75.254"],
        "distribution": {}
    }
}
```

#### 2. 攻击详情 — `POST /api/v1/attack/detail`

```json
{
    "response_code": 0,
    "verbose_msg": "成功",
    "data": {
        "detail_list": [
            {
                "attack_ip": "192.168.75.137",
                "client_name": "client002",
                "service_name": "ELECTRIC蜜罐",
                "service_port": "9303",
                "ip_location": "LAN",
                "attack_type": "暴力破解",
                "timestamp": 1746789123,
                "payload": "root:admin123",
                "country": "中国",
                "province": "浙江省",
                "city": "杭州市"
            }
        ]
    }
}
```

#### 3. 攻击账号 — `POST /api/v1/attack/account`（逐 IP）

```json
{
    "response_code": 0,
    "verbose_msg": "成功",
    "data": [
        {"username": "root",    "password": "admin123"},
        {"username": "admin",   "password": "password"},
        {"username": "test",    "password": "123456"}
    ]
}
```

#### 4. 系统状态 — `GET /api/v1/hfish/sys_info`

```json
{
    "response_code": 0,
    "verbose_msg": "成功",
    "data": {
        "server_num": 2,
        "node_num": 5,
        "attack_num": 1234
    }
}
```

## 项目目录结构

```
D:\HFish_SecOps\
├── hfish_puller.py              # 数据采集器（HFish → Kafka/ES/MySQL）
├── hfish_soar_bridge.py         # SOAR 桥接脚本（ES 轮询 → 引擎触发）
├── hfish_web.py                 # Web 可视化一键启动
├── config.json                  # 主配置文件
├── requirements.txt             # Python 依赖
├── README.md
├── soar_core/
│   ├── engine.py                # 工作流引擎核心
│   ├── workflows/               # 工作流 JSON 定义
│   │   ├── attack_response.json # 攻击自动封禁
│   │   └── hello_world.json     # 引擎测试
│   ├── apps/                    # 插件节点
│   │   ├── linux/               # SSH 远程命令
│   │   ├── es/                  # ES 查询
│   │   ├── http/                # HTTP 请求
│   │   └── helloworld/          # 引擎测试
│   └── ai-agent/
│       └── SKILL.md             # SOAR 工作流编写指南
├── api-server/                  # Web API 服务
│   ├── main.py                  # FastAPI 入口
│   ├── routers/                 # 7 个路由模块
│   ├── services/                # ES / MySQL 数据服务
│   └── models/                  # Pydantic 数据模型
├── web-platform/                # Web 前端
│   ├── src/                     # React 源码（8 页面）
│   ├── dist/                    # 构建产物（npm run build）
│   └── package.json             # 前端依赖清单
├── docs/
│   ├── 系统架构设计.md
│   ├── 总体测试流程.md
│   ├── 扩展方向.md
│   ├── 环境部署/
│   │   ├── kafka部署指南.md
│   │   ├── ELK部署指南.md
│   │   ├── Web可视化部署指南.md
│   │   └── 环境验证指南.md
│   └── 架构图.png
└── hfish_data/                  # 本地 JSON 输出（自动生成）
```

## 文档导航

| 文档 | 内容 |
|------|------|
| `docs/数据结构解释.md` | 四种数据流方向与最终存储结构 |
| `docs/系统架构设计.md` | 整体架构设计与各层职责 |
| `docs/总体测试流程.md` | 全链路连通性验证步骤 |
| `docs/环境部署/kafka部署指南.md` | Kafka 双 listener 部署方法 |
| `docs/环境部署/ELK部署指南.md` | ES + Logstash + Kibana Docker 部署 |
| `docs/环境部署/Web可视化部署指南.md` | Web 可视化平台（React + FastAPI）部署 |
| `docs/环境部署/环境验证指南.md` | 数据汇聚层分段验证 |
| `docs/扩展方向.md` | 平台未来规划（AI 研判、动态蜜罐等） |