Analysis Results

The Analyst API returns analysis results via function get_results() and a task_uuid returned by a previous call to submit_file() or submit_url().

Every response from get_results() contains a number of mandatory fields providing submission information, analysis results, and a classification of the submitted artifact.

Additionally, each response contains optional information, depending on the type of submission (file or URL submission), analysis outcome, and analysis verbosity settings.

Contents of response

  • task_uuid.

    Type: Hexadecimal string.

    Example: 7065a3ba0c729ad5981a1e1072df710d.

    Unique identifier for this analysis submission.

  • score.

    Type: Integer.

    Example: 75.

    Score between 0 and 100 indicating maliciousness of the observed behavior (0=benign, 100=malicious). This allows the client to choose which artifacts to consider malicious according to its own security policies. Lastline standard/best-practice is to consider any artifact with

    • score < 30 to be benign,
    • score >= 30 and score < 70 to be suspicious / a nuisance, and
    • score >= 70 to be malicious.
  • submission.

    Type: Date-Time.

    Example: 2013-10-09 12:12:12.

    Timestamp of the submission that triggered the initial analysis.

  • last_submission_timestamp (optional).

    Type: Date-Time.

    Example: 2013-10-09 12:12:12.

    Timestamp of the most recent submission that returned this analysis task.

  • analysis_subject.

    Type: Dictionary.

    • url: (optional).

      Type: String.

      Example: “http://www.example.com/”.

      URL submitted for analysis (URL analysis only).

    • referer: (optional).

      Type: String.

      Example: “http://www.referer.com/”.

      Referer/Referrer for analysis (URL analysis only).

    • md5: (optional).

      Type: String.

      Example: “c9d2242bbaca823b80916fec27e9f2bb”.

      File MD5 hash (file analysis only).

    • sha1: (optional).

      Type: String.

      Example: “c9d2242bb263483837456fec27e9f2bb”.

      File SHA1 hash (file analysis only).

    • mime_type: (optional).

      Type: String.

      Example: “application/pdf”.

      File mime-type (file analysis only).

Additional response contents for successful analysis

  • malicious_activity. (optional).

    Type: List of strings.

    Example: “Type1: Value1”, “Type2: Value2”.

    Subset of the behavior report identifying malicious behavior. If features outside the observed behavior contribute to the maliciousness score or no malicious behavior was detected during analysis, this field will not be available.

  • threat. (optional).

    Type: String.

    Example: “Zeus”.

    A threat classification. If the analysis subject was classified as benign or does not belong to a known threat family, this field will not be available.

  • threat_class. (optional).

    Type: String.

    Example: “Command & Control”.

    A threat-class classification. If the analysis subject was classified as benign or does not belong to a known threat class family, this field will not be available.

  • report. (optional).

    Type: See Analysis Report Format.

    Analysis report for submitted resource. If an analysis subjects fails be analyzed but can still be classified using other information, the response will not contain this field.

  • child_tasks. (optional).

    Type: List of child tasks. See Child Tasks.

  • reports. (optional).

    Type: List of dictionaries.

    • report_uuid:

      Type: See report uuid.

      Analysis report UUID.

    • relevance:

      Type: Integer.

      Example: 0.

      Number (0-1) on how relevant this report is when compared to other analysis reports available for this result.

    • description (optional):

      Type: String.

      Example: “Dynamic analysis on Microsoft Windows 7”.

      A short description of the analysis report, such as the analysis environment. For details, see Report Descriptions.

    • report_versions (optional):

      Type: List of Strings.

      Example: ‘ll-int-win’, ‘ll-win-timeline-based’.

      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 a list of report versions, see report versions.

Additional response contents for failed analysis

  • errors.

    Type: List of strings.

    Example: “Error1”, “Error2”.

    A list of error messages explaining why a submitted artifact could not be processed.

Report Descriptions

The type of analysis performed for artifacts submitted to the Analyst API depends on the type of the artifact (file or URL) as well as on the configuration of the Analyst API.

Each submission of a supported type is processed by one or more analysis engines. For example, a JavaScript file can be

  • monitored by loading it in an instrumented browser,
  • statically analyzed for anomalies in the script code, and
  • run directly on the operating system via a script interpreter.

Each analysis engine performs its analysis, resulting in an analysis report each having a unique report-UUID, a relevance to the overall task classification, as well as a description.

The analysis report description provides details on what type of analysis was performed. Additionally it may contain optional information describing where the analysis was performed. In most cases this is the system to which the artifact was submitted - such as the Lastline hosted datacenter. For On-Premises customers that have the cloud-analysis component enabled, the report description may indicate that the same artifact was executed on the Lastline cloud and a relevant analysis report may be downloaded from the global Lastline analysis system. If this type of report is available and requested, the Analyst API transparently downloads the report from the Lastline backend and serves it like any other, locally-generated analysis report.

Note

If a report is available for download from the global Lastline (hosted) analysis system, it does not imply that the artifact (file or URL) was uploaded from the local On-Premises installation. Instead, it means that the artifact was already known to the global analysis system and a relevant analysis report was included as additional source of information for classification of the local analysis. For details, refer to the documentation of the cloud-analysis component in the Lastline manuals.

Child Tasks

When analyzing a submitted artifact, the system may generate related sub- or child tasks as part of the analysis. Examples for such child tasks are files extracted from an archive, embedded programs extracted from a document, files found during the analysis of a URL, network traffic generated during the analysis or customized run of a document analysis.

While these child tasks are standalone analysis runs, the analysis outcome/classification of the child task may also influence the classification of the originally submitted artifact. For example, if a file is extracted from an archive and this file is found to be malicious, the archive is also considered to be malicious.

The analysis results of these child tasks are linked to the original analysis and accessible as part of the child_task field of the analysis result.

Child task contents

  • task_uuid.

    Type: Hexadecimal string.

    Example: 7065a3ba0c729ad5981a1e1072df710d.

    Unique identifier for this analysis submission.

  • score.

    Type: Integer.

    Example: 75.

    Score between 0 and 100 indicating maliciousness of the observed behavior (0=benign, 100=malicious). See Contents of response for details.

  • tag.

    Type: String.

    Example: “file extracted from archive”.

    A short description of the child task’s type.

  • parent_report_uuid: (optional).

    Type: String.

    Example: c6600954ea584d0a8912e4be80609122

    If the child task is linked to a specific analysis report, such as the analysis inside the Windows 7 sandbox, of the (original/parent) task, the parent_report_uuid points to the corresponding report.