Retrieving Analysis Reports Using Webhooks

By providing a callbackurl header in the File submission request, once the analysis is complete, the entire analysis report will be automatically send to the callbackurl. No need for additional calls or polling mechanism to retrieve the analysis reports.

For more details, see:

• 8.1.3.1. Process a file

• 8.1.11. Webhooks

Retrieving Analysis Reports Using Data ID

Retrieve analysis results.

Analysis is done asynchronously and each analysis request is tracked by a data ID. Initiating file analysis and retrieving the results need to be done using two separate API calls. This request needs to be made multiple times until the analysis is complete. Analysis completion can be traced using “process_info.progress_percentage” value from the response.

Retrieve Processing Results Using Hash

Successful response

HTTP status code: 200

Response description:

• data_id: data ID of the requested file

• file_info: basic information of the scanned file

• scan_results: results of the scan

  • data_id: data ID of the requested file

  • progress_percentage: percentage of progress, if it is 100, then the scan is completed

  • scan_all_result_a: the overall scan result in string

  • scan_all_result_i: the overall scan result in number code

  • individual scan engine results will be consolidated according to the following priority:

    1. Threat found

    2. Object is suspicious

    3. Object is encrypted / too deep (archive only) / too big (archive only) / containing too many files (archive only) / extraction timeout exceeded (archive only)

    4. Filetype mismatch

    5. No threat detected

    6. Object was not scanned

    7. Failed to scan the object

  • scan_details: scan results for each antivirus engine. The key is the name of the antivirus engine and the value is the result of the antivirus engine

    • def_time: the database definition time for this engine

    • eng_id: the unique identification string for the engine

    • location: place of scan engine

    • scan_result_i: numeric code of engine scan result

    • scan_time: time elapsed during scan with the engine in milliseconds

    • wait_time: time elapsed between sending file to node and receiving the result from the engine in milliseconds

    • threat_found: name of the scan result

  • start_time: start time of scan

  • total_avs: number of used antivirus engines

  • total_time: total time elapsed during scan in milliseconds

• process_info: process information

  • post_processing: Contains information about result of data sanitization

    • "actions_ran": "Sanitized" or "" and the names of Post Actions that were also run.
      The separator is "|" (pipe). (e.g.: actions_ran: "PAscript" or actions_ran: "Sanitized | PAscript")

    • "actions_failed": "Sanitization Failed" or "" and the names of failed Post Actions.
      The separator is "|" (pipe). (e.g.: actions_failed: "PAscript failed" or actions_failed: "Sanitization Failed | PAscript failed" )

    • "converted_to": contains target type name of sanitization

    • "copy_move_destination": ""

    • "converted_destination": contains the name of the sanitized file

  • processing_time: total time elapsed during processing file on the node in milliseconds

  • progress_percentage: percentage of processing completed

  • queue_time: total time elapsed during file waits in the queue in milliseconds

  • user_agent: who called this API

  • username: user identifier who submitted scan request earlier

  • profile: the name of the rule used

  • result: the final result of processing the file (Allowed / Blocked / Processing)

  • blocked_reason: gives the reason if the file is blocked

  • file_type_skipped_scan: indicates if the input file's detected type was configured to skip scanning

  • issues: task related issues (e.g.: blocked by 3rd party software, can not access file for scanning )

  • outdated_data: array of flags - if occur - describing outdated data in the result, these can be

    • enginedefinitions: at least one of the AV engines the item was scanned with has a newer definition database

    • configuration: the process' rule - or any item used by the rule - was modified since the item was processed

    • sanitization: if item was sanitized this flag notifies that the sanitization information regarding this result is outdated, meaning the sanitized item is no longer available

• vulnerability_info: see 8.1.6. Vulnerability Info In Processing Result

• dlp_info: information on matched sensitive data

  • hits: detailed results that contains:

    • type of matched rule: ccn (credit card number), ssn (social security number), regex_<number> (regular expression with a number in order to differentiate the RegEx rules if there are more.)

      • display_name: Credit Card Number, Social Security Number, or in case of RegEx, the name of the rule that has been given by the user

      • hits: the hits for that type

        • before: the context before the matched data

        • after: the context after the matched data

        • hit: the matched data

        • severity: can be 0 (detected) or 1 (suspicious)

  • verdict: the overall result for the scanned file. It can be

    • 0 - clean

    • 1 - found matched data

    • 2 - suspicious

    • 3 - failed

    • 4 - not scanned (e.g. not supported file type)

• yara_info: information on data that matched yara rules

  • hits: detailed results that contains:

    • the name of the matched rules

    • a description

  • verdict: the overall result for the scanned file.

    • 0 - clean

    • 1 - found matched data

    • 2 - suspicious

    • 3 - failed

    • 4 - not scanned

Please find possible overall and per engine scan results here.

Successful response with archive detection

HTTP status code: 200

Completed response description with archive detection:

• extracted_files: information about extracted files

  • files_extracted_count: the number of extracted files

  • files_in_archive: array of files in archive

    • detected_by: number of engines reported threat

    • scanned_with: number of engines used for scanning the file

  • first_index: it tells that from which file (index of the file, 0 is the first) the result JSON contains information about extracted files. (default=0)

  • page_size: it tells how many files the result JSON contains information about (default=20). So by default, the result JSON contains information about the first 20 extracted files.

  • worst_data_id: data id of the file that has the worst result in the archive

• scan_results

  • last_file_scanned (stored only in memory, not in database): If available, the name of the most recent processed file

Response (not existing data_id)

HTTP status code: 200

Error response

Retrieving Analysis Reports Using Data ID containing all files in archive

Using this method under extracted_files key all the info about extracted files will be listed recursively.

Successful response containing all extracted files

HTTP status code: 200

Using this method the following fields will not be shown compared to /file request containing extracted files

• files_extracted_count

• files_in_archive

• first_index

• page_size

• worst_data_id

Also the "outdated_data" field will only be shown in the root archive.

Response (not existing data_id)

HTTP status code: 200

Response (requested file is not an archive)

HTTP status code: 200

Error response