DC3 Malware Configuration Parser (DC3-MWCP) is a framework for parsing configuration information from malware. The information extracted from malware includes items such as addresses, passwords, filenames, and mutex names. A parser module is usually created per malware family. DC3-MWCP is designed to help ensure consistency in parser function and output, ease parser development, and facilitate parser sharing. DC3-MWCP supports both analyst directed analysis and large-scale automated execution, utilizing either the native python API, a REST API, or a provided command line tool. DC3-MWCP is authored by the Defense Cyber Crime Center (DC3).
pip install mwcp
By default, only the dependencies needed to run the base framework are installed. To use the builtin parsers or specific features the optional dependencies may need to be installed:
pip install mwcp[server,parsers,patool,dragodis,kordesii] # installs everything
DC3-MWCP includes a handful of builtin parsers to get you started. These can be used as-is, subclassed, or included in your own parser groups.
To use the builtin parsers, you must ensure the parsers extra is installed:
pip install mwcp[parsers]
To view the available parsers:
mwcp list
Parsers are installed under the dc3 source name. To include them in a group simply add them with
the dc3: prefix.
SuperMalware:
description: SuperMalware component
author: acme
parsers:
- dc3:Archive.Zip
- .Dropper
- .Implant
- dc3:Decoy
DC3-MWCP optionally supports Dragodis
if it is installed. This allows you to obtain a disassembler agnostic interface for parsing
the file's disassembly from the mwcp.FileObject object with the .disassembly() function.
You can install Dragodis along with DC3-MWCP by adding [dragodis] to your appropriate install command:
pip install mwcp[dragodis]
After installation make sure to follow Dragodis's installation instructions to setup a backend disassembler.
It is recommended to also install Rugosa for emulation and regex/yara matching capabilities using Dragodis.
DC3-MWCP optionally supports DC3-Kordesii
if it is installed. This will allow you to run any DC3-Kordesii decoder from the
mwcp.FileObject object with the run_kordesii_decoder function.
You can install DC3-Kordesii along with DC3-MWCP by adding [kordesii] to your appropriate install command:
pip install mwcp[kordesii]
DC3-MWCP is designed to allow easy development and use of malware config parsers. DC3-MWCP is also designed to ensure that these parsers are scalable and that DC3-MWCP can be integrated in other systems.
Most automated processing systems will use a condition, such as a yara signature match, to trigger execution of an DC3-MWCP parser.
There are 3 options for integration of DC3-MWCP:
mwcpmwcp serveDC3-MWCP also includes a utility for test case generation and execution.
DC3-MWCP can be used directly from the command line using the mwcp command.
> 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 -----
<README.md (b21df2332fe87c0fae95bdda00b5a3c0) : Foo>
└── <fooconfigtest.txt (5eb63bbbe01eeed093cb22bb8f5acdc3) : example output file>
see mwcp parse -h for full set of options
DC3-MWCP can be used as a web service. The web service provides a web application as well as a REST API for some commonly used functions:
/run_parser/<parser> -- executes a parser on uploaded file/run_parser -- executes a parser on uploaded file using YARA matching to determine the parser./descriptions -- provides list of available parsers/schema.json -- provides the schema for report outputThe server requires mwcp to be installed with the server extra:
pip install mwcp[server]
To use, first start the server by running:
mwcp serve
Then you can either use an HTTP client to create REST requests.
The REST API for /run_parser will accept a number of request parameters for customizing the processing and output results.
data -- The input file data.legacy -- If this argument is set to True, the legacy JSON schema output will be produced. Defaults to the new schema.output -- Sets the output format for parsing results.json -- JSON format (this is the default)zip -- Generates a ZIP file containing results and extracted residual files.stix -- STIX 2.1 JSON formatinclude_logs -- Whether to include logs in the report. Defaults to True.no_file_data -- If this argument is set to True, binary data for extracted residual files won't be included in the report.recursive - Whether to recursively process unidentified files with YARA matched parsers. (YARA_REPO must be setup for this option to be active.)external_strings -- Whether to create external string reports for reported decoded strings found in each file. Defaults to False.param/parameter -- Provides external parameters which will be injected into the knowledge_base before parsing starts.:. (e.g. param="key_name:secret")> curl --form data=@README.md http://localhost:8080/run_parser/foo
import requests
req = requests.post("http://localhost:8080/run_parser/foo", files={'data': open("README.md", 'rb')})
req.json()
The default parsing results will be in JSON format following the standardized schema.
[
{
"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
}
]
}
]
A simple HTML interface is also available at the same address. By default this
is http://localhost:8080/. Individual samples can be submitted and results
saved as JSON, plain text, or ZIP archives.
DC3-MWCP can be run directly from Python.
#!/usr/bin/env python
"""
Simple example to demonstrate use of the API provided by DC3-MWCP framework.
"""
# first, import mwcp
import mwcp
# register the builtin MWCP parsers and any other parser packages installed on the system
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 to generate a 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 should be setup with `mwcp config` or passed in with "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)
All options are configurable through a settings.toml file.
DC3-MWCP looks for a user defined configuration file at either ~/.config/mwcp/settings.toml or %LOCALAPPDATA%\dc3\mwcp\settings.toml
to overwrite the default settings.
To view the current configuration run the following:
mwcp config list
To edit the configuration run the following to open the file in a text editor. (This will copy the default configuration into a user directory)
mwcp config edit
To create a new user configuration file without ed
$ claude mcp add DC3-MWCP \
-- python -m otcore.mcp_server <graph>