Obtaining malware samples to analyse can be quite difficult at times, depending on the type of access that one has. Several free online malware sample databases exist, but visiting them one by one to check if a specific sample is present, is a tedious and time consuming task. MalPull is created to automate the search on multiple platforms, and download the requested sample from the sample database that contains the sample. The program’s source code and precompiled Java Archive and can be found on GitHub. The latest release is also available on GitHub.
MalPull uses the API of MalShare, Malware Bazaar, and Koodous to search for a sample based on a given MD-5, SHA-1, or SHA-256 hash. Both MalShare and Koodous require an API key that can be obtained by creating a free account. Since Koodous’ free API is quite limited, it is queried as last.
To run the program, one needs a recent version of the Java Runtime Environment. It has been tested with OpenJRE 8, but the code is not dependent on a specific Java version. MalPull requires no further installation, as the dependencies are embedded within the JAR. The required command-line arguments provide the API keys, hash, and the sample’s output location.
The compilation for this project is done using Maven. To compile the Java code with its dependencies, one can use the command that is given below. Note that the current working directory needs to be in the MalPull folder for the exact command to work.
mvn clean compile assembly:single
After the compilation, the compiled JAR is placed inside the target folder.
To use MalPull, one has to provide four command line arguments. The first two are the API keys for MalShare and Koodous, respectively. The third argument is the hash to look for, which should be a MD-5, SHA-1, or SHA-256 hash. The fourth, and last, argument that is required, is the path and file name for the requested sample. An example on how to run MallPull is given below.
java -jar /path/to/MallPull.jar MalShareKey KoodousKey hash /path/to/save/the/sample.bin
Note that the output location will be overwritten without warning if the file already exists.
Below, a list of planned updates is given in no apparent order:
- Optionally store API keys in a config file
- Save the sample in the provided folder with the file name equal to the given hash, if no file name is specified
- Optionally save the sample in a password protected ZIP archive
- Add more malware database repositories (such as URLHaus)
- Minmise the amount of API calls to avoid hitting the rate limit
In the list below, all changes are kept together with the release date of the given version.
1.0-stable [6th of April 2020]