Lastline Analysis API

The Lastline Analysis API is a web-based API to submit objects for analysis, query analysis results, as well as manage the user analysis submission history.

The Lastline Analysis API is accessible at:

https://user.lastline.com/papi/analysis/<function>

Analysis Service

The Lastline Analysis API is the User Interface wrapper to the Analyst API. Most methods accessing the analysis services are directly available to the user through the Analyst API. For these methods, it is recommended to use the Analsyt API whose documentation can be browsed at https://analysis.lastline.com/docs/html/overview.html, or downloaded in PDF format from https://analysis.lastline.com/docs/LastlineAnalystAPI.pdf.

Analysis History

The Lastline Analysis API provides the User Interface with the additional functionality of managing the user history of analysis submissions.

Methods

Method Index

Method Documentation

analysis.get_history(response_format)

Get history of previously submitted analysis tasks.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/get_history[. response_format]

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

HTTP METHOD

GET

GET Parameters

  • limit:

    Limit to this many results.

  • limit_offset:

    Skip this many results.

  • start_time:

    Limit to results after this time.

  • end_time:

    Limit to results before this time

  • timezone:

    Timezone of of the time filters. All results timestamps will be converted to this timezone

  • submission_type:

    Filter results on either analysis_log.TASK_SUBMISSION_TYPE_FILE or analysis_log.TASK_SUBMISSION_TYPE_URL

  • filename:

    Filter on files with this name (either full or substring)

  • file_md5:

    Filter on files with the specified md5s

  • file_sha1:

    Filter on files with the specified sha1s

  • url:

    Limits the results to those with the corresponding url

  • task_uuid:

    Filter results on the specified task_uuids

Error Codes

Contents of successful response

List of dictionaries <submission>.

Dictionary <submission>

This dictionary contains the submission information under the following keys:

  • analysis_history_id:

    Public analysis history identifier.

  • username:

    Username used during the submission.

  • task_uuid:

    Malscape task UUID associated to the submission.

  • task_start_time:

    Submission timestamp.

  • task_subject_url:

    Submitted URL or None for file submissions.

  • task_subject_md5:

    Submitted file md5 or None for URL submissions.

  • task_subject_sha1:

    Submitted file sha1 or None for URL submissions.

  • task_subject_filename:

    Submitted file name or None for URL submissions.

  • status:

    Task status: ‘started’, ‘finished’, ‘errored’.

  • score:

    Task score between 0 and 100, None for unfinished tasks.

  • title:

    Task title if defined, None otherwise.

analysis.get_progress(response_format)

Get progress for a previously submitted analysis task.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/get_progress[. response_format]

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

HTTP METHOD

GET

GET Parameters

  • uuid:

    The unique identifier of the submitted task.

  • analysis_instance (optional):

    If set, defines the analysis instance to query.

Error Codes

Contents of successful response

  • progress:

    Value between 0 and 100 indicating the analysis completion.

  • completed:

    1 if the sample has completed, otherwise 0.

analysis.get_result(report_format)

Get results for a previously submitted analysis task.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/get_result[. report_format]

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

HTTP METHOD

GET

GET Parameters

  • uuid:

    The unique identifier of the submitted task.

  • analysis_instance:

    If set, defines the analysis instance to query.

  • report_uuid (optional):

    If set, include this report in the result.

  • full_report_score (optional):

    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.

  • report_format (optional, default to json)

    Report format to be returned.

  • report_version (optional):

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

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.

  • 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.

  • 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):

    List of dictionaries <analysis_report>.

    Dictionary <analysis_report>

    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.

analysis.get_result_activities(response_format)

Get the activity information for a previously submitted analysis task.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/get_result_activities[. response_format]

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

HTTP METHOD

GET

GET Parameters

  • uuid:

    The unique identifier of the submitted task.

  • analysis_instance (optional):

    If set, defines the analysis instance to query.

Error Codes

Contents of successful response

  • task_uuid:

    Unique identifier of submitted task.

  • report_activities:

    List of dictionaries <report_activity>.

    Dictionary <report_activity>

    Information about the activity:

    • type:

      Activity type e.g. Autorun, Settings...

    • description:

      Activity string describing the behavior.

    • severity:

      Activity type e.g. Autorun, Settings...

    • reports:

      List of dictionaries <report_reference>.

    Dictionary <report_reference>

    References to specific analysis reports of a task:

    • report_uuid:

      Identifier of the analysis report.

    • has_action_ids:

      The activity points to specific activities within the report.

analysis.get_report_artifact()

Get result artifacts for a previously submitted analysis task as a downloadable file.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above. As of version 7.14, the URL /papi/analysis/get_result_artifact has been deprecated and clients should use /papi/analysis/get_report_artifact.

URL

/papi/analysis/get_report_artifact /papi/analysis/get_result_artifact (deprecated)

response format is binary with attachment disposition.

HTTP METHOD

GET

GET Parameters

  • uuid:

    The unique identifier of the submitted task.

  • report_uuid:

    The unique report identifier where the artifact was observed.

  • artifact_name:

    The name of the artifact to be fetched.

  • analysis_instance (optional):

    If set, defines the analysis instance to query.

Error Codes

Contents of successful response

This function serves the artifact content.
analysis.get_report_activities(response_format)

Get the activity information for a specific analysis report.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/get_report_activities[. response_format]

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

HTTP METHOD

GET

GET Parameters

  • uuid:

    The unique identifier of the submitted task.

  • report_uuid:

    The unique report identifier of the analysis report.

  • analysis_instance (optional):

    If set, defines the analysis instance to query.

Error Codes

Contents of successful response

  • task_uuid:

    Unique identifier of submitted task.

  • task_uuid:

    Unique identifier of the analysis report.

  • report_activities:

    List of dictionaries <report_activity>.

    Dictionary <report_activity>

    Information about the activity:

    • type:

      Activity type e.g. Autorun, Settings...

    • description:

      Activity string describing the behavior.

    • severity:

      Activity type e.g. Autorun, Settings...

    • actions_ids:

      Set of action IDs related to this activity.

analysis.export_result(report_format)

Export results for a previously submitted analysis task as a downloadable file.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/export_result[. report_format]

report_format can be json, pdf, rtf or xml (defaults to json), response with attachment disposition.

HTTP METHOD

GET

GET Parameters

  • uuid:

    The unique identifier of the submitted task.

  • analysis_instance:

    If set, defines the analysis instance to query.

  • report_uuid (optional):

    If set, include this report in the result.

  • full_report_score (optional):

    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.

  • report_format (optional, default to json)

    Response format to be returned.

  • report_version (optional):

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

Error Codes

Contents of successful response

This function serves the report content.
analysis.query_task_artifact(response_format)

Query result artifacts for a previously submitted analysis task.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/query_task_artifact[. response_format]

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

HTTP METHOD

GET

GET Parameters

  • uuid:

    The unique identifier of the submitted task.

  • artifact_name:

    The name of the artifact to be queried.

  • analysis_instance (optional):

    If set, defines the analysis instance to query.

Error Codes

Contents of successful response

  • available:

    1 if the artifact is available, otherwise 0.

  • task_uuid: (optional)

    Task UUID (see get_report_artifact()) for which the artifact can be downloaded (if available is set to 1).

  • report_uuid: (optional)

    Analysis report UUID (see get_report_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_report_artifact() function, if available is set to 1).

analysis.submit_url(response_format)

Submit a new URL for analysis.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/submit_url[. response_format]

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

HTTP METHOD

POST

POST Parameters

  • url:

    The url to be submitted.

  • Optional analysis_options

Error Codes

Contents of successful response

  • task_uuid:

    Unique identifier of submitted task, for use with get_results().

  • If results are already available, the analysis report, the score, and other additional fields are returned as in a successful request to get_results().

analysis.submit_file(response_format)

Submit a new file for analysis.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/submit_file[. response_format]

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

HTTP METHOD

POST

FILE Parameters

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

  • file:

    Actual body of the file to analyze.

POST Parameters

  • Optional analysis_options

Error Codes

Contents of successful response

  • task_uuid:

    Unique identifier of submitted task, for use with get_results().

  • If results are already available, the analysis report, the score, and other additional fields are returned as in a successful request to get_results().

analysis.add_submission_to_history(response_format)

Add a submitted task to the analysis history.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/submit_to_history[. response_format]

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

HTTP METHOD

POST

POST Parameters

  • uuid:

    The unique identifier of the submitted task.

  • url (optional, required for URL submissions):

    The submitted url for url submissions.

  • md5 (optional, required for file submissions):

    The md5 of the submitted file for file submissions.

  • sha1 (optional, required for file submissions):

    The sha1 of the submitted file for file submissions.

  • filename (optional):

    The filename of the submitted file for file submissions.

Error Codes

Contents of successful response

  • “OK” in case of success.
analysis.add_submission_to_history_legacy(response_format)

Add a submitted task to the analysis history. Warning: This method supports the legacy parameters, see add_submission_to_history.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.5 or above.

URL

/papi/analysis/submit_to_history_legacy[. response_format]

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

HTTP METHOD

POST

POST Parameters

  • task_uuid:

    The unique identifier of the submitted task.

  • task_subject_url (optional, required for URL submissions):

    The submitted url for url submissions.

  • task_subject_md5 (optional, required for file submissions):

    The md5 of the submitted file for file submissions.

  • task_subject_sha1 (optional, required for file submissions):

    The sha1 of the submitted file for file submissions.

  • filename (optional):

    The filename of the submitted file for file submissions.

Error Codes

Contents of successful response

  • “OK” in case of success.