iocx-dev/iocx-registry-keys

# iocx-registry-keys [PyPI](https://pypi.org/project/iocx-registry-keys/) 一个用于 `iocx` 引擎的高性能注册表键检测插件。 本插件可提取： - 注册表键（常规 Windows 注册表路径） - 注册表值（REG_SZ、REG_DWORD 等） - 持久化键（如 Run 和 RunOnce 等自启动位置） 本插件**不会**进行以下操作： - 读取 Windows 注册表 - 执行代码 - 执行系统检查 它仅分析文本输入并提取与注册表相关的 IOC。 其设计目标是： - 快速 — 在典型输入下实现亚毫秒级检测 - 安全 — 即使在处理病态输入时也不会发生灾难性回溯 - 准确 — 清晰区分键、值和持久化项 - 测试充分 — 具备完整的单元、集成和性能测试覆盖 ## 功能特性 ✔ 注册表键检测 匹配 Windows 注册表路径，例如： ``` HKCU\Software\Example HKLM\System\CurrentControlSet\Services\Tcpip HKEY_LOCAL_MACHINE\Software\Microsoft\Windows ``` ✔ 注册表值检测 检测常见的值类型： ``` REG_SZ REG_DWORD REG_BINARY REG_QWORD REG_MULTI_SZ REG_EXPAND_SZ ``` ✔ 持久化键检测 识别恶意软件常用的自启动位置： ``` HKCU\Software\Microsoft\Windows\CurrentVersion\Run HKLM\Software\Microsoft\Windows\CurrentVersion\RunOnce HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer\Run ``` ✔ 高性能 所有检测器均经过优化，可避免回溯，并与输入大小呈线性扩展。 ✔ 启发式富化（可选） 当使用 `--enrich` 运行或通过 Python API 调用时，此插件会对每个检测到的注册表键应用轻量级评分模型。其目的是突出显示那些更有可能表明存在持久化机制、可疑工具或恶意软件暂存行为的键。富化功能可帮助分析人员快速确定需要深入调查的注册表键的优先级，尤其是在处理大型或嘈杂的数据集时。 每个富化条目包括： - value — 原始注册表键 - score — 整数评分 (0–100) - reasons — 人类可读的解释 - flags — 针对特定启发式规则的布尔指示器 评分模型是**完全确定性**的 — 相同的输入始终会产生相同的分数和原因。 **评分规则：** 以下启发式规则会计入评分： | 启发式规则 | 描述 | 分数 | |---------------------------------------|---------------------------------------------|------------| | 持久化路径 | 键位于已知的自启动位置 | +50 | | | (`Run`、`RunOnce`、`Policies\Explorer\Run`) | | | 可疑子字符串 | 键包含与工具或恶意软件相关的 | 各 +10 | | | 术语 (powershell、cmd.exe、wscript 等) | | | 异常长的键 | 路径长度 > 200 个字符（常见于 | +5 | | | 混淆或隐藏技术中) | | | 未知供应商路径 | 位于不常见供应商命名空间下的键 | +? | | （可选的未来规则） | | | **富化输出示例：** ``` { "value": "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\BadApp", "score": 60, "reasons": [ "Registry path contains persistence location: HKCU/HKLM Run key", "Matched suspicious substring: 'BadApp'" ], "flags": { "persistence": true, "suspicious_substrings": ["BadApp"] } } ``` 这些启发式规则故意设计得较为保守：它们能突出显示可疑模式，而不会对正常的系统活动产生误报。 ## 安装 通过 pip 安装： ``` pip install iocx-registry-keys ``` 或者在开发期间以可编辑模式安装： ``` pip install -e . ``` ## 使用方法 该插件会通过入口点被 `iocx` 引擎自动发现。 ### CLI ``` echo "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\BadApp" | iocx - ``` ### Python API ``` from iocx import Engine engine = Engine() result = engine.extract("HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\BadApp") print(result["iocs"]) ``` ### 输出 ``` { "registry.persistence": [ "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\BadApp" ], "registry.keys": [], "registry.values": [] } ``` ## 相关插件 - `iocx`（核心引擎） ## 开发 ### 安装开发依赖 ``` make install ``` ### 运行测试 ``` make test ``` ``` make test-performance ``` ### 运行覆盖率检查 ``` make test-coverage ``` ### 运行安全检查 ``` make security ``` 此操作会运行： - pip-audit，用于检查依赖项漏洞 - bandit，用于静态代码安全分析 ## 性能 本插件在 `tests/performance/` 目录下包含完整的性能测试套件。 在典型机器上的示例结果： ``` registry-keys 1MB mixed-content: ~0.002s registry-values 1MB mixed-content: ~0.001s registry-persistence 1MB mixed-content ~0.002s registry-enricher 60k mixed-content: ~0.006s ``` 病态情况（深度嵌套、重复模式）依然保持安全且可预测。 ## 测试 本项目包括： - 单元测试 - 集成测试 - 性能测试 - 病态安全性测试 - 插件代码 100% 的覆盖率 运行所有测试： ``` pytest -q ``` ## 贡献 欢迎贡献代码。 如果您想对检测行为提出更改建议（例如，添加新的持久化键），请提交 PR。优先级决策由 IOCX 引擎集中管理，因此贡献者可以通过常规的审查流程提出类别优先级的更改建议。 ## 许可证 MIT 许可证。 详见 LICENSE 文件。

标签：DAST, IOC提取, PyPI, Python, TypeScript, Windows注册表, 入侵指标, 威胁情报, 子域名暴力破解, 安全插件, 安全规则引擎, 库, 应急响应, 开发者工具, 恶意软件分析, 持久化检测, 数字取证, 数据包嗅探, 文本分析, 无后门, 漏洞防御, 网络安全, 自动化检测, 自动化脚本, 逆向工具, 隐私保护