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

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.