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