danielplohmann/mcrit
GitHub: danielplohmann/mcrit
MCRIT 是一个基于 MinHash 算法的二进制代码相似度分析框架，用于简化反汇编函数的相似度估算与恶意代码关系调查。
Stars: 102 | Forks: 14
# 基于 MinHash 的代码关系与调查工具包 (MCRIT)
[](https://github.com/danielplohmann/mcrit/actions/workflows/test.yml)
MCRIT 是一个为了简化 MinHash 算法在代码相似度领域的应用而创建的框架。
它可以用于快速实现“shinglers”，即对反汇编函数的属性进行编码的方法，以便随后通过 MinHash 算法进行相似度估算。
它是专门为处理由 [SMDA](https://github.com/danielplohmann/smda) 生成的反汇编报告而设计的。
## 用法
### Dockerized 用法
我们强烈建议使用完全打包好的 [docker-mcrit](https://github.com/danielplohmann/docker-mcrit)，以实现轻松的部署和使用。
首先，这将确保你拥有所有组件完全兼容的版本，包括用于持久化的数据库和便于交互的 Web 前端。
### 独立用法
单独安装 MCRIT 会需要更多的步骤。
在以下内容中，我们假设主机操作系统为 Ubuntu。
Python 的安装要求列在 `requirements.txt` 中，可以使用以下命令进行安装：
```
# 安装 python 和 MCRIT 依赖
$ sudo apt install python3 python3-pip
$ pip install -r requirements.txt
```
默认情况下，使用 MongoDB 5.0 作为后端，这也是推荐的操作模式，因为它提供了持久的数据存储。
以下命令概述了在 Ubuntu 上的示例安装过程：
```
# 获取 mongodb 签名密钥
$ sudo apt-get install gnupg
$ wget -qO - https://www.mongodb.org/static/pgp/server-5.0.asc | sudo apt-key add -
# 添加包仓库 (Ubuntu 22.04)
$ echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list
# 或添加包仓库 (Ubuntu 20.04)
$ echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list
# 或添加包仓库 (Ubuntu 18.04)
$ echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list
# 安装 mongodb
$ sudo apt-get update
$ sudo apt-get install -y mongodb-org
# 将 mongodb 作为服务启动
$ sudo systemctl start mongod
# 可选：配置在系统启动时启动该服务
$ sudo systemctl enable mongod
```
在进行独立安装时，你可能希望基于克隆的代码库安装 MCRIT 模块，如下所示：
```
$ pip install -e .
```
完成初始安装后，如果需要，MCRIT 可以在没有网络连接的情况下使用。
#### 操作
MCRIT 后端通常分为两个组件：一个提供 API 接口以供交互的服务器，以及一个或多个处理排队任务的 worker。
它们可以在各自独立的 shell 中通过以下命令启动：
```
$ mcrit server
```
和
```
$ mcrit worker
```
默认情况下，REST API 服务器将监听 [http://127.0.0.1:8000/](http://127.0.0.1:8000/)。
## 交互
无论你选择哪种安装方式，一旦运行，你就可以与 MCRIT 后端进行交互了。
### MCRIT Client
我们创建了一个 Python client 模块，它能够处理服务器上所有可用的 endpoint。
此 client 模块的文档目前正在开发中。
### MCRIT CLI
还有一个基于此 client 包的 CLI，示例：
```
# 查询后端中存储数据的一些统计信息
$ mcrit client status
{'status': {'db_state': 187, 'storage_type': 'mongodb', 'num_bands': 20, 'num_samples': 137, 'num_families': 14, 'num_functions': 129110, 'num_pichashes': 25385}}
# 提交一个文件名为 sample_unpacked 的 malware 样本，使用 family 名称 "some_family"
$ mcrit client submit sample_unpacked -f some_family
1.039s -> (architecture: intel.32bit, base_addr: 0x10000000): 634 functions
```
有关 MCRIT CLI 的更详细文档可在[此处](docs/mcrit-cli.md)获取。
### MCRIT IDA 插件
一个 IDA 插件目前也正在开发中。
要使用它，首先创建你自己的 config.py，并根据 MCRIT 实例的部署情况进行必要的更改：
```
cp ./plugins/ida/template.config.py ./plugins/ida/config.py
nano ./plugins/ida/config.py
```
然后只需在 IDA 中运行位于以下位置的脚本：
```
./plugins/ida/ida_mcrit.py
```
### 参考数据
2023 年 7 月，我们开始填充一个 [Github 仓库](https://github.com/danielplohmann/mcrit-data)，其中包含适用于常见编译器和库的、可直接使用的参考数据。
## 版本历史
* 2026-01-13 v1.4.6: 引入了线性 banding 策略，将作为未来版本的默认设置（需要重建整个 index）。
* 2025-12-22 v1.4.5: 修复了一个由于一次性获取多个 FunctionEntries 时发生早期转换而导致的 bug，该 bug 会在某个 function ID 不存在时导致崩溃。
* 2025-12-22 v1.4.4: 无更改，只是将插件移至它们自己的仓库 [mcrit-plugins](https://github.com/danielplohmann/mcrit-plugins)。
* 2025-12-08 v1.4.3: 对 MCRIT IDA 插件 UI 进行了重大改进，后端现在支持仅在选定样本之间进行匹配的更快速交叉匹配任务，以及其他小修复。
* 2025-09-12 v1.4.2: 对控制台客户端进行了易用性改进和 bug 修复（为查询中的结果表提供了规范的 markdown 和强制重新计算选项，加快了目录模式提交的跳过速度）。
* 2025-07-30 v1.4.1: 对唯一匹配的过滤现在优先于分数。
* 2025-06-13 v1.4.0: 更改了计算匹配百分比的方式，现在仅使用可匹配代码与所有代码作为基准。修复了 IDA 插件的 minor 问题。
* 2025-05-22 v1.3.22: McritCLI 现在支持环境变量（`MCRIT_CLI_SERVER` 和 `MCRIT_CLI_APITOKEN`）以及用于设置服务器和 apitoken 的 `.env` 文件 - 感谢 @r0ny123 的建议！
* 2025-03-11 v1.3.21: McritCLI 现在支持通过生成的 worker 进行提交（需要 --worker 标志）。
* 2025-02-26 v1.3.20: 修复了崩溃的 SpawningWorker 未能被正确处理的 bug - 感谢 @yankovs！。
* 2025-02-26 v1.3.18: 为 CLI 添加了服务器和 API token 支持。
* 2024-06-20 v1.3.17: 任务删除和清理现在[更加稳健](https://github.com/danielplohmann/mcrit/pull/77)，并且不会意外清除不需要删除的样本 - @yankovs - 感谢！！
* 2024-05-10 v1.3.16: 队列清理功能已扩展，还可以清除在所有 3 种类型查询（mapped、unmapped、smda）期间上传的文件。
* 2024-04-17 v1.3.15: Worker 类型 `spawningworker` 现在会在 QueueConfig.QUEUE_SPAWNINGWORKER_CHILDREN_TIMEOUT 秒后终止子进程。
* 2024-04-02 v1.3.14: 实验性：引入新的 worker 类型 `spawningworker` - 此变体将像往常一样从队列中消费任务，但会将实际的作业执行推迟到一个单独的（子）进程中，这应该会减少内存分配锁定的问题。
* 2024-04-02 v1.3.13: 在清理队列时，现在还会[删除所有失败的任务](https://github.com/danielplohmann/mcrit/pull/70) @yankovs - 感谢！！
* 2024-03-06 v1.3.12: 修复了一个 bug，该 bug 导致受队列清理保护的近期样本会如 @yankovs 报告的那样出现 key 错误 - 感谢！！
* 2024-02-21 v1.3.10: 升级 SMDA 至 1.13.16，该版本更好地涵盖了另外 200 条转义类别的指令（会影响 MinHashes）。
* 2024-02-16 v1.3.9: 完成并集成了由 @yankovs 提议的自动队列清理功能（默认禁用）- 感谢！！
* 2024-02-15 v1.3.8: 升级 SMDA 以解决 SmdaFunction 中版本识别的问题，修复了 IDA 插件 McritInterface 中的异常打印（感谢 @malwarefrank！！）。
* 2024-02-12 v1.3.5: 重新计算 minhashes 现在将显示正确的百分比（感谢 @malwarefrank！！）。
* 2024-02-02 v1.3.4: IDA 插件中的一个小修复，以避免引用可能未初始化的对象（感谢 @r0ny123！！）。
* 2024-02-01 v1.3.2: 修复：非并行化匹配现在输出[相同的数据格式](https://github.com/danielplohmann/mcrit/pull/63)（感谢 @dannyquist！！）。
* 2024-01-30 v1.3.1: 与 MongoDB 的连接现在已完全[可配置](https://github.com/danielplohmann/mcrit/pull/61)（感谢 @dannyquist！！）。
* 2024-01-24 v1.3.0: 破坏性更新：包含 PicHash 和 MinHash 索引改进的里程碑版本。为了确保完全的向后兼容性，建议重新计算所有哈希。请查看此[迁移指南](https://github.com/danielplohmann/mcrit/blob/main/docs/migration-v1.3.0.md)。
* 2024-01-23 v1.2.26: 将 lief 固定在 0.13.2，以确保固定的 SMDA 保持兼容。
* 2024-01-09 v1.2.25: 确保无论是否存在 `db_state` 和 `db_timestamp`，我们都能提供系统状态。
* 2024-01-05 v1.2.24: 现在支持在 CLI 中使用 "query" 参数，以及紧凑的 MatchingResults（不包含函数匹配信息）以减少文件占用空间。
* 2024-01-03 v1.2.23: 限制最大导出大小，以保护系统免受 OOM 崩溃的影响。
* 2024-01-02 v1.2.22: 引入了带有便捷功能的 UniqueBlocksResult 数据类。
* 2023-12-28 v1.2.21: McritClient 现在支持透传二进制查询匹配。
* 2023-12-28 v1.2.20: 状态现在提供最近一次数据库更新的时间戳。
* 2023-12-13 v1.2.18: 对传递给 getUniqueBlocks 的 sample_ids 进行边界检查。
* 2023-12-05 v1.2.15: 为 Job 对象添加了便捷功能，版本号与 mcritweb 对齐。
* 2023-11-24 v1.2.11: 在升级 SMDA 并引入数据库迁移以通过改进的泛化重新计算 pic + picblock 哈希之前，将 SMDA 固定在 1.12.7 版本。
* 2023-11-17 v1.2.10: 添加了通过 header 字段：`apitoken` 为服务器设置授权 token 的功能；添加了按 job groups 过滤的功能；添加了使孤立任务失败的功能。
* 2023-10-17 v1.2.8: 修复了 job groups 中的一些小问题。
* 2023-10-16 v1.2.6: 汇总了队列统计信息，优化了 Job 分类。
* 2023-10-13 v1.2.4: 将 Queue/Job 删除功能公开到 REST 接口，通过索引和参数化的 mongodb 查询提高了各种队列查找的查询速度。
* 2023-10-13 v1.2.3: 如果 Worker 崩溃，现在会从正在进行的任务中注销（感谢 @yankovs 提供的代码模板）。
* 2023-10-03 v1.2.2: 针对 min/max 样本数的 MatchingResult 过滤（含修复）。
* 2023-10-02 v1.2.0: Virus Bulletin 2023 的里程碑版本。
* 2023-09-18 v1.1.7: Bug 修复：使用 0 个 band 的任务匹配现在会像以前本该有的那样停用 minhash 匹配。同时修复了匹配任务的进度百分比。
* 2023-09-15 v1.1.6: 修复了 BlockMatching 中的 bug，增加了与 Job 对象交互的便捷功能。
* 2023-09-14 v1.1.5: 由于在处理计算繁重的调用时出现不返回调用的问题，暂时停用了 gunicorn 作为默认的 WSGI 处理器。
* 2023-09-14 v1.1.4: BUGFIX：在 `setup.py` 的 `data_files` 中添加了 `requirements.txt`，以确保它对该 package 可用。
* 2023-09-13 v1.1.3: 将一些对性能至关重要的常量提取为可在 MinHashConfig 和 StorageConfig 中配置的参数，修复了批量匹配的进度报告，BUGFIX：将 GunicornConfig 的使用修改为正确的 dataclass。
* 2023-09-13 v1.1.1: 简化了要求 / 设置，针对 Windows 排除了 `gunicorn`（感谢 @yankovs！！）。
* 2023-09-12 v1.1.0: 对于 Linux 部署，MCRIT 现在使用 `gunicorn` 而不是 `waitress` 作为 WSGI 服务器，因为其具有[好得多的性能](https://github.com/danielplohmann/mcrit/pull/39)。由于 gunicorn 需要自己的配置，因此需要提升 minor 版本（感谢 @yankovs！！）。
* 2023-09-08 v1.0.21: McritClient 的所有方法现在都会将 apitokens/usernames 转发给后端。
* 2023-09-05 v1.0.20: 在 SampleEntry、FunctionEntry 存储到 MongoDB 时使用二进制补码表示地址，以解决 BSON 的限制（感谢 @yankovs）。
* 2023-09-05 v1.0.19: 统计信息现在使用一段时间前创建的内部计数器（感谢yankovs）。
* 2023-08-30 v1.0.18: 优化了 LinkHunt 评分和通过 ICFG 关系进行的结果聚类。
* 2023-08-24 v1.0.15: 在 MatchingResult 中集成了链接追踪能力的首次尝试。
* 2023-08-24 v1.0.13: 重建 minhash bands 将不再导致 RAM 使用量激增。移除了冗余的路径检查（感谢 @yankovs）。
* 2023-08-23 v1.0.12: 添加了重建用于索引的 minhash bands 的功能。
* 2023-08-22 v1.0.11: 修复了一个 bug，该 bug 导致在批量导入数据时，`function_name` 没有同时被添加为 `function_label`。
* 2023-08-11 v1.0.10: 修复了一个 bug，该 bug 导致在批量导入数据时，function_id 在将 MinHashes 添加到 bands 之前没有被调整，可能会导致出现不存在的 function_ids。
* 2023-08-02 v1.0.9: IDA 插件现在可以按 block 大小和 minhash 分数进行过滤，优化了布局和用户体验（感谢 @r0ny123 的反馈！！）
* 2023-07-28 v1.0.8: IDA 插件现在可以为远程函数显示彩色图形，并可以为当前查看的函数查询（针对基本块的）PicBlockHashes。
* 2023-06-06 v1.0.7: 扩展了 MatchingResult 上的过滤功能。
* 2023-06-02 v1.0.6: IDA 插件现在可以执行匹配任务、显示其结果并批量导入标签。MatchingResult 的统一化。
* 2023-05-22 v1.0.3: 提高了在 Malpedia 仓库文件夹上使用 MCRIT CLI 时进行路径验证的稳健性。
* 2023-05-12 v1.0.1: 在 IDA 插件的标签导入方面取得了一些进展。在 McritClient 中反映了 MCRITweb 的 API 扩展。
* 2023-04-10 v1.0.0: Botconf 2023 的里程碑版本。
* 2023-04-10 v0.25.0: IDA 插件现在可以针对当前查看的函数执行函数查询。
* 2023-03-24 v0.24.2: McritClient 可以转发 username/apitoken，addJsonReport 现在也是可转发的。
* 2023-03-21 v0.24.0: FunctionEntries 现在可以存储额外的 FunctionLabelEntries，以及提交的用户/日期。
* 2023-03-17 v0.23.0: 现在可以为单个 SmdaFunctions（同步）查询匹配项。
* 2023-03-15 v0.22.0: McritClient 现在支持 apitokens 以及部分功能的原始响应。
* 2023-03-14 v0.21.0: 后端支持更细粒度的过滤。
* 2023-03-13 v0.20.6: 后端支持在 MatchResult 中按分数过滤 family/sample。
* 2023-02-22 v0.20.4: 修复了计算 unique 分数以及访问这些结果的 bug。
* 2023-02-21 v0.20.3: 支持前端功能的实现及结果展示。
* 2023-02-17 v0.20.2: 扩展了 match report 对象以支持前端改进。
* 2023-02-14 v0.20.0: 彻底重构了控制台客户端，以简化与后端的基于 shell 的交互。
* 2023-01-12 v0.19.4: 为 MatchingResults 增加了额外的过滤功能。
* 2022-12-13 v0.19.1: 现在可以要求候选者具备特定（更高）数量的 band 匹配（即降低匹配的模糊性）。
* 2022-12-13 v0.18.x: 支持任意 function ID 的匹配。
* 2022-11-25 v0.18.9: 加速了 Query 匹配。
* 2022-11-18 v0.18.8: 统一了删除和修改的处理，进行了一些小修复。
* 2022-11-13 v0.18.7: 极大地加快了样本删除速度。
* 2022-11-13 v0.18.6: 添加了修改现有样本和 family 信息的功能。
* 2022-11-11 v0.18.2: 升级了匹配过程，现在应该能够更稳健、更高效地处理更大的二进制文件。
* 2022-11-03 v0.18.1: 小修复。
* 2022-11-03 v0.18.0: 唯一块隔离现在也会生成 YARA 规则提案，重构了结果输出。
* 2022-10-24 v0.17.4: 将 setup.py 与 requirements 统一，提高了处理跨任务的内存效率。
* 2022-10-18 v0.17.3: 添加了一个便捷脚本，用于从半结构化文件夹中递归生成 SMDA 报告。
* 2022-10-13 v0.17.2: 通过将需要进行哈希处理的函数分批处理，修复了 MinHash 计算期间潜在的大内存占用（OOM）问题。
* 2022-10-12 v0.17.1: 添加了一个功能，用于安排一个确保已为所有样本/函数计算出 minhashes 的任务。
* 2022-10-11 v0.17.0: 对唯一块的搜索现在是通过 Worker 执行的一个异步任务。
* 2022-10-11 v0.16.0: 来自 MatchQuery 任务的样本现在将与其 Sample/FunctionEntries 存储在一起，以便更好地进行后处理。
* 2022-10-04 v0.15.4: 服务器现在可以显示其版本。
* 2022-09-28 v0.15.3: 解决了较大实例的性能问题，生成用于唯一块的转义指令序列。
* 2022-09-26 v0.15.0: CrossJobs 现已加入后端，开始提供识别样本中唯一基本块的功能。
* 2022-08-29 v0.14.2: 针对部署进行了一些小修复。
* 2022-08-22 v0.14.0: 任务现在可以依赖于其他任务（为将 crossjobs 移至后端做准备），针对任务处理进行了易用性改进。
* 2022-08-17 v0.13.1: 添加了用于性能分析的命令行选项（需要 cProfile）。
* 2022-08-09 v0.13.0: 现在可以对 PicHash 和 PicBlockHash 匹配进行高效直接查询。
* 2022-08-09 v0.12.3: 针对 FamilyEntry 的 Bug 修复
* 2022-08-08 v0.12.2: 针对 XCFG 数据传递的 Bug 修复，添加了缺失的依赖项。
* 2022-08-08 v0.12.0: 集成了高级搜索语法。
* 2022-08-03 v0.11.0: （破坏性更新）Families 现在使用 FamilyEntry 表示。
* 2022-08-03 v0.10.3: 现在默认将函数 xcfg 数据留在数据库中，并通过 REST API 和 McritClient 暴露对其的访问。
* 2022-07-29 v0.10.2: 添加了删除 family 的功能 - 现在默认还为所有函数保留 XCFG 信息。
* 2022-07-12 v0.10.1: 提升了性能。
* 2022-07-12 v0.10.0: （破坏性更新）简化了任务处理。
* 2022-05-13 v0.9.4: 修复了接收提交文件的 bug。
* 2022-05-13 v0.9.3: 对 MatchingResults 进行了进一步更新。
* 2022-05-13 v0.9.2: 在 MatchingResult 中添加了另一个字段和更多便捷功能以实现更好的访问 - 这些对于以前创建的 MatchingResults 来说是破坏性更改。
* 2022-05-05 v0.9.1: 处理二进制提交，针对 minhash 队列进行小修复 - 初始发布。
* 2022-02-09 v0.9.0: 将 PicBlocks 添加到 MCRIT。
* 2022-01-19 v0.8.0: 将 client 和示例迁移到了主要的 MCRIT 仓库中。
* 2021-12-16 v0.7.0: 初始私有版本。
## 致谢与说明
感谢 Steffen Enders 和 Paul Hordiienko 对本项目内部研究原型的贡献！
感谢 Manuel Blatt 对本项目的广泛贡献和重构，以及 client 模块！
欢迎提交 Pull requests！ :)
## 许可证
```
MinHash-based Code Relationship & Investigation Toolkit (MCRIT)
Copyright (C) 2022 Daniel Plohmann, Manuel Blatt
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see
标签：MinHash, Python, 云资产清单, 代码相似度分析, 恶意代码分析, 无后门, 请求拦截, 逆向工具, 逆向工程, 配置文件