MalwareHolmes 🔎

Built with ❤️

The Malware Holmes is a Java project that performs analysis by monitoring a file being added to a given folder to detect malicious behavior and potential security risks.

It leverages native code written in C to access low-level capabilities and enhance the analysis process.

NOTE: This tool is tested on a x86-64 windows 11 system, unix-like systems is not supported currently.

🤩 Features

The Malware Analyzer project offers the following features:

Static Analysis: The project performs static analysis on files to identify potential malware and security risks.
PE Analysis: The project allows the analysis of Portable Executable (PE) files commonly found in Windows operating systems.
Signature-based Detection: It utilizes a signature database to match known malware signatures and identify malicious files based on hash values.
Directory Monitoring: The project provides a directory monitoring service that continuously scans a specified directory for new files and analyzes them in real-time.
Native Code Integration: Native C code is integrated using Java Native Interface (JNI) to access low-level capabilities and perform advanced analysis techniques.
Logging: Every file that is added to the monitored directory is logged onto an external txt file which is saved in the directory you ran the program from which helps in machine learning.
Redis: The project uses Redis, an in-memory data structure store as a database for quick and efficient access to data. It uses Redis to store and retrieve malware signatures for file analysis.

Planned but not Implemented yet:

MalwareBaazar API: Implement POST requests to MalwareBaazar API using different queries, so it can check the generated hash of files on its malware hashes database and give informations such as: malware family, yara rules etc... if found.
Advanced Static Analysis: Implement more advanced static analysis such as using disassemblers and run automated analysis on the disassembled PE file and do more static analysis techniques on normal files i.e: pdf, txt etc...
Dynamic Analysis: The project performs dynamic analysis on executable files to identify potential malware and security risks using different techniques such as API Hooking.
Container Protection: The project runs dynamic analysis on executables in an isolated lightweight docker container which prevents any malware execution damage to your host machine.
Integration with email system: Let downloaded attachments from email inbox get saved to a folder and MalwareHolmes monitor it automatically.
Cross-compatibility: Let MalwareHolmes run on both linux and windows systems, change native C compiling to .so instead of .dll for example.

🪐 Prerequisites

In order to run this application, you will need the following:

Redis

Please ensure these are installed and correctly set up before proceeding.

For development/manual building, the following tools are needed:

Java Development Kit (JDK) version 8 or higher

Apache Maven

MinGW gcc compiler

Redis

📝 Usage

Clone the repository:

git clone https://github.com/smadi0x86/MalwareHolmes

You have 3 choices for running this project either by using:

pre-built release
build with a script
manually building it.

Pre-built Version

You can run the pre-built executable (MalwareHolmes.exe) by installing it directly from the releases by clicking here:

https://github.com/smadi0x86/MalwareHolmes/releases/download/Beta_v1.0.0/MalwareHolmes.exe

After downloading the pre-built binary, you can run it like any normal executable by double clicking on it.

Note: When running the exe make sure you have redis setup and running for optimal experience.

Script Build

The project provides a bash script that automates the setup and execution process.

Before running this script, ensure that the following dependencies are installed on your machine:

Java Development Kit (JDK)
Apache Maven
gcc compiler
Docker

To execute the script, open a Git Bash or any bash terminal and navigate to the root directory of the project.

Run the script with the command:

chmod +x auto_run.sh
./auto_run.sh

This script performs several tasks:

Verifies the installation of the necessary dependencies (JDK, Maven, GCC, Docker)
Compiles the C code into DLLs using GCC
Builds the Maven project
Starts a Redis Docker container
Runs the Java application
The script assumes that the JDK is installed under the JAVA_HOME environment variable.

Ensure JAVA_HOME is correctly set to your JDK installation path before running the script.
Please make sure that Docker is running on your machine before you execute the script.

Manual Build

This command builds the project and packages it into a JAR file. The resulting JAR file can be found in the /target directory.

Compiling native C code using gcc:

Move to maven-final-programming-quickpick/src/main/java/Malware/logic/peAnalysis directory on your terminal then run:

gcc -I"C:\Program Files\Java\jdk-19\include" -I"C:\Program Files\Java\jdk-19\include\win32" -shared -o peAnalysis.dll peAnalysis.c pemetaData.c

Move to maven-final-programming-quickpick/src/main/java/Malware/logic/staticAnalysis directory on your terminal then run:

gcc -I"C:\Program Files\Java\jdk-19\include" -I"C:\Program Files\Java\jdk-19\include\win32" -shared -o staticAnalysis.dll staticAnalysis.c

NOTE: Change path based on your jdk version, mine is jdk-19. After that move both dlls to Main.java directory.

Make sure to move the dll generated by the compiler to the same directory of the Main.java (The start of program).

Now to build the project, navigate to the project directory and execute the following command:

mvn clean package

Pull and run the Redis Docker container:

docker run --name some-redis -d -p 6379:6379 redis

This will start a Redis instance on your local machine on port 6379.

After building the project, you can run it using the following command:

java -Djava.library.path="{changeme}\maven-final-programming-quickpick\src\main\java" -jar target/maven-final-programming-quickpick-1.0-SNAPSHOT-jar-with-dependencies.jar

You will be prompted to enter the path of the directory you want to monitor for malware.

♾️ Continuous Integration and Deployment (CI/CD)

The Malware Analyzer project includes CI/CD pipelines for automated building, testing, and analysis. These pipelines are configured using GitHub Actions.

Unit Testing

The unit testing workflow is triggered on each push to the repository. It runs unit tests to ensure the correctness of the implemented methods.

Maven Build

The Maven build workflow is triggered on each push to the repository. It performs the Maven build process for the project.

CodeQL Analysis

The CodeQL analysis workflow is triggered on each push to the repository. It performs static analysis using CodeQL to identify security issues and potential vulnerabilities.

Dependabot

Dependabot is configured to automate the creation of pull requests for any detected security issues or dependency updates. It ensures that your project stays up to date with the latest security patches and dependencies.

These CI/CD pipelines streamline the development process, automating tasks such as building, testing, and code analysis.

These pipelines enable continuous integration, automated testing, and code analysis, providing confidence in the project's stability and security.

🤝 Contributing

Contributions to the Malware Analyzer project are welcome! If you would like to contribute, please follow these steps:

Fork the repository.
Create a new branch for your feature or bug fix.
Make your changes and commit them.
Push your changes to your forked repository.
Open a pull request, describing your changes and the motivation behind them.

📜 License

This project is licensed under the MIT LICENSE

📙 References

http://www.pelib.com/examples.php https://github.com/NtRaiseHardError/Dreadnought https://gist.github.com/RachidAZ/d3c469cde5cf2498a451a7b9ba251b2d

smadi0x86/MalwareHolmes