Machine

class TH.Machine(muid: Optional[Union[List[str], str]] = None, name: Optional[Union[List[str], str]] = None, client_id: Optional[str] = None, local_ip: Optional[str] = None, period: Optional[TH.Core.period.TimePeriod] = TimePeriod())

Bases: Generic[TH.Core.THCollection.T]

Class representing a Machine (MUID)
A machine can be instantiated by providing the following information:

  • muid: Machine unique identification code

  • name: Machine name (client id must be provided as well)

  • client_id: The client identification code

  • period: The current analysis period

Machine creation examples:

m = Machine(muid="00000000000000000000000000000000")
m = Machine(name="MY_MACHINE", client_id="000000")
get_bandwidth(file: Optional[Union[List[Any], Any]] = None, period: Optional[TH.Core.period.TimePeriod] = None) → pandas.core.frame.DataFrame
Obtain The used bandwith by this machine
The default representation of bandwidth data is a area chart with the values per day
Parameters

  • muid – Limit results to machines in this list

  • file – Limit the query results to certain files (providing File objects)

  • period – Query time period. Defaults to today

Returns

Data frame with the resulting bandwidth data

Following columns are provided within the returned dataframe:

  • Date: Date for the bandwith consumption data

  • Outgoing: MBytes sent

  • Incoming: MBytes received

get_blocked(users: Optional[Union[List[str], str]] = None, file: Optional[Union[List[Any], Any]] = None, period: Optional[TH.Core.period.TimePeriod] = None, histogram: Optional[TH.Core.histogram.Histogram] = None) → Union[pandas.core.frame.DataFrame, TH.Core.THCollection.THCollection]

Obtain machine’s blocked elements

Parameters

  • period – Query time period. Defaults to today

  • histogram – Set if the histogram over the data is required (defaults to None)

  • users – Limit the query results to certain users

  • file – Limit the query results to certain files (providing File objects)

Returns

Machine’s detections represented as a list of Block instances.

If histogram is required, returning values depends on the provided histogram configuration.
Otherwise, following columns are provided within the returned dataframe:

  • DateTime: Date of the detection

  • ClientId: Target client

  • Muid: Target machine

  • LoggedUser: User that performed the detected action

  • ChildMd5: File hash for the detected file

  • ChildPath: File path for the detected file

  • ChildFilename: File name for the detected file

  • ParentMd5: File hash for the parent process file

  • ParentPath: File path for the parent process file

  • ParentFilename: File name for the parent process file

  • WinningTech: Winning technology (the one that performed the detecion)

  • DetectionId: Detection identification code

  • Action: Performed action over the file

get_client() → Any
Returns

Instance of Client representing the client for this machine

get_communications(file: Optional[Union[List[Any], Any]] = None, period: Optional[TH.Core.period.TimePeriod] = None, protocol: Optional[str] = None, port: Optional[str] = None, iptype: Optional[str] = None, direction: Optional[str] = None, ips: Optional[str] = None, top: Optional[int] = None, histogram: Optional[TH.Core.histogram.Histogram] = None) → Union[pandas.core.frame.DataFrame, TH.Core.THCollection.THCollection]
Obtain machine’s communications
The default representation of a machine’s communications through the print_dataframe() method is world
map with colored dots (out of the geolocalization)
Parameters

  • period – Query time period. Defaults to today

  • histogram – Set if the histogram over the data is required (defaults to None)

  • file – Limit the query results to certain files (providing File objects)

  • protocol – Limit the query result to certain protocols (‘ICMP’, ‘IGMP’, ‘RFCOMM’, ‘TCP’, ‘RDP’, ‘UDP’, ‘ICMPV6’, ‘RM’)

  • port – Limit the query result to certain ports (port = number or [‘FTP’, ‘SSH’, ‘TELNET’, ‘SMTP’, ‘HTTP’, ‘POP3’, ‘HTTPS’, ‘RDP’])

  • iptype – Limit the query result to certain IP type (iptype = ‘Public’|’Private’)

  • direction – Limit the query result to certain direction (direction = ‘Incoming’|’Outgoing’)

  • ips – Limit the query results to certain ip addresses

  • top – Limit the query result to certain number of rows

Returns

Machine’s communications represented as a list of Connection instances.

If histogram is required, returning values depends on the provided histogram configuration.
Otherwise, following columns are provided within the returned dataframe:

  • DateTime: Date and time of the connection

  • Date: Date of the connection

  • Muid: Machine for the connection

  • LoggedUser: User affected by the connection

  • ParentFilename: Process (name) affected by the connection

  • ParentPid: Process (pid) affected by the connection

  • RemoteIp: The remote IP address

  • RemotePort: Connection port

  • LocalIp: The local IP of the machine when the connection was stablished

  • LocalPort: The local IP port

  • Protocol: The communication protocol

  • Direction: Incoming / Outgoing

  • Ipv4Status: Private / Public

  • Times: Number of times (agregates) this connection has been done

get_detections(users: Optional[Union[List[str], str]] = None, file: Optional[Union[List[Any], Any]] = None, period: Optional[TH.Core.period.TimePeriod] = None, histogram: Optional[TH.Core.histogram.Histogram] = None) → Union[pandas.core.frame.DataFrame, TH.Core.THCollection.THCollection]

Obtain machine’s deteccions

Parameters

  • period – Query time period. Defaults to today

  • histogram – Set if the histogram over the data is required (defaults to None)

  • users – Limit the query results to certain users

  • file – Limit the query results to certain files (providing File objects)

Returns

Machine’s detections represented as a list of Detect instances.

If histogram is required, returning values depends on the provided histogram configuration.
Otherwise, following columns are provided within the returned dataframe:

  • DateTime: Date of the detection

  • ClientId: Target client

  • Muid: Target machine

  • LoggedUser: User that performed the detected action

  • ChildMd5: File hash for the detected file

  • ChildPath: File path for the detected file

  • ChildFilename: File name for the detected file

  • ParentMd5: File hash for the parent process file

  • ParentPath: File path for the parent process file

  • ParentFilename: File name for the parent process file

  • WinningTech: Winning technology (the one that performed the detecion)

  • DetectionId: Detection identification code

  • Action: Performed action over the file

get_events(period: Optional[TH.Core.period.TimePeriod] = None, by: Optional[str] = None) → pandas.core.frame.DataFrame

Obtain machine’s events

Parameters

  • period – Query time period, only 1 or 2 days is allowed. Defaults to today

  • by – Group results (by = ‘type’ | ‘classif’ | None). Defaults to None

Returns

Machine’s events in period

get_executions(file: Optional[Union[List[Any], Any]] = None, user: Optional[str] = None, kind: Optional[str] = None, operation: Optional[str] = None, command: Optional[str] = None, attributes: Optional[str] = None, period: Optional[TH.Core.period.TimePeriod] = None, histogram: Optional[TH.Core.histogram.Histogram] = None) → Union[pandas.core.frame.DataFrame, TH.Core.THCollection.THCollection]

Obtain machine’s actions over processes

Parameters

  • period – Query time period. Defaults to today

  • histogram – Set if the histogram over the data is required (defaults to None)

  • file – Limit the results to those actions affecting provided file (providing File objects)

  • user – Limit the results to those actions affecting provided user

  • kind – Limit results by the application type [‘interpreter’, ‘remoteaccess’, ‘admintool’, ‘hackingtool’] or action [‘userallowed’]

  • operation – Limit results by the operation type [‘create’, ‘kill’, ‘thread’, ‘load’]

  • command – Limit results to those containing the given command line

  • attributes – Limit the results by the operation attributes (OR’ed values of [ATTR_REMOTE, ATTR_EXTERNAL, ATTR_FRESHUNKNOWN, ATTR_LANSHARED])

Available operations are:

  • create: Process creation operations

  • kill: Kill process operations

  • thread: Remote threads creation operations

  • load: Load library operations

Returns

Machine’s processes actions in period as a list of Process instances.

If histogram is required, returning values depends on the provided histogram configuration.
Otherwise, following columns are provided within the returned Process instances:

  • DateTime: timestamp for the operation

  • Muid: Target machine

  • LoggedUser: User that performed the logged action

  • ChildFilename: Child process (name)

  • ChildPath: Child process (path)

  • ChildMd5: Child process (file md5 hash)

  • ChildPid: Child Process (pid)

  • ParentFilename: Parent process (name)

  • ParentPath: Parent process (path)

  • ParentMd5: Parent process (file md5 hash)

  • ParentPid: Parent Process (pid)

  • CommandLine: Command line for process creation events

  • RemoteIp: Origin IP for file creation events from remote machines

  • Operation: Operation type

  • RemoteSession: True if action is performed from a remote session

  • External: The file comes from outside

  • FreshUnknown: This file is new along Panda community

  • LanShared: The file comes from outside (inside the local network)

get_files(file: Optional[Union[List[Any], Any]] = None, user: Optional[str] = None, kind: Optional[str] = None, operation: Optional[str] = None, attributes: Optional[str] = None, period: Optional[TH.Core.period.TimePeriod] = None, histogram: Optional[TH.Core.histogram.Histogram] = None) → Union[TH.Core.histogram.Histogram, TH.Core.THCollection.THCollection]

Obtain machine’s actions over files

Parameters

  • period – Query time period. Defaults to today

  • histogram – Set if the histogram over the data is required (defaults to None)

  • file – Limit the results to those actions affecting provided file

  • user – Limit the results to those actions affecting provided user

  • kind – Limit results by the application type [‘interpreter’, ‘remoteaccess’, ‘admintool’, ‘hackingtool’]

  • operation – Limit results by the operation type [‘create’, ‘modify’, ‘delete’, ‘rename’, ‘folder’, ‘newcmp’, ‘opencmp’, ‘access’, ‘script’ ]

  • attributes – Limit the results by the operation attributes (OR’ed values of [ATTR_REMOTE, ATTR_EXTERNAL, ATTR_FRESHUNKNOWN, ATTR_LANSHARED])

Available operations are:

  • create: File (PE) creation operations

  • modify: File (PE) modification operations

  • delete: File (PE) deletion operations

  • rename: File (PE) rename operations

  • folder: Folder creation operations

  • newcmp: CMP files creation operations

  • opencmp: CMP files open operations

  • access: Data access operations

  • script: Operations over no PE / script files

Returns

Machine’s file actions in period as a list of File instances.

If histogram is required, returning values depends on the provided histogram configuration.
Otherwise, following columns are provided within the returned File instances:

  • DateTime: timestamp for the operation

  • Muid: Target machine

  • LoggedUser: User that performed the logged action

  • ChildFilename: Child process (name)

  • ChildPath: Child process (path)

  • ChildMd5: Child process (file md5 hash)

  • ChildPid: Child Process (pid)

  • ParentFilename: Parent process (name)

  • ParentMd5: Parent process (file md5 hash)

  • ParentPid: Parent Process (pid)

  • CommandLine: Command line for process creation events

  • RemoteIp: Origin IP for file creation events from remote machines

  • Operation: Operation type

  • RemoteSession: True if action is performed from a remote session

  • External: The file comes from outside

  • FreshUnknown: This file is new along Panda community

  • LanShared: The file comes from outside (inside the local network)

get_info(period: Optional[TH.Core.period.TimePeriod] = None) → Optional[list]
Obtain the machine type
Parameters

period – Query time period. Defaults to today

Returns

The machine identified profile (list of strings with the identified machine profiles)

get_ioas(rules: Optional[str] = None, period: Optional[TH.Core.period.TimePeriod] = None) → TH.Core.THCollection.THCollection
Obtain machine’s IoAs
The default representation for 1 day period IoA’s is a pie chart, for more that 1 day a bar chart will be displayed
Parameters

  • period – Query time period. Defaults to today

  • rules – Query results limited to those containing the provided rule names

Returns

Machine’s attack identifications in period, represented as a list of IoAs instances

Following columns are provided within the returned dataframe:

  • alertDateTime: Datetime from when the alert was identified

  • clientId: The client for this alert

  • critical: True if the alert is critical

  • details: Alert details

  • excluded: True if alert is excluded

  • huntingRule: The hunting rule name thar triggered the alert

  • id: The alert identification code

  • lastHourEvidenceCount: Number of acummulated alerts of this type in the last hour

  • mitre: Mitre equivalence for this alert

  • muid: This alert machine identification code

  • severity: The alert severity value

  • status: The alert status

  • timeStamp: Timestamp for this alert (when it was first produced)

  • weight: The alert weight value

get_name() → pandas.core.frame.DataFrame
Returns

Dataframe relating the machine MUID and name

get_os_info()

Obtain machine’s OS information

Returns

OS information

get_processes(file: Optional[Union[List[Any], Any]] = None, user: Optional[str] = None, kind: Optional[str] = None, period: Optional[TH.Core.period.TimePeriod] = None, histogram: Optional[TH.Core.histogram.Histogram] = None) → TH.Core.THCollection.THCollection

Obtain all processes with activity in the machine

Parameters

  • period – Query time period. Defaults to today

  • histogram – Set if the histogram over the data is required (defaults to None)

  • file – Limit the results to those actions affecting provided file (providing File objects)

  • user – Limit the results to those actions affecting provided user

  • kind – Limit results by the application type [‘interpreter’, ‘remoteaccess’, ‘admintool’, ‘hackingtool’] or action [‘userallowed’]

Returns

Machine’s processes in period as a list of Process instances.

If histogram is required, returning values depends on the provided histogram configuration.
Otherwise, following columns are provided within the returned dataframe:

  • DateTime: timestamp for the operation

  • Muid: Target machine

  • LoggedUser: User that performed the logged action

  • ChildFilename: Child process (name)

  • ChildPath: Child process (path)

  • ChildMd5: Child process (file md5 hash)

  • ChildPid: Child Process (pid)

  • ParentFilename: Parent process (name)

  • ParentPath: Parent process (path)

  • ParentMd5: Parent process (file md5 hash)

  • ParentPid: Parent Process (pid)

  • Operation: Operation type

get_registry(file: Optional[Union[List[Any], Any]] = None, user: Optional[str] = None, kind: Optional[str] = None, operation: Optional[str] = None, period: Optional[TH.Core.period.TimePeriod] = None, histogram: Optional[TH.Core.histogram.Histogram] = None) → Union[TH.Core.histogram.Histogram, TH.Core.THCollection.THCollection]

Obtain machine’s actions over registry keys

Parameters

  • period – Query time period. Defaults to today

  • histogram – Set if the histogram over the data is required (defaults to None)

  • file – Limit the results to those actions affecting provided file

  • user – Limit the results to those actions affecting provided user

  • kind – Limit results by the application type [‘interpreter’, ‘remoteaccess’, ‘admintool’, ‘hackingtool’] or action [‘userallowed’]

  • operation – Limit results by the operation type [‘create’, ‘modify’, ‘access’]

Available operations are:

  • create: Registry key creation operations (for autorun)

  • modify: Registry key modification operations (for autorun)

  • access: Monitored registry keys access

Returns

Machine’s registry actions in period as a list of Registry instances.

If histogram is required, returning values depends on the provided histogram configuration.
Otherwise, following columns are provided within the returned Registry instances:

  • DateTime: timestamp for the operation

  • Muid: Target machine

  • LoggedUser: User that performed the logged action

  • Key: Affected registry key

  • Value: The registry key value

  • ValueData The modified content

  • ParentFilename: Parent process (name)

  • ParentMd5: Parent process (file md5 hash)

  • ParentPid: Parent Process (pid)

  • CommandLine: Command line for process creation events

  • RemoteIp: Origin IP for file creation events from remote machines

  • Operation: Operation type

  • RemoteSession: True if action is performed from a remote session

  • External: The file comes from outside

  • FreshUnknown: This file is new along Panda community

  • LanShared: The file comes from outside (inside the local network)

get_timetable(period: Optional[TH.Core.period.TimePeriod] = None) → pandas.core.frame.DataFrame
Obtain The distribution of machine actions over time (hours per weekday)
The default representation for the timetable is a heatmap with coloured cells per weekday and hour
Parameters

  • period – Query time period. Defaults to today

  • muid – Limit results to machines in this list

Returns

Dataframe with the actions distriution over time

Following columns are provided within the returned dataframe:

  • LoggedUser: The user under analysis

  • Weekday: The analyzed weekday [1..7]

  • Hour: The analyzed hour [0..23]

  • AvgActions: The average number of actions (any kind) in the analyzed weekday and hour

  • StdActions: The standard deviation of actions (any kind) in the analyzed weekday and hour

get_users(users: Optional[Union[List[str], str]] = None, period: Optional[TH.Core.period.TimePeriod] = None, histogram: Optional[TH.Core.histogram.Histogram] = None) → pandas.core.frame.DataFrame
Obtain the list of users for this machine
Parameters

  • period – Query time period. Defaults to today

  • histogram – Set if the histogram over the data is required (defaults to None)

  • users – Limit the query results to users whose name contains the provided user names

Returns

A list of users represented as User instances.

If histogram is required, returning values depends on the provided histogram configuration.
Otherwise, following columns are provided within the returned dataframe:

  • LoggedUser: The logged user name

  • IniDate: The date in where the user was first seen (in the given period)

  • EndDate: The date in where the user was last seen (in the given period)

  • NumDays: The number of days where the user had actity (in the given period)

property first_seen
Returns

The date for the first recorded activity for this machine

property last_seen
Returns

The date for the last recorded activity for this machine

property muid
Returns

The machine’s muid (Machine Unique IDentification)

property name
Returns

The machine’s name