brockbeck7/huntbot

# HuntBot — 自主式 SOC AI 分析师 [](https://www.python.org/) [](LICENSE) [](https://ollama.com/) ## 概述 HuntBot 是一个用 Python 构建的自主式 SOC 分析师。只需输入一个简明的英文威胁狩猎问题；它就会自主构建查询上下文，检索相关的日志数据，选择合适的本地 LLM，运行结构化的威胁狩猎，并输出包含 IOC、MITRE 技术映射以及针对 Microsoft Defender for Endpoint 的可选补救措施的可行性调查结果。 无需 OpenAI 账户。任何日志数据都不会离开您的环境。 ### 工作原理 ``` Analyst question (natural language) │ ▼ ┌──────────────────┐ │ Round 1 LLM │ Small, fast model translates NL → structured query context │ (tool call) │ (table, fields, time window, device/user filters) └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ Guardrails │ Validates table, fields, lookback, row count, model └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ Log Source │ mock (built-in IOCs) | file (JSONL export) | azure (live KQL) └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ Round 2 LLM │ Larger model hunts for anomalies, maps MITRE, extracts IOCs │ (threat hunt) │ Returns strict JSON findings schema └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ Remediation │ Isolate device, block IP, disable account (MDE API or dry-run) └──────────────────┘ ``` ## 功能特性 - **100% 本地化** — 连接到 Ollama、LM Studio、vLLM 或任何兼容 OpenAI 的服务器 - **两轮自主流水线** — 专用模型分别用于查询构建和深度分析 - **双重工具调用策略** — 原生 `tool_choice="required"`，并为不支持该特性的模型提供 JSON 回退机制 - **三种日志后端** — 内置包含真实 IOC 的模拟数据、JSONL 文件导出，或通过 KQL 连接实时的 Azure Monitor / Microsoft Sentinel - **六种日志表架构** — DeviceLogonEvents、DeviceProcessEvents、DeviceNetworkEvents、DeviceFileEvents、SigninLogs、EmailEvents - **MITRE ATT&CK 映射** — 调查结果包含来自 ATT&CK 框架的技术 ID - **安全护栏** — 表/字段允许列表、14 天回溯上限、5 万行上限、上下文窗口安全检查 - **自主补救** — MDE 隔离、IP 封禁、账户禁用（默认为试运行模式；配置 Azure AD 凭证后可实际执行） - **持久化** — 调查结果附带 UTC 时间戳追加到 `threats.jsonl` - **`--autonomous` 模式** — 跳过确认提示，适用于自动化流水线 ## 快速开始 ### 前置条件 - Python 3.10+ - [Ollama](https://ollama.com/) (或 LM Studio / vLLM) ### 1. 克隆并安装 ``` git clone https://github.com//huntbot.git cd huntbot pip install -r requirements.txt ``` ### 2. 拉取模型 ``` ollama pull llama3.1:8b # Round 1 — query context (fast) ollama pull qwen2.5:14b # Round 2 — threat hunt (default) ollama serve ``` ### 3. 运行狩猎 ``` # 交互式 prompt python main.py # 内联 question python main.py "Any brute force attempts on WIN-DC-01 in the last 12 hours?" # 跳过 remediation 确认 python main.py "Lateral movement from WORKSTATION-07?" --autonomous ``` 默认的 `LOG_BACKEND=mock` 模式针对植入了 IOC 的合成日志数据运行，因此流水线可以立即工作——无需连接 SIEM。 ## 配置 将 `.env.example` 复制到 `.env` 并设置您需要的变量： ``` cp .env.example .env ``` | 变量 | 默认值 | 描述 | |---|---|---| | `LOCAL_LLM_BASE_URL` | `http://localhost:11434/v1` | LLM 服务器 endpoint | | `LOCAL_LLM_API_KEY` | `not-needed` | API 密钥（Ollama 不需要） | | `LOG_BACKEND` | `mock` | `mock` \| `file` \| `azure` | | `LOCAL_LOG_DIR` | `./logs` | JSONL 日志文件的目录（文件后端） | | `AZURE_WORKSPACE_ID` | — | Azure Log Analytics 工作区 ID | | `AAD_TENANT_ID` | — | Azure AD 租户 ID（Sentinel + MDE 补救） | | `AAD_CLIENT_ID` | — | Azure AD 应用注册客户端 ID | | `AAD_CLIENT_SECRET` | — | Azure AD 应用注册密钥 | ## 日志后端 ### Mock（默认） 无需设置。生成带有真实植入 IOC 的合成日志行： | 表 | 植入的威胁 | |---|---| | DeviceLogonEvents | 来自 `203.0.113.77` 的暴力破解（15 次失败 → 成功） | | DeviceProcessEvents | `winword.exe` → `powershell -enc` → `certutil` 下载链 | | DeviceNetworkEvents | 每 60 秒向 `203.0.113.77:8443` 发送 C2 信标 | | DeviceFileEvents | 大批量 `.locked` 文件重命名（勒索软件） | | SigninLogs | 不可能旅行：5 分钟内从纽约移动到哈萨克斯坦 | | EmailEvents | 来自 `micros0ft-support.com` 的钓鱼邮件，未通过 SPF/DKIM/DMARC | ### 文件 将任何 SIEM 的日志导出为 JSON Lines 并放入 `./logs/` 中： ``` logs/ DeviceLogonEvents.jsonl DeviceProcessEvents.jsonl SigninLogs.jsonl ... ``` 每一行必须是一个有效的 JSON 对象。字段名应与 `modules/guardrails.py` 中定义的 schema 匹配。 ``` export LOG_BACKEND=file export LOCAL_LOG_DIR=./logs python main.py "Any suspicious logon activity in the last 24 hours?" ``` ### Azure Monitor / Microsoft Sentinel（实时） 在 `requirements.txt` 中取消 Azure 包的注释，安装它们，并配置 Azure 环境变量： ``` pip install azure-identity azure-monitor-query export LOG_BACKEND=azure export AZURE_WORKSPACE_ID= export AAD_TENANT_ID= export AAD_CLIENT_ID= export AAD_CLIENT_SECRET= python main.py "Password spray against any account in the last 6 hours?" ``` Azure 后端在每次调用时构建并运行针对您实时工作区的 KQL 查询。 ## 模型配置 模型在 `modules/model_management.py` 中配置。添加本地服务器中可用的任何模型： ``` MODELS = { "llama3.1:8b": {"context_window": 128_000, "good_for": "fast tool-calling"}, "qwen2.5:14b": {"context_window": 32_000, "good_for": "balanced reasoning (default)"}, "mistral-nemo:12b": {"context_window": 128_000, "good_for": "long-context fallback"}, # Add your own: "deepseek-r1:14b": {"context_window": 64_000, "good_for": "strong reasoning"}, } TOOL_CALL_MODEL = "llama3.1:8b" # Round 1 DEFAULT_HUNT_MODEL = "qwen2.5:14b" # Round 2 ``` HuntBot 根据估算的 prompt token 自动选择狩猎模型，当默认模型的上下文窗口太小时，会回退到大型上下文模型。 ## 调查结果 Schema 由第二轮 LLM 生成的每个调查结果都遵循以下 schema： ``` { "title": "Brute Force Success — svc_backup from 203.0.113.77", "severity": "High", "confidence": "High", "summary": "15 failed logon attempts followed by a successful authentication ...", "mitre": ["T1110.001"], "iocs": { "ips": ["203.0.113.77"], "hosts": ["WIN-DC-01"], "users": ["svc_backup"], "processes": [], "files": [], "hashes": [] }, "evidence_row_ids": [0, 1, 2, 15], "recommended_actions": [ "Reset the svc_backup credential immediately", "Block 203.0.113.77 at the perimeter firewall", "Review all sessions authenticated as svc_backup in the last 24h" ] } ``` 所有调查结果都会附带 UTC `_detected_at` 时间戳追加到 `threats.jsonl` 中。 ## 补救措施 对于严重性为 `High` 或 `Critical` 且置信度为 `Medium` 或 `High` 的调查结果，HuntBot 提供补救措施： | 操作 | 实现方式 | 要求 | |---|---|---| | 隔离设备 | MDE API `/machines/{id}/isolate` | AAD 凭证 | | 封禁 IP | 存根（可扩展至您的防火墙） | — | | 禁用账户 | 存根（可扩展至 Azure AD / AD） | — | 在未配置 AAD 凭证的情况下，所有操作都将在**试运行模式**下运行，并记录它们将执行的操作。 使用 `--autonomous` 跳过交互式确认提示： ``` python main.py "Active C2 beaconing?" --autonomous ``` ## 项目结构 ``` huntbot/ ├── main.py # 9-step orchestrator (entry point) ├── requirements.txt ├── .env.example # Environment variable template ├── .gitignore └── modules/ ├── __init__.py ├── keys.py # Environment-driven configuration ├── model_management.py # Model catalog + auto-selection ├── prompt_management.py # All prompts, tool schemas, table guidance ├── guardrails.py # Input validation and safety limits ├── log_source.py # Mock / file / Azure log backends ├── llm_client.py # OpenAI-compatible client (tool-call + JSON fallback) ├── executor.py # Remediation actions (MDE, stubs) └── utilities.py # ANSI output, display helpers, JSONL persistence ``` ## 扩展 HuntBot **添加新的日志表** — 在 `guardrails.py` 中添加表名和允许的字段，在 `prompt_management.py` 中添加狩猎指南，在 `log_source.py` 中添加模拟生成器。 **添加新的日志后端** — 在 `log_source.query_logs()` 中添加一个新分支，并为 `LOG_BACKEND` 添加相应的环境变量值。 **添加新的补救措施** — 在 `executor.py` 中添加一个函数，并从 `consider_remediation()` 中调用它。 **使用不同的 LLM 提供商** — 将 `LOCAL_LLM_BASE_URL` 更改为任何兼容 OpenAI 的 endpoint。支持 LM Studio、vLLM、llama.cpp server、Groq 等。 ## 灵感来源 根据 Josh Madakor 的 [Agentic Cybersecurity AI SOC Analyst 课程](https://www.youtube.com/) 中的架构构建，经过重新工程设计，可通过任何兼容 OpenAI 的服务器完全在本地 LLM 上运行。 ## 许可证 MIT — 详情请参阅 [LICENSE](LICENSE)。

标签：AI安全, AI智能体, AI风险缓解, Azure Sentinel, Chat Copilot, Cloudflare, IOC, IP 地址批量处理, JSONL, KQL, LLM评估, LM Studio, MDE, Microsoft Defender for Endpoint, MITRE ATT&CK, Ollama, Python, SOAR, SOC分析师, vLLM, Web报告查看器, 人工智能, 入侵指标, 威胁情报, 子域名变形, 安全合规, 安全运营中心, 开发者工具, 开源安全工具, 异常检测, 无后门, 本地大模型, 用户模式Hook绕过, 端点安全防御, 网络代理, 网络安全, 网络安全审计, 网络映射, 自动化响应, 逆向工具, 逆向工程平台, 隐私保护