Hatching Triage Java API client version 1.2 release notes

The last release of the Java API client was published on the 23rd of December 2020, as can be read here. In this release, several features have been added. Below, the changes are explained in detail. One can find the library’s code here. The latest release of the precompiled JAR can be found here.

Table of contents

Uploading samples

In the older versions, only the uploadSample function was present. In the new version, one can also upload all files within a given folder, using uploadFolder. This excludes folders (and their content) in the given folder, meaning there is no recursive crawler present.

To increase the ease of use of the API, the new upload function can handle a Java File object that points to either a file or a folder. This makes the uploadSample and uploadFolder technically redundant, but both have been kept within the API to allow the user to choose whatever method they prefer. The old and new function signatures are given below.

//Old
public FileUploadResult uploadSample(File file) throws IOException
//New
public List<FileUploadResult> upload(File object) throws IOException
public List<FileUploadResult> uploadFolder(File folder) throws IOException

Downloading samples

Previously one could only download a sample based on a given sample ID in the form of a string. As one can find the Triage ID in several objects, additional methods have been added to increase the ease of use of the API. One can now use the downloadSample function with a TriageReport, Sample, and TargetDesc object.

Additionally, one can provide a list of any of these objects (including the prior added String option) to download samples in bulk. The returned value is a mapping, where the key is the Triage ID of the sample, and the value for the key is a boxed byte array. The function signatures are given below.

//Old
public byte[] downloadSample(String sampleId) throws IOException
//New
public byte[] downloadSample(TriageReport report) throws IOException
public byte[] downloadSample(Sample sample) throws IOException
public byte[] downloadSample(TargetDesc targetDesc) throws IOException
public Map<String, Byte[]> downloadSamples(List<String> sampleIds) throws IOException
public Map<String, Byte[]> downloadSamples(TriageReport[] reports) throws IOException
public Map<String, Byte[]> downloadSamples(Sample[] samples) throws IOException
public Map<String, Byte[]> downloadSamples(TargetDesc[] targetDescs) throws IOException

Searching samples

Previously, one could search through the selected cloud (either public or private) using the search functions. These functions always required a query to search for. Optionally, one could provide an offset to obtain more results, and a limit to specify how many samples should be returned at most, with a maximum of 200 per request. Obtaining more than the given limit was possible by using several calls, together with the returned offset.

In the newly added search functions, one has to provide a query, and a timeframe. This timeframe is represented in the form of a LocalDateTime object. The timeframe is the time between the earliest and latest objects. To further increase the ease of use, one can use the function overload that only uses the earliest variable to define a timeframe between now and the earliest given moment.

//New
public List<SearchResultEntry> search(String query, LocalDateTime earliest, LocalDateTime latest) throws IOException
public List<SearchResultEntry> search(String query, LocalDateTime earliest) throws IOException

Future work

This library is not a carbon copy of the endpoints that Triage exposes. Maintenance 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. For now, it looks like most of the useful features are implemented when trying to work with malware and Triage. Requests can always be shared via an issue on the Github repository, as can pull requests.


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.