stephen-devops/THF-MAS
GitHub: stephen-devops/THF-MAS
THF-MAS 是一个基于 LangChain 和 Claude 的自然语言威胁狩猎框架，为 Wazuh SIEM 提供对话式分析与 MITRE 检测能力。
Stars: 0 | Forks: 0
# THF (威胁狩猎框架)
一个用于 Wazuh SIEM 的 AI 驱动自然语言接口，基于 LangChain 和 Anthropic Claude。
# 📖 用户指南
## 概述
THF（威胁狩猎框架）是一个功能强大的 AI 驱动安全分析平台，提供与 Wazuh SIEM 数据对话的界面。该系统通过 LangChain 使用 Anthropic 的 Claude Sonnet 4，使安全分析师能够使用自然语言查询调查安全事件、分析告警并了解自身的安全态势。
该框架将用户查询转换为结构化的函数调用，在 Wazuh OpenSearch 后端和 Wazuh API 上执行，并返回具有完整上下文保留的多轮对话中的可操作安全洞察。
## 安装说明与设置
### 先决条件
- Python 3.9+
- Anthropic API 密钥
- 可访问 Wazuh OpenSearch 集群
- Redis（可选，用于缓存）
### 安装步骤
1. 克隆仓库：
git clone https://github.com/resilmesh2/THF.git
cd THF/
2. 安装所需依赖
pip install -r requirements.txt
3. 配置环境变量
cp .env.example .env
## 环境变量
### 编辑 .env 并配置 API 密钥
必须在 `.env` 文件中配置以下环境变量：
**Anthropic 配置：**
- `ANTHROPIC_API_KEY` - 用于 Claude AI 访问的 Anthropic API 密钥
**OpenSearch 配置：**
- `OPENSEARCH_HOST` - OpenSearch 主机地址
- `OPENSEARCH_PORT` - OpenSearch 端口（默认：9200）
- `OPENSEARCH_USER` - OpenSearch 用户名（默认：admin）
- `OPENSEARCH_PASSWORD` - OpenSearch 密码
- `OPENSEARCH_USE_SSL` - 为 OpenSearch 连接启用 SSL（true/false）
**Wazuh API 配置：**
- `WAZUH_API_HOST` - Wazuh API 主机地址（默认：localhost）
- `WAZUH_API_PORT` - Wazuh API 端口（默认：55000）
- `WAZUH_API_USERNAME` - Wazuh API 用户名
- `WAZUH_API_PASSWORD` - Wazuh API 密码
- `WAZUH_API_USE_SSL` - 为 Wazuh API 启用 SSL（true/false）
- `WAZUH_API_VERIFY_CERTS` - 验证 SSL 证书（true/false）
**Redis 配置（可选）：**
- `REDIS_HOST` - Redis 主机地址（默认：localhost）
- `REDIS_PORT` - Redis 端口（默认：6379）
- `REDIS_PASSWORD` - Redis 密码（如果不需要则留空）
**应用程序配置：**
- `LOG_LEVEL` - 日志级别（INFO、DEBUG、WARNING、ERROR）
- `API_HOST` - FastAPI 主机绑定（默认：0.0.0.0）
- `API_PORT` - FastAPI 端口（默认：8000 用于 Docker，8000 用于本地）
**端口说明：**
- **Docker**：容器运行在 8000 端口，映射到主机端口 8030（通过 `http://localhost:8030` 访问，docker-compose.yml 中配置为 `8030:8000`）
- **本地**：应用程序直接在 8000 端口运行（通过 `http://localhost:8000` 访问）
## 运行应用程序
安装依赖后，需要启动 FastAPI 后端和 Streamlit 前端 UI。
1. 首先启动 FastAPI 后端服务器：
uvicorn main:app --host 0.0.0.0 --port 8000
2. 然后在新的终端中启动 Streamlit UI：
streamlit run ./streamlit_ui.py
后端将在 `http://localhost:8000` 处可用，UI 默认在 `http://localhost:8501` 处可用。
**注意**：使用 Docker 时，由于端口映射（`8030:8000` 在 docker-compose.yml 中），后端通过 `http://localhost:8030` 访问。
3. 访问 Streamlit UI 并开始威胁狩猎：
- 打开浏览器并导航至 `http://localhost:8501`
- 在文本输入框中输入自然语言安全查询
- 按回车或点击输入框外部以提交
尝试以下威胁狩猎查询示例：
- 显示过去两天内告警最多的前 10 台主机
- user SYSTEM 有哪些告警？
- 查找失败登录尝试超过 20 次的主机
- 哪些代理已断开连接？
- 在过去 24 小时内哪些用户访问了主机 win10-01？
- 在过去 12 小时内检测 T1055 进程注入技术。
- 检查我们 Windows 主机上的 Log4Shell 漏洞。
## 功能
### 8 个核心安全能力
1. **analyze_alerts** - 带排名、过滤、计数和分布的告警分析
2. **investigate_entity** - 实体调查（主机、用户、进程、文件）
3. **detect_threats** - MITRE ATT&CK 技巧、战术、威胁行为者
4. **map_relationships** - 实体关系、活动关联映射
5. **find_anomalies** - 阈值、行为、趋势检测
6. **trace_timeline** - 按时间顺序重建事件
7. **check_vulnerabilities** - CVE 检查与漏洞评估
8. **monitor_agents** - 代理状态、运行状况和连接性监控
### 详细的安全意图与子操作分解
#### 1. 分析告警
| 子操作 | 描述 |
|--------|------|
| **计数** | 返回按严重性、规则、代理和时间模式分组的警报数量统计分析 |
| **过滤** | 检索与过滤条件匹配的特定告警文档，并提供用于调查的上下文摘要 |
| **分布** | 执行单一或多维告警模式分析，涵盖代理、用户、进程、规则、严重级别、时间标准和规则组，并包含交叉关联、百分比分解和时间模式用于威胁分析 |
| **排名/堆叠** | 按告警频率对实体进行排名或堆叠（例如告警最多的主机、用户、规则、最严重的告警等） |
**示例查询：**
**计数：**
- “统计过去 24 小时内所有关键告警”
- “按用户和完整性级别统计今日告警”
- “统计过去 2 天内高严重性告警并分解 MITRE 技巧”
**过滤：**
- “筛选严重级别为 15 的告警”
- “查找进程名为 'powershell.exe' 的告警”
- “筛选过去 12 小时内所有规则组为 'sysmon' 的关键告警”
**分布：**
- “显示本周按规则组的告警分布”
- “显示过去三天内按严重级别和每小时时间段的告警分布”
- “提供用户、主机和严重级别之间的告警关联”
**排名/堆叠：**
- “按告警频率对主机排名”
- “在过去 24 小时内哪些安全规则触发最频繁？”
- “显示过去 6 小时内安全告警最活跃的主机”
#### 2. 发现异常
| 子操作 | 描述 |
|--------|------|
| **行为基线** | 通过将当前行为与 RCF 学习到的基线在数天内进行比较，检测实体的长期行为活动 |
| **基于阈值的检测** | 通过将实时数据与 RCF 学习基线建立的动态指标阈值（告警计数、主机活动、用户活动、告警严重性）进行比较，检测短时间内大量异常活动。检测到的异常活动包括暴力破解或蠕虫传播 |
| **趋势分析** | 检测异常网络活动的升级和渐进趋势，包括内部威胁升级检测或零日漏洞利用 |
**示例查询：**
**基于阈值的检测：**
- “检测过去 12 小时内失败的登录尝试突然激增”
- “使用 3 天 RCF 基线查找身份验证暴力破解尝试，且用户多样性超过异常”
- “使用 3 天 RCF 基线检测主机多样性超过 20 个受影响系统和告警量超过 500 的快速恶意软件传播”
- “使用 3 天 RCF 学习基线检测过去 12 天内主机上的关键告警量阈值违规”
**行为基线
- “查找过去 4 小时内涉及用户 SYSTEM 的协调活动”
- “使用 7 天 RCF 行为基线检测过去 2 天内用户活动模式和进程执行偏差的受损用户账户行为”
- “使用 60 天 RCF 行为基线（中等敏感度）检测过去 21 天内的内部威胁行为，包括异常的用户活动多样性和异常的主机访问模式”
**趋势分析：**
- “显示过去一周升级的威胁趋势”
- “使用 7 天基线检测过去 24 小时内告警量上升趋势（高敏感度）”
- “使用 14 天 RCF 趋势基线（高敏感度）检测过去 24 小时内的横向移动和渐进式主机传播”
- “使用 30 天 RCF 趋势基线检测过去 7 天内用户活动和严重性升级的内部威胁升级模式”
#### 3. 调查实体
| 子操作 | 描述 |
|--------|------|
| **告警检索** | 检索并分析指定实体（用户账户、主机、进程、文件）的告警，提供按时间顺序的告警分布统计和最近触发的告警 |
| **详细信息** | 提供实体的全面详细信息，包括总告警数、详细的 MITRE ATT&CK 关联、风险评分和告警严重性分解 |
| **活动分析** | 对实体进行行为分析，识别行为模式，包括告警活动爆发、峰值使用时间窗口、进程执行和用户交互，以了解指定实体的正常行为 |
| **状态监控** | 提供实体的运行状况和性能分析，包括最近的安全告警、代理连接状态、服务状态和实体整体健康评分 |
**示例查询：**
**告警检索：**
- “显示主机 win10-01 的所有告警”
- “提供主机 012 过去 6 小时内的所有告警”
- “本周由用户 SYSTEM 触发的告警有哪些？”
**详细信息：**
- “获取用户 administrator 的详细信息”
- “显示今天主机 U209-PC-BLEE 的详细信息”
- “获取包含风险评分的完整主机详细信息 192.168.201.33”
**活动分析：**
- “分析进程 powershell.exe 的行为模式”
- “分析过去三天内主机 win10-02 的行为模式”
- “跟踪过去四天内主机 Win10-01 的活动模式”
**状态监控：**
- “显示主机 U209-PC-BLEE 的状态报告”
- “主机 MAIL-SERVER 的当前安全状态是什么？”
- “提供 IP 地址为 192.168.201.33 的主机状态报告”
#### 4. 映射关系
| 子操作 | 描述 |
|--------|------|
| **实体到实体** | 通过查找共享事件或安全数据中的直接交互，映射指定实体（主机、用户、进程、文件）之间的直接关系。识别哪些实体相互交互，并基于告警严重性评估关系强度、类型和风险评分，用于安全调查和横向移动检测 |
| **行为关联** | 识别在相似时间范围内发生的多个实体之间的关联行为模式，表明协调行动、攻击链或系统性行为 |
**示例查询：**
**实体到实体：**
- “显示今天 user SYSTEM 访问了哪些主机”
- “在过去 24 小时内哪些用户访问了 IP 为 192.168.201.33 的主机？”
- “显示过去 6 小时内由 svchost.exe 进程加载的所有文件”
- “2025 年 5 月 15 日 process TiWorker.exe 删除了哪些文件？”
- “显示 2025 年 8 月 13 日某个进程注入到另一个进程的情况”
**行为关联：**
- “分析过去 6 小时内主机 win10-01 与其他实体的关联活动”
- “查找过去 4 小时内涉及用户 SYSTEM 的协调活动”
- “检测过去一小时内来自 IP 192.168.201.33 的异常访问序列”
#### 5. 追踪时间线
| 子操作 | 描述 |
|--------|------|
| **显示序列** | 按发生顺序生成安全事件的时间线，例如按主机、用户或特定进程的事件序列 |
| **攻击进展** | 跟踪攻击随时间的演变和进展，识别攻击链，重点关注关键事件并展示攻击者从初始入侵到后续阶段如何移动 |
| **时间关联** | 查找在指定时间窗口内发生的事件，帮助识别可能属于同一攻击或事件的相关活动 |
**示例查询：**
**显示序列：**
- “显示主机 server-01 从下午 2 点到 4 点的事件序列”
- “显示昨天 06:00:00 到 12:00:00 之间的事件序列”
- “显示过去 12 小时内所有关键告警的时序”
- “显示过去 2 天内代理 012 的身份验证事件详细序列”
**攻击进展：**
- “显示过去一小时内 T1059.003 告警之前的事件时间线”
- “追踪 win10-01 从初始访问时间 09:47:45 UTC 开始的攻击发展”
- “显示 IP 地址为 192.168.201.33 的主机在过去两小时内的攻击演变”
**时间关联：**
- “显示主机 win10-01 在过去四小时内的任何时间关联”
- “识别 10 分钟时间窗口内的协调活动模式”
- “显示过去三天内用户 SYSTEM 的时间关联事件”
## 使用 THF 进行威胁狩猎
### 入门
1. **提出初始问题**：从广泛查询开始以了解安全态势
- “显示过去 12 小时内主机 U209-PC-BLEE 的告警统计”
- “显示今日关键告警”
- “哪些代理已断开连接？”
- “哪些主机的告警最多？”
2. **后续问题**：THF 会记住之前查询的上下文
- 看到告警后：“请提供这些关键告警的更多细节”
- 看到主机后：“该主机的身份验证失败情况如何？”
- 调查后：“显示这些事件的时间线”
3. **调查实体**：深入调查特定主机、用户、进程或文件
- “主机 win10-01 有哪些告警？”
- “显示用户 administrator 在过去 24 小时内的所有活动”
- “powershell.exe 今天创建了哪些文件？”
4. **检测威胁**：查找 MITRE ATT&CK 技巧和可疑模式
- “最近检测到哪些 T1055 进程注入技巧？”
- “昨天的异常登录模式有哪些？”
- “是否有任何凭证转储尝试？”
5. **映射关系**：理解实体之间的连接
- “哪些用户今天访问了主机 win10-01？”
- “cmd.exe 创建了哪些进程？”
- “显示可疑进程访问的文件”
### 会话管理
- 每次对话都会跨多个查询保持上下文
- 使用侧边栏中的“重置会话”按钮开始新的调查
- 查看会话信息以查看对话历史
```
# 重置会话内存
POST /reset?session_id=your-session-id
# 获取会话信息
GET /session/{session_id}
# 列出所有活动会话
GET /sessions
```
### 系统信息与运行状况
```
# 健康检查
```bash
curl http://localhost:8000/health
# 或者如果使用 Docker：curl http://localhost:8030/health
```
## 路线图
### 已完成的功能 ✓
- [x] 使用 Claude Sonnet 4 的自然语言接口
- [x] 基于会话的对话记忆
- [x] 跨查询的上下文保留
- [x] 30 多个子操作的 8 个核心安全分析意图
- [x] Streamlit Web 界面
- [x] FastAPI REST API
- [x] OpenSearch 和 Wazuh API 集成
- [x] 智能路由和字段检测
- [x] 自然语言时间解析
- [x] MITRE ATT&CK 威胁检测
- [x] 实体关系映射
- [x] 使用 RCF 基线的异常检测
- [x] 全面日志记录和跟踪
### 计划中的功能
- [ ] 使用本地模型替换 Claude Sonnet 4.5 以实现加速的威胁狩猎响应
- [ ] 支持自定义 Wazuh 规则和解码器
- [ ] 集成外部威胁情报源
- [ ]租户支持与基于角色的访问控制
- [ ] 高级可视化功能和仪表板
- [ ] 使用 Redis 的查询结果缓存
- [ ] 自动报告生成
- [ ] 计划威胁狩猎查询
- [ ] 与工单系统集成（Jira、ServiceNow）
- [ ] 移动应用界面
# 🔧 技术文档
## 应用程序架构
```
User Query → Context Processor → LangChain Agent → Tool Selection → Function Execution → OpenSearch/Wazuh API → Response Generation → User
↓ ↓
Session Memory Function Dispatcher
```
### 核心组件
#### 1. WazuhSecurityAgent (`agent/wazuh_agent.py`)
负责整个查询处理生命周期的中央协调器：
- **LLM 模型**：Claude Sonnet 4
- **Agent 类型**：STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION
- **会话管理**：每个会话使用唯一的会话 ID 进行隔离的对话上下文
- **内存系统**：ConversationSummaryBufferMemory（每个会话 1500 令牌限制）
- **最大迭代次数**：3 次，配合提前停止以优化 API 使用
- **超时设置**：每个 API 调用 30 秒超时，带指数退避重试逻辑
- **关键特性**：
- 基于会话的对话内存防止用户之间的上下文泄漏
- API 负载过高时自动重试（529 错误），采用 2 秒、4 秒退避策略
- 跨多轮对话的上下文保留
- 实时代理状态管理
#### 2. ConversationContextProcessor (`agent/context_processor.py`)
智能上下文分析与保留系统：
- **上下文检测**：识别上下文引用（“这些告警”、“那个主机”、“此进程”）
- **实体提取**：从对话历史中提取主机、用户、进程、文件、IP
- **时间上下文**：跨查询保留时间范围
- **查询增强**：自动将之前的筛选器应用于后续查询
- **检测策略**：
- 显式关键词匹配
- 数值引用跟踪
- 定冠词模式
- 实体引用提取
#### 3. 安全功能模块 (`functions/`)
8 个专用模块，包含 30 多个子操作，用于全面的安全分析：
- **analyze_alerts**：告警排名、过滤、计数、分布分析
- **investigate_entity**：深度调查（主机、用户、进程、文件、IP）
- **detect_threats**：MITRE ATT&CK 技巧、战术、威胁行为者、IoC
- **map_relationships**：实体关系映射与行为关联
- **find_anomalies**：阈值、行为、趋势检测与 RCF 基线
- **trace_timeline**：按时间顺序重建事件与攻击进展
- **check_vulnerabilities**：CVE 检查、补丁状态、漏洞评估
- **monitor_agents**：代理状态、运行状况、连接性监控
#### 4. 数据集成层 (`functions/_shared/`)
**WazuhOpenSearchClient**：
- 异步 OpenSearch 连接，支持 SSL
- 智能字段映射（自动检测 agent.id 与 agent.name）
- 智能查询构建，支持通配符和词项查询
- 自然语言时间范围解析（“3 天前”、“昨天 6am-11am”）
- Wazuh 数组字段规范化
**WazuhAPIClient**：
- JWT 认证与令牌缓存
- 代理状态监控（活跃、断开、从未连接）
- 代理搜索与统计摘要
- 完整的代理信息检索
#### 5. Web 界面
**FastAPI 后端** (`main.py`)：
- 异步 REST API，支持 WebSocket
- 会话管理端点
- 健康检查与监控
- 生产环境 CORS 配置
**Streamlit UI** (`streamlit_ui.py`)：
- 实时对话界面
- 会话管理（创建、重置、查看信息）
- 示例查询建议
- API 运行状况指示器
- 带时间戳的对话历史
#### 6. 类型安全与验证 (`schemas/`)
- 所有函数参数的 Pydantic 架构
- 基于枚举的动作/类型选择
- 自动 JSON 序列化
- 请求/响应验证
## 高级用法
### REST API
查询助手：
```
curl -X POST "http://localhost:8000/query" \
-H "Content-Type: application/json" \
-d '{"query": "Show me critical alerts from the last hour"}'
```
### 查询端点
```
POST /query
Content-Type: application/json
{
"query": "Show me critical alerts from the last hour",
"session_id": "optional-session-id"
}
```
## 开发
### 项目结构
```
THF/
├── agent/ # Core LLM agent implementation
│ ├── wazuh_agent.py # Main LangChain agent orchestrator
│ ├── context_processor.py # Conversation context analysis
│ └── __init__.py
├── functions/ # Security analysis function modules
│ ├── analyze_alerts/ # Alert ranking, filtering, counting, distribution
│ ├── investigate_entity/ # Host, user, process, file investigation
│ ├── map_relationships/ # Entity relationship mapping and correlation
│ ├── detect_threats/ # MITRE ATT&CK detection, threat actors, IoCs
│ ├── find_anomalies/ # Threshold, behavioral, trend anomaly detection
│ ├── trace_timeline/ # Event timeline reconstruction
│ ├── check_vulnerabilities/ # CVE checking, vulnerability assessment
│ ├── monitor_agents/ # Agent status, health, version monitoring
│ ├── smart_routing/ # Intelligent query routing
│ └── _shared/ # Shared utilities
│ ├── opensearch_client.py # OpenSearch integration
│ ├── wazuh_api_client.py # Wazuh API integration
│ ├── time_parser.py # Natural language time parsing
│ └── utils.py # Common utilities
├── tools/ # LangChain tool wrappers
├── schemas/ # Pydantic validation schemas
├── assets/ # Static assets (logos, images)
├── tests/ # Test suite
├── docs/ # Documentation
├── main.py # FastAPI backend server
├── streamlit_ui.py # Streamlit web UI
├── demo_server.py # Demo/testing server
├── start_ui.py # UI launcher script
├── requirements.txt # Python dependencies
├── README.md # This file
└── .env # Environment configuration
```
### 关键架构特性
#### 基于会话的内存管理
- **隔离上下文**：每个用户会话维护独立的对话内存
- **防止内存泄漏**：并发用户不会相互干扰
- **上下文感知跟进**：系统记住前序查询中的实体、筛选器和时间范围
- **令牌优化**：ConversationSummaryBufferMemory 1500 令牌限制
#### 智能上下文保留
`ConversationContextProcessor`（agent/context_processor.py:1）分析对话以：
- 检测上下文引用（“这些告警”、“那个主机”）
- 从之前响应中提取实体
- 保留时间上下文
- 用相关筛选器增强后续查询
#### 智能路由与字段检测
- **自动字段映射**：检测使用 agent.id 还是 agent.name
- **进程智能**：在 originalFileName、image、commandLine 中搜索
- **多字段搜索**：对主机、进程、文件进行全面覆盖
- **自然语言时间解析**：支持“3 天前”、“昨天 6am-11am”等格式
标签：AI安全, AI安全工具, Anthropic Claude, Chat Copilot, FTP漏洞扫描, Kubernetes, LangChain, RESTful API, SOAR, Wazuh OpenSearch, Wazuh SIEM, 会话上下文, 函数调用, 威胁情报, 安全分析师, 安全分析平台, 安全态势感知, 安全编排, 开发者工具, 提示词优化, 搜索引擎查询, 自然语言查询, 轻量级, 逆向工具, 速率限制