Analyst API client

This is a Python client for the Lastline Analyst API.

The AnalysisClient class implements the client side of the Lastline Analyst API methods. It can be imported into Python client code that uses the API.

The client is available at analysis_apiclient.py .

Requirements

The Analysis API client requires:

  • Python 2.7.
  • The python requests module (tested with version 2.2.1).
  • The python simplejson module (tested with version 3.6.5).
  • To use the client as a python shell, the ipython module (tested with version 2.4.1).

Required python modules can be installed using tools such as apt, pip, or easy_install, e.g.:

apt-get install python-pycurl=7.19.0-4ubuntu3
pip install ipython==2.4.1
easy_install requests==2.2.1

Note

You may want to consider installing the API client and its dependencies inside an isolated environment, such as a container, schroot, or VirtualEnv. This allows experimenting with the Lastline APIs without affecting system libraries/modules.

Changelog

The changelog only reflects backwards-incompatible changes; new functionality may not be reflected in all cases

  • 2016-10-05: Stop download of full report details during submission
    Submission functions, such as submit_file(), submit_file_hash(), or submit_url(), now default to full_report_score=ANALYSIS_API_NO_REPORT_DETAILS (constant for -1), which disables automatic download of the full, detailed analysis report if a cached result is immediately available. To access the full analysis report, use get_result() with the task_uuid returned as part of the submission result.
  • 2016-10-28: Move API client shell to dedicated script.
    The API client shell is now available via analysis_apiclient_shell.py, which povides easier access to helper modules provided by the API client module.

Analysis Client Shell

In addition to the client, an API shell allows running the client from the command line. This provides an interactive shell for manually sending requests to the Lastline Analyst API, and it can be used to experiment with the API for analyzing files or URLs. For details, refer to the API Client Shell documentation.

Analyst API Client Classes

class analysis_apiclient.AnalysisClientBase(base_url, use_cdn=None, logger=None, config=None)

A client for the Lastline analysis API.

This is an abstract base class: concrete subclasses just need to implement the _api_request method to actually send the API request to the server.

Parameters:
  • base_url – URL where the lastline analysis API is located. (required)
  • logger – if provided, should be a python logging.Logger object or object with similar interface.
submit_file(file_stream, download_ip=None, download_port=None, download_url=None, download_host=None, download_path=None, download_agent=None, download_referer=None, download_request=None, full_report_score=-1, bypass_cache=None, delete_after_analysis=None, backend=None, analysis_timeout=None, analysis_env=None, allow_network_traffic=None, filename=None, keep_file_dumps=None, keep_memory_dumps=None, keep_behavior_log=None, push_to_portal_account=None, raw=False, verify=True, server_ip=None, server_port=None, server_host=None, client_ip=None, client_port=None, is_download=True, protocol='http', apk_package_name=None, password=None, password_candidates=None, report_version=None, analysis_task_uuid=None, analysis_engine=None, task_metadata=None, priority=None, bypass_prefilter=None, fast_analysis=None)

Submit a file by uploading it.

For return values and error codes please see api.analysis.submit_file().

Parameters:
  • file_stream – file-like object containing the file to upload.
  • download_ip – DEPRECATED! Use server_ip instead.
  • download_port – DEPRECATED! Use server_port instead.
  • download_url – DEPRECATED! replaced by the download_host and download_path parameters
  • download_host – hostname of the server-side endpoint of the connection, as a string of bytes (not unicode).
  • download_path – host path from which the submitted file was originally downloaded, as a string of bytes (not unicode)
  • download_agent – HTTP user-agent header that was used when the submitted file was originally downloaded, as a string of bytes (not unicode)
  • download_referer – HTTP referer header that was used when the submitted file was originally downloaded, as a string of bytes (not unicode)
  • download_request – full HTTP request with which the submitted file was originally downloaded, as a string of bytes (not unicode)
  • full_report_score – if set, this value (between -1 and 101) determines starting at which scores a full report is returned. -1 and 101 indicate “never return full report”; 0 indicates “return full report at all times”
  • bypass_cache – if True, the API will not serve a cached result. NOTE: This requires special privileges.
  • delete_after_analysis – if True, the backend will delete the file after analysis is done (and noone previously submitted this file with this flag set)
  • analysis_timeout – timeout in seconds after which to terminate analysis. The analysis engine might decide to extend this timeout if necessary. If all analysis subjects terminate before this timeout analysis might be shorter
  • analysis_env – environment in which to run analysis. This includes the operating system as well as version of tools such as Microsoft Office. Example usage: - windows7:office2003, or - windowsxp By default, analysis will run on all available operating systems using the most applicable tools.
  • allow_network_traffic – if False, all network connections will be redirected to a honeypot. Requires special permissions.
  • filename – filename to use during analysis. If none is passed, the analysis engine will pick an appropriate name automatically. An easy way to pass this value is to use ‘file_stream.name’ for most file-like objects
  • keep_file_dumps – if True, all files generated during analysis will be kept for post-processing. NOTE: This can generate large volumes of data and is not recommended. Requires special permissions
  • keep_memory_dumps – if True, all buffers allocated during analysis will be kept for post-processing. NOTE: This can generate large volumes of data and is not recommended. Requires special permissions
  • keep_behavior_log – if True, the raw behavior log extracted during analysis will be kept for post-processing. NOTE: This can generate very very large volumes of data and is not recommended. Requires special permissions
  • push_to_portal_account – if set, a successful submission will be pushed to the web-portal using the specified username
  • backend – DEPRECATED! Don’t use
  • verify – if False, disable SSL-certificate verification
  • raw – if True, return the raw JSON results of the API query
  • server_ip – ASCII dotted-quad representation of the IP address of the server-side endpoint.
  • server_port – integer representation of the port number of the server-side endpoint of the flow tuple.
  • server_host – DEPRECATED! Don’t use
  • client_ip – ASCII dotted-quad representation of the IP address of the client-side endpoint.
  • client_port – integer representation of the port number of the client-side endpoint of the flow tuple.
  • is_download – Boolean; True if the transfer happened in the server -> client direction, False otherwise (client -> server).
  • protocol – app-layer protocol in which the file got transferred. Short ASCII string.
  • report_version – Version name of the Report that will be returned (optional);
  • apk_package_name – package name for APK files. Don’t specify manually.
  • password – password used to analyze password-protected or encrypted content (such as archives or documents)
  • password_candidates – List of passwords used to analyze password-protected or encrypted content (such as archives or documents)
  • analysis_task_uuid – if the call is used to create a child task, it specifies the current analysis task UUID; None otherwise. Lastline-internal/do not use.
  • analysis_engine – if analysis_task_uuid is provided, it specifies the sandbox it refers to; None otherwise. Lastline-internal/do not use.
  • task_metadata – optional task-metadata to upload. Requires special permissions; Lastline-internal/do not use
  • priority – Priority level to set for this analysis. Priority should be between 1 and 10 (1 is the lowest priority, 10 is the highest) Setting priority to any value other than 1 requires special permissions.
  • bypass_prefilter – Boolean; If True, file is submitted to all supported analysis components without prior static analysis. Requires special permissions.
  • fast_analysis – Boolean; If True, file is submitted only to fast analyzers (static)
Raises:
submit_file_hash(md5=None, sha1=None, sha256=None, download_ip=None, download_port=None, download_url=None, download_host=None, download_path=None, download_agent=None, download_referer=None, download_request=None, full_report_score=-1, bypass_cache=None, password=None, password_candidates=None, backend=None, require_file_analysis=True, mime_type=None, analysis_timeout=None, analysis_env=None, allow_network_traffic=None, filename=None, keep_file_dumps=None, keep_memory_dumps=None, keep_behavior_log=None, push_to_portal_account=None, raw=False, verify=True, server_ip=None, server_port=None, server_host=None, client_ip=None, client_port=None, is_download=True, protocol='http', apk_package_name=None, report_version=None, analysis_task_uuid=None, analysis_engine=None, task_metadata=None, priority=None, bypass_prefilter=None, fast_analysis=None)

Submit a file by hash.

One of the md5, sha1, or sha256 parameters must be provided. If both are provided, they should be consistent.

For return values and error codes please see api.analysis.submit_file().

Parameters:
  • md5 – md5 hash of file.
  • sha1 – sha1 hash of file.
  • sha256 – sha256 hash of file.
  • download_ip – DEPRECATED! Use server_ip instead.
  • download_port – DEPRECATED! Use server_port instead.
  • download_url – DEPRECATED! replaced by the download_host and download_path parameters
  • download_host – hostname of the server-side endpoint of the connection, as a string of bytes (not unicode).
  • download_path – host path from which the submitted file was originally downloaded, as a string of bytes (not unicode)
  • download_agent – HTTP user-agent header that was used when the submitted file was originally downloaded, as a string of bytes (not unicode)
  • download_referer – HTTP referer header that was used when the submitted file was originally downloaded, as a string of bytes (not unicode)
  • download_request – full HTTP request with which the submitted file was originally downloaded, as a string of bytes (not unicode)
  • full_report_score – if set, this value (between -1 and 101) determines starting at which scores a full report is returned. -1 and 101 indicate “never return full report”; 0 indicates “return full report at all times”
  • bypass_cache – if True, the API will not serve a cached result. NOTE: This requires special privileges.
  • password – password used to analyze password-protected or encrypted content (such as archives or documents)
  • password_candidates – List of passwords used to analyze password-protected or encrypted content (such as archives or documents)
  • require_file_analysis – if True, the submission requires an analysis run to be started. If False, the API will attempt to base a decision solely on static information such as download source reputation and hash lookups. Requires special permissions; Lastline-internal/do not use
  • mime_type – the mime-type of the file; This value should be set when require_file_analysis is True to enforce getting the most information available
  • analysis_timeout – timeout in seconds after which to terminate analysis. The analysis engine might decide to extend this timeout if necessary. If all analysis subjects terminate before this timeout analysis might be shorter
  • analysis_env – environment in which to run analysis. This includes the operating system as well as version of tools such as Microsoft Office. Example usage: - windows7:office2003, or - windowsxp By default, analysis will run on all available operating systems using the most applicable tools.
  • allow_network_traffic – if False, all network connections will be redirected to a honeypot. Requires special permissions.
  • filename – filename to use during analysis. If none is passed, the analysis engine will pick an appropriate name automatically. An easy way to pass this value is to use ‘file_stream.name’ for most file-like objects
  • keep_file_dumps – if True, all files generated during analysis will be kept for post-processing. NOTE: This can generate large volumes of data and is not recommended. Requires special permissions
  • keep_memory_dumps – if True, all buffers allocated during analysis will be kept for post-processing. NOTE: This can generate very large volumes of data and is not recommended. Requires special permissions
  • keep_behavior_log – if True, the raw behavior log extracted during analysis will be kept for post-processing. NOTE: This can generate very very large volumes of data and is not recommended. Requires special permissions
  • push_to_portal_account – if set, a successful submission will be pushed to the web-portal using the specified account
  • backend – DEPRECATED! Don’t use
  • verify – if False, disable SSL-certificate verification
  • raw – if True, return the raw json results of the API query
  • server_ip – ASCII dotted-quad representation of the IP address of the server-side endpoint.
  • server_port – integer representation of the port number of the server-side endpoint of the flow tuple.
  • server_host – DEPRECATED! Don’t use
  • client_ip – ASCII dotted-quad representation of the IP address of the client-side endpoint.
  • client_port – integer representation of the port number of the client-side endpoint of the flow tuple.
  • is_download – Boolean; True if the transfer happened in the server -> client direction, False otherwise (client -> server).
  • protocol – app-layer protocol in which the file got transferred. Short ASCII string.
  • apk_package_name – package name for APK files. Don’t specify manually.
  • report_version – Version name of the Report that will be returned (optional);
  • analysis_task_uuid – if the call is used to create a child task, it specifies the current analysis task UUID; None otherwise. Lastline-internal/do not use.
  • analysis_engine – if analysis_task_uuid is provided, it specifies the sandbox it refers to; None otherwise. Lastline-internal/do not use.
  • task_metadata – optional task-metadata to upload. Requires special permissions; Lastline-internal/do not use
  • priority – Priority level to set for this analysis. Priority should be between 1 and 10 (1 is the lowest priority, 10 is the highest). Setting priority to any value other than 1 requires special permissions.
  • bypass_prefilter – Boolean; If True, file is submitted to all supported analysis components without prior static analysis. Requires special permissions.
  • fast_analysis – Boolean; If True, file is submitted only to fast analyzers (static)
Raises:
submit_url(url, referer=None, full_report_score=-1, bypass_cache=None, backend=None, analysis_timeout=None, push_to_portal_account=None, raw=False, verify=True, user_agent=None, report_version=None, analysis_task_uuid=None, analysis_engine=None, priority=None, task_metadata=None, fast_analysis=None, password_candidates=None)

Submit a url.

For return values and error codes please see api.analysis.submit_url().

Parameters:
  • url – url to analyze
  • referer – referer header to use for analysis
  • full_report_score – if set, this value (between -1 and 101) determines starting at which scores a full report is returned. -1 and 101 indicate “never return full report”; 0 indicates “return full report at all times”
  • bypass_cache – if True, the API will not serve a cached result. NOTE: This requires special privileges.
  • analysis_timeout – timeout in seconds after which to terminate analysis. The analysis engine might decide to extend this timeout if necessary. If all analysis subjects terminate before this timeout analysis might be shorter
  • push_to_portal_account – if set, a successful submission will be pushed to the web-portal using the specified account
  • backend – DEPRECATED! Don’t use
  • verify – if False, disable SSL-certificate verification
  • raw – if True, return the raw JSON results of the API query
  • report_version – Version name of the Report that will be returned (optional);
  • user_agent – user agent header to use for analysis
  • analysis_task_uuid – if the call is used to create a child task, it specifies the current analysis task UUID; None otherwise. Lastline-internal/do not use.
  • analysis_engine – if analysis_task_uuid is provided, it specifies the sandbox it refers to; None otherwise. Lastline-internal/do not use.
  • priority – Priority level to set for this analysis. Priority should be between 1 and 10 (1 is the lowest priority, 10 is the highest). Setting priority to any value other than 1 requires special permissions.
  • task_metadata – optional task-metadata to upload. Requires special permissions; Lastline-internal/do not use
  • fast_analysis – Boolean; If True, url is submitted only to fast analyzers (static)
  • password_candidates – List of passwords used to analyze password-protected or encrypted content from the URL.
Raises:
get_result(uuid, report_uuid=None, full_report_score=None, include_scoring_components=None, raw=False, requested_format='json', verify=True, report_version=None, allow_datacenter_redirect=None)

Get results for a previously submitted analysis task.

For return values and error codes please see api.analysis.get_results().

Parameters:
  • uuid – the unique identifier of the submitted task, as returned in the task_uuid field of submit methods.
  • report_uuid – if set, include this report in the result.
  • full_report_score – if set, this value (between -1 and 101) determines starting at which scores a full report is returned. -1 and 101 indicate “never return full report”; 0 indicates “return full report at all times”
  • include_scoring_components – if True, the result will contain details of all components contributing to the overall score. Requires special permissions
  • raw – if True, return the raw JSON/XML results of the API query.
  • requested_format – JSON, XML, PDF, or RTF. If format is not JSON, this implies raw.
  • report_version – Version of the report to be returned If report_uuid is not specified, this parameter is ignored. (optional)
  • allow_datacenter_redirect – If False, redirection to other datacenters prevented.
Raises:
get_result_summary(uuid, raw=False, requested_format='json', score_only=False, verify=True, allow_datacenter_redirect=None)

Get result summary for a previously submitted analysis task.

For return values and error codes please see api.analysis.get_result().

Parameters:
  • uuid – the unique identifier of the submitted task, as returned in the task_uuid field of submit methods.
  • raw – if True, return the raw JSON/XML results of the API query.
  • requested_format – JSON or XML. If format is not JSON, this implies raw.
  • score_only – if True, return even less data (only score and threat/threat-class classification).
  • allow_datacenter_redirect – If False, redirection to other datacenters prevented.
Raises:
get_result_artifact(uuid, report_uuid, artifact_name, password_protected=None, raw=False, verify=True, allow_datacenter_redirect=None)

Get artifact generated by an analysis result for a previously submitted analysis task.

NOTE: Consider using get_report_artifact() if the artifact is bound to a specific analysis report (which it is in practically all cases.

Parameters:
  • uuid – the unique identifier of the submitted task, as returned in the task_uuid field of submit methods.
  • report_uuid – the unique report identifier returned as part of the dictionary returned by get_result().
  • artifact_name – the name of the artifact as mentioned in the given report in the dictionary returned by get_result().
  • password_protected (str) – If provided, use this password to create a zip which will contain the artifact being fetched. The password provided should be using only ASCII characters and have max length of 128 characters
  • raw – if True, return the raw JSON/XML results of the API query.
  • allow_datacenter_redirect – If False, redirection to other datacenters prevented.
Raises:
get_report_artifact(uuid, report_uuid, artifact_name, password_protected=None, verify=True, allow_datacenter_redirect=None)

Get artifact generated by an analysis result for a previously submitted analysis task.

Parameters:
  • uuid (str) – the unique identifier of the submitted task, as returned in the task_uuid field of submit methods.
  • report_uuid (str) – the unique report identifier returned as part of the dictionary returned by get_result().
  • artifact_name (str) – the name of the artifact as mentioned in the given report in the dictionary returned by get_result().
  • password_protected (str) – If provided, use this password to create a zip which will contain the artifact being fetched. The password provided should be using only ASCII characters and have max length of 128 characters
  • allow_datacenter_redirect – If False, redirection to other datacenters prevented.
Returns:

A stream containing the artifact content
Return type:

stream
Raises:
get_completed(after, before=None, raw=False, verify=True, include_score=False)

Get the list of uuids of tasks that were completed within a given time frame.

The main use-case for this method is to periodically request a list of uuids completed since the last time this method was invoked, and then fetch each result with get_result().

Date parameters to this method can be:
  • date string: %Y-%m-%d’
  • datetime string: ‘%Y-%m-%d %H:%M:%S’
  • datetime.datetime object

All times are in UTC.

For return values and error codes please see api.analysis.get_completed().

Parameters:
  • after – Request tasks completed after this time.
  • before – Request tasks completed before this time.
  • include_score – If True, the response contains scores together with the task-UUIDs that have completed
  • raw – if True, return the raw JSON results of the API query.
Raises:
get_completed_with_metadata(after, before=None, raw=False, verify=True)

Get the list of dictionaries, each containing a uuid for a task that was completed within a given time frame, the resulting score, and additional task_metadata

The main use-case for this method is to periodically request a list of of dictionaries containing information about each task, such as the score and task_metadata. Then, additional information can be retrieved for a task with get_result()

Date parameters to this method can be:
  • date string: %Y-%m-%d’
  • datetime string: ‘%Y-%m-%d %H:%M:%S’
  • datetime.datetime object

All times are in UTC.

For return values and error codes please see api.analysis.get_completed_with_metadata().

Parameters:
  • after – Request tasks completed after this time.
  • before – Request tasks completed before this time.
  • raw – if True, return the raw JSON results of the API query.
Raises:
get_progress(uuid, raw=False, allow_datacenter_redirect=None)

Get a progress estimate for a previously submitted analysis task.

For return values and error codes please see api.analysis.get_results().

Parameters:
  • uuid – the unique identifier of the submitted task, as returned in the task_uuid field of submit methods.
  • raw – if True, return the raw JSON/XML results of the API query.
  • requested_format – JSON or XML. If format is not JSON, this implies raw.
  • allow_datacenter_redirect – If False, redirection to other datacenters prevented.
Raises:
is_risky_analysis_artifact(report_uuid, artifact_name, task_uuid=None, raw=False, verify=True, allow_datacenter_redirect=None)

Check if the artifact can potentially be malicious using the artifact information.

Parameters:
  • report_uuid (str) – Identifier of the requested report to which the artifact is assigned
  • artifact_name (str) – Identifier of task artifact
  • task_uuid (str|None) – Unique identifier for the task that analyzed the artifact. If not present, will only look for artifact in local datacenter.
  • raw (bool) – if True, return the raw JSON results of the API query.
  • verify (bool) – if True, verify ssl, otherwise False
  • allow_datacenter_redirect (bool|None) – If False, redirection to other datacenters prevented.
Returns:

True if the artifact is risky, False otherwise
Return type:

bool
Raises:
  • AnalysisAPIError – Analysis API returns HTTP error or error code (and ‘raw’ not set)
  • CommunicationError – Error contacting Lastline Analyst API.
  • InvalidArtifactError – Invalid artifact uuid.
class analysis_apiclient.AnalysisClient(base_url, key, api_token, logger=None, ca_bundle=None, verify_ssl=True, use_curl=False, timeout=60, use_cdn=None, proxies=None, config=None)

Client for the Analysis API.

A client for the Analysis API that accesses the API through the web, using key and api token for authentication, and the python requests module for sending requests.

NOTE: This class is not thread safe

class analysis_apiclient.SubmissionHelper(analysis_client, logger=None, num_retries=10)

Helper class for handling submission and task retrieval

submit_file_stream(file_stream, **kwargs)

Submit a file for analysis and retrieve results if they are immediately available. Additional parameters passed to this function are forwarded to the client (see submit_file_hash or submit_file).

NOTE: To avoid a race-condition between submission and polling for results, use the following approach:

helper = SubmissionHelper(<client>)
ts = helper.get_api_utc_timestamp()
submission = helper.submit_file_stream(<stream>)
helper.wait_for_completion_of_submission(submission, ts)

or use the submit_file_streams_and_wait_for_completion() helper function.

NOTE: You may provide any of the parameters - file_md5, - file_sha1, or - file_sha256 to avoid repeated file-hash calculations. Any hash not provided will be generated from the given file-stream.

Parameters:

file_stream (stream) – Stream to submit
Returns:

Submission results
Return type:

SubmittedFileTask
Raises:
submit_filename(filename, **kwargs)

Submit a file for analysis and retrieve results if they are immediately available. Additional parameters passed to this function are forwarded to the client (see submit_file_hash or submit_file).

NOTE: To avoid a race-condition between submission and polling for results, use the following approach:

helper = SubmissionHelper(<client>)
ts = helper.get_api_utc_timestamp()
submission = helper.submit_filename(<filename>)
helper.wait_for_completion_of_submission(submission, ts)

or use the submit_filenames_and_wait_for_completion() helper function.

Parameters:

filename (str) – File on the local filesystem to submit
Returns:

Submission results
Return type:

SubmittedFileTask
Raises:
submit_url(url, **kwargs)

Submit a URL for analysis and retrieve results if they are immediately available. Additional parameters passed to this function are forwarded to the client (see submit_url).

NOTE: To avoid a race-condition between submission and polling for results, use the following approach:

helper = SubmissionHelper(<client>)
ts = helper.get_api_utc_timestamp()
submission = helper.submit_url(<url>, referer=<referer>)
helper.wait_for_completion_of_submission(submission, ts)

or use the submit_urls_and_wait_for_completion() helper function.

Parameters:

url (str) – URL to submit
Returns:

Submission results
Return type:

SubmittedURLTask
Raises:
wait_for_completion_of_submission(submission, start_timestamp, wait_completion_interval_seconds=15, wait_completion_max_seconds=None, verify=True)

Wait for completion of a given tasks.

Parameters:
  • submission (SubmittedTask) – A submitted task. This object is updated in place with result data
  • start_timestamp (datetime.datetime) – UTC timestamp before the first submission has happened. Use self.get_api_utc_timestamp() to retrieve or use the submission_timestamp returned from the submission.
  • wait_completion_interval_seconds (float) – How long to wait between polls for completion
  • wait_completion_max_seconds (float) – Don’t wait for longer than this many seconds for completion. If None is specified, wait forever
  • verify (bool) – if False, disable SSL-certificate verification
Raises:
submit_file_streams_and_wait_for_completion(file_streams, wait_completion_interval_seconds=15, wait_completion_max_seconds=None, **kwargs)

Submit a list of files and wait for completion: For each file, submit the file for analysis, wait for completion, and retrieve results. Additional parameters passed to this function are forwarded to the client (see submit_file_hash or submit_file).

Parameters:
  • file_streams (list`(`stream)) – List of streams to submit
  • wait_completion_interval_seconds (float) – How long to wait between polls for completion
  • wait_completion_max_seconds (float) – Don’t wait for longer than this many seconds for completion. If None is specified, wait forever. NOTE: If waiting times out, the result will contain elements whose score is set to None. This method does not raise WaitResultTimeout to allow retrieving the result even when waiting for completion timed out.
Returns:

Dictionary of results
Return type:

dict`(`SubmittedFileTask)
Raises:
submit_filenames_and_wait_for_completion(filenames, wait_completion_interval_seconds=15, wait_completion_max_seconds=None, **kwargs)

Submit a list of files and wait for completion: For each file, submit the file for analysis, wait for completion, and retrieve results. Additional parameters passed to this function are forwarded to the client (see submit_file_hash or submit_file).

Parameters:
  • filenames (list`(`str)) – List of files on the local filesystem to submit
  • wait_completion_interval_seconds (float) – How long to wait between polls for completion
  • wait_completion_max_seconds (float) – Don’t wait for longer than this many seconds for completion. If None is specified, wait forever. NOTE: If waiting times out, the result will contain elements whose score is set to None. This method does not raise WaitResultTimeout to allow retrieving the result even when waiting for completion timed out.
Returns:

Dictionary of results
Return type:

dict`(`SubmittedFileTask)
Raises:
submit_urls_and_wait_for_completion(urls, wait_completion_interval_seconds=15, wait_completion_max_seconds=None, **kwargs)

Submit a list of URLs and wait for completion: For each URL, submit the URL for analysis, wait for completion, and retrieve results. Additional parameters passed to this function are forwarded to the client (see submit_url).

Parameters:
  • urls (list`(`str)) – List of URLs to submit
  • wait_completion_interval_seconds (float) – How long to wait between polls for completion
  • wait_completion_max_seconds (float) – Don’t wait for longer than this many seconds for completion. If None is specified, wait forever
Returns:

Dictionary of results
Return type:

dict`(`SubmittedURLTask)
Raises:
wait_for_completion(submissions, start_timestamp, wait_completion_interval_seconds=15, wait_completion_max_seconds=None, verify=True)

Wait for completion of a given dictionary of tasks.

NOTE: Results are filled in in provided submissions dictionary.

Parameters:
  • submissions (dict`(id:`SubmittedTask)) – Dictionary of submissions: submission identifier to SubmittedTask mapping. NOTE: The submission identifier can be an arbitrary value unique to the dictionary
  • start_timestamp (datetime.datetime) – UTC timestamp before the first submission has happened. Use self.get_api_utc_timestamp() to retrieve or use the submission_timestamp returned from the submission.
  • wait_completion_interval_seconds (float) – How long to wait between polls for completion
  • wait_completion_max_seconds (float) – Don’t wait for longer than this many seconds for completion. If None is specified, wait forever
  • verify (bool) – if False, disable SSL-certificate verification
Raises:

Exceptions

class analysis_apiclient.AnalysisAPIError(msg, error_code)

Analysis API returned an error.

The error_code member of this exception is the error code returned by the API.

class analysis_apiclient.CommunicationError(msg=None, error=None)

Contacting Malscape failed.

class analysis_apiclient.WaitResultTimeout(msg='Waiting for results timed out')

Waiting for results timed out.

Specifying custom command line arguments

This part of the documentation has been moved to a dedicated section, see Application Bundle Module.

Replaying traffic of pcaps for web analyses

This part of the documentation has been moved to a dedicated section, see Application Bundle Module.