kbugra/huntmcp

# HuntMCP HuntMCP 是一个达到作品集级别、确定性优先的 SOC 调查原型。 它能解析导出的安全日志，规范化事件，应用基于规则的狩猎 逻辑，提取 IOC，使用 CTI 来源对其进行富化，并生成一份 分析师风格的 Markdown 报告。 核心理念很简单：LLM 不是检测引擎。HuntMCP 首先使用可审计的规则检测 可疑活动，然后仅将兼容 OpenAI 的 LLM 用作分析师助手，以提供解释、严重性推理、MITRE ATT&CK 建议、误报说明和推荐的后续步骤。 ## 项目状态 本仓库旨在作为一个网络安全作品集项目和高级 MVP，而非用于生产的 SIEM 或替代生产环境的检测方案。 当前验证状态： - CLI 管道可端到端运行。 - FastAPI 后端支持调查作业和持久化的案例摘要。 - SQLite 持久化存储案例、运行、事件、发现、IOC、富化结果、 分诊结果、报告和作业状态。 - 即使存在本地 `.env`，确定性测试也能离线运行。 - 当前验证基线：`302 passed`，`ruff check` 干净，`ruff format` 干净。 ## 它的功能 HuntMCP 可以： - 解析 CSV、JSON 和 JSONL 导出的日志。 - 规范化 Windows Security、Sysmon、DNS、Proxy/Web 和通用 CSV 日志。 - 运行受 Sigma 启发的确定性检测规则。 - 提取诸如 IPv4 地址、域名、URL、哈希、CVE 和电子邮件等 IOC。 - 使用模拟/本地 CTI 和可选的外部 CTI 连接器富化 IOC。 - 使用兼容 OpenAI 的 LLM 或确定性模拟后备方案对发现进行分诊。 - 生成 Markdown 调查报告。 - 将调查输出持久化到 SQLite 以供案例审查。 - 公开一个小型 FastAPI 后端，用于上传、作业、案例、发现、IOC 和报告。 ## 它不是什么 - HuntMCP 不是一个 SIEM。 - HuntMCP 不是用于生产的检测替代方案。 - HuntMCP 不执行攻击者归因。 - HuntMCP 不会自动证明存在恶意活动。 - 生成的报告需要分析师审查。 - 公共 CTI 来源可能存在嘈杂、过时、不完整或不可用的情况。 ## 架构 代码库的组织方式使得模块以后可以包装为 MCP 服务器： ``` huntmcp.parsers -> Log Parser MCP candidate huntmcp.detection -> Detection MCP candidate huntmcp.ioc -> IOC Extractor MCP candidate huntmcp.enrichment -> CTI Enrichment MCP candidate huntmcp.llm -> Analyst Triage MCP candidate huntmcp.reporting -> Report MCP candidate ``` 高级流程： ``` Raw logs -> Parser -> Normalized events -> Deterministic rule engine -> Findings -> IOC extractor -> CTI enrichment -> Redacted LLM triage -> Markdown report + SQLite case storage ``` ## 支持的日志类型 - Windows Security - Sysmon - DNS - Proxy/Web - 通用 CSV ## 检测规则 默认规则集包括： - 多次登录失败 - 登录失败后伴随登录成功 - 可疑的 PowerShell 命令 - 创建新的本地管理员用户 - DNS 信标候选 - 已知的可疑 URL/域访问 该引擎是确定性的且可审计。分块检测具有一致性测试，以 确保在使用 `--chunk-size` 运行 CLI 时不会遗漏关联规则。 ## CTI 富化 `--cti` 支持的 CTI 来源名称： - `mock` 或 `mock-local-cti` - `urlhaus` - `abuseipdb` - `otx` - `virustotal` 外部 CTI 连接器是可选的。如果缺少密钥，本地/模拟工作流 仍可运行。URLhaus 元数据查询不会下载恶意软件样本。 ## LLM 分诊工作流 1. 规则从规范化的事件中生成发现。 2. 从这些发现中提取 IOC。 3. 附加 CTI 富化结果。 4. 脱敏敏感值。 5. 仅将选定的可疑上下文发送给 LLM。 6. 日志内容被明确视为不受信任的数据。 7. 模型返回结构化的 JSON： - `verdict` - `severity` - `reason` - `mitre_attack` - `false_positive_notes` - `recommended_next_steps` - `analyst_summary` 如果未设置 `OPENAI_API_KEY`，HuntMCP 将返回确定性的模拟分诊，以便 测试和演示不需要密钥。 默认示例模型为： ``` LLM_MODEL=mimo-v2.5 ``` ## 安全注意事项 - `.env` 被忽略，绝对不能被提交。 - `.env.example` 仅包含空/示例值。 - API 密钥不会被记录或发送给模型。 - 原始日志被视为不受信任的输入。 - 提示模板会警告 LLM 不要遵循日志内容中的指令。 - 脱敏支持用户名、内部 IP、主机名、电子邮件、令牌和 cookie。 - CTI 查询使用防护措施来阻止 localhost、私有范围、链路本地 范围、多播和元数据 IP。 - 测试会隔离秘密环境变量，以避免意外的实时 API 调用。 - CORS 源可通过 `HUNTMCP_CORS_ALLOW_ORIGINS` 配置。 ## 快速开始 ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt python huntmcp.py self-test ``` 预期的自检结果： ``` ok: true event_count: 5 finding_count: 5 enriched_count: 5 triage_count: 5 ``` ## 配置 从示例创建一个本地 `.env` 文件： ``` Copy-Item .env.example .env ``` 示例变量： ``` OPENAI_API_KEY= LLM_MODEL=mimo-v2.5 OPENAI_BASE_URL= URLHAUS_AUTH_KEY= ABUSEIPDB_API_KEY= OTX_API_KEY= VIRUSTOTAL_API_KEY= LLM_TIMEOUT_SECONDS=30 HUNTMCP_MAX_UPLOAD_SIZE_BYTES=10485760 HUNTMCP_MAX_LLM_FINDINGS=50 HUNTMCP_CTI_LOOKUP_LIMIT=250 ``` ## CLI 演示 解析日志： ``` python huntmcp.py parse --input data/sample_logs/windows_security.csv --type windows_security ``` 运行检测： ``` python huntmcp.py detect ``` 富化发现： ``` python huntmcp.py enrich --cti mock ``` 运行 LLM/模拟分诊： ``` python huntmcp.py triage --limit 5 ``` 生成报告： ``` python huntmcp.py report ``` 运行持久化调查工作流： ``` python huntmcp.py init-db python huntmcp.py investigate --input data/sample_logs/windows_security.csv --type windows_security --cti mock --model mimo-v2.5 --case-id demo-windows --case-name demo-windows python huntmcp.py case-summary --case-id demo-windows ``` 使用多个 CTI 来源： ``` python huntmcp.py enrich --cti mock,urlhaus,abuseipdb,otx,virustotal --cti-lookup-limit 250 ``` `--cti-lookup-limit` 限制单次运行中唯一的远程 IOC 查询次数。这可以防止大型 公共数据集在 LLM 分诊步骤开始前，在第三方 CTI 调用上耗费数分钟时间。仅当您有意需要无限制的实时 CTI 查询时，才使用 `-1`。 获取一个小型的 URLhaus 派生代理样本： ``` python huntmcp.py fetch-urlhaus-sample --limit 25 python huntmcp.py parse --input data/public_samples/urlhaus_recent_proxy.csv --type proxy python huntmcp.py detect ``` ## 公共数据集验证 HuntMCP 还使用 `deepseek-v4-flash`，针对 URLhaus 公共最新 URL 元数据进行了实时 兼容 OpenAI 的 LLM 分诊验证。作品集规模的运行 处理了 1000 条 URLhaus 记录，产生了 1504 个确定性发现，富化了 1504 个发现，并在最终报告中使用了 200 个实时 DeepSeek 分诊结果。 有关命令、指标、CTI 查询预算、裁定/严重性分布和 MITRE ATT&CK 映射摘要，请参阅 [docs/deepseek_v4_flash_urlhaus_200_run.md](docs/deepseek_v4_flash_urlhaus_200_run.md)。 生成的 JSON、SQLite、下载的 CSV 和报告 产物被有意排除在 git 之外；此文档文件是 可安全推送的证据产物。 ## API 演示 启动 API： ``` uvicorn huntmcp.api:app --reload ``` 如果需要，设置显式的 CORS 源： ``` $env:HUNTMCP_CORS_ALLOW_ORIGINS="http://localhost:3000,http://localhost:5173" uvicorn huntmcp.api:app --reload ``` 有用的端点： ``` GET /health POST /investigate POST /investigations GET /jobs/{job_id} GET /cases GET /cases/{case_id}/summary GET /findings/{case_id} GET /iocs/{case_id} GET /reports/{case_id} GET /dashboard ``` ## 测试 运行完整的验证套件： ``` python -m pytest -q python -m ruff check huntmcp huntmcp.py tests python -m ruff format --check huntmcp huntmcp.py tests ``` 当前本地验证： ``` 302 passed All ruff checks passed 76 files already formatted ``` ## 示例输出 报告包括： - 执行摘要 - 发现 - 时间线 - IOC 表 - MITRE ATT&CK 映射 - 检测逻辑 - 误报说明 - 推荐的后续步骤 - 局限性 报告在 `reports/` 目录下生成。默认情况下，生成的报告会被 git 忽略，以 保持仓库整洁。 ## 仓库维护 该仓库有意排除了： - `.env` - Python 缓存 - pytest/ruff 缓存 - SQLite 数据库 - 生成的规范化事件 - 生成的发现 - 生成的富化输出 - 生成的报告 - 下载的公共 CTI 数据集 只应推送源代码、测试、文档、配置和少量样本日志。 ## 局限性 - 这是一个作品集级别的原型，而不是一个生产级 SOC 平台。 - 当前的检测集有意保持较小规模。 - SQLite 适用于本地/单用户工作流，不适用于多租户生产环境。 - 非常大的数据集需要一个真正的有状态流式检测引擎。 - 外部 CTI 质量取决于第三方的可用性和速率限制。 - LLM 输出可能有误，必须由分析师进行审查。 - API 身份验证、RBAC、审计日志和部署强化是未来的工作。 ## 未来工作 - 针对超大型数据集的真正有状态的流式检测 - 更多兼容 Sigma 的规则加载和规则元数据 - 更丰富的分析师 UI，用于时间线、IOC 透视和发现审查 - API 身份验证和基于角色的访问控制 - 用于长时间调查的作业队列后端 - 更多 CTI 连接器响应规范化和速率限制处理 - Docker 部署配置文件和生产机密管理 - 用于解析器、检测、富化、分诊和报告模块的真正 MCP 服务器包装器

标签：AMSI绕过, AV绕过, Cloudflare, DLL 劫持, DNS日志, FastAPI, IOC提取, IP 地址批量处理, LLM辅助报告, Markdown报告, MITRE ATT&CK, Mock测试, Petitpotam, Python, SIEM原型, Sigma规则, SOC调查, SQLite, Sysmon, Windows安全日志, 代理日志, 基于规则的检测, 大语言模型, 威胁情报富化, 威胁检测, 安全信息与事件管理, 安全分析师, 安全日志解析, 安全组合项目, 安全规则引擎, 安全运营中心, 库, 应急响应, 插件系统, 搜索引擎爬取, 无后门, 无线安全, 案件管理, 目标导入, 网络安全, 网络映射, 逆向工具, 隐私保护