Hatching Triage API client in Java

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.

Dependencies

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

<!-- https://mvnrepository.com/artifact/org.json/json -->
<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20200518</version>
</dependency>
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.11</version>
    <type>jar</type>
</dependency>
<!-- https://mvnrepository.com/artifact/org.apache.httpcomponents/httpmime -->
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpmime</artifactId>
    <version>4.5.12</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.8.6</version>
</dependency>

Future work

In the future, changes in Triage’s endpoints will also be reflected in updates of this library. This is done on a best effort basis, meaning there can and will be a delay between the creation of new endpoints by Triage and the implementation of those endpoints in this library.

Note that this API client does not include all endpoints that Triage exposes. It does contain the most relevant parts when handling malware samples, as one can upload local samples and retrieve the static and dynamic analysis report, as well as the PCAP(NG) and the kernel monitoring output. Note that the submission of a URL or the fetching of a remote sample is not supported in this API, but is planned to be supported in future releases. The usage of profiles, as well as other segments of the exposed API endpoints are not handled. These might be added in the future.

Based upon further testing during private projects, I will further improve this library and remove bugs. Preliminary testing showed that the core functionality is working, which is why this library is now publicly available for all to use.


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 @LibraAnalysis.