Towelie/HuntKit

# HuntKit [](https://github.com/Towelie/HuntKit/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) **HuntKit 是一个开源的安全调查工具包，为 AI 代理提供一个安全、一致的接口，用于威胁狩猎、DFIR、IOC 富化、日志搜索、YARA 扫描和事件响应支持。** HuntKit 专注于防御性安全，与提供商无关，且默认为只读。它通过 Model Context Protocol (MCP) 公开工作流，但 MCP 只是该工具包的一个接口。其核心设计是一小部分可重用的提供商抽象，这些抽象可以在本地进行测试、安全地扩展，并且无需向 AI 代理授予广泛的 shell 或控制台访问权限即可使用。 ## 状态 HuntKit 是早期阶段的软件。v1 基础版本包括模拟提供商、本地样本数据、确定性摘要、本地 MITRE ATT&CK 映射、可选的 YARA 扫描以及一个 MCP 适配器。真正的第三方集成特意留给用户自有的提供商包来实现。 ## 功能 - 用于常见安全调查工作流的安全 MCP 工具 - 默认启用模拟模式，并内置样本日志和端点数据 - 用于日志、端点数据、IOC 富化、规则扫描和案例管理的提供商抽象 - 用于离线演示和测试的确定性 IOC 富化和调查摘要 - 使用样本关键字映射的本地 MITRE ATT&CK 映射 - 通过 `yara-python` 进行可选的 YARA 扫描 - 带有 MCP 工具调用审计事件的 JSON 结构化日志 - 支持 Python 3.11+，包含类型提示、pytest、Ruff、Black、mypy 和 GitHub Actions CI ## 为什么选择 HuntKit 安全团队越来越希望 AI 代理能够帮助关联遥测数据、丰富指标、总结发现并准备事件响应记录。这项工作得益于一个精确且可预测的接口。 HuntKit 为代理提供只读的安全工作流，而不是不受限制地访问终端、SIEM 控制台、EDR 控制台或案例管理系统。它避免了专有的供应商逻辑、特定于公司的假设、内部 schema、破坏性操作以及隐藏的修复工作流。 ## 架构 ``` flowchart LR Agent["AI Agent / MCP Client"] --> MCP["HuntKit MCP Adapter"] MCP --> Tools["Read-Only Workflow Tools"] Tools --> Logs["LogSearchProvider"] Tools --> EDR["EDRProvider"] Tools --> IOC["IOCEnrichmentProvider"] Tools --> Rules["RuleScanProvider"] Tools --> Cases["CaseManagementProvider"] Tools --> MITRE["Local MITRE Mapper"] Logs --> MockLogs["MockLogSearchProvider"] EDR --> MockEDR["MockEDRProvider"] IOC --> MockIOC["MockIOCEnrichmentProvider"] Rules --> YARA["YARA Scanner Provider"] ``` ## 仓库布局 ``` src/huntkit/ server.py # MCP adapter config.py # Environment-driven settings logging_config.py # Structured logging and audit events models.py # Pydantic response models providers/ # Provider protocols and bundled providers tools/ # Provider-backed workflow functions samples/ # Source checkout sample data tests/ # Pytest coverage .github/workflows/ci.yml # GitHub Actions checks ``` ## 安装说明 使用 `uv`： ``` uv venv uv pip install -e ".[dev]" ``` 使用 `pip`： ``` python -m venv .venv . .venv/bin/activate pip install -e ".[dev]" ``` 可选的 YARA 支持： ``` pip install -e ".[yara]" ``` ## 快速开始 运行 MCP 服务器： ``` huntkit ``` 或者： ``` python -m huntkit.server ``` 通用 MCP 客户端配置： ``` { "mcpServers": { "huntkit": { "command": "python", "args": ["-m", "huntkit.server"], "cwd": "E:\\HuntKit", "env": { "HUNTKIT_MOCK_MODE": "true" } } } } ``` Claude Desktop / Codex 风格的代码片段： ``` { "mcpServers": { "huntkit": { "command": "uv", "args": ["run", "huntkit"], "cwd": "E:\\HuntKit", "env": { "HUNTKIT_MOCK_MODE": "true" } } } } ``` ## MCP 工具 | 工具 | 用途 | | --- | --- | | `search_logs` | 搜索只读的标准化安全日志。 | | `lookup_ioc` | 富化 IP、域名、哈希或 URL。 | | `query_endpoint` | 查询端点摘要、进程、网络或警报数据。 | | `run_yara_scan` | 在安装了 `yara-python` 时使用 YARA 扫描本地文件。 | | `map_to_mitre` | 将调查文本映射到可能的 MITRE ATT&CK 技术。 | | `summarize_findings` | 生成确定性的高管、分析师或事件报告摘要。 | ## 示例 Prompt - “在日志中搜索 PowerShell 编码命令，并总结受影响的主机。” - “将 `203.0.113.44` 作为 IP 指标进行查询，并解释其富化信息。” - “查询端点 `workstation-17` 的网络活动。” - “将此发现映射到 MITRE ATT&CK：PowerShell 编码命令发起了出站 TLS 连接。” - “将这些发现总结为一份事件报告，并给出建议的后续步骤。” ## 安全模型 HuntKit 专为防御性安全工作流而设计： - 默认只读 - 无破坏性操作 - 不提交机密信息 - 默认启用模拟模式 - 无专有供应商逻辑 - 无特定于公司的假设 - 无修复、隔离、删除、阻止或隔离工作流 - 除非设置 `HUNTKIT_ALLOW_EXTERNAL_PATHS=true`，否则本地文件扫描仅限于项目目录 - 对 MCP 工具调用进行结构化审计日志记录 - 无需外部 LLM 或 API 调用的确定性本地摘要 ## 提供商抽象 HuntKit 核心在 `src/huntkit/providers/base.py` 中定义了少量协议： - `LogSearchProvider` - `EDRProvider` - `IOCEnrichmentProvider` - `RuleScanProvider` - `CaseManagementProvider` 初始项目仅包含通用提供商： - `MockLogSearchProvider` - `MockEDRProvider` - `MockIOCEnrichmentProvider` - `YaraRuleScanProvider` - `LocalMitreMapper` v1 版本不包含真实集成。要添加您自己的提供商，请实现其中一个协议并通过 `ProviderRegistry` 进行注册。将特定于集成的 schema、凭据、速率限制和 API 行为隔离到该提供商包中。 ## 配置 如果需要本地覆盖，请将 `.env.example` 复制到 `.env`： ``` HUNTKIT_MOCK_MODE=true HUNTKIT_LOG_LEVEL=INFO HUNTKIT_ALLOW_EXTERNAL_PATHS=false HUNTKIT_YARA_TIMEOUT_SECONDS=30 ``` ## 开发 运行完整的本地质量检测： ``` pytest ruff check . black --check . mypy src ``` 构建 wheel： ``` python -m pip wheel --no-deps . -w dist ``` ## 路线图 - 为外部集成包提供 Provider entry-point 加载 - 为样本数据集和提供商功能提供 MCP 资源 - 只读案例时间线和证据包接口 - 为常见的开放式安全格式提供额外的本地解析器 - 扩展本地 ATT&CK 映射数据 - 可选的 Streamable HTTP 部署配置文件 - 签名的发布构件和已发布的包元数据 ## 安全 请私下报告安全问题。请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 HuntKit 基于 GNU General Public License v3.0 发布。请参阅 [LICENSE](LICENSE)。

标签：AI代理, MCP, YARA, 云资产可视化, 安全规则引擎, 安全调查, 数据泄露, 网络信息收集, 逆向工具