File¶

class TH.File(md5: Optional[str] = None, name: Optional[str] = None, path: Optional[str] = None, muid: Optional[str] = None, logged_user: Optional[str] = None, parent_filename: Optional[str] = None, parent_md5: Optional[str] = None, parent_pid: Optional[str] = None, client_id: Optional[str] = None, period: Optional[TH.Core.period.TimePeriod] = None)¶

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

Class representing a file in disk

A file can be instantiated by providing the following information:

name: Name for this file
path: Full path for this file
md5: Md5 file hash for this file
muid: Machine unique identification code in where the operation over the file has been executed
logged_user: User that created the operation over the file has been executed
parent_filename: Process (name) that performed the operation over the file
parent_md5: Process (md5) that performed the operation over the file
parent_pid: Process (pid) that performed the operation over the file
client_id: The client identification code
period: The current analysis period

first_seen(client: Optional[str] = None) → Any¶

Obtain the first seen information for this file

If client is provided, the information will be limited to the provided client

Parameters: client – Client (or list of clients) in where to find the requested information
Returns: The first seen date for the file (only available when MD5 is provided)

return File(md5='F3ADE3F9BCC57211FC388878EA83EE48').first_seen()

get_classification() → pandas.core.frame.DataFrame¶

Returns: Dataframe relating the file and its current classification

get_client() → Any¶

get_download_urls(muid: str, client: Optional[str] = None, period=TimePeriod()) → pandas.core.frame.DataFrame¶

Obtain download urls for this file
If muid and period are provided, will obtain the download urls for the file in this machine and period.
Otherwise, the file md5 is required in order to perform the request

Parameters

muid – the target machine (Allways required)
client – the target client id (optional)
period – the query period (Allways required)

Returns

URLs where the file was downloaded from

Example to request for download URLS where the file has been seen

file = File(md5='F3ADE3F9BCC57211FC388878EA83EE48')
return file.get_urls()

Example to request for download URLS for given machine and period

file = File(name='myfile.zip')
return file.get_urls(
    muid='00000000000000000000000000000000', 
    period=TimePeriod(num_days=15)
)

get_events(muid: Optional[str] = None) → pandas.core.frame.DataFrame¶

Parameters: muid – Limit the results to certain machines (by the MUID)
Returns: Events related to file (only available when MD5 is provided)

return File(md5='F3ADE3F9BCC57211FC388878EA83EE48').get_events(MUID)

get_file_path(muid: Optional[str] = None, md5s: Optional[Union[List[str], str]] = None, client: Optional[str] = None) → str ¶

Returns: name used in file initialization or else, list of names related to the file hash

get_info(full: Optional[bool] = False) → dict ¶

Obtain stored information for a file

Returns: dictionary with stored information regarding the file

ej: Obtain file information

return File(md5='F3ADE3F9BCC57211FC388878EA83EE48').get_info()

get_machine() → Any¶

Returns: The machine as an instance of Machine in where the file has been created

This method is only available when the file is obtained through a Obj.get_files() method.

Otherwise the information is not available and an exception will be raised

For example: this piece of code will raise a ‘information not available’ exception

f = File(name = 'chrome.exe')
m = f.get_machine()     # WILL RAISE AN EXCEPTION (File operation information has not been provided)

This piece of code, will execute succesfully:

u = User(users = 'MYDOMAIN/MyUser', client_id='000000')
filelist = u.get_files(file=File(name='chrome.exe'), operation='create')
if len(filelist) > 0:
    f = filelist[0]
    m = f.get_machine()
    print(m)

get_machines() → TH.Core.THCollection.THCollection ¶

Obtain machines where this file was seen

return File(md5='F3ADE3F9BCC57211FC388878EA83EE48').get_machines()

Returns

List of Machine where this file was seen (only available when MD5 is provided)

Following information is available in the machines returned out of this query:

MUID: The machine MUID in where this file has been seen
ClientId: The client id whom the machine belogs to
firstSeen: The first seen date for this machine and file
lastSeen: The last seen date fot this machine and file
lastPath: The last seen full route to the file

get_md5(muid: Optional[str] = None, period: Optional[TH.Core.period.TimePeriod] = None) → Union[list, str]¶

If md5 was provided in file initialization, return that md5

Otherwise, return the list of md5s for the given file name in a machine, client and period

Parameters

muid – Machine (or list of machines) in where to find for file ocurences
period – Analysis period

Returns

Md5 used in file initialization or else, list of md5s related to the file name (during a period in a machine and/or client)

# Example 1: 
# Prints 'F3ADE3F9BCC57211FC388878EA83EE48'
f = File(md5='F3ADE3F9BCC57211FC388878EA83EE48')
print(f.get_md5())      

# Example 2: 
# Prints the list of different md5s given to 'chrome.exe' in the given machine and period
f = File(name='chrome.exe')
print(f.get_md5(muid='00000000000000000000000000000000', period=TimePeriod()))

get_name() → list ¶

Returns: name used in file initialization or else, list of names related to the file hash

get_process() → Any¶

Returns: The process as an instance of Process that performed the operation over the file

This method is only available when the file is obtained through a Obj.get_files() method.

Otherwise the information is not available and an exception will be raised

For example: this piece of code will raise a ‘information not available’ exception

f = File(name = 'chrome.exe')
p = f.get_process()     # WILL RAISE AN EXCEPTION (File operation information has not been provided)

This piece of code, will execute succesfully:

u = User(users = 'MYDOMAIN/MyUser', client_id='000000')
filelist = u.get_files(file=File(name='chrome.exe'), operation='create')
if len(filelist) > 0:
    f = filelist[0]
    p = f.get_process()
    print(p)

get_user() → Any¶

Returns: The user as an instance of User that performed the operation over the file

This method is only available when the file is obtained through a Obj.get_files() method.

Otherwise the information is not available and an exception will be raised

f = File(name = 'chrome.exe')
u = f.get_user()     # WILL RAISE AN EXCEPTION (File operation information has not been provided)

This piece of code, will execute succesfully:

m = Machine(name = 'MYMACHINE', client_id='000000')
filelist = m.get_files(file=File(name='chrome.exe'), operation='create')
if len(filelist) > 0:
    f = filelist[0]
    u = f.get_user()
    print(u)

last_seen(client: Optional[str] = None) → Any¶

Obtain the last seen information for this file

If client is provided, the information will be limited to the provided client

Parameters: client – Client (or list of clients) in where to find the requested information
Returns: The first seen date for the file (only available when MD5 is provided)

return File(md5='F3ADE3F9BCC57211FC388878EA83EE48').last_seen

property classification¶

Returns: The current classification for the file (only available when MD5 is provided)

return File(md5='F3ADE3F9BCC57211FC388878EA83EE48').classification

property md5¶

Returns: The md5 hash of the file

property name¶

Returns: The name of the file

property path¶

Returns: The path of the file