MalShare API client in Java

MalShare is a free initiative for researchers to share malware samples for research purposes, which can be accessed via the website and via the API. Before open-sourcing this API client, there was no publicly supported Java library. The code can be found on Github. Below, more information on the usage is given, as well as a rationale on the code.

Table of contents


The API client is contained within a single class that depends on Apache’s HTTP Components’s HttpClient and HttpMime.

Building it as a JAR that includes the dependencies can be done using the command that is given below.

mvn clean compile assembly:single

Alternatively, one can simply copy the Java class into the project that one wishes to use it in. The dependencies that are listed above need to be added to the project, which can be done by linking the JARs. Additionally, one can add the dependencies from Maven by adding them in the pom.xml. The group ID, artifact ID and version of the used libraries are given below.

Group ID: org.apache.httpcomponents
Artifact ID: httpclient
Version: 4.5.11
Group ID: org.apache.httpcomponents
Artifact ID: httpmime
Version: 4.5.12

The version of either or both of the dependencies can be outdated, depending on when this post is read.


The MalShareApi object requires the API key in the constructor. The public functions of the class expose the API endpoints. The private functions get and post are used internally for the network connection.

To avoid adding more dependencies, there is no specific JSON object. Instead, JSON values are returned in full in a String object. Parsing this is to be done in the project itself, as there are several known JSON libraries that can be used. A downloaded sample is stored as a byte array, which can be handled as the user sees fit.

To contact me, you can e-mail me at [info][at][maxkersten][dot][nl], send me a PM on Reddit, or DM me on Twitter @Libranalysis.