dod-cyber-crime-center/DC3-MWCP
GitHub: dod-cyber-crime-center/DC3-MWCP
DC3-MWCP 是由美国国防网络犯罪中心开发的恶意软件配置解析框架，旨在标准化恶意软件配置信息的提取、开发和共享流程。
Stars: 343 | Forks: 64
# DC3-MWCP
[更新日志](CHANGELOG.md) | [发布版本](https://github.com/Defense-Cyber-Crime-Center/DC3-MWCP/releases)
DC3 恶意软件配置解析器 (DC3-MWCP) 是一个用于从恶意软件中提取配置信息的框架。
从恶意软件中提取的信息包括地址、密码、文件名以及互斥体 (mutex) 名称等项目。通常情况下，每个恶意软件家族都会创建一个对应的解析器模块。
DC3-MWCP 旨在帮助确保解析器功能和输出的一致性，简化解析器的开发过程，并促进解析器的共享。DC3-MWCP 支持分析师主导的分析以及大规模的自动化执行，可通过原生的 Python API、REST API 或提供的命令行工具来实现。DC3-MWCP 由国防网络犯罪中心 (DC3) 编写。
- [安装](#install)
- [内置解析器](#builtin-parsers)
- [Dragodis 支持](#dragodis-support)
- [DC3-Kordesii 支持](#dc3-kordesii-support)
- [用法](#usage)
- [CLI 工具](#cli-tool)
- [REST API](#rest-api)
- [Python API](#python-api)
- [Schema](#schema)
- [STIX 输出](#stix-output)
- [YARA 匹配](#yara-matching)
- [辅助工具](#helper-utilities)
### 指南
- [解析器开发](docs/ParserDevelopment.md)
- [解析器组件](docs/ParserComponents.md)
- [解析器安装](docs/ParserInstallation.md)
- [解析器测试](docs/ParserTesting.md)
- [Python 风格指南](docs/PythonStyleGuide.md)
- [Malstruct 教程](docs/malstruct.ipynb)
- [风格指南](docs/PythonStyleGuide.md)
- [测试](docs/Testing.md)
## 安装说明
```
> pip install mwcp
```
或者，你可以克隆此仓库并在本地安装。
```
> git clone https://github.com/Defense-Cyber-Crime-Center/DC3-MWCP.git
> pip install ./DC3-MWCP
```
如果在开发模式下使用，请使用 `-e` 标志以可编辑模式安装：
```
> git clone https://github.com/Defense-Cyber-Crime-Center/DC3-MWCP.git
> pip install -e ./DC3-MWCP
```
## 内置解析器
DC3-MWCP 包含一些内置的[解析器](./mwcp/parsers)，帮助你快速入门。
这些解析器可以按原样使用、作为子类继承，或者包含在你自己的解析器组中。
要查看可用的解析器：
```
$ mwcp list
```
解析器安装在 `dc3` 源名称下。要将它们包含在组中，只需添加带有 `dc3:` 前缀的名称即可。
```
SuperMalware:
description: SuperMalware component
author: acme
parsers:
- dc3:Archive.Zip
- .Dropper
- .Implant
- dc3:Decoy
```
## Dragodis 支持
如果已安装，DC3-MWCP 可选择支持 [Dragodis](https://github.com/Defense-Cyber-Crime-Center/Dragodis)。
这允许你通过 `mwcp.FileObject` 对象上的 `.disassembly()` 函数，获取一个与反汇编工具无关的接口，用于解析文件的反汇编代码。
你可以通过在相应的安装命令中添加 `[dragodis]`，将 Dragodis 与 DC3-MWCP 一起安装：
```
pip install mwcp[dragodis]
pip install ./DC3-MWCP[dragodis]
pip install -e ./DC3-MWCP[dragodis]
```
安装后，请务必按照 Dragodis 的[安装说明](https://github.com/Defense-Cyber-Crime-Center/Dragodis/blob/master/docs/install.rst)来设置后端反汇编工具。
*建议也安装 [Rugosa](https://github.com/Defense-Cyber-Crime-Center/rugosa)，以利用 Dragodis 实现模拟执行和正则表达式/YARA 匹配功能。*
## DC3-Kordesii 支持
如果已安装，DC3-MWCP 可选择支持 [DC3-Kordesii](https://github.com/Defense-Cyber-Crime-Center/kordesii)。
这将允许你通过 `mwcp.FileObject` 对象上的 `run_kordesii_decoder` 函数运行任何 DC3-Kordesii 解码器。
你可以通过在相应的安装命令中添加 `[kordesii]`，将 DC3-Kordesii 与 DC3-MWCP 一起安装：
```
pip install mwcp[kordesii]
pip install ./DC3-MWCP[kordesii]
pip install -e ./DC3-MWCP[kordesii]
```
## 用法
DC3-MWCP 旨在简化恶意软件配置解析器的开发和使用。同时，它也确保这些解析器具有可扩展性，并且能够被集成到其他系统中。
大多数自动化处理系统会使用一个条件（例如 YARA 签名匹配）来触发 DC3-MWCP 解析器的执行。
DC3-MWCP 提供了 3 种集成选项：
- CLI：`mwcp`
- REST API：`mwcp serve`
- Python API
DC3-MWCP 还包含用于生成和执行测试用例的工具。
### CLI 工具
DC3-MWCP 可以直接通过命令行使用 `mwcp` 命令来运行。
```
> mwcp parse foo ./README.md
----- File: README.md -----
Field Value
------------ ----------------------------------------------------------------
Parser foo
File Path README.md
Description Foo
Architecture
MD5 b21df2332fe87c0fae95bdda00b5a3c0
SHA1 8841a1fff55687ccddc587935b62667173b14bcd
SHA256 0097c13a3541a440d64155a7f4443d76597409e0f40ce3ae67f73f51f59f1930
Compile Time
Tags
---- Socket ----
Tags Address Network Protocol
------ --------- ------------------
127.0.0.1 tcp
---- URL ----
Tags Url Address Network Protocol Application Protocol
------ ---------------- --------- ------------------ ----------------------
http://127.0.0.1 127.0.0.1 tcp http
---- Residual Files ----
Tags Filename Description MD5 Arch Compile Time
------ ----------------- ------------------- -------------------------------- ------ --------------
fooconfigtest.txt example output file 5eb63bbbe01eeed093cb22bb8f5acdc3
---- Logs ----
[+] File README.md identified as Foo.
[+] size of inputfile is 15560 bytes
[+] README.md dispatched residual file: fooconfigtest.txt
[+] File fooconfigtest.txt described as example output file
[+] operating on inputfile README.md
----- File Tree -----
└──
```
有关完整的选项集，请参见 `mwcp parse -h`
### REST API
DC3-MWCP 可以作为 Web 服务使用。该 Web 服务提供了一个 Web 应用程序以及用于一些常用功能的 REST API：
- `/run_parser/` -- 对上传的文件执行指定的解析器
- `/run_parser` -- 使用 YARA 匹配来确定解析器，对上传的文件执行解析。
- `/descriptions` -- 提供可用解析器的列表
- `/schema.json` -- 提供报告输出的 [schema](#schema)
要使用它，首先通过运行以下命令启动服务器：
```
> mwcp serve
```
然后你可以使用 HTTP 客户端来创建 REST 请求。
#### 参数
`/run_parser` 的 REST API 会接受一些请求参数，用于自定义处理过程和输出结果。
- `data` -- 输入文件的数据。
- `legacy` -- 如果此参数设置为 `True`，将生成旧版 JSON schema 输出。默认使用新 schema。
- *注意：旧版输出最终将在 4.0 版本中被移除。*
- `output` -- 设置解析结果的输出格式。
- `json` -- JSON 格式（这是默认值）
- `zip` -- 生成一个包含结果和提取的残留文件的 ZIP 文件。
- `stix` -- STIX 2.1 JSON 格式
- `include_logs` -- 是否在报告中包含日志。默认为 True。
- `no_file_data` -- 如果此参数设置为 `True`，提取的残留文件的二进制数据将不会包含在报告中。
- `recursive` - 是否使用 YARA 匹配的解析器递归处理未识别的文件。（必须设置 [YARA_REPO](#yara-matching) 才能激活此选项。）
- `external_strings` -- 是否为在每个文件中发现的已报告解码字符串创建外部字符串报告。默认为 False。
- 这些报告将以与残留文件相同的方式返回。
- 启用后，主报告中的字符串将被移除。
- `param`/`parameter` -- 提供外部参数，这些参数将在解析开始前注入到 [`knowledge_base`](./docs/ParserComponents.md#knowledge-base) 中。
- 值应该是用 `:` 分隔的键/值对。（例如 `param="key_name:secret"`）
- 可以多次提供此参数以传递多个参数。
#### 使用 cURL 的示例
```
> curl --form data=@README.md http://localhost:8080/run_parser/foo
```
#### 使用 Python 的示例
```
import requests
req = requests.post("http://localhost:8080/run_parser/foo", files={'data': open("README.md", 'rb')})
req.json()
```
#### 输出示例
默认的解析结果将采用遵循标准化 [schema](#schema) 的 JSON 格式。
```
[
{
"type": "report",
"tags": [],
"input_file": {
"type": "input_file",
"tags": [],
"name": "README.md",
"description": "Foo",
"md5": "80a3d9b88c956c960d1fea265db0882e",
"sha1": "994aa37fd26dd88272b8e661631eec8a5f425920",
"sha256": "3bef8d5dc4cd94c0ee92c9b6d7ee47a4794e550d287ee1affde84c2b7bcdf3cb",
"architecture": null,
"compile_time": null,
"file_path": "README.md",
"data": null
},
"parser": "foo",
"errors": [],
"logs": [
"[+] File README.md identified as Foo.",
"[+] size of inputfile is 15887 bytes",
"[+] README.md dispatched residual file: fooconfigtest.txt",
"[+] File fooconfigtest.txt described as example output file",
"[+] operating on inputfile README.md"
],
"metadata": [
{
"type": "url",
"tags": [],
"url": "http://127.0.0.1",
"socket": {
"type": "socket",
"tags": [],
"address": "127.0.0.1",
"port": null,
"network_protocol": "tcp",
"c2": null,
"listen": null
},
"path": null,
"query": "",
"application_protocol": "http",
"credential": null
},
{
"type": "socket",
"tags": [],
"address": "127.0.0.1",
"port": null,
"network_protocol": "tcp",
"c2": null,
"listen": null
},
{
"type": "residual_file",
"tags": [],
"name": "fooconfigtest.txt",
"description": "example output file",
"md5": "5eb63bbbe01eeed093cb22bb8f5acdc3",
"sha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
"sha256": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9",
"architecture": null,
"compile_time": null,
"file_path": "README.md_mwcp_output\\5eb63_fooconfigtest.txt",
"data": null
}
]
}
]
```
在同一地址也提供了一个简单的 HTML 接口。默认地址为 `http://localhost:8080/`。可以提交单个样本，并将结果保存为 JSON、纯文本或 ZIP 压缩包。
### Python API
DC3-MWCP 可以直接通过 Python 运行。
```
#!/usr/bin/env python
"""
Simple example to demonstrate use of the API provided by DC3-MWCP framework.
"""
# 首先，import mwcp
import mwcp
# register the builtin MWCP parsers 以及系统上安装的所有其他 parser packages
mwcp.register_entry_points()
# register a directory containing parsers
mwcp.register_parser_directory(r'C:\my_parsers')
# view all available parsers
print(mwcp.get_parser_descriptions(config_only=False))
# Call the run() function 来生成一个 mwcp.Report object。
report = mwcp.run("FooParser", file_path=r"C:\input.exe")
# Run on provided data buffer。
report = mwcp.run("FooParser", data=b"lorem ipsum")
# Let MWCP determine parser(s) to run based on YARA match results by excluding the parser。
# （YARA_REPO 应该使用 `mwcp config` 进行 setup 或通过 "yara_repo" argument 传入）
report = mwcp.run(file_path=r"C:\input.exe")
report = mwcp.run(data=b"lorem ipsum")
# Provide external knowledge by supplying a knowledge_base dictionary。
report = mwcp.run("FooParser", file_path=r"C:\input.exe", knowledge_base={"key": "secret"})
# Display report results in a variety of formats：
print(report.as_dict())
print(report.as_json())
print(report.as_text())
print(report.as_markdown())
print(report.as_html())
print(report.as_csv())
print(report.as_dataframe()) # Pandas dataframe object.
print(report.as_stix()) # STIX 2.1 JSON formatted text.
# To get the legacy format use the following：
print(report.as_dict_legacy())
print(report.as_json_legacy())
# You can also programmatically view results of report：
from mwcp import metadata
# display errors that may occur
for log in report.errors:
print(log)
# display data about original input file
print(report.input_file)
# get all url's using ftp protocol or has a query
for url in report.get(metadata.URL):
if url.application_protocol == "ftp" or url.query:
print(url.url)
# get residual files
for residual_file in report.get(metadata.File):
print(residual_file.name)
print(residual_file.description)
print(residual_file.md5)
print(repr(residual_file.data))
# iterate through all metadata elements
for element in report:
print(element)
```
## 配置
所有选项都可以通过 [settings.toml](src/mwcp/config/settings.toml) 文件进行配置。
DC3-MWCP 会在 `~/.config/mwcp/settings.toml` 或 `%LOCALAPPDATA%\dc3\mwcp\settings.toml` 路径下查找用户自定义的配置文件，以覆盖默认设置。
要查看当前配置，请运行以下命令：
```
mwcp config list
```
要编辑配置，请运行以下命令以在文本编辑器中打开该文件。
（这会将默认配置复制到用户目录中）
```
mwcp config edit
```
要在不编辑的情况下创建新的用户配置文件：
```
mwcp config create
```
也可以通过在当前目录下创建 `mwcp.toml` 文件来使用备用配置文件。
此文件比其他设置的优先级更高。
```
echo -e 'keep_tmp = true' > mwcp.toml
mwcp test Foo
```
我们使用 [Dynaconf](https://dynaconf.com)，它提供了诸多便利，例如允许使用带有 `MWCP_` 前缀的环境变量来设置配置。
例如，要设置恶意软件仓库的位置：
```
export MWCP_MALWARE_REPO="/data/malware_repo"
```
## 日志
DC3-MWCP 使用 Python 内置的 `logging` 模块来记录所有消息。
默认情况下，日志记录使用 [log_config.yml](mwcp/config/log_config.yml) 配置文件进行配置。目前，该配置被设置为将所有消息记录到控制台，并将错误消息记录到 `%LOCALAPPDATA%/mwcp/errors.log` 中。
你可以通过将自定义日志配置文件的路径添加到配置参数 `LOG_CONFIG_PATH` 中来提供该文件。
（有关如何编写自定义配置文件的更多信息，请参阅 [Python 文档](http://docs.python.org/dev/library/logging.config.html)。）
在使用 `mwcp` 工具时，你还可以使用 `--verbose` 或 `--debug` 标志来调整日志级别。
## Schema
DC3-MWCP 的主要目标之一是标准化恶意软件配置解析器的输出，使一个解析器产生的数据能够与其他解析器的数据进行对比。这是通过建立一个由标准化元数据元素组成的 schema 来实现的，这些元素代表了在各个恶意软件家族中常见的恶意软件配置项。
你可以在 [schema.json](/mwcp/config/schema.json) 找到正式的 [JSON Schema](https://json-schema.org)，也可以通过在命令行调用 `mwcp schema` 或在编程中调用 `mwcp.schema()` 来获取。
此 schema 与 DC3-MWCP 的版本号保持一致。版本的变化不一定反映实际 schema 的更改。但是，对 schema 所做的任何主要或次要更改都会反映在相应的版本更改中，并记录在[更新日志](/CHANGELOG.md)中。
请确保你适当地固定了所使用的 DC3-MWCP 版本。
我们承认，一组通用元素通常不足以捕捉各个恶意软件家族之间的细微差别。为了确保在解析器输出中适当地捕获恶意软件家族的特定属性，schema 包含了一个 "Other" 元素，该元素支持任意的键值对。
键和值是任意的，允许灵活地描述特定恶意软件家族的特性。
未在抽象的标准化元素中捕获的信息会通过此机制进行捕获。
我们鼓励使用 [标签](/docs/ParserComponents.md#tagging) 来为配置项提供额外的上下文。
例如，如果某个特定的 URL 被用于下载第二阶段组件，则可以向报告的 URL 元素添加 "download" 标签。或者，如果该 URL 被用作代理，则可以包含 "proxy" 标签。
关于有哪些可用标签以及何时应该包含它们，目前尚无统一标准。
这应由你的组织自行决定。
### 扩展 Schema
你可以扩展 schema 以包含自定义的元数据元素。
这可以通过创建一个继承自 `mwcp.metadata.Metadata` 的类来实现。
此类必须使用 [attr](https://attrs.org) 进行装饰，并采用自定义配置 `mwcp.metadata.config`。
*注意：类名必须与其他元数据元素保持唯一。*
```
from typing import List
import attr
import mwcp
from mwcp import metadata
@attr.s(**metadata.config)
class MyCustom(metadata.Metadata):
"""
This is my custom metadata item.
"""
field_a: str
field_b: int
field_c: List[str] = attr.ib(factory=list)
item = MyCustom(field_a="hello", field_b=42, field_c=["a", "b"])
print(item)
print(item.as_dict())
# Custom items can be included in the report like normal。
# MWCP will automatically format and display the custom element in the report。
report = mwcp.Report()
with report:
report.add(item)
print(report.as_text())
```
```
MyCustom(tags=set(), field_a='hello', field_b=42, field_c=['a', 'b'])
{'type': 'my_custom', 'tags': [], 'field_a': 'hello', 'field_b': 42, 'field_c': ['a', 'b']}
---- My Custom ----
Tags Field A Field B Field C
------ --------- --------- ----------
hello 42 a, b
```
请注意，扩展 schema 显然会导致 [schema.json](/mwcp/config/schema.json) 文件变得不正确。
要重新生成包含自定义元素的 schema，请随后运行 `mwcp.schema()`。
```
import json
import mwcp
with open("schema.json", "w") as fo:
json.dump(mwcp.schema(id="https://acme.org/0.1/schema.json"), fo, indent=4)
```
## STIX 输出
MWCP 可以生成适合集成到许多支持 STIX 标准的系统中的 [STIX 2.1](https://www.oasis-open.org/standard/stix-version-2-1/) JSON 输出。除了当前定义的 STIX 对象外，此输出格式还使用了三个 SCO 扩展和一个属性扩展，以便准确传达 MWCP 的扫描结果。
某些工具可能尚不支持这些扩展，这可能导致在导入 MWCP 的 STIX 输出时省略以下数据。以下提供了所用 STIX 对象和扩展的列表，以及它们关联的 MWCP 类：
1. artifact (SCO)
1. File -- 仅在请求原始二进制文件时使用
2. crypto-currency-address (SCO 扩展)
1. CryptoAddress
3. directory (SCO)
1. File
2. Path
3. Service
4. domain-name (SCO)
1. Socket
2. URL
5. email-address (SCO)
1. EmailAddress
6. file (SCO)
1. File
2. Path
3. Service
7. ipv4-address (SCO)
1. Socket
2. URL
8. ipv6-address (SCO)
1. Socket
2. URL
9. malware-analysis (SDO)
1. MWCP 的扫描结果通过一个 malware-analysis 对象绑定在一起，显示输入对象和输出结果
10. mutex (SCO)
1. Mutex
11. network-traffic (SCO)
1. Socket
2. URL
12. note (SDO)
1. Other 中的布尔值和整数值。这些将被添加到 Note 的描述中。
2. 绑定到 SCO 的描述和其他叙述性文本
3. 排除文件之外的 SCO 的标签
13. observed-string (SCO 扩展)
1. DecodedString
2. MissionID
3. Other
4.
5. User Agent
6. UUID
14. process (SCO)
1. Command
2. Service
15. relationship (SRO)
1. DecodedString
2. URL
16. RSA Private Key (x509-certificate 的属性扩展)
1. RSAPrivateKey
17. symmetric-encryption (SCO)
1. EncryptionKey
18. user-account (SCO)
1. Credential
19. url (SCO)
1. URL
20. x509-certificate (SCO)
1. RSAPrivateKey
2. RSAPublicKey
3. SSLCertSHA1
21. windows-registry-key (SCO)
1. Registry2
## YARA 匹配
MWCP 包含一个运行器，可以使用 YARA 匹配结果来确定在给定文件上运行哪个（或哪些）解析器。
无论何时，只要在命令行中使用 `-` 代替指定解析器，或者在 `mwcp.run()` 中未指定解析器，亦或是在服务器请求中未指定解析器，都会使用此功能。
```
$ mwcp parse - input.exe
$ curl --form data=@input.exe http://localhost:8080/run_parser
```
```
import mwcp
mwcp.register_entry_points()
report = mwcp.run(data=b"file data")
```
同时，YARA 匹配将递归用于未识别的残留文件。
如果你想禁用此功能，请在命令行中设置 `--no-recursive`，或在 `mwcp.run()` 中设置 `recursive=False`。
### 设置
要启用 YARA 匹配，你需要指定一个包含 YARA 签名的目录，这些签名使用 `mwcp` 元字段将签名映射到以逗号分隔的解析器列表。解析器的指定方式与在命令行或 Python API 中相同。也就是说，解析器组名称、用于特定解析器组件的 `.` 表示法，以及使用 `:` 指定解析器源都是有效的。
任何没有 `mwcp` 元字段的签名都将被忽略。
```
rule SuperMalware {
meta:
mwcp = "SuperMalware"
...
}
```
要设置 YARA 仓库，请在运行 `mwcp config` 时显示的配置文件中，将 `YARA_REPO` 字段设置为指向包含 YARA 签名的目录（允许包含子目录）。
如果你是从旧版本的 MWCP 升级的，可能需要先备份并删除原始配置文件，然后再次运行 `mwcp config` 让 MWCP 重新创建该文件。
另外，可以在命令行中使用 `--yara-repo` 指定 yara 仓库。但是，要在服务器中使用 YARA 匹配，前一种方法是必须的。
### 测试
在创建测试用例时，可以对未识别的文件进行递归 YARA 匹配。只需在添加新测试用例或更新现有测试用例时包含 `--recursive` 标志即可。
```
$ mwcp test SuperMalware --add="C:\input.exe" --recursive
$ mwcp test SuperMalware -u --recursive
```
一旦创建了启用递归的测试用例，运行你的测试用例的任何人都必须设置一个包含相同 YARA 签名的 YARA 仓库，测试才能通过。
由于这个原因，建议仅在解析器的完整功能依赖于它时，才为测试开启递归。
## 辅助工具
MWCP 附带了一些辅助工具（位于 `mwcp.utils` 中），这些工具在解析恶意软件文件时可能会非常有用。
- `pefileutils` - 提供使用 `pefile` 库执行常见操作的辅助函数。（获取或检查导出、导入、资源、节等）
- `elffileutils` - 提供使用 `elftools` 库执行常见操作的辅助函数。提供类似于 `pefileutils` 的一致接口。
- `custombase64` - 提供使用自定义字母表进行 base64 编码/解码数据的函数。
- `poshdeob` - 一个实验性的 PowerShell 反混淆工具，用于静态反混淆代码并提取字符串。
标签：DAST, DC3-MWCP, Dragodis, Kordesii, Python, REST API, STIX, YARA, YARA匹配, 云资产可视化, 云资产清单, 信息提取, 威胁情报, 开发者工具, 恶意软件分析, 无后门, 网络安全, 自动化分析, 自动化执行, 解析器开发, 跨站脚本, 逆向工具, 逆向工程, 配置解析器, 隐私保护