Hatching Triage Java API client

Hatching provides a sandbox named Triage. The sandbox is free for researchers, where each uploaded sample is made publicly available to others who visit the website. The API of Triage returns JSON values based on models that are outlined in the documentation. Using this documentation, I recreated their API endpoints into a Java library, which one can use to interact with the service. The only prerequisite is to have a functioning account, which can either be a free one or a paid one. One can find the library’s code here. The latest release of the precompiled JAR can be found here.

Below, more information about the library’s architecture, used dependencies, and future work that is already known, is given.

Table of contents

Usage

One can use this API client library in two ways: either as a Maven dependency, or as a generic library. Below, both methods are explained in detail.

Maven

Since the project is Maven based, one can install it in your local Maven repository using the command that is given below, where one has to change the paths. More information can be found on the official Maven website.

mvn install:install-file -Dfile=<path-to-file> -DpomFile=<path-to-pomfile>

To include the project, one has to include it as a dependency in the project’s pom.xml file. Note that it first needs to be installed in the local Maven repository on the machine where the compilation takes place. The XML snippet below can be used to add the most recent version as a dependency.

<dependency>
  <groupId>triageapi</groupId>
  <artifactId>TriageApi</artifactId>
  <version>1.5-stable</version>
  <type>jar</type>
</dependency>

Generic library

Building it as a JAR that includes the dependencies can be done using the command that is given below. One can use this file as a local dependency in any kind of Java project.

mvn clean compile assembly:single

The library’s architecture

Triage’s endpoints only return a value within an object if it is actually present. This way, no unnecessary data is transferred, but it does pose a problem when working with objects in Java, as this would result in NullPointerExceptions. To combat this, I decided to create objects that contain all possible fields, and also ensured that they can always be accessed. The absence of a field in the JSON response means that it is initialised as an empty field in Java.

This design does have the issue that an empty field in a class might be related to the fact that only that field was missing in the response, or because the whole object is empty. To quickly verify this, every object has a built-in check named isEmpty. If this value is set to true, it means that the complete object is empty. If it is false, the fields in the object are partially (or completely) filled.

To create an empty object, simply call the argumentless constructor. If one is using the constructor that contains arguments, the value is set to false.

To parse the incoming JSON in this manner, several parser classes are present. These are grouped into a single class for easy access. This provides the advantage that the code for each parser is managed separately. To avoid having double code within the library, an abstract class is used to contain code that is used in multiple classes.

To use the library, simply create an instance of the TriageApi class with your API key. The boolean in the constructor is used to specify if the account uses Triage’s private or public cloud, which depends on the type of account that you want to use. This class then contains all functions that you need to work with the API.

The return values are either classes that are embedded within the library, which are based upon the models that Triage provides in the documentation, or they are native Java objects, such as a byte array when downloading the raw malware sample from Triage.

The program uses several dependencies, as can be seen in the project’s pom.xml file.

Release notes

Below, links are given to the blogs that contain the version specific release notes. The most recent release is the first link in the list.


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.