Summary

File processing is done asynchronously and each analysis request is tracked by a file ID. Because processing a file is a potentially time-consuming operation, scheduling a file for processing and retrieving the results needs 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 tracked using the processingState and the progress values from the response.

HTTP Headers

Request URL parameters

Request errors

Response

Example of a successful request:

Description of response

• id: ID of the requested file

• storageType: type of the storage

• storageName: name of the storage

• scanId: ID of the scan

• scanName: name of the scan

• name: file name

• path: file path

• size: file size

• hash: storage specific hash (for S3 and OneDrive it is the ETag, for Box it is SHA1)

• progress: progress information about upload and scanning

• processingState: file processing state

  • 0 - In Progress

  • 1 - Failed

  • 2 - Available

• exceptionDetails: a field describing the issue in case of a processing failure

• created: date and time when request was made

• uploadTimeSpanMs: time needed to upload the file (the difference between created and uploadCompleted in milliseconds)

• uploadCompleted: date and time when the upload was completed

• scanResult: results of the scan returned by MetaDefender Core

  • extractedFiles: information about extracted files in case of an archive file

  • dataId: MetaDefender Core generated ID of the requested file

  • fileInfo: basic information of the scanned file

  • processInfo: process information

    • postProcessing: Contains information about result of data sanitization

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

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

      • convertedTo: contains target type name of sanitization

      • copyMoveDestination: this field is obsolete, it should not be used

      • convertedDestination: contains the name of the sanitized file

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

    • progressPercentage: percentage of processing completed

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

    • userAgent: who called this API

    • profile: the name of the rule used

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

    • blockedReason: gives the reason if the file is

    • blockedProcessInfo: process information

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

  • scanResults: results of the scan

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

      • defTime: the database definition time for this engine

      • engId: the unique identification string for the engine

      • scanResultI: numeric code of engine scan result

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

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

      • threatFound: name of the scan result

    • dataId: MetaDefender Core generated ID of the requested file

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

    • scanAllResultA: the overall scan result in string

    • startTime: start time of scan as recorded by MetaDefender Core

    • totalAvs: number of used antivirus engines

    • totalTime: total time elapsed during scan in milliseconds as recorded by MetaDefender Core

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

• vulnerabilityInfo: see 8.1.6. Vulnerability Info In Processing Result

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

        • certainty: text version of "certainty_score", possible values:

          • Very Low

          • Low

          • Medium

          • High

          • Very High

        • certainty_score: is defined by the relevance of the given hit in its context. It is calculated based on multiple factors such as the number of digits, possible values: [0-100]

        • hit: the matched data

        • severity (NOTE: this field is deprecated): can be 0 (detected) or 1 (suspicious)

  • severity (NOTE: this field is deprecated): represents the severity of the data loss, possible values:

    • 0 - Certainly is data loss

    • 1 - Might be data loss

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