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
, andset_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
andcomplete_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
andcomplete_callback_prototype
.:param metadata (
list
ofMetadataShim
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
, optionalReturns: 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
andcomplete_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
andcomplete_callback_prototype
.Parameters: - 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.
- data_callback (
-
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
andcomplete_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
andcomplete_callback_prototype
.Parameters: - metadata (
list
ofMetadataShim
) – 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.
- metadata (
-
history
(metadata)[source] Gets annotation history from FIRST.
This is a short operation and is a blocking call.
Parameters: metadata ( MetadataShim
orMetadataServer
) – 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
andcomplete_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
andcomplete_callback_prototype
.Parameters: - metadata (
list
ofMetadataShim
) – 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.
- metadata (
-
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}'
-
-
class