Ultru Query

Used to query the Ultru^TM API for threat intelligence via a simple chained query library. Requires an API key and an engagement to perform basic library configuration, after which commands and parameters can be chained in order to deliver effects. Ultru^TM Query is currently intended to be used with the ULTRU API.

Using the Library

Initializing The Ultru^TM Python Library has a simple constructor that requires the API KEY, which can be obtained from the user portal.

import query

query_object = Query("<API KEY>")

Simple Type Query A simple query involves specifying the desired type, see table below the code example for a full list of types. Otherwise, the engagement has to be set using the set_engagement("<engagement>") function. The execute() function must be called before the store(StreamIO) function to execute the query. Finally the store function will accept any io.IOBase derived stream class to either write to a memory text buffer or to a file.

import io
from record_types import Types

string_stream = io.StringIO()
query_object.by_type(Types().USER).set_engagement("demo").execute().store(string_stream)
results = string_stream.read()

The Results object The results object generally has the following structure:

• if the count_only() function is specified, it returns an integer specifying the count of records.
• if the count_only() function is omitted, a list of dictionaries is returned with the data.

Simple Count Query When all that is needed is a simple count of records, chain in the count_only() function to specify the return type. Not also that the all() function was specified. More to that below in the Limit number of records returned.

import io
from record_types import Types

string_stream = io.StringIO()
query_object.by_type(Types().USER).set_engagement("demo").count_only().all().store(string_stream)
results = string_stream.read()

Limit Number of Records returned The default number of records returned in a query is set to a default of 100 records. If more or less records are desired, chain in the set_count(<number>) function to set the number of returned records. Note: the number provided is still constrained by the overall record result size of 1MB. To retrieve all the records in a particular record set, use the all() function.

import io
from record_types import Types

string_stream = io.StringIO()
query_object.by_type(Types().USER).set_engagement("demo").set_count(400).store(string_stream)
results = string_stream.read()

Retrieve a set of records that have a specific score To retrieve records that have a specific Ultru^TM score, use the by_score(score, _type) selector function, which takes in as a parameter a scores.Scores object as well as a record_types.Types object.

import io
from record_types import Types
from scores import Scores

string_stream = io.StringIO()
query_object.by_score(Scores().BENIGN, Types().PROCESS).set_engagement("demo").all().store(string_stream)
results = string_stream.read()

The results object now has a list of all benign processes in the demo engagement.