Ultru Query
Used to query the UltruTM 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. UltruTM Query is currently intended to be used with the ULTRU API.
Using the Library
Initializing The UltruTM 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()
Type | Description | Supported OS |
---|---|---|
AMCACHE | Amcache analysis results | Windows |
DIRECTORY_LISTING | Directory listing results | Linux, Mac, Windows |
ERROR | Any errors encountered in processing and analysis | Linux, Mac, Windows |
FILE | File analysis results | Linux, Mac, Windows |
GROUP | Group analysis results | Linux, Mac, Windows |
HOST | Host analysis results | Linux, Mac, Windows |
LOG | Log analysis results | Linux, Mac, Windows |
MEMORY_MAP | Analysis of loaded modules | Linux, Mac, Windows |
PERSISTENCE | Analysis of persistent threats | Linux, Mac, Windows |
PREFETCH | Analysis of prefetch | Windows |
PROCESS | Analysis of processes | Linux, Mac, Windows |
PROFILE | Analysis of profiles | Windows |
RUN_INFO | Information regarding a scan | Linux, Mac, Windows |
SERVICE | Analysis of services | Windows |
SHIMCACHE | Analysis of shimcache | Windows |
USER | Analysis of user entries | Linux, Mac, Windows |
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 UltruTM 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.