This project has the following dependencies that cannot be installed via Python:
- Poetry - Dependency management for Python (https://python-poetry.org/)
- Radare2/Rizin - Reverse Engineering Framework (https://rada.re/ / https://rizin.re/)
- libfuzzy-dev
Required for M2Crypto:
- libssl-dev
- swig
- python3-dev
- gcc
For the Zeek plugin:
For the Bulk Extractor plugin:
NB: Support for Rizin is still new and has not been fully tested.
Clone the repository with GIT using the following command:
git clone --recurse-submodules https://github.com/WithSecureLabs/deject.git
In the deject folder run:
poetry install
This should install the Python dependencies and create a new virtual environment for Deject.
Run Deject by typing the following command in the Deject directory:
poetry run deject
To run the tests, to check that Deject is working correct, use the following command in the Deject directory:
poetry run pytest
If the above command fails on the M2Crypto Python package, install the following dependancies:
libssl-dev swig python3-dev gcc
(these are the package names for Debian, if using RedHat names might be different.)
Install Zeek from via a package manager (https://docs.zeek.org/en/master/install.html) or from source (https://github.com/zeek/zeek).
Run ln -s /path/to/zeek bin/zeek to link the Zeek binary in the bin directory for the Zeek plugin to find it.
This is only needed if you want to run the Zeek plugin to analyse pcap files.
To list the available plugins: poetry run deject plugins
In the deject folder run poetry run deject run <path to memory dump>
To run only a single plugin use the --include <plugin name> option.
Some plugins require an argument, place this after the memory dump, such as:
--include pe_hashes <path to memory dump> <base_addr>
To provide an argument starting with a - or more than one argument to the application, use quotes:
--include cobaltstrike_check <path to memory dump> " -J "--include pe_sections <path to exe> "carve .text"
To provide a unified environment a Dockerfile is provided.
Buildx is the suggested client, install buildx from https://docs.docker.com/build/install-buildx/ (documentation: https://github.com/docker/buildx#linux-packages). (On Debian run apt-get install docker-buildx-plugin)
Running docker buildx install makes Buildx the default build client (this only needs to be done once.)
docker buildx install
docker build --tag deject .
cd dir/with/malware
docker run -v "$PWD":/work --tty deject --include pdf_object /work/<file> <object>
If you want to test Deject but don't have any malware, you can download malware samples from: https://github.com/jstrosch/malware-samples Beware that these are live samples, use at your own risk.
Documentation can be generated using Doxygen (https://github.com/doxygen/doxygen) by using the following command:
doxygen deject-docs
This will output HTML pages to the docs/ directory.
For plugins that require a VirusTotal API key, set a VT_KEY environment variable:
set VT_KEY=<vtapi>
The default Yara rule repository is located at scripts/yara-rules. To use a different set of Yara rules, set the RULES environment variable:
set RULES=<path/to/yara/rules>
The default location for Zeek is the bin/ directory. This can be changed using the ZEEK_PATH environment variable:
set ZEEK_PATH=</path/to/zeek>`
You will need to install Zeek separately.
The default location for Bulk Extractor is the bin/ directory. This can be changed using the BULK_PATH environment variable:
set BULK_PATH=</path/to/bulk_extractor>
You will need to install Bulk Extractor separately.
- https://www.forrest-orr.net/post/masking-malicious-memory-artifacts-part-ii-insights-from-moneta
- https://github.com/jstrosch/malware-samples
- Didier StevenS (1768.py and pdftool/pdfid/pdf-parser)
- Chepy
- mwcfg-modules
- Malduck
- Radare2/Rizin
- Yara
- KaitaiStruct
- Protections Artifacts (Elastic)
- pefile
- dc3-mwcp
- minidump