FIRST :: Server

data_callback_prototype(thread, response)

Function prototype for data_callback arguments.

Parameters:
  • thread (threading.Thread) – The thread associated with the server operation.
  • response (requests.models.response) – The response from the server in JSON form.
complete_callback_prototype(thread, data)

Function prototype for complete_callback arguments. This function should call FIRST.server.remove_operation to ensure data is released once it is not needed.

Parameters:
  • thread (threading.Thread) – The thread associated with the server operation.
  • data (dict) – All data received from the server.
class first_plugin_ida.first.FIRST[source]
class Server(config, h_md5, crc32, h_sha1=None, h_sha256=None)[source]

Encapsulate interacting with the FIRST server’s REST API.

Note

Using functions set_protocol, set_server, and set_port do not update the configuration details, just the server instance represented with this class.

urn

URL format string.

Type:str
paths

Mapping between operations and FIRST URI path format strings.

Type:dict
MAX_CHUNK

The maximum number of entries sent to the server. Default: 20

Note

The FIRST server can set the max number of entries received. If this value is greater than the server’s then the server will not perform the operation.

Type:int
Args

config (Configuration): FIRST configuration information. h_md5 (str): The MD5 of the sample. crc32 (int): The CRC32 of the sample. h_sha1 (str, optional): The SHA1 of the sample. h_sha256 (str, optional): The SHA256 of the sample.

MAX_CHUNK = 20
add(metadata, data_callback=None, complete_callback=None)[source]

Adds function metadata to FIRST.

This is a long operation, thus it has the option of providing a data_callback and complete_callback arguments. Those arguments are functions that will be called with the newly returned data and when the whole operation is complete, respectively. Both functions should follow the below their respective prototypes; data_callback_prototype and complete_callback_prototype.

:param metadata (list of MetadataShim or: MetadataShim): The metadata to be added to FIRST. :param data_callback: A function to call when data is receieved from the server. :type data_callback: data_callback_prototype, optional :param complete_callback: A function to call when the whole long operation completes. :type complete_callback: complete_callback_prototype, optional

Returns:threading.Thread. The thread created for the operation.
applied(metadata_id)[source]

Sets a FIRST annotation as applied to this sample.

This is a short operation and is a blocking call.

Parameters:metadata_id (str) – The FIRST annotation ID.
Returns:JSON data returned from the server. None on failure.
Return type:dict
checkin(action)[source]

Checks in with FIRST server to ensure annotations can be added.

This function must be called before any annotations are added to FIRST. This function allows the FIRST server to setup information about the sample, thereby allowing functions to be associated with the sample. This only needs to be called once and is attempted before the first user selected operation.

This operation is not done if the operation to be performed is to test the connection to the server.

Parameters:action (str) – The FIRST operation to be performed
created(data_callback=None, complete_callback=None)[source]

Retrieves FIRST annotations the user has created.

This is a long operation, thus it has the option of providing a data_callback and complete_callback arguments. Those arguments are functions that will be called with the newly returned data and when the whole operation is complete, respectively. Both functions should follow the below their respective prototypes; data_callback_prototype and complete_callback_prototype.

Parameters:
Returns:

threading.Thread. The thread created for the operation.

delete(metadata_id)[source]

Deletes a FIRST annotation created by the user.

This is a short operation and is a blocking call.

Parameters:metadata_id (str) – The FIRST annotation ID.
Returns:JSON data returned from the server. None on failure.
Return type:dict
get(metadata_ids, data_callback=None, complete_callback=None)[source]

Retrieves FIRST annotations the user has created.

This is a long operation, thus it has the option of providing a data_callback and complete_callback arguments. Those arguments are functions that will be called with the newly returned data and when the whole operation is complete, respectively. Both functions should follow the below their respective prototypes; data_callback_prototype and complete_callback_prototype.

Parameters:
  • metadata (list of MetadataShim) – The metadata to be retrieved from FIRST.
  • data_callback (data_callback_prototype, optional) – A function to call when data is receieved from the server.
  • complete_callback (complete_callback_prototype, optional) – A function to call when the whole long operation completes.
Returns:

threading.Thread. The thread created for the operation.

history(metadata)[source]

Gets annotation history from FIRST.

This is a short operation and is a blocking call.

Parameters:metadata (MetadataShim or MetadataServer) – The FIRST annotation the history is being requested.
Returns:JSON data returned from server. None on failure.
Return type:dict
paths = {'add': 'api/metadata/add/{0[api_key]}', 'applied': 'api/metadata/applied/{0[api_key]}', 'checkin': 'api/sample/checkin/{0[api_key]}', 'created': 'api/metadata/created/{0[api_key]}/{0[page]}', 'delete': 'api/metadata/delete/{0[api_key]}/{0[id]}', 'get': 'api/metadata/get/{0[api_key]}', 'history': 'api/metadata/history/{0[api_key]}', 'scan': 'api/metadata/scan/{0[api_key]}', 'test': 'api/test_connection/{0[api_key]}', 'unapplied': 'api/metadata/unapplied/{0[api_key]}'}
remove_operation(server_thread)[source]

Removes operation from server thread structure.

Parameters:server_thread (threading.Thread) – The thread to remove.
scan(metadata, data_callback=None, complete_callback=None)[source]

Queries FIRST for matches.

This is a long operation, thus it has the option of providing a data_callback and complete_callback arguments. Those arguments are functions that will be called with the newly returned data and when the whole operation is complete, respectively. Both functions should follow the below their respective prototypes; data_callback_prototype and complete_callback_prototype.

Parameters:
  • metadata (list of MetadataShim) – The metadata to be queried for matches in FIRST.
  • data_callback (data_callback_prototype, optional) – A function to call when data is receieved from the server.
  • complete_callback (complete_callback_prototype, optional) – A function to call when the whole long operation completes.
Returns:

threading.Thread. The thread created for the operation.

set_port(port)[source]

Overrides the FIRST server port set in the configuration.

Parameters:port (int) – The FIRST server port.
set_protocol(protocol)[source]

Overrides the FIRST server protocol set in the configuration.

Parameters:protocol (int) – The FIRST server protocol.
set_server(server)[source]

Overrides the FIRST server set in the configuration.

Parameters:port (int) – The FIRST server.
stop_operation(server_thread)[source]

Signals a server thread to stop its work.

Parameters:server_thread (threading.Thread) – The thread to stop.
test_connection()[source]

Interacts with server to see if there is a valid connection.

This is a short operation and is a blocking call.

Returns:
True if connection can be made and FIRST returns a
success message. False otherwise.
Return type:bool
to_json(response)[source]

Converts Requests’ response object to json.

Parameters:response (requests.models.Response) – A request response.
Returns:JSON data or empty dictionary.
Return type:dict
unapplied(metadata_id)[source]

Sets a FIRST annotation as unapplied to this sample.

This is a short operation and is a blocking call.

Parameters:metadata_id (str) – The FIRST annotation ID.
Returns:JSON data returned from the server. None on failure.
Return type:dict
urn = '{0.protocol}://{0.server}:{0.port}/{1}'