API Reference

Authentication

For authentication, all Lastline Analyst API endpoints accept two methods of reading credentials: HTTP Basic Authentication (as defined in RFC-7617) or the following pair of authentication parameters in the request:

  • key: Lastline Analyst API key
  • api_token: secret Lastline Analyst API token

Since the API is accessed over https, these parameters are never sent in clear-text. Both parameters are ASCII text.

The key and api_token parameters can be embedded in each request to the Lastline Analyst API. Alternatively, the client can use the login() function to explicitly validate its credentials and establish an HTTP session. As long as the client provides the session token and the session is valid, the client may skip providing the credentials. When using an expired session token for authentication, the API will return the error ANALYSIS_API_AUTHENTICATION_REQUIRED, instructing the client to re-authenticate.

A client may mandate that the API should not establish a session by setting the HTTP header x-nsx-lastline-no-session: 1.

Response Format

The format of API responses can be selected by appending an extension to the request URL. Supported formats are JSON and XML. If no extension is provided, the format defaults to JSON. JSON is the recommended format for automated processing, while XML is recommended for human consumption (since modern browsers make it readable by pretty-printing it).

A successful response comes in the form:

{"success": 1, "data":...}

A failed response will return:

{"success": 0, "error_code": <ERROR_CODE>, "error": <ERROR_MESSAGE>}

The error_code field is optional.

Numbers returned by the API can be either decimal or hexadecimal. Hexadecimal numbers are always prefixed by ‘0x’.

Timestamps returned by the API are in UTC.

Methods

Method Index

  • login():
    Performs an initial login to service and establish a session
  • ping():
    Verifies an active session

Method Documentation

api.analysis.submit_file(response_format)

Submit a file for analysis.

There are two main use-cases for this function.

  • Caller provides a hash of the file (through the md5 and/or sha1 parameters). The submit will fail if the a file with that hash is not already available to in the cloud.
  • Caller uploads a file using the file parameter. In this case, the md5 and sha1 parameters are ignored.

The typical work-flow is to first attempt to submit a hash and, if that fails with error-code ANALYSIS_API_FILE_UPLOAD_REQUIRED, try again with the actual file.

NOTE: Submissions by file hash and submissions using the file content have identical semantics. Either submission type may trigger a new analysis, even if the file has been seen by the analysis system before. Using submissions by file hash brings the advantage that the file content may not need to be transferred, providing significantly reduced data upload for submissions of large files. The client cannot assume that a file is available for submissions by hash, even if the file has been uploaded previously (files may be deleted after analysis or may be subject to data-retention). Thus, submissions by file hash may fail with error-code ANALYSIS_API_FILE_UPLOAD_REQUIRED any time the file content is not provided as part of the submission.

On a successful submission, this method will return a unique identifier for the task, which can later be used to query for results using get_results(). Furthermore, if there are already results available for the submitted file, they will be included in the response (see function get_results()). If the detailed analysis report is not required, the caller may set the full_report_score parameter (e.g., to value -1) to suppress downloading the unnecessary data.

URL

/analysis/submit/file[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    Lastline API key. (required)

  • api_token:

    Lastline API token. (required)

  • md5:

    MD5 hash (in hex) of submitted file.

  • sha1:

    SHA1 hash (in hex) of submitted file.

  • sha256:

    SHA256 hash (in hex) of submitted file.

  • full_report_score:

    Minimum score that causes detailed analysis reports to be served; -1 indicates “never return full report”; 0 indicates “return full report at all times”. (optional, default=0)

  • delete_after_analysis:

    Boolean (specified as 1 or 0). If true, the backend will delete the file after analysis is done (and noone previously submitted this file with this flag set). (optional, default=0)

  • bypass_cache:

    Boolean (specified as 1 or 0). If true, the API will not serve a cached result. NOTE: Setting this parameter requires non-default privileges. (optional, default=0)

  • analysis_timeout:

    Timeout in seconds after which to terminate analysis. By default, the analysis engine automatically detect this timeout based on the behavior observed during analysis. By setting this parameter explicitly, the analysis terminates when all relevant behavior has been observed or when the given timeout is reached. NOTE: Setting this parameter requires non-default privileges. (optional, default=<depends on type of submission>)

  • analysis_env:

    Enforce analysis in a specific environment. By default, the system selects the most appropriate environment(s) based on the type of file submitted and the available analysis environments. Thus, it is advisable to allow the system to auto-detect this value. The availability of different operating systems depends on the customization of the analysis system. By default (or when using the API hosted by Lastline), the following values are available:

    • windows10, and
    • windows7

    NOTE: Setting this parameter requires non-default privileges - any value provided in absence of the required permission will be overridden with automatically selected data. (optional, default=<depends on type of submission>)

  • allow_network_traffic:

    Boolean (specified as 1 or 0). If false, all network connections will be redirected to a honeypot. NOTE: Setting this parameter requires non-default privileges. (optional, default=1)

  • filename:

    Filename to use during analysis. If none is passed, the analysis engine will pick an appropriate name automatically, but submitting this information is highly recommended for obtaining best analysis results. See Filename for details. (optional, default=<none>)

  • keep_file_dumps:

    Boolean (specified as 1 or 0). If true, more files generated during analysis will be stored for post-processing. NOTE: This can generate large volumes of data and is not recommended. NOTE: Setting this parameter requires non-default privileges. (optional, default=0)

  • keep_memory_dumps:

    Boolean (specified as 1 or 0). If true, more memory snapshots taken during analysis will be kept for post-processing. NOTE: This can generate large volumes of data and is not recommended. NOTE: Setting this parameter requires non-default privileges. (optional, default=0)

  • keep_behavior_log:

    Boolean (specified as 1 or 0). 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. NOTE: Setting this parameter requires non-default privileges. (optional, default=0)

  • push_to_portal_account:

    If set, a successful submission will be pushed to the web-portal using the specified username. NOTE: It is strongly discouraged to use this parameter for automated or bulk submissions. See Web-Portal Integration for details. (optional, default=<none>)

  • protocol:

    Protocol used to obtain the submitted file. One of “FTP”, “HTTP”, “SMB. (optional, default=HTTP)

  • server_ip:

    ASCII dotted-quad representation of the IP address that was originally used to download this file. The IP is mandatory for the storage of the metadata. See File Origin for details. (optional, default=<none>)

  • server_port:

    Integer representation of the network port number that was originally used to download this file. The port is mandatory for the storage of the metadata. See File Origin for details. (optional, default=<none>)

  • client_ip:

    ASCII dotted-quad representation of the IP address of the client for FTP or SMB connections. (optional, default=<none>)

  • client_port:

    Integer representation of the network port number of the client used for FTP or SMB connections. (optional, default=<none>)

  • direction:

    One of “TO_SERVER” or “FROM_SERVER”. Use “TO_SERVER” to indicate FTP or SMB uploads, “FROM_SERVER” to indicate FTP or SMB downlaods. (optional, default=”FROM_SERVER”)

  • report_version:

    Version name of the report that will be returned. (optional, default=<most applicable, depends on type of report>)

  • download_ip:

    DEPRECATED, do not use. See server_ip.

  • download_port:

    DEPRECATED, do not use. See server_port.

  • apk_package_name:

    DEPRECATED, do not use. Package name for APK files. (optional, default=<none>)

  • password:

    Password to use when trying to analyze password-protected or encrypted content (such as archives or documents) (optional, default=<none>)

  • priority:

    Priority level to set for this analysis. Priority must be between 1 and 10 (1 is the lowest priority, 10 is the highest) (optional, default=<user default>)

  • bypass_prefilter:

    Boolean (specified as 1 or 0). If True, file is submitted to all supported analysis components without prior static analysis. NOTE: Setting this parameter requires non-default privileges. (optional, default=0)

  • fast_analysis:

    Boolean (specified as 1 or 0). If True, file is submitted only to static analyzers NOTE: Setting this parameter requires non-default privileges. (optional, default=0)

FILE Parameters

These parameters are provided as uploaded files encoded as multipart/form-data.

  • file:

    Actual body of the file to analyze

  • download_host:

    HTTP host header from which this file was originally downloaded. See File Origin for details. (optional, default=<none>)

  • download_path:

    FTP/HTTP/SMB host path from which this file was originally downloaded from or uploaded to. See File Origin for details. (optional, default=<none>)

  • download_user_agent:

    HTTP user-agent header that was used when this file was originally downloaded. (optional, default=<none>)

  • download_referer:

    HTTP refer(r)er header that was used when this file was originally downloaded. (optional, default=<none>)

  • download_request:

    Full HTTP request that was originally used to download this file. (optional, default=<none>)

  • password_candidates:

    A list of passwords to use when trying to analyze password-protected or encrypted content (such as archives or documents) (optional, default=<none>)

    NOTE The API will reject a submission if this parameter exceedes the max number of 1000 password_candidates or if the amount of data passed is longer than 128 Kb

Error Codes

Contents of successful response

  • task_uuid:
    Unique identifier of submitted task, for use with get_results()
  • submission_timestamp:
    Timestamp of when the submission was created.
  • expires
    The time after which the response is considered stale. The client may cache the returned task for this submission up to this time. For any submission after this time, the API may decide to return a new task.
  • If results are already available, the analysis report, the score, and other additional fields are returned as in a successful request to get_results().
api.analysis.submit_url(response_format)

Submit a URL for analysis.

On a successful submission, this method will return a unique identifier for the task, which can later be used to query for results using get_results(). Furthermore, if there are already results available for the submitted URL, they will be included in the response (see function get_results()). If the detailed analysis report is not required, the caller may set the full_report_score parameter (e.g., to value -1) to suppress downloading the unnecessary data.

URL

/analysis/submit/url[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • url:
    URL to analyze. (required)
  • referer:
    HTTP refer(r)er header to use in request (note that this is not spelled “referrer” to be in accordance with the original HTTP specification). (optional, default=<none>)
  • full_report_score:
    Minimum score that causes detailed analysis reports to be served; -1 indicates “never return full report”; 0 indicates “return full report at all times”. (optional, default=0)
  • bypass_cache:
    Boolean (specified as 1 or 0). If true, the API will not serve a cached result. NOTE: Setting this parameter requires non-default privileges. (optional, default=0)
  • analysis_timeout:
    Timeout in seconds after which to terminate analysis. By default, the analysis engine automatically detect this timeout based on the behavior observed during analysis. By setting this parameter explicitly, the analysis terminates when all relevant behavior has been observed or when the given timeout is reached. NOTE: Setting this parameter requires non-default privileges. (optional, default=<depends on type of submission>)
  • push_to_portal_account:
    If set, a successful submission will be pushed to the web-portal using the specified username. NOTE: It is strongly discouraged to use this parameter for automated or bulk submissions. See Web-Portal Integration for details. (optional, default=<none>)
  • user_agent:
    HTTP User-Agent header to use in requests. (optional, default=<none>)
  • report_version:
    Version name of the report that will be returned. (optional, default=<most applicable, depends on type of report>)
  • priority:
    Priority level to set for this analysis. Priority must be between 1 and 10 (1 is the lowest priority, 10 is the highest) (optional, default=<user default>)
  • fast_analysis:
    Boolean (specified as 1 or 0). If True, URL is submitted only to selected static analyzers. NOTE: Setting this parameter requires non-default privileges. (optional, default=0)

FILE Parameters

These parameters are provided as uploaded files encoded as multipart/form-data.

  • password_candidates:

    A list of passwords to use when trying to analyze password-protected or encrypted URL content. (optional, default=<none>)

    NOTE The API will reject a submission if this parameter exceeds the max number of 1000 password_candidates or if the amount of data passed is longer than 128 Kb

Error Codes

Contents of successful response

  • task_uuid:
    Unique identifier of submitted task, for use with get_results()
  • submission_timestamp:
    Timestamp of when the submission was created.
  • expires
    The time after which the response is considered stale. The client may cache the returned task for this submission up to this time. For any submission after this time, the API may decide to return a new task.
  • If results are already available, the analysis report, the score, and other additional fields are returned as in a successful request to get_results().
api.analysis.get_results(response_format)

Get analysis results for a task.

NOTE: Do not call this method to query if a task has completed. This method may only be used on tasks that have been marked as completed as part of the results returned to a call of get_completed(). The method get_completed() allows to efficiently query for task completion of a large number of pending tasks in parallel without polling for the status of individual tasks. If a client violates this protocol and too frequently invokes the get_results method on incomplete tasks, the client may be blocked from making further calls.

URL

/analysis/get[. response_format]

response_format can be xml, json, RTF, or PDF (defaults to json).
For RTF or PDF the result is an HTTP file download response.

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • full_report_score:
    Minimum score that causes detailed analysis reports to be served; -1 indicates “never return full report”; 0 indicates “return full report at all times”. If report_uuid is specified, this parameter is ignored. (optional, default=0)
  • report_version:
    Version name of the report that will be returned. If report_uuid is not specified, this parameter is ignored. (optional, default=<most applicable, depends on type of report>)
  • report_uuid:
    Identifier of the requested report if the task results is composed of multiple reports. Requires special permissions. (optional, default=<most applicable, depends on type of report>)
  • include_scoring_components:
    Boolean (specified as 1 or 0), telling whether details of all components contributing to the overall score should be returned individually. NOTE: Setting this parameter requires non-default privileges. (optional, default=0)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

  • score:
    Score between 0 and 100 indicating maliciousness of the observed behavior (0=benign, 100=malicious).
  • submission:
    Timestamp of when the task was created.
  • last_submission_timestamp: (optional)
    Timestamp of when the task was last re-evaluated, which is the most recent submission with the current task-UUID.
  • malicious_activity: (optional)
    Subset of the behavior report identifying interesting behavior. If features outside the observed behavior contribute to the maliciousness score, this field might not be available.
  • activity_to_mitre_techniques: (optional)
    Dictionary that maps the malicious activities found to a list of Mitre techniques information correlated with the activity.
  • errors: (optional)
    A list of error messages explaining why a submitted artifact could not be processed.
  • threat: (optional)
    A threat classification.
  • threat_class: (optional)
    A threat-class classification.
  • report (optional):
    Analysis report for submitted resource. This field will not be returned if the full_report_score parameter has been provided and is greater than the score.
  • reports (optional):
    Information about available analysis reports and their relevance for the analysis results.
    • report_uuid:
      Analysis report UUID (see report_uuid parameter).
    • relevance:
      Number (0-1) on how relevant this report is when compared to other analysis reports available for this result.
    • description (optional):
      A short description of the analysis report, such as the analysis environment.
    • report_versions (optional):
      A list of available report versions. Each report versions represents analysis information differently, focusing on different aspects of the analysis. Not all report versions apply to all reports.

For more information on the response format and report details, refer to Analysis Results.

api.analysis.get_result(response_format)

Get analysis result summary for a task. This is a short version of the data returned by get_results().

NOTE: Do not call this method to query if a task has completed. This method may only be used on tasks that have been marked as completed as part of the results returned to a call of get_completed(). The method get_completed() allows to efficiently query for task completion of a large number of pending tasks in parallel without polling for the status of individual tasks. If a client violates this protocol and too frequently invokes the get_result method on incomplete tasks, the client may be blocked from making further calls.

URL

/analysis/get_result[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • score_only:
    If set to 1, the results only contain the score and threat/threat- class classification. Some licenses are restrictred to fetching only this data. (optional, default=0)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

api.analysis.get_result_activities(response_format)

Get the behavior/activity information for an analysis task.

URL

/analysis/get_result_activities[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

  • task_uuid:
    The task uuid sent in the request
  • report_activities:
    A list of details about each activity in the given result. Each list entry has the following keys:
    • type:
      Type of the activity (e.g. “Behavior” or “Evasion”).
    • description:
      Description of the activity.
    • severity:
      Severity of this activity.
    • reports:
      Reports in this result that contain this activity. Each list entry has the keys described below
Contents of reports entries
api.analysis.get_report_activities(response_format)

Get the behavior/activity information for a specific analysis report.

URL

/analysis/get_report_activities[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • report_uuid:
    Identifier of the report. (required)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

  • task_uuid:
    The task uuid sent in the request
  • report_uuid:
    The report uuid sent in the request
  • report_activities:
    A list of details about each activity in the given report. Each list entry has the following keys:
    • type:
      Type of the activity (e.g. “Behavior” or “Evasion”).
    • description:
      Description of the activity.
    • severity:
      Severity of this activity.
    • action_ids:
      Action-IDs related to this activity (set of IDs).
api.analysis.get_result_artifact(response_format)

Get artifact associated with or generated by an analysis result.

NOTE: For artifacts extracted from a specific analysis report, consider using get_report_artifact() instead of this function.

URL

/analysis/get_result_artifact[. response_format]

response_format can be raw, xml, or json (defaults to raw).
Files should always be downloaded in raw format, which serves the result as HTTP file download. Other formats are only meaningful to get a more descriptive error-code.

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • artifact_uuid:
    Identifier of requested task artifact in the form of <report-UUID>:<artifact-name>. (required)
  • password_protected:
    If provided, use this password to protect the artifact in a zip archive. The password provided should be using only ASCII characters and have max length of 128 characters (optional)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Other than most API calls, this function serves raw HTTP responses if the default response_format (raw) is used. In this case, the API will use standard HTTP error codes:

  • 401 - Unauthorized:
    Access to service functionality has been denied.
  • 404 - Not Found:
    The requested artifact is not available.
  • 410 - Gone:
    The requested artifact is no longer available. Old analysis artifacts are cleaned up after a certain time.
  • 412 - Precondition Failed:
    task_uuid is not a valid uuid (as returned by submit_file() or submit_url()).

For response_formats json and xml, the API will respond using the following error status codes:

Contents of successful response

Other than most API calls, this function serves raw HTTP responses containing the artifact content if the default response_format (raw) is used.

Otherwise the response contains the following fields:

  • content:
    A human-readable representation of the artifact.
  • errors: (optional)
    A list of error messages explaining why a submitted artifact could not be processed.
api.analysis.get_report_artifact()

Get artifact associated with a specific analysis report.

URL

/analysis/get_report_artifact

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • report_uuid:
    Identifier of the requested report to which the artifact is assigned. (required)
  • artifact_name:
    Identifier of the requested assigned. (required)
  • password_protected:
    If provided, use this password to protect the artifact in a zip archive. The password provided should be using only ASCII characters and have max length of 128 characters (optional)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Other than most API calls, this function serves raw HTTP responses. The API will use standard HTTP error codes:

  • 401 - Unauthorized:
    Access to service functionality has been denied.
  • 404 - Not Found:
    The requested artifact is not available.
  • 410 - Gone:
    The requested artifact is no longer available. Old analysis artifacts are cleaned up after a certain time.
  • 422 - Unprocessable Entity:
    The provided task, report, or artifact UUID is not valid (as returned by get_result()).

Contents of successful response

Other than most API calls, this function serves raw HTTP responses containing the artifact content.
api.analysis.get_completed(response_format)

Get the list of uuids of tasks that were completed within a given time frame. This allows to efficiently query the completion status of multiple previously submitted tasks in one call, without requiring to poll for the status for individual tasks.

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().

get_completed_with metadata() should be used instead since it retrieves the score as well as any additional metadata for each task.

The format for date parameters is one of:

  • date: ‘YYYY-MM-DD’
  • datetime: ‘YYYY-MM-DD HH:MM:SS’

All times are in UTC.

URL

/analysis/get_completed[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • after:
    Request tasks completed after this time. (required)
  • before:
    Request tasks completed before this time. (optional, default=<current timestamp>)
  • include_score:
    If set to 1, the result will be a mapping between completed task UUIDs and task scores. (optional, default=0)

Error Codes

Contents of successful response

  • after:
    Start of considered time range.
  • before:
    End of considered time range. If no such value was specified, the API returns the current timestamp (which can be used if the local clock is skewed)
  • resume:
    The ‘after’ time to use for a subsequent get_completed call to resume collection of completed tasks.
  • more_results_available (optional):
    The API limits the number of tasks returned in a single result in some situations. If this happened, this flag is set to ‘1’ and the caller must continue fetching completed-data.
  • tasks:
    List of task UUIDs of tasks completed in the specified time range either as plain list (if include_score=0) or as mapping between task UUIDs and scores (if include_score=1).

Example

To periodically request a list of completed UUIDs, the following pattern can be used:

ret = analysis.get_completed(after="2020-08-05 14:00:39")

# ret contents will be similar to:
#{u'data': {u'after': u'2020-08-05 14:00:39',
#           u'before': u'2020-08-07 00:25:49',
#           u'resume': u'2020-08-07 00:25:50',
#           u'tasks': [u'05243bb7443e4bba80a5890969102082',
#                      u'a8ea86b5d0d84b4bb86fedd785a9d903']},
# u'success': 1}

# ...wait some time...

analysis.get_completed(after=ret["data"]["resume"])

# the method will respond with:
#{u'data': {u'after': u'2020-08-07 00:25:50',
#           u'before': u'2020-08-07 00:27:49',
#           u'resume': u'2020-08-07 00:27:50',
#           u'tasks': [u'e66b56f2cd4948c7ab314217e3be5cf2']},
# u'success': 1}

Notes

While individual analysis reports (returned by get_results()) specify the start and end time of their analysis, they should be ignored for the purposes of this method. Only the values of the after and before fields in the response contents should be considered.

The resume parameter contains the timestamp to be used for subsequent calls to allow iterating through all available, completed analysis result UUIDs. If more_results_available is set then more results are immediately available.

api.analysis.get_completed_with_metadata(response_format)

Get the list of uuids of tasks that were completed within a given time frame along with additional metadata. This allows to efficiently query the completion status of multiple previously submitted tasks in one call, without requiring to poll for the status for individual tasks.

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() and any relevant analysis errors.

The format for date parameters is one of:

  • date: ‘YYYY-MM-DD’
  • datetime: ‘YYYY-MM-DD HH:MM:SS’

All times are in UTC.

URL

/analysis/get_completed_with_metadata[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • after:
    Request tasks completed after this time. (required)
  • before:
    Request tasks completed before this time. (optional, default=<current timestamp>)

Error Codes

Contents of successful response

  • after:

    Start of considered time range.

  • before:

    End of considered time range. If no such value was specified, the API returns the current timestamp (which can be used if the local clock is skewed)

  • resume:

    The ‘after’ time to use for a subsequent get_completed call to resume collection of completed tasks.

  • more_results_available (optional):

    The API limits the number of tasks returned in a single result in some situations. If this happened, this flag is set to ‘1’ and the caller must continue fetching completed-data.

  • tasks:

    List of tasks completed in the specified time range with corresponding task UUIDs and scores with additional task metadata. The fields in each mapping are as follows:

    • task_uuid:

      The analyzed task’s uuid.

    • score:

      The final score for the task after analysis is complete.

    • insufficient_task_input_errors:

      If analysis was blocked due to insufficient input to the system returns a list of error codes that describe where invalid input was provided. Error codes returned can be any of:

      • 1001: Failed to extract a file from an archive
      • 1002: Failed to decrypt an archive due to an invalid password
      • 1003: Failed to decrypt sample due to an invalid password

Example

To periodically request a list of completed UUIDs, the following pattern can be used:

ret = analysis.get_completed_with_metadata(after="2020-12-05 14:00:39")

#ret contents will be similar to:
{u'data': {u'after': u'2012-12-05 14:00:39',
           u'before': u'2012-12-07 00:25:49',
           u'tasks': [
                      {
                       u'task_uuid': u'05243bb7443e4bba80a5890969102082',
                       u'score': 50,
                       u'insufficient_task_input_errors': [1001]
                      },
                      {
                       u'task_uuid': u'a8ea86b5d0d84b4bb86fedd785a9d903',
                       u'score': 29
                      }
                    ]}
   u'success': 1}
# ...wait some time...

analysis.get_completed_with_metadata(after=ret["data"]["before"])

# the method will respond with:
{u'data': {u'after': u'2020-12-07 00:25:49',
           u'before': u'2020-12-07 00:27:49',
           u'tasks': [
                       {
                       u'task_uuid': u'e66b56f2cd4948c7ab314217e3be5cf2',
                       u'score': 50,
                       u'insufficient_task_input_errors': [1004]
                       }
                    ]}
 u'success': 1}

Notes

While individual analysis reports (returned by get_results()) specify the start and end time of their analysis, they should be ignored for the purposes of this method. Only the values of the after and before fields in the response contents should be considered.

If more_results_available is set, the before parameter contains the timestamp to be used for subsequent calls to allow iterating through all available, completed analysis result UUIDs.

api.analysis.get_pending(response_format)

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

The format for date parameters is one of:

  • date: YYYY-MM-DD’
  • datetime: ‘YYYY-MM-DD HH:MM:SS’

All times are in UTC.

URL

/analysis/get_pending[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • after:
    Request pending tasks created after this time. (optional, default=<since epoch>)
  • before:
    Request pending tasks created before this time. (optional, default=<current timestamp>)

Error Codes

Contents of successful response

  • after:
    Start of considered time range. If no such value was specified, the API returns the time created for the first submission returned (or current timestamp if no submissions returned).
  • before:
    End of considered time range. If no such value was specified, the API returns the current timestamp (which can be used if the local clock is skewed)
  • more_results_available (optional):
    The API limits the number of tasks returned in a single result in some situations. If this happened, this flag is set to ‘1’ and the caller must continue fetching completed-data.
  • tasks:
    List of task UUIDs of tasks completed in the specified time range as plain list.

Example

To periodically request a list of pending UUIDs, the following pattern can be used:

ret = analysis.get_pending()

# ret contents will be similar to:
#{u'data': {u'after': u'2020-08-05 14:00:39',
#           u'before': u'2020-08-07 00:25:49',
#           u'tasks': [u'05243bb7443e4bba80a5890969102082',
#                      u'a8ea86b5d0d84b4bb86fedd785a9d903']},
# u'success': 1}

# ...wait some time...

analysis.get_pending(after=ret["data"]["resume"])

# the method will respond with:
#{u'data': {u'after': u'2020-08-07 00:25:49',
#           u'before': u'2020-08-07 00:27:49',
#           u'tasks': [u'e66b56f2cd4948c7ab314217e3be5cf2']},
# u'success': 1}

Notes

The resume parameter contains the timestamp to be used for subsequent calls to allow iterating through all available, pending analysis result UUIDs. If more_results_available is set then more results are immediately available.

api.analysis.get_progress(response_format)

Get analysis progress for a task.

NOTE: Do not call this method to query if a task has completed or not. This method estimates the analysis progress on a scale of 0 to 100, thus providing more data than the client may need. The method get_completed() allows to efficiently query for task completion of a large number of pending tasks in parallel without polling for the status of individual tasks. If a client violates this protocol and too frequently invokes the get_progress method, the client may be blocked from making further calls.

URL

/analysis/get_progress[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

  • progress:
    Value between 0 and 100 indicating completion of the analysis.
  • completed:
    1 if the sample has completed, otherwise 0.
api.analysis.get_task_metadata(response_format)

Get information about a task by its UUID.

URL

/analysis/get_task_metadata[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required for some license types)
  • uuid:
    Identifier of requested task. (required)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

The available details highly depend on the type of task. Available data includes:

  • task_uuid: (required)
    Identifier of the task.
  • task_type: (optional)
    ‘file’ for tasks generated from a file submission, ‘url’ for tasks generated from a URL submission.
  • file_md5: (optional)
    MD5 hash of the file for which the task was generated, if it was generated from a file submission.
  • file_sha1: (optional)
    SHA1 hash of the file for which the task was generated, if it was generated from a file submission.
  • file_sha256: (optional)
    SHA256 hash of the file for which the task was generated, if it was generated from a file submission.
  • file_mime_type: (optional)
    Mime-type of the file for which the task was generated, if it was generated from a file submission.
  • filename: (optional)
    Name of the file that was sent during the file submission, if it was provided during the submission.
  • file_size: (optional)
    Size of the file that was sent during the file submission, if it was generated from a file submission and the size is known.
  • url: (optional)
    URL for which the task was generated, if it was generated from a URL submission.
  • referer: (optional)
    Referer used for analysis, if the task was generated from a URL submission and a referer was specified.
api.analysis.query_file_hash(response_format)

Query if the file has been seen before.

NOTE: Other than submit_file(), this function will always return a completed analysis result, if one is available. In contrast, submit_file() will verify if the submission should be reanalyzed to guarantee best results. Reasons for reanalysis include the availability of new/updated detectors, updated meta-information, or analysis report expiration.

URL

/analysis/query/file_hash[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • hash_algorithm:
    Hash algorithm used in the query. One of ‘MD5’, ‘SHA1’, or ‘SHA256’. (required)
  • hash_block_size:
    Size of the block in bytes (beginning at the start of the file) on which the hash was computed. NOTE: Do not submit the file-size as block-size to query for a hash on the entire file. Instead, omit the parameter. (optional, default=<full file size>)
  • hash_value:
    Value (in hex) of the hash (using ‘hash-algorithm’ on the first ‘hash-block-size’ bytes, required)

Error Codes

Contents of successful response

  • files_found:
    Number of files that matched the query.
  • tasks: (optional)
    List of analysis tasks matching the query.
    • file_md5: (optional)
      MD5 of the (complete) file matching the query.
    • file_sha1: (optional)
      SHA1 of the (complete) file matching the query.
    • file_sha256: (optional)
      SHA256 of the (complete) file matching the query.
    • task_uuid:
      Task UUID to the most recent analysis task of the file matching the query.
    • score:
      Score between 0 and 100 indicating maliciousness of the observed behavior (0=benign, 100=malicious).
    • insufficient_task_input_errors:
      If analysis was blocked due to insufficient input to the system, returns a list of error codes that describe where invalid input was provided.
    • expires:
      The time after which the response is considered stale. The client may cache the returned task for this submission up to this time. For any submission after this time, the API may decide to return a new task.
api.analysis.is_blocked_file_hash(response_format)

Query if the file has been seen before and enough information has been gathered to consider the file as block-able.

URL

/analysis/query/is_blocked_file_hash[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required for some license types)
  • hash_algorithm:
    Hash algorithm used in the query. One of ‘MD5’, ‘SHA1’, or ‘SHA256’. (required)
  • hash_block_size:
    Size of the block in bytes (beginning at the start of the file) on which the hash was computed. NOTE: Do not submit the file-size as block-size to query for a hash on the entire file. Instead, omit the parameter. (optional, default=<full file size>)
  • hash_value:
    Value (in hex) of the hash (using ‘hash-algorithm’ on the first ‘hash-block-size’ bytes). (required)

Error Codes

Contents of successful response

  • decision:
    One of

    • FILE_UNKNOWN: The file is not known,

    • BLOCK: The client should assume the file to be malicious,

    • NOBLOCK: The client should not assume the file to be malicious.

      NOTE: This does not indicate that the file is benign, it merely means that using the given hash, there is no (or not enough) evidence to make a decision.

  • file_md5: (optional)

    MD5 of the (complete) file matching the query if the file is known.

  • file_sha1: (optional)

    SHA1 of the (complete) file matching the query if the file is known.

  • file_sha256: (optional)

    SHA256 of the (complete) file matching the query if the file is known.

api.analysis.query_task_artifact(response_format)

Query if a specific task artifact is available for download.

URL

/analysis/query_task_artifact[. response_format]

response_format can be raw, xml, or json (defaults to raw).
For raw, the result is an HTTP file download response.

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • artifact_name:
    Identifier of task artifact. Most tasks allow to download the file that was submitted for analysis - to query for this artifact, use artifact_name primary_analysis_subject. (required)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

  • available:
    1 if the artifact is available, otherwise 0.
  • task_uuid: (optional)
    Task UUID (see get_result_artifact()) for which the artifact can be downloaded (if available is set to 1).
  • report_uuid: (optional)
    Analysis report UUID (see get_result_artifact() function) for which the artifact can be downloaded (if available is set to 1).
  • artifact_name: (optional)
    Name under which the artifact can be downloaded (see get_result_artifact() function, if available is set to 1).
api.analysis.get_network_iocs(response_format)

Get the network IoC data for an analysis task.

URL

/analysis/ioc/get_network_iocs[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

  • task_uuid:
    The task uuid sent in the request
  • network_iocs:
    A list of network iocs extracted from pcaps. Each list entry has the following keys:
    • report_uuid:
      Analysis report that generated this PCAP data
    • pcap_info_version:
      The version number of the pcap data
    • pcap_info:
      The pcap data with the network ioc information. For more information, please look at the explanation under Contents of Pcap Info

Contents of Pcap Info

  • ioc_list
    List of information on specific IOCs
    • ioc_type
      Type of IoC being reported (host|IP|…)
    • value
      Value of the associated IoC
    • tags
      List of string tags on the specific IoC value
api.analysis.get_ioc_metadata(response_format)

Get information about an IOC by its UUID.

URL

/analysis/ioc/get_ioc_metadata[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required for some license types)
  • ioc_uuid:
    Identifier of IOC. (required)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

The available details highly depend on the type of IOC or the origin of the IOC (which system triggered its generation). Available data includes:

  • ioc_uuid: (required)
    Identifier of the IOC.
  • task_uuid: (optional)
    Identifier of task for which the IOC was generated, if the IOC was generated from a single analysis task.
  • report_uuid: (optional)
    Identifier of the report the IOC was generated for, if the IOC was generated from a single analysis report.
  • report_version: (optional)
    Version name of the IOC report that this IOC UUID is referring to.
  • task_score: (optional)
    Score associated with the analysis task, if the IOC was generated from a single analysis task, as returned by get_results().
  • file_md5: (optional)
    MD5 hash of the file for which the IOC was extracted, if it was generated from a single file.
  • file_sha1: (optional)
    SHA1 hash of the file for which the IOC was extracted, if it was generated from a single file.
  • file_mime_type: (optional)
    Mime-type of the file for which the IOC was extracted, if it was generated from a single file.
  • report_env: (optional)
    Analysis environment description (such as the operating system) on which data for the IOC was extracted, if it was extracted from a single analysis report.
api.analysis.get_ioc_report(response_format)

Get an IOC by its UUID.

NOTE: This function does not define the format in which the results are returned, as this is mandated by the IOC-UUID already.

URL

/ioc/get_ioc_report

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required for some license types)
  • ioc_uuid:
    Identifier of IOC. (required)

Error Codes

See function get_results()

Contents of successful response

See function get_results()
api.analysis.create_ioc_from_result(response_format)

Create an IOC based on an analysis result.

URL

/analysis/ioc/create_ioc_from_result[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • report_version:
    Type of IOC report to create. (required)
  • report_uuid:
    Identifier of the requested report. (required)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

api.analysis.get_api_utc_timestamp(response_format)

Get the current UTC timestamp to be used in the API on calls that can require the current timestamp, such as get_completed for example

URL

/analysis/get_api_utc_timestamp[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)

Error Codes

Contents of successful response

  • timestamp:
    The current timestamp for the API
api.analysis.get_analysis_tags(response_format)

Get the analysis tags for an analysis task.

URL

/analysis/get_analysis_tags[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • uuid:
    Identifier of requested task. (required)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

  • task_uuid:
    The task uuid sent in the request
  • analysis_tags:
    A list of details about each tag in the given result. Each list entry has the following keys:
    • format:
      Format of the tag.
    • data:
      Content of the tag data and score
      • type:
        Type/source of the tag (eg: “activity”). format = typed_tag
      • value:
        Tag value. format = typed_tag
      • detector:
        Detector name of the hit. format = signature_detection_tag
      • host:
        Domain/IP hit of the tag. format = signature_detection_tag, blacklist_detection_tag
      • url:
        ASCII url hit of the tag. format = signature_detection_tag, blacklist_detection_tag
      • score: (optional)
        Score value of the tag
api.analysis.get_child_tasks_recursively(response_format)

Get a list of child tasks of the given task UUID recursively

URL

/analysis/get_child_tasks_recursively[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required for some license types)
  • uuid:
    Identifier of task. (required)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response

  • task_uuid:
    The task uuid sent in the request
  • child_tasks:
    A mapping between the child task UUID and child task information
    • depth:
      The depth of the child task. For example, if the depth is 1, it means the child task is the direct child task of the submitted task UUID. If the depth is 2, it means the child task is the grandchild task (the child task of the child task) of the submitted task UUID
api.analysis.export_report(response_format)

Export a report or a combination of reports for a task.

Note: This method is currently available only to customers using the hosted, software-as-a-service API deployment.

This method allows exporting analysis results. This export works asynchronously, and a call to this method triggers the generation of a report. On a successful request, this method will return a unique identifier for the report along with an event id that can be used to get report completion status using the API call get_completed_exported_reports(). Once a report identifier has successfully been returned by get_completed_exported_reports(), the report itself can be obtained with the API call get_exported_report().

URL

/analysis/export_report[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    Lastline API key. (required)

  • api_token:

    Lastline API token. (required)

  • uuid:

    Identifier of requested task. (required)

  • report_type:

    The kind of report to export. (required)

    • Supported types:

      • OVERVIEW:
        The exported report contains an overview of the analysis.
      • ALL:
        The exported report contains an overview of the analysis and all reports for the task.
      • FULL:
        The exported report contains an overview of the analysis and all reports for the task and all child tasks (recursively).
  • report_format:

    The format of the generated report. (optional, default=”PDF”)

    • Supported formats:

      • PDF

Error Codes

Contents of successful response

api.analysis.get_completed_exported_reports(response_format)

Get a list of exported reports that are available for download.

Note: This method is currently available only to customers using the hosted, software-as-a-service API deployment.

URL

/analysis/get_completed_exported_reports[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required for some license types)
  • resume_after_report_uuid:
    The last consumed report UUID. To enumerate reports ready for download, specify the last UUID that the client processed; the API will return UUIDs of new reports that were make available after the given one. If not provided, will return all stored reports. If the API returns no reports then use the same resume_after_report_uuid for the following call to the API. (optional)

Error Codes

Contents of successful response

  • available_reports:

    A list of reports with the following info, ordered by report completion time. - exported_report_uuid:

    The UUID of the report

    • task_uuid:
      UUID of the task associated with this report
    • export_timestamp:
      Timestamp of the creation of the exported report.
    • export_error: (optional)
      An error message explaining why a report could not be exported.
api.analysis.get_exported_report()

Get a completed exported report.

Note: This method is currently available only to customers using the hosted, software-as-a-service API deployment.

URL

/analysis/get_exported_report

HTTP METHOD

GET

GET Parameters

  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required for some license types)
  • exported_report_uuid:
    The uuid of the report to receive (required).
  • cdn:
    Boolean (specified as 1 or 0). If True, may redirect to CDN to retrieve the exported report. If False, will directly return the exported report (optional, default is 1).

Error Codes

Other than most API calls, this function serves raw HTTP responses. The API will use standard HTTP error codes:

  • 401 - Unauthorized:
    Access to service functionality has been denied.
  • 404 - Not Found:
    The requested artifact is not available.
  • 422 - Unprocessable Entity:
    The provided report UUID is not valid.

Contents of successful response

Other than most API calls, this function serves raw HTTP responses containing the exported report content.
api.analysis.is_risky_analysis_artifact(response_format)

Determine if artifact associated with or generated by an analysis result could be malicious.

URL

/analysis/is_risky_analysis_artifact[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET
GET Parameters
  • key:
    Lastline API key. (required)
  • api_token:
    Lastline API token. (required)
  • artifact_uuid:
    Identifier of requested task artifact in the form of <report-UUID>:<artifact-name>. (required)
  • uuid:
    Identifier of requested task used to redirect to the correct datacenter. (optional)
  • allow_datacenter_redirect:
    If set to False, redirection to other datacenters will be prevented. (optional, default=1)

Error Codes

Contents of successful response
  • is_risky:
    ‘1’ if the artifact could be malicious, ‘0’ if safe.
api.authentication.login(response_format)

Authenticate with the API.

URL

/authentication/login[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:
    Lastline license key.
  • api_token:
    Lastline API-token. (optional, but required for many APIs)

Contents of successful response

“success”

Error Codes

  • ANALYSIS_API_AUTHENTICATION_REQUIRED:
    Credentials or session identifier missing.
  • ANALYSIS_API_INVALID_CREDENTIALS:
    Invalid pair of ‘key’/’api_token’ were provided.
  • ANALYSIS_API_PERMISSION_DENIED:
    Credentials are valid, but current user have no rights to call this API.
api.authentication.ping(response_format)

Validate authenticated session.

URL

/authentication/ping[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

Contents of successful response

“pong”

Error Codes

  • ANALYSIS_API_AUTHENTICATION_REQUIRED:
    Credentials or session identifier missing.
  • ANALYSIS_API_INVALID_CREDENTIALS:
    Invalid pair of ‘key’/’api_token’ were provided.
  • ANALYSIS_API_PERMISSION_DENIED:
    Credentials are valid, but current user have no rights to call this API.

Error Codes

api.analysis.ANALYSIS_API_FILE_UPLOAD_REQUIRED

Error code 101: Returned when submitting a file using the file’s hash, but the file content is required for performing an analysis. Submit the actual file instead - see submit_file() for details.

Note

Even if the file content has been uploaded for analysis previously, it is possible that this error is returned.

Note

The optimized Workflow of submitting files for analysis suggests submitting a file by the file’s MD5 and SHA1 hashes first. This can avoid transmitting large files when an upload may not be required. If this error is returned and the client repeats the submission to upload the file content, the first submission is not counted against a client’s submission quota.

api.analysis.ANALYSIS_API_FILE_NOT_AVAILABLE

See ANALYSIS_API_FILE_UPLOAD_REQUIRED

api.analysis.ANALYSIS_API_INVALID_CREDENTIALS

Error code 104: No valid API credentials were provided. All requests to the Lastline Analyst API require a valid API key and API token.

api.analysis.ANALYSIS_API_INVALID_UUID

Error code 105: Returned when requesting results for a task, if the provided UUID is not valid. Make sure that the UUID parameter is being provided as returned by submit_file() or submit_url()

api.analysis.ANALYSIS_API_NO_RESULT_FOUND

Error code 106: Returned when requesting results for a task, if the results are not yet available. Please try again later, or use the get_completed() API function to obtain a list of tasks that have already completed.

api.analysis.ANALYSIS_API_TEMPORARILY_UNAVAILABLE

Error code 107: API functionality is temporarily unavailable. Please try again later.

api.analysis.ANALYSIS_API_PERMISSION_DENIED

Error code 108: Access to service functionality has been denied.

api.analysis.ANALYSIS_API_FILE_TOO_LARGE

Error code 109: When submitting by file: Provided file exceeds upload limit. In the default configuration, the upload-limit is 10MB.

api.analysis.ANALYSIS_API_INVALID_D_METADATA

Error code 112: Invalid download metadata was submitted.

api.analysis.ANALYSIS_API_INVALID_FILE_TYPE

Error code 113: When submitting by file: Provided file-type is not supported by any available analysis engine.

api.analysis.ANALYSIS_API_INVALID_ARTIFACT_UUID

Error code 114: The requested artifact UUID was invalid or the requested artifact is no longer available (e.g., data retention policies caused it to be deleted).

api.analysis.ANALYSIS_API_SUBMISSION_LIMIT_EXCEEDED

Error code 115: The license used during a submission is limited to a certain maximum number of submissions per day. This limit has been exceeded.

api.analysis.ANALYSIS_API_INVALID_HASH_ALGORITHM

Error code 116: The given algorithm is either invalid or unknown.

api.analysis.ANALYSIS_API_INVALID_URL

Error code 117: An invalid URL or refer(r)er was submitted.

api.analysis.ANALYSIS_API_INVALID_REPORT_VERSION

Error code 118: The requested report version is invalid.

api.analysis.ANALYSIS_API_FILE_EXTRACTION_FAILED

Error code 119: The submitted file is an archive and the API was unable to extract the contained files. This can be due to an incorrectly specified decryption password in submit_file().

api.analysis.ANALYSIS_API_NO_IOC_EXTRACTABLE

Error code 120: The requested report cannot be expressed as an IOC in the requested format. Typically this happens when the analysis report does not contain sufficient actions to represent the behavior in a meaningful IOC report, or the set of actions exported as IOC report would cause too many false positives. It is also possible that the requested IOC report format does not allow expressing the observed behavior accurately, for example when an observable cannot be described in the chosen IOC format.

api.analysis.ANALYSIS_API_CHILD_TASK_CHAIN_TOO_DEEP

Error code 121: Internal, do not use. The submission was rejected due to generation of overly long chains of analysis child tasks.

api.analysis.ANALYSIS_API_AUTHENTICATION_REQUIRED

Error code 122: The request does not contain the required credentials and no valid session identifier was provided (or the session has expired).

api.analysis.ANALYSIS_API_DATA_NO_LONGER_AVAILABLE

Error code 123: The requested data is no longer available (e.g., data retention policies caused it to be deleted).

Submission Metadata

While many of the parameters for submit_file() and submit_url() are technically optional, it is highly recommended to provide these values to guarantee the most accurate analysis results.

Filename

The Lastline analysis system (including the API) uses the content of an uploaded file to determine the file’s type. However, for some files, the file content can be ambiguous and the intended way to analyze a file cannot be determined reliably from the content alone.

Consider the case of examining encrypted files, such as archives, PDFs, or Microsoft Office documents: much of the actual content used for determining the type is not available - either because a password or passphrase is required to access the content, or because the file format is proprietary. As a result, the file type detection needs to incorporate the filename in the decision logic to determine how (and if) the file should be analyzed.

Or consider the following example:

function calculate(value1, value2) {
    return value1 + value;
}

By looking at the file content alone, it is not straight-forward to decide what programming or scripting language this is. Therefore, it is not clear how to run, open, or analyze the given file:

  • it could be a JavaScript file meant for running in a browser, or
  • it could be a JavaScript file to be executed via JScript.exe on a Microsoft Windows host, or
  • it could be Powershell script for Microsoft Windows, or
  • it could be C or C++ depending on the context in which it is compiled, or
  • it could simply be a text file that resembles code.

The analysis system attempts to find the best fit for a given file, and if a file could be interpreted differently, the file is executed in multiple ways. If there are too many options and the system cannot find a reasonable set of candidates, the file may be rejected. By using the filename in addition to the file content, the analysis system can make a better decision and more accurately analyze the file.

Providing the filename is not only important for file-type detection, it may also affect how a file behaves: The Microsoft Windows operating system, for example, may execute programs differently depending on the name of the file, as the OS makes the UI and system interact with the user differently if the filename suggests that the program is an installer (just as one example).

File Origin

Information on the origin of a file, such as provided via download_host or download_path may improve the classification accuracy. By using such metadata, the system can track reputation information and can identify reputable programs more reliably.

Web-Portal Integration

The submit_file() and submit_url() allow specifying an optional push_to_portal_account parameter for forwarding successful API submissions to the web-portal Submission history tab.

This Submission history tab is not designed to store large numbers of submissions. As a result, it is strongly discouraged to use/set the parameter when doing automated or bulk submissions using this API. Populating the Submission history with excessive data can negatively impact the user experience of the web-portal. The integration with the portal is currently considered for deprecation in a future version.