plast — Modular Threat Hunting Tool & Framework

plast ("Programme Libre d’Analyse STatique" in french) is a command-line and heavily modular threat-hunting tool. It comes with several modules that allow processing of multiple data sources, trigger automatic action(s) upon detection and produce customized output.

plast 's engine uses YARA under the hood, leveraged through multiprocessing tasks to perform rule-based detection on multiple types of input.

The main goal of the plast project is to provide an efficient and effortless way to detect indicators of compromise during incident-response operations.

It provides a comprehensive framework that easily allows to add functionalities to the tool in just a few lines of code, without worrying about efficiency and scalability. plast embeds all referenced modules in one single tool, allowing it to be used on the field as a standalone utility.

plast is entirely written in Python 3 which makes it compatible with all GNU/Linux, BSD and macOS distributions. Nevertheless, some minimal dependencies are required.

Note that running plast on Microsoft Windows operating systems is totally untested at the moment.

Getting Started

Follow these steps to get a copy of the project up and running on a live system.

Prerequisites

Follow the steps described below to install the project on your system.

Install the latest Python 3 environment (here using the Debian package management utility apt):

apt install -y python3 python3-pip

If you plan on building a developpement environment, you may also need to install the following package:

apt install -y python3-venv

Note that modules have their own dependencies, and thus may not be listed here (though standard plast module(s) will always raise an error pointing to the missing libraries).

Also, if you plan on compiling hash-based YARA rules, you will need to install the OpenSSL library:

apt install -y libssl-dev

Installation

Installing plast as a system-wide utility is as simple as:

./setup.py install

It might be necessary to chmod u+x setup.py to be able to execute the setup.py file.

To install a basic developpement environment, issue the following commands:

git clone https://github.com/sk4la/plast.git plast
cd plast
python3 -m venv .env
source .env/bin/activate
pip install --upgrade pip && pip install -r REQUIREMENTS

Usage

Manual

Use the following command to display the main help menu:

plast --help

Each Pre module also has a custom help menu that can be called like this (e.g. with the raw module):

plast raw --help

Basic examples

The following command will recursively look for every file in the case directory, process them using the raw module (which basically does nothing but feed the core engine) and feeds the match(es) to every registered Callback and Post module:

plast -ri case -o out raw

One can easily choose which modules will be invoked during processing by setting the --callbacks and --post arguments accordingly:

plast -ri case --callbacks pineapple kiwi --post banana apple orange -o out raw

Modules are called by their basename without extension (e.g. banana for banana.py). Disabled or non-existing modules will be ignored.

Custom plast modules dwell in the framework.modules package.

Not that in cases like below, one may need to add a dummy - before any positional argument to break the previous list-based argument’s parsing:

plast -o out -ri case - raw

Data type inference

In case no positional argument is supplied, plast implements several techniques (based on magic numbers and MIME-type guessing) to infer the data type of the provided evidence(s).

This is useful when one does not necessarily know which preprocessing module to invoke when processing exotic evidence(s).

plast -i $CASES/sample.pdf -o out

See more examples in CONTRIBUTING.adoc.

Adding YARA rulesets

Hmmm, what’s a YARA rule again?

YARA rulesets dwell in the rulesets directory. To add custom YARA rulesets, simply drop any .yar or .yara file(s) to this directory.

Custom rulesets extensions can be added in the YARA_EXTENSION_FILTERS list in the configuration.json file.

See this page to learn how to write custom YARA rules.

Contributing

Everyone is welcome to contribute to the project. I’ll be glad to include community modules to the public repository.

Please refer to the instructions provided in CONTRIBUTING.adoc before submitting pull requests (PR) though.

Similar Projects

The initiative that made me create plast comes from a lack of modular tools in the #threat-hunting field.

Similar projects exist though, including:

FireEye’s IOC Finder (www.fireeye.com/services/freeware/ioc-finder.html): "The FireEye Indicators of Compromise (IOC) Finder is a free tool for collecting host system data and reporting the presence of IOCs."
Nextron’s Loki (github.com/Neo23x0/Loki): "LOKI is an open-source IOC and YARA scanner written in Python."
ioc-finder (github.com/fhightower/ioc-finder)
ELAT (github.com/reed1713/ELAT)
FSF (github.com/EmersonElectricCo/fsf): "FSF is a modular, recursive file scanning solution. FSF enables analysts to extend the utility of the YARA signatures they write and define actionable intelligence within a file. This is accomplished by recursively scanning a file and looking for opportunities to extract file objects using a combination of YARA signatures (to define opportunities) and programmable logic (to define what to do with the opportunity). The framework allows you to build out your intelligence capability by empowering you to apply observations wrought out of the analytical process…"
Kaspersky’s KLara (github.com/KasperskyLab/klara): "KLara project is aimed at helping Threat Intelligence researchers hunt for new malware using YARA."
Laika BOSS (github.com/lmco/laikaboss): "Laika is an object scanner and intrusion detection system that strives to achieve scalability, flexibility and verbosity."
malscan (github.com/usualsuspect/malscan): " malscan is a tool to scan process memory for YARA matches and execute Python scripts if a match is found. This is useful for extracting configurations from malware process memory for example."
Spyre (github.com/DCSO/spyre): "Spyre is a simple YARA scanner, the main goal is easy operationalization of YARA rules. Comprehensive rule sets are not included. Spyre is intended to be used as an investigation tool by incident responders with an appropriate skill level. It is not meant to be used as any kind of endpoint protection service."
stoQ (github.com/PUNCH-Cyber/stoq): "stoQ is an automation framework that helps to simplify the more mundane and repetitive tasks an analyst is required to do. It allows analysts and DevSecOps teams the ability to quickly transition from different data sources, databases, decoders/encoders, and numerous other tasks. stoQ was designed to be enterprise-ready and scalable, while also being lean enough for individual security researchers."
yaraPCAP (github.com/kevthehermit/YaraPcap): "YARA scanner for IMAP feeds and saved streams."
yextend (github.com/BayshoreNetworks/yextend): "YARA-integrated software to handle archive file data. yextend was written for the sake of augmenting YARA. YARA by itself is great but we realized that it could not natively handle archived content in the granular way that we needed it to. For instance, if we were hunting for malware and it happened to be buried a few levels into archived content, YARA in its native form could not help us. So what we have done is natively handle the inflation of archived content. And we pass the inflated content of each discovered resource to YARA so that it can work its magic natively on one file’s payload. Then YARA does what it does quite well in terms of pattern matching and such based on a given set of rules."
yaraprocessor (github.com/MITRECND/yaraprocessor): " yaraprocessor was originally written for Chopshop. Combined with Chopshop, it allows for dynamic scanning of payloads plucked from network packet capture. Historically, signature based tools operate over the entire PCAP file. With Chopshop and yaraprocessor, YARA can be ran against individual packet payloads as well as a concatenation of some or all of the payloads. Ideally, this makes writing signatures easier. Check out the Chopshop module yarashop to see it in action!"

Versioning

Please refer to the current git repository to retrieve the latest version of the project.

Copyright & Licensing

See the LICENSE file for details.

sk4la / plast