Objects

TH Objects Overview
Represent the diffent objects or concepts managed in the TH library.
Objects can be manipulated independently (as items of one of the defined types)
or grouped inside a container (as a list of objects of the same type)
class TH.Core.THCollection.THBase(*args, **kwds)
TH.Core.THCollection.THClass

alias of TH.Core.THCollection.THCollection

class TH.Core.THCollection.THCollection(df: pandas.core.frame.DataFrame, tClass: Union[List[Any], Any], kwargs: Optional[dict] = {})
Object representing a TH data table
Following information is required to build a THCollection instance:

  • df: Source dataframe from where to obtain the items information

  • tClass: Name of the class for the contained items

  • kwargs: Dictionary with the dataframe columns that must match the item members

This is a container of objects of the same type.
Provides the following functionality over the objects group:

  • The group is indexable and iterable

  • A method that can be used in a single object can be used in all the group

Examples:

m = Machine(muid='00000000000000000000000000000000')
# will return a group of all processes in the machine and period
all_processes = m.get_executions()

if not all_processes.empty:
    # will return the first processs by its index
    first_process = all_processes[0]

    print(type(first_process)) # TH.Core.THProcess.Process
    print(first_process)

# The group is iterable
for p in all_processes:
    print(p)

# request a list of all machines present in the processes group
m2 = all_processes.get_machine()
# Only one machine is returned (as all processes belong to the same machine)
print(m2)
append(obj: Any) → T

Append an item to an existing THCollection container. A new updated container is returned. Source container remains unchanged

Parameters

obj – The object to append to the container

Returns

The container with the new object added

static create(tClass: Any) → T

Obtain an empty THCollection container

Parameters

tClass – The object type for this container

Returns

An empty container to store objects of the specified type

filter(filterfn: Callable, neg: Optional[bool] = False) → T
Parameters

  • filterfn – The filter function to be called

  • neg – Set to True to return those items that do not satisfy the filter criteria

Returns

Execute a filter function and return a new container with the items that satisfies the filter criteria

def is_malware(process):
    return p.get_file().classification == 'Malware'

all_processes = machine.get_executions()
malware_processes = all_processes.filter(is_malware)
geolocate(**kwargs) → pandas.core.frame.DataFrame

Adds geolocation info to input DataFrame rows.

Parameters

  • input – pandas Dataframe to add geolocation info

  • ip_column – Name of the input column containing IPs to geolocate

Returns

merge of input pandas DataFrame and geolocation info

group(**kwargs) → pandas.core.frame.DataFrame

Obtains a report pandas.Dataframe out of the given dataframe grouping and counting by the given column values.

Parameters

  • input – the source dataframe

  • by – List of columns of the source dataframe used to group the rows

  • sum – When defined will perform the sum of values in the specified column (instead of counting)

  • name – Name of the additional column created with the count for each of the grouped rows

Code example:

def do_report(source_dataframe)
    return reports.group(source_dataframe, by=['MUID', 'UserName'], name='Actions')
Returns

Dataframe with the resulting data or exception

query(q: str) → T
Parameters

q – The query sentence to be executed over the container

Returns

Perform a query over the object list and return a new container with the filtered items

all_processes = machine.get_executions()
chrome_processes = all.processes.query("ChildFilename == 'chrome.exe'")
to_dataframe() → pandas.core.frame.DataFrame
Returns

The original dataframe used to build the container

top(**kwargs) → pandas.core.frame.DataFrame

Obtains a pandas.DataFrame with the top results for a given one

Parameters

  • input – the source dataframe

  • n – Number of rows for the resulting dataframe

  • by – Name of the column used to order the dataframe results

  • ascending – True to return the ‘n’ greater results according to column ‘by’ and false for the ‘n’ lowest

Code example:

def do_top(source_dataframe)
    return reports.top(source_dataframe, n=10, by='Actions', ascending=False)
Returns

DataFrame with the resulting data or exception

property empty
Returns

True if the list contains no items

empty_process_list = THCollection(pd.DataFrame(), Process)
print(empty_process_list.empty)         # True
print(len(empty_process_list) == 0)     # True
TH.Core.THCollection.from_dataframe(df: pandas.core.frame.DataFrame) → Optional[TH.Core.THCollection.THCollection]

Obtain a THCollection table from a Dataframe

Parameters

df – Dataframe

Returns

THCollection table object

TH.Core.THCollection.get_object(id: int) → TH.Core.THCollection.THCollection

Obtain an object from a THCollection table

Parameters

id – Object ID (value in ‘oref’ column)

Returns

Object