inhale - A malware analysis and classification tool.

项目说明

Inhale - Malware Inhaler

Inhale is a malware analysis and classification tool that is capable of automating and scaling many static analysis operations.

This is the beta release , for testing purposes, feedback, and community de.

Background

Inhale started as a series of small scripts that I used when collecting and analyzing a large amount of malware from diverse sources.
There are plenty of frameworks and tools for doing similar work, but none of them really matched my work flow of quickly finding,
classifying, and storing information about a large number of files. Some also require expensive API keys and other services that cost money.

I ended up turning these scripts into something that people can quickly set up and use, whether you run from a research server, a laptop,
or a low cost computer like a Raspberry Pi.

Install

This tool is built to run on Linux using Python3, ElasticSearch, radare2, yara and binwalk. jq is also needed to pretty print output from the database. Here are some of the basic instructions to install.

There's a bunch of things in the config.yml file that aren't actually set up yet, just leave them be unless otherwise stated in this documentation.

Python3

Install requirements

python3 -m pip install -r requirements.txt

Installing ElasticSearch (Debian)

A database is not required to use Inhale, but if you would like to set one up, just follow these instructions and set the config.yml option "enable_database" to True.

Documentation

wget -qO - | sudo apt-key add -
sudo apt-get install apt-transport-https
echo "deb stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list
sudo apt-get update && sudo apt-get install elasticsearch
sudo service elasticsearch start

You can also install manually by following this documentation

Additionally you can set up a full ELK stack for and data analysis purposes. It is not necessary for using this tool.

Installing radare2

It's important to install radare2 from the repo, and not your package manager. Package manager don't come with all the bells and whistles required for inhale.

git clone
cd radare2
sys/install.sh

Installing Yara

Documentation

sudo apt-get install automake libtool make gcc
wget
tar xvzf v3.10.0.tar.gz
cd yara-3.10.0/
./bootstrap.sh
./configure
make
sudo make install

If you get any errors about shared objects, try this to fix it.

sudo sh -c 'echo "/usr/local/lib" >> /etc/ld.so.conf'
sudo ldconfig

Installing binwalk

It's most likely best to simply install binwalk from the repo.

git clone
cd binwalk
sudo python3 setup.py install

More information on installing additional features for binwalk is located here.

Installing telfhash/tshl

This is a library that hashes sections of ELF files for malware family analysis. telfhash relies on tlsh, so instructions for installing both are as follows:

Set up tlsh

git clone
cd tlsh
./make.sh
cd py_ext/
python3 ./setup.py build
sudo python3 ./setup.py install

Set up telfhash

git clone
cd telfhash
sudo python3 setup.py install

Setting up web server

If you want to use a web server to host inhale output to share, set the in config.yml to the appropriate paths, and make sure that the directories exist!

web:
gen_html: False
webdir: "/var/www/html/" # The actual web directory
fqdn: " # Your website
in_path: "/var/www/html/inhaled/" # The path to inhale output
ex_path: "/var/www/html/exhaled/" # The path for db query cache output

To use html output, run inhale like this:

python3 inhale.py [all your args here] --html

Usage

Specify the file you are scraping by type:

-f INFILE Analyze a single file
-d DIRECTORY Analyze a directory of files
-u URLFILE Analyze a remote file (url)
-r RDIRECTORY Analyze a remote directory (url)
-l URLLIST Analyze a list of URLs in a text file

Other options:

-t TAGS Add additional tags to the output.
-b Turn off binwalk signatures
-y YARARULES Specify custom Yara Rules
-o OUTDIR Store scraped files in specific output dir (default: ./files/<date>/)
-i Just print info, don't add files to database
--html Sa as html to the webdir.

Examples

Running inhale.py will perform all of the analysis on a given file/directory/url and print it to your terminal.

View info on /bin/ls, but don't add to the database

python3 inhale.py -f /bin/ls -i

Add directory 'malwarez' to database

python3 inhale.py -d malwarez/

Download this file and add to the database

python3 inhale.py -u

Download e in this remote directory, tag it all as "phishing":

python3 inhale.py -r -t phishing

PROTIP: Use this Twitter hashtag search to find interesting open directories that possibly contain malware. Use at your own risk.

Yara

You can pass your own yara rules with -y, this is a huge work in progress and almost e in "YaraRules" is from Shoutout @Ke

Querying the Database

Use db.sh to query (Soon to be a nice script)

db.sh *something* | jq .

Data Model

The following is the current data model used for the elasticsearch database. Not every one of these will be used for every given file. Any r2_* tags are typically reserved for binaries of some sort.

| Name | Description |
| ----------- |-----------------------------|
| filename | The full path of the binary |
| file_ext | The file extension |
| filesize | The file size |
| filetype | Filetype based on magic value. Not as reliable as binwalk signatures. |
| md5 | The files MD5 hash |
| sha1 | The files SHA1 hash |
| sha256 | The files SHA256 hash |
| added | The date the file was added |
| r2_arch | Architecture of the binary file |
| r2_baddr | The binary's base address |
| r2_binsz | The size of the program code |
| r2_bits | Architecture bits - 8/16/32/64 etc. |
| r2_canary | Whether or not stack canaries are enabled |
| r2_class | Binary Class |
| r2_compiled | The date that the binary was compiled |
| r2_dbg_file | The debug file of the binary |
| r2_intrp | The interpreter that the binary calls if dynamically linked |
| r2_lang | The language of the source code |
| r2_lsyms | Whether or not there are debug symbols |
| r2_machine | The machine type, usually means the CPU the binary is for |
| r2_os | The OS that the machine is supposed to run on |
| r2_pic | Whether or not there is Position Independent Code |
| r2_relocs | Whether or not there are relocations |
| r2_rpath | The run-time search path - if applicable |
| r2_stripped | Whether or not the binary is stripped |
| r2_subsys | The binary's subsystem |
| r2_format | The binary format |
| r2_iorw | Whether ioctl calls are present |
| r2_type | The binary type, whether or not it's an executable, shared object etc. |
| yara | Contains a list of yara matches |
| binwalk | Contains a list of binwalk signatures and their locations in the binary |
| tags | Any user defined tags passed with the -t flag. |
| url | The origin url if a file was remotely downloaded |
| urls | Any URLs that have been pulled from the binary |

Solutions to Issues

There are some known issues with this project (mainly to do with from package managers), and here I will track anything that has a solution for it.

ElasticSearch index field limit

If you get an error like this:

elasticsearch.exceptions.RequestError: RequestError(400, 'illegal_argument_exception', 'Limit of total fields [1000] in index [inhaled] has been exceeded')

You may have an older of elasticSearch. You can upgrade, or you can increase the fields limit with this one liner.

curl -XPUT 'localhost:9200/inhaled/_settings' -H 'Content-Type: application/json' -d'{ "index" : { "mapping" : { "total_fields" : { "limit" : "100000" }}}}'

Future Features

* Re-doing the bot plugin for Discord / Matrix
* Additional binary analysis features - pulling import/export tables, hashing of specific structures in the header, logging all strings etc. Some implemented in telfhash!
* Checking if the file is the database before adding. This feature was remo due to specific issues with older of ES.
* Configuration options for requests such as: user agent, timeout, proxy etc.
* Dockerization of this entire project.

Contribution

PRs are welcome! If you want to gi feedback, you can also DM me on Twitter.

Thanks

I'd like to thank e who helped to test this tool with me. I'd also like to thank Plazmaz for doing an initial sweep of the code to make it a bit neater.

Greetz to: hermit, plazmaz, nux, x0, dustyfresh, aneilan, sshell, readme, dnz, notdan, rqu, specters, nullcookies, ThugCrowd, and e in with ThreatLand and the TC Safari Zone.

项目信息

开发语言：Python

Star 数：191

技术要点

该项目属于病毒分析方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A malware analysis and classification tool.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。