Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sk4la/plast

Modular command-line threat hunting tool & framework.
https://github.com/sk4la/plast

apt digital-forensics framework incident-response ioc python python3 threat-hunting yara

Last synced: 3 months ago
JSON representation

Modular command-line threat hunting tool & framework.

Awesome Lists containing this project

README 

        
= +plast+ — Modular Threat Hunting Tool & Framework

Nelson (sk4la) 

:imagesdir: ./resources/rendered

:hide-uri-scheme:

:uri-repo: https://github.com/sk4la/plast

:uri-blob: {uri-repo}/blob/master

:uri-license: {uri-blob}/LICENSE

:uri-contrib: {uri-blob}/CONTRIBUTING.adoc

:uri-python: https://www.python.org

:uri-yara: https://virustotal.github.io/yara/

:uri-framework: {uri-blob}/plast/framework



image:https://img.shields.io/badge/python-3.7-blue.svg[link={uri-python}] image:https://img.shields.io/badge/License-GPLv3-blue.svg[link={uri-license}]



image::logo.png[alt=plast, align="center", width=60%, link={uri-repo}]



`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 {uri-yara}[YARA] under the hood, leveraged through https://docs.python.org/3.7/library/multiprocessing.html[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 https://en.wikipedia.org/wiki/indicator_of_compromise[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 https://www.python.org/[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.



image::usage.png[alt=Usage, align="center", link={uri-repo}]



image::flow.png[alt=Flow, align="center", link={uri-repo}]



== 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 https://www.python.org/[Python 3] environment (here using the Debian package management utility `apt`):



[source,sh]

----

apt install -y python3 python3-pip

----



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



[source,sh]

----

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 https://www.openssl.org/[OpenSSL] library:



[source,sh]

----

apt install -y libssl-dev

----



=== Installation



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



[source,sh]

----

./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:



[source,sh,subs="attributes"]

----

git clone {uri-repo}.git plast

cd plast

python3 -m venv .env

source .env/bin/activate

pip install --upgrade pip && pip install -r REQUIREMENTS

----



== Usage



image::usage.png[alt=Usage, align="center", link={uri-repo}]



=== Manual



Use the following command to display the main help menu:



[source,sh]

----

plast --help

----



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



[source,sh]

----

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:



[source,sh]

----

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:



[source,sh]

----

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:



[source,sh]

----

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).



[source,sh]

----

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

----



See more examples in {uri-contrib}[CONTRIBUTING.adoc].



=== Adding YARA rulesets



Hmmm, https://virustotal.github.io/yara/[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 https://yara.readthedocs.io/en/v3.7.1/writingrules.html[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 {uri-contrib}[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 https://github.com/search?q=%23threat-hunting[#threat-hunting] field.



Similar projects exist though, including:



* FireEye's IOC Finder (https://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 (https://github.com/Neo23x0/Loki): _"LOKI is an open-source IOC and YARA scanner written in Python."_

* ioc-finder (https://github.com/fhightower/ioc-finder)

* ELAT (https://github.com/reed1713/ELAT)

* FSF (https://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 (https://github.com/KasperskyLab/klara): _"KLara project is aimed at helping Threat Intelligence researchers hunt for new malware using YARA."_

* Laika BOSS (https://github.com/lmco/laikaboss): _"Laika is an object scanner and intrusion detection system that strives to achieve scalability, flexibility and verbosity."_

* malscan (https://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 (https://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 (https://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 (https://github.com/kevthehermit/YaraPcap): _"YARA scanner for IMAP feeds and saved streams."_

* yextend (https://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 (https://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



Copyright (c) 2018 Nelson (sk4la). Free use of this software is granted under the terms of the GNU GPLv3 license.



See the {uri-license}[LICENSE] file for details.