ThreatHunter

A python malware detection, analysis and reverse ngineering toolkit. This is a Linux command-line interface (CLI) utility that use YARA , Capstone ,Redare2 among otheres to detect analyze and reverse engineer malware. This is still a work in progress version, great things are underway.

---

Table of Contents

1. Features
2. Prerequisites
3. Installation
4. Usage
   • Options
   • Examples
5. Custom Rules
6. Contributing
7. License
8. Acknowledgements

---

Features

• YARA‑powered: Pattern‑based detection using customizable YARA rules.
• Capstone Disassembly: Decode binaries into human‑readable assembly.
• Radare2 Integration: Advanced reverse‑engineering workflows.
• Recursive Scanning: Analyze entire directories or individual files.
• Custom Rule Management: Add or exclusively use specific YARA rule sets.
• Verbose Mode: Detailed output to trace each analysis step.

---

Prerequisites

• Python 3.8+
• pip (Python package manager)
• YARA (often via pip install yara-python or your distro’s package manager)
• Capstone (via pip install capstone)
• Radare2 (installable via apt, brew, or from Radare2’s site)

---

Installation

From PyPI

pip install ThreatHunter

From GitHub (latest development)

pip install git+https://github.com/skye-cyber/ThreatHunter.git

Usage

To run the CLI app, use the following command:

ThreatHunter [OPTIONS]

Replace [options] with the appropriate command-line options.

Options

Flag	Description
-p, --path <file folder>	Path to directory or file to scan
-v, --verbose	Enable verbose output (disables screen-clearing between results)
-a, --add <rule>	Add a custom YARA rule file, directory, or inline rule
-u, --use <rule>	Use only the specified rule (requires --path)
-h, --help	Show full help and exit

Help output

ThreatHunter --help

Examples

1. Scan the Documents directory

Unix

ThreatHunter -p /home/user/Documents/

ThreatHunter -p /home/user/Documents/ -v

win:

ThreatHunter -p \path\toDocuments\

The toolkit will scan all the files and folder in the /home/user/Documents/ directory and it's nested files and folders to the last child. -p also accepts file input

2. Scan working directory

   ThreatHunter

3. Scan current directory in verbose mode

   ThreatHunter -v

Giving no option as in the above case, the toolkit will recursively scan the current directory (working directory)

Adding rule(s) to the existing rules

ThreatHunter --add @foo

where @foo is the rule file, folder or even rule in text form

Using exclusive rule

You may also want to rune scan using a given rule only, that case, you can follow this format

ThreatHunter --use @foo -p

where @foo is the rule file, folder or rule itself. if -u/--use is used, then -p/--path must be provided

Contributing

Feel free to submit any suggestions!

Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request.

License

This project is an open source software. Under GPL-3.0 license

Feel free to modify and customize this template according to your specific project requirements and add any additional sections or information that you think would be helpful for users.

Acknowledgements

YARA – Pattern‑matching engine

Capstone – Disassembly framework

Radare2 – Reverse engineering toolkit

Shields.io – Status badges

GitHub’s README guidelines