API Gateway v2.6.0 Terms of Service Apache 2.0

Developer Guide

This is the API documentation for MetaDefender Cluster API Gateway Public API. If you would like to evaluate or have any questions about this documentation, please contact us via our Contact Us form.

How to Interact with MetaDefender Cluster API Gateway using REST API

MetaDefender Cluster API Gateway is used to submit files for analysis, retrieve scan results, manage file processing, download processed files, and manage file batches. OPSWAT recommends using the JSON-based REST API. The available methods are documented below.

Note: MetaDefender Cluster API doesn't support chunk upload, however is recommended to stream the files to MetaDefender Cluster API Gateway as part of the upload process.

File Analysis Process

MetaDefender Cluster is a system with multiple components that work together to utilize the power of multiple MetaDefender Core instances. The system is designed to handle large volumes of files and provide high throughput for file analysis. The system can be deployed in a distributed manner, allowing for horizontal scaling and load balancing across multiple MetaDefender Core instances.

Below is a brief description of the API integration flow:

Upload a file for analysis to MetaDefender Cluster API Gateway (POST /file), which returns the data_id: File Analysis.
The following method can be used to retrieve the analysis report:
- Polling: Fetch the result with previously received data_id (GET /file/{data_id} resource) until scan result belonging to data_id doesn't reach the 100 percent progress_percentage: (Fetch analysis result)
Note: Too many data_id requests can reduce performance. It is enough to just check every few hundred milliseconds.
Retrieve the analysis results anytime after the analysis is completed with hash for files (md5, sha1, sha256, sha512) by calling Fetch analysis result by hash.
- The hash can be found in the scan results
Retrieve processed file (sanitized, redacted, watermarked, etc.) after the analysis is complete.

Note: Based on the configured retention policy, the files might be available for retrieval at a later time.

OPSWAT provides some sample codes on GitHub to make it easier to understand how the MetaDefender REST API works.

Server

http://localhost:8899

Authentication

apiKey apikey

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Fields

Key	In
apikey	Header

Auth

Authentication APIs

User authentication is done via username & password.

Login

Initiate a new session. Required for using protected REST APIs.

Auth

Request Body

object	object
user	string	Username
password	string	User's password

POST /login

 
curl --request POST \ --url 'http://localhost:8899/login' \ --data '{  "user": "admin",  "password": "admin"}'
Copy

Responses

200

object	object
oms-csrf-token	string	The randomly generated token used to prevent CSRF attacks
session_id	string	The apikey used to make API calls which requires authentication

403

Invalid credentials

500

Unexpected event on server

Response

 
{ "oms-csrf-token": "ZWU3NDJkNDcwMzQ4NWNlNGUzOTFjMGJiNDFkZDQ4ZWM=", "session_id": "a5dd6114dbd14a3b8f4577b7b54e6b0a"}
Copy

Logout

Destroy session for not using protected REST APIs.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

POST /logout

 
curl --request POST \ --url 'http://localhost:8899/logout' \ --header 'apikey: {apikey}'
Copy

Responses

200

object	object
response	string

400

Bad Request.

403

Invalid user information.

500

Unexpected event on server

Response

 
{ "response": "Logout success"}
Copy

Analysis

File analysis APIs

Submit each file to MetaDefender Cluster API Gateway individually or group them in batches. Each file submission will return a data_id which will be the unique identifier used to retrieve the analysis results.

Note: MetaDefender API doesn't support chunk upload. You shouldn't load the file in memory, is recommended to stream the files to MetaDefender Cluster API Gateway as part of the upload process.

/hash/{md5|sha1|sha256|sha512}

GET

/file/rules

GET

/file/converted/{data_id}

GET

/file/download/{data_id}

POST

/file/{data_id}/cancel

GET

/file/webhook/{data_id}

Analyze File (Asynchronous mode)

Scanning a file using a specified workflow. Scan is done asynchronously and each scan request is tracked by data id of which result can be retrieved by API Fetch Scan Result.

Note: Chunked transfer encoding (applying header Transfer-Encoding: Chunked) is not supported on /file API. API Gateway only accepts file uploads with a known content length and a content type of application/octet-stream

Auth

Headers

apikey	string	Generated `session_id` from Login call can be used as an `apikey` for API calls that require authentication.
filename	string	The name of the submitted file
user_agent	string	user_agent header used to identify (and limit) access to a particular rule. For rule selection, `rule` header should be used.
rule	string	Select rule for the analysis, if no header given the default rule will be selected (URL encoded UTF-8 string of rule name)
batch	string	Batch id to scan with, coming from `Initiate Batch` (If it is not given, it will be a single file scan.)
archivepwd	string	Password for archive ( URL encoded UTF-8 string) Multiple passwords is also supported, format: archivepwdX X: Could be empty When having value, X must be a number >= 1 For example: archivepwd1: "fox" archivepwd2: "cow" archivepwd3: "bear"
content-encoding	string	Content encoding of the file. This header is used to specify the encoding of the file content. The value should be a valid content encoding type, such as "base64", "gzip". This header is optional and can be omitted if the encoding is not applicable.
metadata	string	Could be utilized for: Additional parameter for pre-defined post actions and external scanners (as a part of STDIN input). Customized macro variable for watermarking text (Proactive DLP engine feature). Additional context / verbose information for each file submission (appended into JSON response scan result). It is strongly recommended to apply URL encoding before sending `metadata` to Metadefender Core to prevent unexpected issues related to encoding errors or unsafe characters.
engines-metadata	string	Since MetaDefender Core 5.0.0, preferred context / verbose information can be sent to the engines. Please see the below pages for the details: File Type engine (supported since Core 5.2.1) Archive engine (supported since Core 5.4.1) Deep CDR Proactive DLP
callbackurl	string	Client's URL where MetaDefender Cluster Callback Service will notify scan result back to whenever scan is finished (webhook model). * Format: protocol://<ip \| domain>: * Example: http://10.0.1.100:8081/listenback * Supported protocol: HTTP / HTTPS * Supported host types: domain name, IPv4 (IPv6 not supported) * Method: POST Note: The Callback URL is only supported when MetaDefender Cluster Callback Service is deployed, and MetaDefender Core version must be 5.16.1 or higher.
global-timeout	integer	This custom global timeout (in seconds) will override the global timeout predefined in corresponding workflow rule.

Request Body

file file

POST /file

 
curl --request POST \ --url 'http://localhost:8899/file' \ --header 'apikey: {apikey}' \ --header 'filename: {filename}' \ --header 'user_agent: {user_agent}' \ --header 'rule: {rule}' \ --header 'batch: {batch}' \ --header 'archivepwd: {archivepwd}' \ --header 'content-encoding: base64' \ --header 'metadata: {  "key1": "value",  "key2": ["valueA", "valueB"]}' \ --header 'engines-metadata: {  "charset": "ISO-2022-JP",  "content-type": "text/html",  "content-transfer-encoding": "quoted-printable"}' \ --header 'callbackurl: {callbackurl}' \ --header 'global-timeout: {global-timeout}' \ --data-binary '"<Payload in raw bytes>"'
Copy

Responses

200

Successful file submission

object	object
data_id	string	Unique submission identifier. Use this value to reference the submission.

403

Invalid user information or Not Allowed

411

Content-Length header is missing from the request.

422

Body input is empty.

500

Unexpected event on server

503

Server is too busy. Try again later.

Response

 
{ "data_id": "61dffeaa728844adbf49eb090e4ece0e"}
Copy

Fetch Analysis Result

Retrieve scan results.

Scan is done asynchronously and each scan request is tracked by a data ID.

Initiating file scans and retrieving the results need to be done using two separate API calls. This request needs to be made multiple times until the scan is complete. Scan completion can be traced using scan_results.progress_percentage value from the response.

Note: The REST API also supports pagination for archive file result. A 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, min=0)

page_size: it tells how many files the result JSON contains information about (default=50, min=0, max=2000). So by default, the result JSON contains information about the first 50 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

Auth

Headers

apikey	string	Generated `session_id` from Login call can be used as an `apikey` for API calls that require authentication.
user_agent	string	user_agent header used to identify (and limit) access to a particular rule. For rule selection, `rule` header should be used.

Path Params

data_id

string

Unique submission identifier. Use this value to reference the submission.

Query String

first

integer

The first item order in the list child files of archive file

minimum: 0

Default: 0

size

integer

The number of items to be fetched next, counting from the item order indicated in first header. The default value is 50, and the maximum value is 2000.

maximum: 2000

minimum: 0

Default: 50

GET /file/{data_id}

 
curl --get \ --url 'http://localhost:8899/file/{data_id}' \ --header 'apikey: {apikey}' \ --header 'user_agent: {user_agent}' \ --data first={first} \ --data size=50
Copy

Responses

200

Entire analysis report generated by MetaDefender Core

object	object
data_id	string	data identifier of the requested file
dlp_info	object	Full report from Proactive DLP
certainty	string	Describes how certain the hit is, possible values: `Very Low` `Low` `Medium` `High` `Very High` Enum: `Very Low`,`Low`,`Medium`,`High`,`Very High`
errors	object	A list of error objects (empty if no errors happened), each error object contains following keys: `scan`: scan related error description `redact`: redaction related error description `watermark`: watermark related error description `metadata_removal`: metadata removal related error description
filename	string	Output processed file name (pre-configured on engine settings under Core's worflow rule)
hits	object	Detailed results that contains as key the type of matched rule: ccn (credit card number), ssn (social security number), regex_ (regular expression with an index in order to differentiate the RegEx rules if there are more.)
ccn	object
display_name	string	Credit Card Number, Social Security Number, or in case of RegEx, the name of the rule that has been given by the user
hits	array[object]	A list of detections that matched this rule/pattern.
after	string	The context after the matched data.
before	string	The context before the matched data.
certainty	string	The text version of "certainty_score", possible values: `Very Low` `Low` `Medium` `High` `Very High` Enum: `Very Low`,`Low`,`Medium`,`High`,`Very High`
certainty_score	integer	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	string	The matched data.
location	string	The location of the hit that is found in a file.
severity	integer	(NOTE: this field is deprecated): can be 0 (detected) or 1 (suspicious). Enum: `0`,`1`
tryRedact	boolean	If file was redacted or not.
metadata_removal	object	Result of metadata removal.
result	string	Result of the metadata removal process, possible values: `removed` `not removed` `failed to remove` Enum: `removed`,`not removed`,`failed to remove`
redact	object	Result of redaction process.
result	string	Result of the redaction process, possible values: `redacted` `not redacted` `failed to redact` Enum: `redacted`,`not redacted`,`failed to redact`
severity	integer	(NOTE: this field is deprecated): represents the severity of the data loss, possible values: `0` - Certainly is data loss `1` - Might be data loss Enum: `0`,`1`
verdict	integer	The overall result for the scanned file. Possible values: `0` - Clean `1` - Found matched data `2` - Suspicious `3` - Failed `4` - Not scanned Enum: `0`,`1`,`2`,`3`,`4`
watermark	object	Result of watermarking process.
result	string	Result of the watermarking process, possible values: `added` `not added` `failed to add` Enum: `added`,`not added`,`failed to add`
download_info	object	The downloading status.
error_detail	string	Revealed detailed reason why the download failed.
progress	number	Only applicable when "status" is `Downloading`, indicates download finished percentage, in a range of [1, 99]. Once hitting 100, the status will be changed to `Download Success`. or other problematic status (`Download Cancelled`, `Download Failed`) if the download stopped unexpectedly.
status	string	Indicates download status, which could be either `Downloading` Check `progress` key value for actual download percentage `"download_info": { "progress": 7, "status": "Downloading", "url": "http://192.168.200.97:8080/5gb.zip" }` `Download Success` `"download_info": { "status": "Download Success", "url": "https://secure.eicar.org/eicar.com" }` `Download Failed` Check `error_detail` key value for an error explanation `"download_info": { "error_detail": "Connection error", "status": "Download Failed", "url": "http://192.168.200.97:8080/2gb.zip" }` `Download Timeout` Expecting to occur when the download progress takes longer than what time window allowed in MetaDefender Core's pre-configured setting under workflow rule (under "SCAN" tab) `"download_info": { "status": "Download Timeout", "url": "http://192.168.200.97:8080/2gb.zip" }` `Download Cancelled` Expecting to occur when user explicitly cancelled that file scan request, or batch request that the scan belongs to `"download_info": { "status": "Download Cancelled", "url": "http://192.168.200.97:8080/5gb.zip" }`
url	string	Original download link which was specified in HTTP(S) request's `downloadfrom` header
extraction_info	object	Details for archive extraction.
decrypted_status	string	Indicate that decryption phase is successful or not. Enum: `Success`,`Failed`
err_category	string	Error category
err_code	integer	Error code
err_details	string	Error message
is_encrypted_file	boolean	Indicate if file is password-protected or not.
file_info	object	basic information of the scanned file
display_name	string	The filename reported via `filename` header.
file_size	integer	Total file size in bytes.
file_type	string	The filetype using mimetype.
file_type_description	string	The filetype in human readable format.
md5	string	File's MD5 hash.
sha1	string	File's SHA1 hash.
sha256	string	File's SHA256 Hash.
sha512	string	File's SHA512 Hash.
signer_infos	array[object]	Digital signature information of the scanned file.
digest_algorithm	string	Digest algorithm.
digest_encryption_algorithm	string	Encryption algorithm.
issuer	string	Entity that develops and registers the certificate.
serial_number	string	Serial number of the certificate.
vendor_name	string	Entity that is issued a certificate and utilize it for creating a digital signature.
version	string	Version of X.509 that is used in the certificate. This version field is zero-based. 0: v1 1: v2 2: v3
type_category	array[string]	File type category. `A` - Archive files `AP` - Application `D` - Document (Microsoft Office) `D_ENC` - Encrypted Documents `E` - Executables `G` - Graphical format (JPG, PNG, GIF, etc.) `I` - Disk image `M` - Audio or video format `OPENSSL_ENC` - OpenSSL Encrypted Files `P` - PDF format `T` - Text `Z` - Mail messages `O` - Other (anything that is not recognized as one of the above) Enum: `A`,`D`,`E`,`G`,`I`,`M`,`P`,`T`,`Z`,`O`
receive_data_timestamp	string	The timestamp when upload progress started (first byte received) (in milliseconds)
upload_time	integer	Total time elapsed for upload process (in milliseconds).
upload_timestamp	string	The timestamp when upload progress finished (all bytes received) (in milliseconds)
filetype_info	object	response information from FileType engine
file_info	object
description	string	File type description
detected_by	string	Analyzer that detected the file type
encrypted	boolean	File is password-protected or not
extensions	string	File type extension
groupID	string	File type category
groupIDs	array[string]	File type category. `A` - Archive files `AP` - Application `D` - Document (Microsoft Office) `D_ENC` - Encrypted Documents `E` - Executables `G` - Graphical format (JPG, PNG, GIF, etc.) `I` - Disk image `M` - Audio or video format `OPENSSL_ENC` - OpenSSL Encrypted Files `P` - PDF format `T` - Text `Z` - Mail messages `O` - Other (anything that is not recognized as one of the above) Enum: `A`,`D`,`E`,`G`,`I`,`M`,`P`,`T`,`Z`,`O`
group_description	string	File type category description
likely_type_ids	array[object]	A list of likely file type IDs
score	integer	Likelihood score of the file type
typeID	string	File type ID
type	string	MIME type
typeID	string	File type ID
type_ids	array[string]	A list of file type IDs
final_verdict	object	Final verdict of the file type analysis.
verdict	string	Final verdict of the file type analysis. Enum: `allowed`,`blocked`
verdict_explanation	string	Explanation of the final verdict.
is_file_type_mismatch	boolean	Indicates if the file type does not match the expected type.
result_template_hash	string	SHA256 Hash of user-interface template. For web console only.
spoofing_info	object	Spoofing information.
detection_result	string	Result of the spoofing detection.
result_explanation	string	Explanation of the spoofing detection result.
result_overview	string	Overview of the spoofing detection result.
opswatfilescan_info	object	response information from OPSWAT Filescan engine
process_info	object	Processing information
blocked_reason	string	Provides the reason why the file is blocked (if so).
blocked_reasons	array[string]	Provides the reason why the file is blocked in an array (if so).
file_type_skipped_scan	boolean	Indicates if the input file's detected type was configured to skip scanning.
hash_time	integer	Total time elapsed for computing hashes (in milliseconds).
outdated_data	array[string]	array of flags - if occur - describing outdated data in the result, these can be engineconfigurations: the configuration of any AV engine in Inventory > Modules has been modified since the item was processed 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 Enum: `engineconfigurations`,`enginedefinitions`,`configuration`,`sanitization`
processing_time	integer	Total time elapsed during processing file (in milliseconds).
processing_time_details	object	Processing time on each major workflow processing step.
av_scan_time	integer	AV engines' processing time.
cdr_time	integer	Deep CDR engine's sanitization time.
dlp_time	integer	Proactive DLP engine's processing time.
extraction_time	integer	Archive extraction engine's processing time.
filetype_time	integer	FileType engine's processing time.
opswatfilescan_time	integer	OPSWAT Filescan engine's processing time.
others_time	integer	Total time elapsed for following processing tasks in the product (in milliseconds): Decryption time (if receiving an encrypted file) External scanner (if configured) Post action (if configured) Other internal processing time among components in the product
parse_dgsg_time	integer	Digital signature analyzing time.
vul_time	integer	Vulnerability engine's lookup time.
yara_time	integer	YARA engine's processing time.
filetype_wait_time	integer	FileType engine's wait time.
profile	string	The used rule name.
progress_percentage	integer	Percentage of processing completed (from 1-100).
queue_time	integer	Total time elapsed for file processing task was waiting in MetaDefender Core’s queue until being picked up (queue_time = start_time - upload_timestamp) (in milliseconds).
result	string	The final result of processing the file (Allowed / Blocked / Processing).
user_agent	string	Identifier for the REST Client that calls the API.
username	string	User identifier who submitted scan request earlier.
verdicts	array[string]	Aggregated list of potential issues.
post_processing	object	Contains information about result of sanitization process and any action done after finalizing the process using Post Actions.
actions_failed	string	Empty string if no action failed or list of failed actions, separated by "\|".
actions_ran	string	List of successful actions, separated by "\|". Empty string if otherwise.
converted_destination	string	Contains the name of the sanitized file.
converted_to	string	Contains target type name of sanitization.
copy_move_destination	string	Contains target type name of sanitization.
sanitization_details	object	Deep CDR module returns forensic info to describe what happened during the process in the case file was successfully sanitized.
cdr_wait_time	integer	The time in milliseconds that the CDR process took to complete.
description	string	Action was successful or not.
details	array[object]	List of all sanitized objects
action	string	The type of action that was performed Enum: `sanitized`,`removed`
count	integer	The number of objects that were sanitized/removed.
details	object	List of all sanitized objects of a sanitized embedded file
action	string	The type of action that was performed Enum: `sanitized`,`removed`
count	integer	The number of objects that were sanitized/removed.
object_details	array[string]	Additional information about the sanitized object
object_name	string	The object type that was sanitized/removed.
description	string	Action was successful or not.
file_name	string	If an embedded file was sanitized.
object_details	array[string]	Additional information about the sanitized object
object_name	string	The object type that was sanitized/removed.
failure_category	string	Deep CDR errors are classified into different categories. For more details, please find Troubleshooting sanitization failures
result	string	The result of the CDR process. Sanitized: the file was successfully sanitized. Sanitized failed: the file could not be sanitized due to an error during the process. Sanitized skipped: the file was skipped from sanitization. Common reasons include the file being digitally signed or other policy-based exclusions. Enum: `Sanitized`,`Sanitized failed`,`Sanitized skipped`
result_template_hash	string	The hash value of the result template, which is used for displaying results on the Core UI and for internal communication between MetaDefender Core and the Deep CDR engine. This value is intended for system use only and is not required for external integration.
sanitized_file_info	object	Information of sanitized file. Only applicable to individual file sanitization, or original archive document sanitization level.
file_size	integer	Size of sanitized file in bytes.
sha256	string	SHA256 hash of sanitized file.
verdict	string	The verdict of the CDR process. blocked: the file is recommended for blocking by Deep CDR. allowed: the file is recommended for allowing by Deep CDR as it found no reason to recommend blocking it. Enum: `blocked`,`allowed`
verdict_explanations	array[string]	The explanations for the verdict of the CDR process.
scan_results	object	Result of the scanning process.
data_id	string	Data ID of the requested file
progress_percentage	integer	Track analysis progress until reaches 100.
scan_all_result_a	string	Processing result and its index `No Threat Detected`: 0 `Infected`: 1 `Suspicious`: 2 `Failed`: 3 `Whitelisted`: 7 `Blacklisted`: 8 `Exceeded Archive Depth`: 9 `Not Scanned`: 10 `Encrypted Archive`: 12 `Exceeded Archive Size`: 13 `Exceeded Archive File Number`: 14 `Password Protected Document`: 15 `Exceeded Archive Timeout`: 16 `Mismatch`: 17 `Potentially Vulnerable File`: 18 `Cancelled`: 19 `Sensitive Data Found`: 20 `Yara Rule Matched`: 21 `Potentially Unwanted`: 22 `Unsupported File Type`: 23 `Extraction Failed`: 24 `Scan Failed`: 25 `Suspicious Verdict by Sandbox`: 26 `Likely Malicious Verdict by Sandbox`: 27 `Malicious Verdict by Sandbox`: 28 `Blocked Verdict by Sandbox`: 29 `Blocked Verdict by Deep CDR`: 30 `Global Timeout Exceeded`: 31 `Vulnerable Verdict by SBOM`: 32 `Non-vulnerable Verdict by SBOM`: 33 `Blocked Verdict by SBOM`: 34 `Blocked by Post Action`: 36 `Known Bad`: 38 `Known Good`: 39 `Unknown`: 40 `Allowed Verdict by COO`: 41 `Blocked Verdict by COO`: 42 `Unknown Verdict by COO`: 43 `In Progress`: 255 `Skip Processing Fast Symlink`: 1014 Enum: `No Threat Detected`,`Infected`,`Suspicious`,`Failed`,`Whitelisted`,`Blacklisted`,`Exceeded Archive Depth`,`Not Scanned`,`Encrypted Archive`,`Exceeded Archive Size`,`Exceeded Archive File Number`,`Password Protected Document`,`Exceeded Archive Timeout`,`Mismatch`,`Potentially Vulnerable File`,`Cancelled`,`Sensitive Data Found`,`Yara Rule Matched`,`Potentially Unwanted`,`Unsupported File Type`,`Extraction Failed`,`Scan Failed`,`Suspicious Verdict by Sandbox`,`Likely Malicious Verdict by Sandbox`,`Malicious Verdict by Sandbox`,`Blocked Verdict by Sandbox`,`Blocked Verdict by Deep CDR`,`Global Timeout Exceeded`,`Vulnerable Verdict by SBOM`,`Non-vulnerable Verdict by SBOM`,`Blocked Verdict by SBOM`,`Blocked by Post Action`,`Known Bad`,`Known Good`,`Unknown`,`Allowed Verdict by COO`,`Blocked Verdict by COO`,`Unknown Verdict by COO`,`In Progress`,`Skip Processing Fast Symlink`
scan_all_result_i	integer	Scan result as index in the Processing Results table above Enum: `0`,`1`,`2`,`3`,`7`,`8`,`9`,`10`,`12`,`13`,`14`,`15`,`16`,`17`,`18`,`19`,`20`,`21`,`22`,`23`,`24`,`25`,`26`,`27`,`28`,`29`,`30`,`31`,`32`,`33`,`34`,`36`,`38`,`39`,`40`,`41`,`42`,`43`,`255`,`1014`
start_time	string	Timestamp when the scanning process starts.
total_avs	integer	Total number of scanning engines used as part of this analysis.
total_time	integer	Total time elapsed during scan (in milliseconds).
scan_details	object	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
ClamAV	object	Scan report per each engine.
def_time	string	The database definition time for this engine
eng_id	string	The unique identification string for the engine
location	string	Where this engine is deployed (local/remote).
scan_result_i	integer	Scan result as index in the Processing Results table
scan_time	integer	The time elapsed during scan with this engine (in milliseconds).
threat_found	string	The threat name, IF scan result is Infected or Suspicious. Otherwise empty string or error message from the engine.
wait_time	integer	Time elapsed between sending file to Core and receiving the result from the engine (in milliseconds).
vulnerability_info	object	Contains all vulnerability information of the analysis result
result	object	The result information provided by the OESIS Framework
code	integer	The result code for vulnerability check, 0 means a successful check
hash	string	The file's SHA1 hash value
method	integer	The method used by OESIS Framework, it should be 50700 every time. Enum: `50700`
timestamp	string	Timestamp of the request issued
timing	integer	The vulnerability check's duration in milliseconds
detected_product	object	Detected products object is present if input hash has been found to correspond to verified product
has_kb	boolean	Indicates whether any KBs or MSBs exist for this hash
has_vulnerability	boolean	Indicates whether any vulnerabilities have been associated with the particular product
is_current	boolean	True if this product's patch level is current, defaults to true
product	object	Product data object
id	integer	The OPSWAT product id
name	string	The product name
remediation_link	string	A link where product updates or patches can be obtained
severity	string	String description of Severity level: `LOW` `MODERATE` `IMPORTANT` `CRITICAL` `NOT_AVAILABLE` `UNKNOWN` Enum: `LOW`,`MODERATE`,`IMPORTANT`,`CRITICAL`,`NOT_AVAILABLE`,`UNKNOWN`
sig_name	string	Product signature descriptor
signature	integer	OPSWAT signature id
vendor	object	Vendor data object
id	integer	The OPSWAT vendor id
name	string	The vendor name
version	string	The installed product version
version_data	object	Object containing detailed patch information
count_behind	integer	The number of patches behind of the installed product
feed_id	integer	The remote feed ID used to determine patch level
version	string	The current version of the product in the remote feed
vulnerabilites	array[object]	A list of specific vulnerabilities
description	string	A text description of the specific vulnerability
details	object	A set of optional vulnerability details
cpe	string	A CPE product reference
cve	string	A CVE identification string
cvss	object	A set of cvss severity information
access-complexity	string	A CVSS access-complexity descriptor
access-vector	string	A CVSS access-vector descriptor
authentication	string	A CVSS authentication descriptor
availability-impact	string	A CVSS availability impact descriptor
confidentiality-impact	string	A CVSS confidentiality impact descriptor
generated-on-epoch	string	An epoch timestamp indicating CVSS generation time
integrity-impact	string	A CVSS integrity impact descriptor
score	string	A CVSS 10-point severity score
source	string	A CVSS source descriptor
cwe	string	A CWE group identification string
last_modified_epoch	string	An epoch timestamp indicating source last update time
published-epoch	string	An epoch timestamp indicating source publishing time
references	array[string]	An array of external reference links
severity	string	String description of Severity level: `LOW` `MODERATE` `IMPORTANT` `CRITICAL` `NOT_AVAILABLE` `UNKNOWN` Enum: `LOW`,`MODERATE`,`IMPORTANT`,`CRITICAL`,`NOT_AVAILABLE`,`UNKNOWN`
severity_index	integer	A 5 point scale numerical description of Severity level with 5 being greatest and 0 being unknown
static_id	integer	An OPSWAT identifier for the vulnerability
verdict	integer	The vulnerability check's duration in milliseconds `0` - No Vulnerability Found `1` - Vulnerability Found `3` - Failed `16` - Processing Timed Out
yara	object	Information on data that matched YARA rules
hits	object	detailed results that contains the name of the matched rules and a description for each.
verdict	integer	The overall result for the analyzed file. Value will be one of the following: \| index \| status \| \|---------------\|------------------------------\| \| 0 \| Clean \| \| 1 \| Found matched data \| \| 2 \| Suspicious \| \| 3 \| Failed \| \| 4 \| Not scanned \| Enum: `0`,`1`,`2`,`3`,`4`

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

405

The user has no rights for this operation.

500

Unexpected event on server

Response

xxxxxxxxxx
 
{
 "data_id": "8101abae27be4d63859c55d9e0ed0135", "dlp_info": {...},
 "download_info": {...},
 "extraction_info": {...},
 "file_info": {...},
 "filetype_info": {...},
 "opswatfilescan_info": {}, "process_info": {...},
 "scan_results": {...},
 "vulnerability_info": {...},
 "yara": {...}
}
Copy

Fetch Analysis Result By Hash

Retrieve analysis result by hash

Auth

Headers

apikey	string	Generated `session_id` from Login call can be used as an `apikey` for API calls that require authentication.
rule	string	Select rule for the analysis, if no header given the default rule will be selected (URL encoded UTF-8 string of rule name)
selfonly	boolean	Useful to archive hash lookup. Allow specifying to only perform hash lookup against the original archive file self only, and skip searching all child files result within the original archive. Default value is false.
timerange	integer	Scoping down the recent number of hours that hash lookup task should start from till now, instead of searching the entire scan history in MetaDefender Cluster database. Default value is 0. That means no time scope.
include-inprogress	boolean	False (default): API will return "Not Found" if the verdict is in progress. True: If the queried hash has a completed processing result before, API will return the completed processing result. If this hash doesn't have any completed processing result, API will return this In-progress result.

Path Params

md5|sha1|sha256|sha512

string

Hash value to search. This can be md5, sha1, sha256, sha512

Query String

first

integer

The first item order in the list child files of archive file

minimum: 0

Default: 0

size

integer

The number of items to be fetched next, counting from the item order indicated in first header. The default value is 50, and the maximum value is 2000.

maximum: 2000

minimum: 0

Default: 50

GET /hash/{md5|sha1|sha256|sha512}

 
curl --get \ --url 'http://localhost:8899/hash/{md5|sha1|sha256|sha512}' \ --header 'apikey: {apikey}' \ --header 'rule: {rule}' \ --header 'selfonly: {selfonly}' \ --header 'timerange: {timerange}' \ --header 'include-inprogress: {include-inprogress}' \ --data first={first} \ --data size=50
Copy

Responses

200

Get information of file

object	object
data_id	string	data identifier of the requested file
dlp_info	object	Full report from Proactive DLP
certainty	string	Describes how certain the hit is, possible values: `Very Low` `Low` `Medium` `High` `Very High` Enum: `Very Low`,`Low`,`Medium`,`High`,`Very High`
errors	object	A list of error objects (empty if no errors happened), each error object contains following keys: `scan`: scan related error description `redact`: redaction related error description `watermark`: watermark related error description `metadata_removal`: metadata removal related error description
filename	string	Output processed file name (pre-configured on engine settings under Core's worflow rule)
hits	object	Detailed results that contains as key the type of matched rule: ccn (credit card number), ssn (social security number), regex_ (regular expression with an index in order to differentiate the RegEx rules if there are more.)
ccn	object
display_name	string	Credit Card Number, Social Security Number, or in case of RegEx, the name of the rule that has been given by the user
hits	array[object]	A list of detections that matched this rule/pattern.
after	string	The context after the matched data.
before	string	The context before the matched data.
certainty	string	The text version of "certainty_score", possible values: `Very Low` `Low` `Medium` `High` `Very High` Enum: `Very Low`,`Low`,`Medium`,`High`,`Very High`
certainty_score	integer	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	string	The matched data.
location	string	The location of the hit that is found in a file.
severity	integer	(NOTE: this field is deprecated): can be 0 (detected) or 1 (suspicious). Enum: `0`,`1`
tryRedact	boolean	If file was redacted or not.
metadata_removal	object	Result of metadata removal.
result	string	Result of the metadata removal process, possible values: `removed` `not removed` `failed to remove` Enum: `removed`,`not removed`,`failed to remove`
redact	object	Result of redaction process.
result	string	Result of the redaction process, possible values: `redacted` `not redacted` `failed to redact` Enum: `redacted`,`not redacted`,`failed to redact`
severity	integer	(NOTE: this field is deprecated): represents the severity of the data loss, possible values: `0` - Certainly is data loss `1` - Might be data loss Enum: `0`,`1`
verdict	integer	The overall result for the scanned file. Possible values: `0` - Clean `1` - Found matched data `2` - Suspicious `3` - Failed `4` - Not scanned Enum: `0`,`1`,`2`,`3`,`4`
watermark	object	Result of watermarking process.
result	string	Result of the watermarking process, possible values: `added` `not added` `failed to add` Enum: `added`,`not added`,`failed to add`
download_info	object	The downloading status.
error_detail	string	Revealed detailed reason why the download failed.
progress	number	Only applicable when "status" is `Downloading`, indicates download finished percentage, in a range of [1, 99]. Once hitting 100, the status will be changed to `Download Success`. or other problematic status (`Download Cancelled`, `Download Failed`) if the download stopped unexpectedly.
status	string	Indicates download status, which could be either `Downloading` Check `progress` key value for actual download percentage `"download_info": { "progress": 7, "status": "Downloading", "url": "http://192.168.200.97:8080/5gb.zip" }` `Download Success` `"download_info": { "status": "Download Success", "url": "https://secure.eicar.org/eicar.com" }` `Download Failed` Check `error_detail` key value for an error explanation `"download_info": { "error_detail": "Connection error", "status": "Download Failed", "url": "http://192.168.200.97:8080/2gb.zip" }` `Download Timeout` Expecting to occur when the download progress takes longer than what time window allowed in MetaDefender Core's pre-configured setting under workflow rule (under "SCAN" tab) `"download_info": { "status": "Download Timeout", "url": "http://192.168.200.97:8080/2gb.zip" }` `Download Cancelled` Expecting to occur when user explicitly cancelled that file scan request, or batch request that the scan belongs to `"download_info": { "status": "Download Cancelled", "url": "http://192.168.200.97:8080/5gb.zip" }`
url	string	Original download link which was specified in HTTP(S) request's `downloadfrom` header
extraction_info	object	Details for archive extraction.
decrypted_status	string	Indicate that decryption phase is successful or not. Enum: `Success`,`Failed`
err_category	string	Error category
err_code	integer	Error code
err_details	string	Error message
is_encrypted_file	boolean	Indicate if file is password-protected or not.
file_info	object	basic information of the scanned file
display_name	string	The filename reported via `filename` header.
file_size	integer	Total file size in bytes.
file_type	string	The filetype using mimetype.
file_type_description	string	The filetype in human readable format.
md5	string	File's MD5 hash.
sha1	string	File's SHA1 hash.
sha256	string	File's SHA256 Hash.
sha512	string	File's SHA512 Hash.
signer_infos	array[object]	Digital signature information of the scanned file.
digest_algorithm	string	Digest algorithm.
digest_encryption_algorithm	string	Encryption algorithm.
issuer	string	Entity that develops and registers the certificate.
serial_number	string	Serial number of the certificate.
vendor_name	string	Entity that is issued a certificate and utilize it for creating a digital signature.
version	string	Version of X.509 that is used in the certificate. This version field is zero-based. 0: v1 1: v2 2: v3
type_category	array[string]	File type category. `A` - Archive files `AP` - Application `D` - Document (Microsoft Office) `D_ENC` - Encrypted Documents `E` - Executables `G` - Graphical format (JPG, PNG, GIF, etc.) `I` - Disk image `M` - Audio or video format `OPENSSL_ENC` - OpenSSL Encrypted Files `P` - PDF format `T` - Text `Z` - Mail messages `O` - Other (anything that is not recognized as one of the above) Enum: `A`,`D`,`E`,`G`,`I`,`M`,`P`,`T`,`Z`,`O`
receive_data_timestamp	string	The timestamp when upload progress started (first byte received) (in milliseconds)
upload_time	integer	Total time elapsed for upload process (in milliseconds).
upload_timestamp	string	The timestamp when upload progress finished (all bytes received) (in milliseconds)
filetype_info	object	response information from FileType engine
file_info	object
description	string	File type description
detected_by	string	Analyzer that detected the file type
encrypted	boolean	File is password-protected or not
extensions	string	File type extension
groupID	string	File type category
groupIDs	array[string]	File type category. `A` - Archive files `AP` - Application `D` - Document (Microsoft Office) `D_ENC` - Encrypted Documents `E` - Executables `G` - Graphical format (JPG, PNG, GIF, etc.) `I` - Disk image `M` - Audio or video format `OPENSSL_ENC` - OpenSSL Encrypted Files `P` - PDF format `T` - Text `Z` - Mail messages `O` - Other (anything that is not recognized as one of the above) Enum: `A`,`D`,`E`,`G`,`I`,`M`,`P`,`T`,`Z`,`O`
group_description	string	File type category description
likely_type_ids	array[object]	A list of likely file type IDs
score	integer	Likelihood score of the file type
typeID	string	File type ID
type	string	MIME type
typeID	string	File type ID
type_ids	array[string]	A list of file type IDs
final_verdict	object	Final verdict of the file type analysis.
verdict	string	Final verdict of the file type analysis. Enum: `allowed`,`blocked`
verdict_explanation	string	Explanation of the final verdict.
is_file_type_mismatch	boolean	Indicates if the file type does not match the expected type.
result_template_hash	string	SHA256 Hash of user-interface template. For web console only.
spoofing_info	object	Spoofing information.
detection_result	string	Result of the spoofing detection.
result_explanation	string	Explanation of the spoofing detection result.
result_overview	string	Overview of the spoofing detection result.
opswatfilescan_info	object	response information from OPSWAT Filescan engine
process_info	object	Processing information
blocked_reason	string	Provides the reason why the file is blocked (if so).
blocked_reasons	array[string]	Provides the reason why the file is blocked in an array (if so).
file_type_skipped_scan	boolean	Indicates if the input file's detected type was configured to skip scanning.
hash_time	integer	Total time elapsed for computing hashes (in milliseconds).
outdated_data	array[string]	array of flags - if occur - describing outdated data in the result, these can be engineconfigurations: the configuration of any AV engine in Inventory > Modules has been modified since the item was processed 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 Enum: `engineconfigurations`,`enginedefinitions`,`configuration`,`sanitization`
processing_time	integer	Total time elapsed during processing file (in milliseconds).
processing_time_details	object	Processing time on each major workflow processing step.
av_scan_time	integer	AV engines' processing time.
cdr_time	integer	Deep CDR engine's sanitization time.
dlp_time	integer	Proactive DLP engine's processing time.
extraction_time	integer	Archive extraction engine's processing time.
filetype_time	integer	FileType engine's processing time.
opswatfilescan_time	integer	OPSWAT Filescan engine's processing time.
others_time	integer	Total time elapsed for following processing tasks in the product (in milliseconds): Decryption time (if receiving an encrypted file) External scanner (if configured) Post action (if configured) Other internal processing time among components in the product
parse_dgsg_time	integer	Digital signature analyzing time.
vul_time	integer	Vulnerability engine's lookup time.
yara_time	integer	YARA engine's processing time.
filetype_wait_time	integer	FileType engine's wait time.
profile	string	The used rule name.
progress_percentage	integer	Percentage of processing completed (from 1-100).
queue_time	integer	Total time elapsed for file processing task was waiting in MetaDefender Core’s queue until being picked up (queue_time = start_time - upload_timestamp) (in milliseconds).
result	string	The final result of processing the file (Allowed / Blocked / Processing).
user_agent	string	Identifier for the REST Client that calls the API.
username	string	User identifier who submitted scan request earlier.
verdicts	array[string]	Aggregated list of potential issues.
post_processing	object	Contains information about result of sanitization process and any action done after finalizing the process using Post Actions.
actions_failed	string	Empty string if no action failed or list of failed actions, separated by "\|".
actions_ran	string	List of successful actions, separated by "\|". Empty string if otherwise.
converted_destination	string	Contains the name of the sanitized file.
converted_to	string	Contains target type name of sanitization.
copy_move_destination	string	Contains target type name of sanitization.
sanitization_details	object	Deep CDR module returns forensic info to describe what happened during the process in the case file was successfully sanitized.
cdr_wait_time	integer	The time in milliseconds that the CDR process took to complete.
description	string	Action was successful or not.
details	array[object]	List of all sanitized objects
action	string	The type of action that was performed Enum: `sanitized`,`removed`
count	integer	The number of objects that were sanitized/removed.
details	object	List of all sanitized objects of a sanitized embedded file
action	string	The type of action that was performed Enum: `sanitized`,`removed`
count	integer	The number of objects that were sanitized/removed.
object_details	array[string]	Additional information about the sanitized object
object_name	string	The object type that was sanitized/removed.
description	string	Action was successful or not.
file_name	string	If an embedded file was sanitized.
object_details	array[string]	Additional information about the sanitized object
object_name	string	The object type that was sanitized/removed.
failure_category	string	Deep CDR errors are classified into different categories. For more details, please find Troubleshooting sanitization failures
result	string	The result of the CDR process. Sanitized: the file was successfully sanitized. Sanitized failed: the file could not be sanitized due to an error during the process. Sanitized skipped: the file was skipped from sanitization. Common reasons include the file being digitally signed or other policy-based exclusions. Enum: `Sanitized`,`Sanitized failed`,`Sanitized skipped`
result_template_hash	string	The hash value of the result template, which is used for displaying results on the Core UI and for internal communication between MetaDefender Core and the Deep CDR engine. This value is intended for system use only and is not required for external integration.
sanitized_file_info	object	Information of sanitized file. Only applicable to individual file sanitization, or original archive document sanitization level.
file_size	integer	Size of sanitized file in bytes.
sha256	string	SHA256 hash of sanitized file.
verdict	string	The verdict of the CDR process. blocked: the file is recommended for blocking by Deep CDR. allowed: the file is recommended for allowing by Deep CDR as it found no reason to recommend blocking it. Enum: `blocked`,`allowed`
verdict_explanations	array[string]	The explanations for the verdict of the CDR process.
scan_results	object	Result of the scanning process.
data_id	string	Data ID of the requested file
progress_percentage	integer	Track analysis progress until reaches 100.
scan_all_result_a	string	Processing result and its index `No Threat Detected`: 0 `Infected`: 1 `Suspicious`: 2 `Failed`: 3 `Whitelisted`: 7 `Blacklisted`: 8 `Exceeded Archive Depth`: 9 `Not Scanned`: 10 `Encrypted Archive`: 12 `Exceeded Archive Size`: 13 `Exceeded Archive File Number`: 14 `Password Protected Document`: 15 `Exceeded Archive Timeout`: 16 `Mismatch`: 17 `Potentially Vulnerable File`: 18 `Cancelled`: 19 `Sensitive Data Found`: 20 `Yara Rule Matched`: 21 `Potentially Unwanted`: 22 `Unsupported File Type`: 23 `Extraction Failed`: 24 `Scan Failed`: 25 `Suspicious Verdict by Sandbox`: 26 `Likely Malicious Verdict by Sandbox`: 27 `Malicious Verdict by Sandbox`: 28 `Blocked Verdict by Sandbox`: 29 `Blocked Verdict by Deep CDR`: 30 `Global Timeout Exceeded`: 31 `Vulnerable Verdict by SBOM`: 32 `Non-vulnerable Verdict by SBOM`: 33 `Blocked Verdict by SBOM`: 34 `Blocked by Post Action`: 36 `Known Bad`: 38 `Known Good`: 39 `Unknown`: 40 `Allowed Verdict by COO`: 41 `Blocked Verdict by COO`: 42 `Unknown Verdict by COO`: 43 `In Progress`: 255 `Skip Processing Fast Symlink`: 1014 Enum: `No Threat Detected`,`Infected`,`Suspicious`,`Failed`,`Whitelisted`,`Blacklisted`,`Exceeded Archive Depth`,`Not Scanned`,`Encrypted Archive`,`Exceeded Archive Size`,`Exceeded Archive File Number`,`Password Protected Document`,`Exceeded Archive Timeout`,`Mismatch`,`Potentially Vulnerable File`,`Cancelled`,`Sensitive Data Found`,`Yara Rule Matched`,`Potentially Unwanted`,`Unsupported File Type`,`Extraction Failed`,`Scan Failed`,`Suspicious Verdict by Sandbox`,`Likely Malicious Verdict by Sandbox`,`Malicious Verdict by Sandbox`,`Blocked Verdict by Sandbox`,`Blocked Verdict by Deep CDR`,`Global Timeout Exceeded`,`Vulnerable Verdict by SBOM`,`Non-vulnerable Verdict by SBOM`,`Blocked Verdict by SBOM`,`Blocked by Post Action`,`Known Bad`,`Known Good`,`Unknown`,`Allowed Verdict by COO`,`Blocked Verdict by COO`,`Unknown Verdict by COO`,`In Progress`,`Skip Processing Fast Symlink`
scan_all_result_i	integer	Scan result as index in the Processing Results table above Enum: `0`,`1`,`2`,`3`,`7`,`8`,`9`,`10`,`12`,`13`,`14`,`15`,`16`,`17`,`18`,`19`,`20`,`21`,`22`,`23`,`24`,`25`,`26`,`27`,`28`,`29`,`30`,`31`,`32`,`33`,`34`,`36`,`38`,`39`,`40`,`41`,`42`,`43`,`255`,`1014`
start_time	string	Timestamp when the scanning process starts.
total_avs	integer	Total number of scanning engines used as part of this analysis.
total_time	integer	Total time elapsed during scan (in milliseconds).
scan_details	object	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
ClamAV	object	Scan report per each engine.
def_time	string	The database definition time for this engine
eng_id	string	The unique identification string for the engine
location	string	Where this engine is deployed (local/remote).
scan_result_i	integer	Scan result as index in the Processing Results table
scan_time	integer	The time elapsed during scan with this engine (in milliseconds).
threat_found	string	The threat name, IF scan result is Infected or Suspicious. Otherwise empty string or error message from the engine.
wait_time	integer	Time elapsed between sending file to Core and receiving the result from the engine (in milliseconds).
vulnerability_info	object	Contains all vulnerability information of the analysis result
result	object	The result information provided by the OESIS Framework
code	integer	The result code for vulnerability check, 0 means a successful check
hash	string	The file's SHA1 hash value
method	integer	The method used by OESIS Framework, it should be 50700 every time. Enum: `50700`
timestamp	string	Timestamp of the request issued
timing	integer	The vulnerability check's duration in milliseconds
detected_product	object	Detected products object is present if input hash has been found to correspond to verified product
has_kb	boolean	Indicates whether any KBs or MSBs exist for this hash
has_vulnerability	boolean	Indicates whether any vulnerabilities have been associated with the particular product
is_current	boolean	True if this product's patch level is current, defaults to true
product	object	Product data object
id	integer	The OPSWAT product id
name	string	The product name
remediation_link	string	A link where product updates or patches can be obtained
severity	string	String description of Severity level: `LOW` `MODERATE` `IMPORTANT` `CRITICAL` `NOT_AVAILABLE` `UNKNOWN` Enum: `LOW`,`MODERATE`,`IMPORTANT`,`CRITICAL`,`NOT_AVAILABLE`,`UNKNOWN`
sig_name	string	Product signature descriptor
signature	integer	OPSWAT signature id
vendor	object	Vendor data object
id	integer	The OPSWAT vendor id
name	string	The vendor name
version	string	The installed product version
version_data	object	Object containing detailed patch information
count_behind	integer	The number of patches behind of the installed product
feed_id	integer	The remote feed ID used to determine patch level
version	string	The current version of the product in the remote feed
vulnerabilites	array[object]	A list of specific vulnerabilities
description	string	A text description of the specific vulnerability
details	object	A set of optional vulnerability details
cpe	string	A CPE product reference
cve	string	A CVE identification string
cvss	object	A set of cvss severity information
access-complexity	string	A CVSS access-complexity descriptor
access-vector	string	A CVSS access-vector descriptor
authentication	string	A CVSS authentication descriptor
availability-impact	string	A CVSS availability impact descriptor
confidentiality-impact	string	A CVSS confidentiality impact descriptor
generated-on-epoch	string	An epoch timestamp indicating CVSS generation time
integrity-impact	string	A CVSS integrity impact descriptor
score	string	A CVSS 10-point severity score
source	string	A CVSS source descriptor
cwe	string	A CWE group identification string
last_modified_epoch	string	An epoch timestamp indicating source last update time
published-epoch	string	An epoch timestamp indicating source publishing time
references	array[string]	An array of external reference links
severity	string	String description of Severity level: `LOW` `MODERATE` `IMPORTANT` `CRITICAL` `NOT_AVAILABLE` `UNKNOWN` Enum: `LOW`,`MODERATE`,`IMPORTANT`,`CRITICAL`,`NOT_AVAILABLE`,`UNKNOWN`
severity_index	integer	A 5 point scale numerical description of Severity level with 5 being greatest and 0 being unknown
static_id	integer	An OPSWAT identifier for the vulnerability
verdict	integer	The vulnerability check's duration in milliseconds `0` - No Vulnerability Found `1` - Vulnerability Found `3` - Failed `16` - Processing Timed Out
yara	object	Information on data that matched YARA rules
hits	object	detailed results that contains the name of the matched rules and a description for each.
verdict	integer	The overall result for the analyzed file. Value will be one of the following: \| index \| status \| \|---------------\|------------------------------\| \| 0 \| Clean \| \| 1 \| Found matched data \| \| 2 \| Suspicious \| \| 3 \| Failed \| \| 4 \| Not scanned \| Enum: `0`,`1`,`2`,`3`,`4`

404

Invalid hash format

Response

xxxxxxxxxx
 
{
 "data_id": "8101abae27be4d63859c55d9e0ed0135", "dlp_info": {...},
 "download_info": {...},
 "extraction_info": {...},
 "file_info": {...},
 "filetype_info": {...},
 "opswatfilescan_info": {}, "process_info": {...},
 "scan_results": {...},
 "vulnerability_info": {...},
 "yara": {...}
}
Copy

Fetching Available Analysis Rules

Retrieve all available rules with their custom configurations. Fetching available processing rules.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication. Only those rules are returned, that:

Match the apikey's role sent using the apikey header, or
Are not restricted to a specific role.

user_agent

string

The user agent string value sent in the header (specified by the client).

Only those rules are returned, that:

Match the client's user agent sent using the user_agent header, or
Are not restricted to a specific user agent.

For details see KB article What are Security Policies and how do I use them?.

GET /file/rules

 
curl --get \ --url 'http://localhost:8899/file/rules' \ --header 'apikey: {apikey}' \ --header 'user_agent: {user_agent}'
Copy

Responses

200

Returns the list of available rules.

array	array[object]
max_file_size	integer	The maximum allowed file size (in bytes) for this rule.
name	string	A unique identifier for identify in the used rule for a scan..
global_timeout	object	The global timeout for the rule in seconds. If the rule takes longer than this time, it will be stopped.
value	integer	The timeout value in seconds.
enabled	boolean	Indicates whether the global timeout is enabled.

500

Unexpected event on server

Response

 
[ {  "max_file_size": 200000000,  "name": "File scan",  "global_timeout": {   "value": 1440,   "enabled": false  } }]
Copy

Download Sanitized Files

Retrieve sanitized file based on the data_id

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Path Params

data_id

string

The data_id comes from the result of Analyze a file. In case of sanitizing the content of an archive, the data_id of contained file can be found in Fetch analysis result.

GET /file/converted/{data_id}

 
curl --get \ --url 'http://localhost:8899/file/converted/8101abae27be4d63859c55d9e0ed0135' \ --header 'apikey: {apikey}'
Copy

Responses

200

Returns the sanitized content.

file file

404

Requests resource was not found.

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
<Raw bytes content>
Copy

Download either sanitized files or DLP processed files

Retrieve sanitized file based on the data_id. In case there's no sanitized file, and DLP processed file is available, user will retrieve DLP processed file.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Path Params

data_id

string

The data_id comes from the result of Analyze a file. In case of sanitizing the content of an archive, the data_id of contained file can be found in Fetch analysis result.

GET /file/download/{data_id}

 
curl --get \ --url 'http://localhost:8899/file/download/8101abae27be4d63859c55d9e0ed0135' \ --header 'apikey: {apikey}'
Copy

Responses

200

Returns the sanitized or DLP processed content.

file file

404

File could not be found

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
<Raw bytes content>
Copy

Cancel File Analysis

When cancelling a file analysis, the connected analysis (e.g. files in an archive) that are still in progress will be cancelled also.

The cancelled analysis will be automatically closed.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Path Params

data_id

string

Unique submission identifier. Use this value to reference the submission.

POST /file/{data_id}/cancel

 
curl --request POST \ --url 'http://localhost:8899/file/{data_id}/cancel' \ --header 'apikey: {apikey}'
Copy

Responses

200

Analysis was sucessfully cancelled.

object object

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Data ID not found (invalid id) or Requests resource was not found

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "<<data_id>>": "cancelled"}
Copy

Query webhook status

Prior to being notified when webhook mode is enabled, the client can request MetaDefender Cluster API Gateway for the file processing webhook status at any time.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Path Params

data_id

string

The data_id of the file to query.

GET /file/webhook/{data_id}

 
curl --get \ --url 'http://localhost:8899/file/webhook/{data_id}' \ --header 'apikey: {apikey}'
Copy

Responses

200

Webhook status is fetched successfully.

object	object
data_id	string	The file submission identifier
request_time	string	A timestamp when the request has been made.
status_code	integer	What was the returned HTTP status code. `200` - Callback was sent successfully `403` - ContentAccessDenied. The access to the remote content was denied (similar to HTTP(S) error 401). `404` - ContentNotFoundError. The remote content was not found at the server (similar to HTTP(S) error 404). `408` - TimeoutError. The connection to the remote server timed out. `503` - HostNotFoundError. The remote host name was not found (invalid hostname). `520` - RemoteHostClosedError. The remote server closed the connection prematurely, before the entire reply was received and processed. `444` - Other error types.
url	string	What was the called URL (should match the `callbackurl` header).

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

500

Unexpected event on server

Response

 
{ "data_id": "j2939fh3ifoqkhwhr3h9h1h0re", "request_time": "{string}", "status_code": 200, "url": "https://apigateway.corporate.com/metadefender/callbackurl"}
Copy

Batch

Group the analysis requests in batches. Supported with endpoints: MetaDefender Cluster API Gateway.

POST

/file/batch

POST

/file/batch/{batchId}/close

GET

/file/batch/{batchId}

GET

/file/batch/{batchId}/certificate

POST

/file/batch/{batchId}/cancel

Initiate Batch

Create a new batch and retrieve the batch_id

Auth

Headers

apikey	string	Generated `session_id` from Login call can be used as an `apikey` for API calls that require authentication.
rule	string	Select rule for the analysis, if no header given the default rule will be selected (URL encoded UTF-8 string of rule name)
user_agent	string	user_agent header used to identify (and limit) access to a particular rule. For rule selection, `rule` header should be used.
user-data	string	Name of the batch (max 1024 bytes, URL encoded UTF-8 string).

POST /file/batch

 
curl --request POST \ --url 'http://localhost:8899/file/batch' \ --header 'apikey: {apikey}' \ --header 'rule: {rule}' \ --header 'user_agent: {user_agent}' \ --header 'user-data: {user-data}'
Copy

Responses

200

Batch created successfully.

object	object
batch_id	string	The batch identifier used to submit files in the batch and to close the batch.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

500

Unexpected event on server

Response

 
{ "batch_id": "74c85f475147439bac4d33b181853923"}
Copy

Close Batch

The batch will be closed and files can no longer be added to the current batch.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Path Params

batchId

string

The batch identifier used to submit files in the batch and to close the batch.

POST /file/batch/{batchId}/close

 
curl --request POST \ --url 'http://localhost:8899/file/batch/{batchId}/close' \ --header 'apikey: {apikey}'
Copy

Responses

200

Batch successfully closed.

object	object	The response for a Batch status request.
batch_files	object	Information about the files included in this batch.
batch_count	integer	The total number of files/entries in the batch.
current_finished_files	integer	The total number of files/entries that have been fully processed in the batch.
files_in_batch	array[object]	The list of files in the batch.
data_id	string	Unique identifer for the file.
detected_by	integer	Total number of engines that detected this file.
display_name	string	The filename reported via `filename` header.
file_size	integer	Total file size in bytes.
file_type	string	The filetype using mimetype.
file_type_description	string	The filetype in human readable format.
process_info	object	The analysis summary
blocked_reason	string	Provides the reason why the file is blocked (if so).
progress_percentage	integer	Percentage of processing completed (from 1-100).
result	string	The final result of processing the file (Allowed / Blocked / Processing).
verdicts	array[string]	Aggregated list of potential issues.
progress_percentage	integer	Track analysis progress until reaches 100.
scan_all_result_a	string	Processing result and its index `No Threat Detected`: 0 `Infected`: 1 `Suspicious`: 2 `Failed`: 3 `Whitelisted`: 7 `Blacklisted`: 8 `Exceeded Archive Depth`: 9 `Not Scanned`: 10 `Encrypted Archive`: 12 `Exceeded Archive Size`: 13 `Exceeded Archive File Number`: 14 `Password Protected Document`: 15 `Exceeded Archive Timeout`: 16 `Mismatch`: 17 `Potentially Vulnerable File`: 18 `Cancelled`: 19 `Sensitive Data Found`: 20 `Yara Rule Matched`: 21 `Potentially Unwanted`: 22 `Unsupported File Type`: 23 `Extraction Failed`: 24 `Scan Failed`: 25 `Suspicious Verdict by Sandbox`: 26 `Likely Malicious Verdict by Sandbox`: 27 `Malicious Verdict by Sandbox`: 28 `Blocked Verdict by Sandbox`: 29 `Blocked Verdict by Deep CDR`: 30 `Global Timeout Exceeded`: 31 `Vulnerable Verdict by SBOM`: 32 `Non-vulnerable Verdict by SBOM`: 33 `Blocked Verdict by SBOM`: 34 `Blocked by Post Action`: 36 `Known Bad`: 38 `Known Good`: 39 `Unknown`: 40 `Allowed Verdict by COO`: 41 `Blocked Verdict by COO`: 42 `Unknown Verdict by COO`: 43 `In Progress`: 255 `Skip Processing Fast Symlink`: 1014 Enum: `No Threat Detected`,`Infected`,`Suspicious`,`Failed`,`Whitelisted`,`Blacklisted`,`Exceeded Archive Depth`,`Not Scanned`,`Encrypted Archive`,`Exceeded Archive Size`,`Exceeded Archive File Number`,`Password Protected Document`,`Exceeded Archive Timeout`,`Mismatch`,`Potentially Vulnerable File`,`Cancelled`,`Sensitive Data Found`,`Yara Rule Matched`,`Potentially Unwanted`,`Unsupported File Type`,`Extraction Failed`,`Scan Failed`,`Suspicious Verdict by Sandbox`,`Likely Malicious Verdict by Sandbox`,`Malicious Verdict by Sandbox`,`Blocked Verdict by Sandbox`,`Blocked Verdict by Deep CDR`,`Global Timeout Exceeded`,`Vulnerable Verdict by SBOM`,`Non-vulnerable Verdict by SBOM`,`Blocked Verdict by SBOM`,`Blocked by Post Action`,`Known Bad`,`Known Good`,`Unknown`,`Allowed Verdict by COO`,`Blocked Verdict by COO`,`Unknown Verdict by COO`,`In Progress`,`Skip Processing Fast Symlink`
scan_all_result_i	integer	Scan result as index in the Processing Results table above Enum: `0`,`1`,`2`,`3`,`7`,`8`,`9`,`10`,`12`,`13`,`14`,`15`,`16`,`17`,`18`,`19`,`20`,`21`,`22`,`23`,`24`,`25`,`26`,`27`,`28`,`29`,`30`,`31`,`32`,`33`,`34`,`36`,`38`,`39`,`40`,`41`,`42`,`43`,`255`,`1014`
scanned_with	integer	The total number of engines used to analyze this file.
first_index	integer	The starting index in the batch. Used for pagination.
page_size	integer	The number of entries per page.
batch_id	string	The batch unique identifer
is_closed	boolean	The batch status (open/close).
process_info	object	Overall batch process result
blocked_reason	string	Provides the reason why the file is blocked (if so).
file_type_skipped_scan	boolean	Indicates if the input file's detected type was configured to skip scanning.
profile	string	The used rule name.
result	string	The final result of processing the file (Allowed / Blocked / Processing).
user_agent	string	Identifier for the REST Client that calls the API.
username	string	User identifier who submitted scan request earlier.
scan_results	object	Metascan analysis result.
batch_id	string	The batch unique identifer
scan_all_result_a	string	Processing result and its index `No Threat Detected`: 0 `Infected`: 1 `Suspicious`: 2 `Failed`: 3 `Whitelisted`: 7 `Blacklisted`: 8 `Exceeded Archive Depth`: 9 `Not Scanned`: 10 `Encrypted Archive`: 12 `Exceeded Archive Size`: 13 `Exceeded Archive File Number`: 14 `Password Protected Document`: 15 `Exceeded Archive Timeout`: 16 `Mismatch`: 17 `Potentially Vulnerable File`: 18 `Cancelled`: 19 `Sensitive Data Found`: 20 `Yara Rule Matched`: 21 `Potentially Unwanted`: 22 `Unsupported File Type`: 23 `Extraction Failed`: 24 `Scan Failed`: 25 `Suspicious Verdict by Sandbox`: 26 `Likely Malicious Verdict by Sandbox`: 27 `Malicious Verdict by Sandbox`: 28 `Blocked Verdict by Sandbox`: 29 `Blocked Verdict by Deep CDR`: 30 `Global Timeout Exceeded`: 31 `Vulnerable Verdict by SBOM`: 32 `Non-vulnerable Verdict by SBOM`: 33 `Blocked Verdict by SBOM`: 34 `Blocked by Post Action`: 36 `Known Bad`: 38 `Known Good`: 39 `Unknown`: 40 `Allowed Verdict by COO`: 41 `Blocked Verdict by COO`: 42 `Unknown Verdict by COO`: 43 `In Progress`: 255 `Skip Processing Fast Symlink`: 1014 Enum: `No Threat Detected`,`Infected`,`Suspicious`,`Failed`,`Whitelisted`,`Blacklisted`,`Exceeded Archive Depth`,`Not Scanned`,`Encrypted Archive`,`Exceeded Archive Size`,`Exceeded Archive File Number`,`Password Protected Document`,`Exceeded Archive Timeout`,`Mismatch`,`Potentially Vulnerable File`,`Cancelled`,`Sensitive Data Found`,`Yara Rule Matched`,`Potentially Unwanted`,`Unsupported File Type`,`Extraction Failed`,`Scan Failed`,`Suspicious Verdict by Sandbox`,`Likely Malicious Verdict by Sandbox`,`Malicious Verdict by Sandbox`,`Blocked Verdict by Sandbox`,`Blocked Verdict by Deep CDR`,`Global Timeout Exceeded`,`Vulnerable Verdict by SBOM`,`Non-vulnerable Verdict by SBOM`,`Blocked Verdict by SBOM`,`Blocked by Post Action`,`Known Bad`,`Known Good`,`Unknown`,`Allowed Verdict by COO`,`Blocked Verdict by COO`,`Unknown Verdict by COO`,`In Progress`,`Skip Processing Fast Symlink`
scan_all_result_i	integer	Scan result as index in the Processing Results table above Enum: `0`,`1`,`2`,`3`,`7`,`8`,`9`,`10`,`12`,`13`,`14`,`15`,`16`,`17`,`18`,`19`,`20`,`21`,`22`,`23`,`24`,`25`,`26`,`27`,`28`,`29`,`30`,`31`,`32`,`33`,`34`,`36`,`38`,`39`,`40`,`41`,`42`,`43`,`255`,`1014`
start_time	string	Timestamp when the scanning process starts.
total_avs	integer	Total number of scanning engines used as part of this analysis. Not like files, batch is not processed by engine, so this value is always 0.
total_time	integer	Total time elapsed during scan (in milliseconds).
user_data	string	Metadata submitted at batch creation.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

500

Unexpected event on server

Response

 
{ "batch_files": {  "batch_count": 4,  "current_finished_files": 4,  "files_in_batch": [   {    "data_id": "24c8b5dadd48445989ac3431544fdc34",    "detected_by": 4,    "display_name": "eicar.com",    "file_size": 68,    "file_type": "application/octet-stream",    "file_type_description": "EICAR virus test files",    "process_info": {     "blocked_reason": "Infected",     "progress_percentage": 100,     "result": "Blocked",     "verdicts": [      "Infected"     ]    },    "progress_percentage": 100,    "scan_all_result_a": "No Threat Detected",    "scan_all_result_i": 0,    "scanned_with": 4   }  ],  "first_index": 0,  "page_size": 50 }, "batch_id": "b7cc760038324b02908a5c111cb1563d", "is_closed": true, "process_info": {  "blocked_reason": "Infected",  "file_type_skipped_scan": false,  "profile": "File process",  "result": "Blocked",  "user_agent": "mdicapserver",  "username": "LOCAL/admin" }, "scan_results": {  "batch_id": "b7cc760038324b02908a5c111cb1563d",  "scan_all_result_a": "No Threat Detected",  "scan_all_result_i": 0,  "start_time": "2020-03-12T08:37:05.427Z",  "total_avs": 0,  "total_time": 18403 }, "user_data": "http://localhost:8899/"}
Copy

Status of Batch Analysis

Retrieve status report for the entire batch

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Path Params

batchId

string

The batch identifier used to submit files in the batch and to close the batch.

Query String

first

integer

The first item order in the list of files in this batch

minimum: 0

Default: 0

size

integer

The number of items to be fetched next, counting from the item order indicated in first header. The default value is 50, and the maximum value is 2000.

maximum: 2000

minimum: 0

Default: 50

GET /file/batch/{batchId}

 
curl --get \ --url 'http://localhost:8899/file/batch/{batchId}' \ --header 'apikey: {apikey}' \ --data first={first} \ --data size=50
Copy

Responses

200

Batch progress paginated report (50 entries/page).

object	object	The response for a Batch status request.
batch_files	object	Information about the files included in this batch.
batch_count	integer	The total number of files/entries in the batch.
current_finished_files	integer	The total number of files/entries that have been fully processed in the batch.
files_in_batch	array[object]	The list of files in the batch.
data_id	string	Unique identifer for the file.
detected_by	integer	Total number of engines that detected this file.
display_name	string	The filename reported via `filename` header.
file_size	integer	Total file size in bytes.
file_type	string	The filetype using mimetype.
file_type_description	string	The filetype in human readable format.
process_info	object	The analysis summary
blocked_reason	string	Provides the reason why the file is blocked (if so).
progress_percentage	integer	Percentage of processing completed (from 1-100).
result	string	The final result of processing the file (Allowed / Blocked / Processing).
verdicts	array[string]	Aggregated list of potential issues.
progress_percentage	integer	Track analysis progress until reaches 100.
scan_all_result_a	string	Processing result and its index `No Threat Detected`: 0 `Infected`: 1 `Suspicious`: 2 `Failed`: 3 `Whitelisted`: 7 `Blacklisted`: 8 `Exceeded Archive Depth`: 9 `Not Scanned`: 10 `Encrypted Archive`: 12 `Exceeded Archive Size`: 13 `Exceeded Archive File Number`: 14 `Password Protected Document`: 15 `Exceeded Archive Timeout`: 16 `Mismatch`: 17 `Potentially Vulnerable File`: 18 `Cancelled`: 19 `Sensitive Data Found`: 20 `Yara Rule Matched`: 21 `Potentially Unwanted`: 22 `Unsupported File Type`: 23 `Extraction Failed`: 24 `Scan Failed`: 25 `Suspicious Verdict by Sandbox`: 26 `Likely Malicious Verdict by Sandbox`: 27 `Malicious Verdict by Sandbox`: 28 `Blocked Verdict by Sandbox`: 29 `Blocked Verdict by Deep CDR`: 30 `Global Timeout Exceeded`: 31 `Vulnerable Verdict by SBOM`: 32 `Non-vulnerable Verdict by SBOM`: 33 `Blocked Verdict by SBOM`: 34 `Blocked by Post Action`: 36 `Known Bad`: 38 `Known Good`: 39 `Unknown`: 40 `Allowed Verdict by COO`: 41 `Blocked Verdict by COO`: 42 `Unknown Verdict by COO`: 43 `In Progress`: 255 `Skip Processing Fast Symlink`: 1014 Enum: `No Threat Detected`,`Infected`,`Suspicious`,`Failed`,`Whitelisted`,`Blacklisted`,`Exceeded Archive Depth`,`Not Scanned`,`Encrypted Archive`,`Exceeded Archive Size`,`Exceeded Archive File Number`,`Password Protected Document`,`Exceeded Archive Timeout`,`Mismatch`,`Potentially Vulnerable File`,`Cancelled`,`Sensitive Data Found`,`Yara Rule Matched`,`Potentially Unwanted`,`Unsupported File Type`,`Extraction Failed`,`Scan Failed`,`Suspicious Verdict by Sandbox`,`Likely Malicious Verdict by Sandbox`,`Malicious Verdict by Sandbox`,`Blocked Verdict by Sandbox`,`Blocked Verdict by Deep CDR`,`Global Timeout Exceeded`,`Vulnerable Verdict by SBOM`,`Non-vulnerable Verdict by SBOM`,`Blocked Verdict by SBOM`,`Blocked by Post Action`,`Known Bad`,`Known Good`,`Unknown`,`Allowed Verdict by COO`,`Blocked Verdict by COO`,`Unknown Verdict by COO`,`In Progress`,`Skip Processing Fast Symlink`
scan_all_result_i	integer	Scan result as index in the Processing Results table above Enum: `0`,`1`,`2`,`3`,`7`,`8`,`9`,`10`,`12`,`13`,`14`,`15`,`16`,`17`,`18`,`19`,`20`,`21`,`22`,`23`,`24`,`25`,`26`,`27`,`28`,`29`,`30`,`31`,`32`,`33`,`34`,`36`,`38`,`39`,`40`,`41`,`42`,`43`,`255`,`1014`
scanned_with	integer	The total number of engines used to analyze this file.
first_index	integer	The starting index in the batch. Used for pagination.
page_size	integer	The number of entries per page.
batch_id	string	The batch unique identifer
is_closed	boolean	The batch status (open/close).
process_info	object	Overall batch process result
blocked_reason	string	Provides the reason why the file is blocked (if so).
file_type_skipped_scan	boolean	Indicates if the input file's detected type was configured to skip scanning.
profile	string	The used rule name.
result	string	The final result of processing the file (Allowed / Blocked / Processing).
user_agent	string	Identifier for the REST Client that calls the API.
username	string	User identifier who submitted scan request earlier.
scan_results	object	Metascan analysis result.
batch_id	string	The batch unique identifer
scan_all_result_a	string	Processing result and its index `No Threat Detected`: 0 `Infected`: 1 `Suspicious`: 2 `Failed`: 3 `Whitelisted`: 7 `Blacklisted`: 8 `Exceeded Archive Depth`: 9 `Not Scanned`: 10 `Encrypted Archive`: 12 `Exceeded Archive Size`: 13 `Exceeded Archive File Number`: 14 `Password Protected Document`: 15 `Exceeded Archive Timeout`: 16 `Mismatch`: 17 `Potentially Vulnerable File`: 18 `Cancelled`: 19 `Sensitive Data Found`: 20 `Yara Rule Matched`: 21 `Potentially Unwanted`: 22 `Unsupported File Type`: 23 `Extraction Failed`: 24 `Scan Failed`: 25 `Suspicious Verdict by Sandbox`: 26 `Likely Malicious Verdict by Sandbox`: 27 `Malicious Verdict by Sandbox`: 28 `Blocked Verdict by Sandbox`: 29 `Blocked Verdict by Deep CDR`: 30 `Global Timeout Exceeded`: 31 `Vulnerable Verdict by SBOM`: 32 `Non-vulnerable Verdict by SBOM`: 33 `Blocked Verdict by SBOM`: 34 `Blocked by Post Action`: 36 `Known Bad`: 38 `Known Good`: 39 `Unknown`: 40 `Allowed Verdict by COO`: 41 `Blocked Verdict by COO`: 42 `Unknown Verdict by COO`: 43 `In Progress`: 255 `Skip Processing Fast Symlink`: 1014 Enum: `No Threat Detected`,`Infected`,`Suspicious`,`Failed`,`Whitelisted`,`Blacklisted`,`Exceeded Archive Depth`,`Not Scanned`,`Encrypted Archive`,`Exceeded Archive Size`,`Exceeded Archive File Number`,`Password Protected Document`,`Exceeded Archive Timeout`,`Mismatch`,`Potentially Vulnerable File`,`Cancelled`,`Sensitive Data Found`,`Yara Rule Matched`,`Potentially Unwanted`,`Unsupported File Type`,`Extraction Failed`,`Scan Failed`,`Suspicious Verdict by Sandbox`,`Likely Malicious Verdict by Sandbox`,`Malicious Verdict by Sandbox`,`Blocked Verdict by Sandbox`,`Blocked Verdict by Deep CDR`,`Global Timeout Exceeded`,`Vulnerable Verdict by SBOM`,`Non-vulnerable Verdict by SBOM`,`Blocked Verdict by SBOM`,`Blocked by Post Action`,`Known Bad`,`Known Good`,`Unknown`,`Allowed Verdict by COO`,`Blocked Verdict by COO`,`Unknown Verdict by COO`,`In Progress`,`Skip Processing Fast Symlink`
scan_all_result_i	integer	Scan result as index in the Processing Results table above Enum: `0`,`1`,`2`,`3`,`7`,`8`,`9`,`10`,`12`,`13`,`14`,`15`,`16`,`17`,`18`,`19`,`20`,`21`,`22`,`23`,`24`,`25`,`26`,`27`,`28`,`29`,`30`,`31`,`32`,`33`,`34`,`36`,`38`,`39`,`40`,`41`,`42`,`43`,`255`,`1014`
start_time	string	Timestamp when the scanning process starts.
total_avs	integer	Total number of scanning engines used as part of this analysis. Not like files, batch is not processed by engine, so this value is always 0.
total_time	integer	Total time elapsed during scan (in milliseconds).
user_data	string	Metadata submitted at batch creation.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

500

Unexpected event on server

Response

 
{ "batch_files": {  "batch_count": 4,  "current_finished_files": 3,  "files_in_batch": [   {    "data_id": "24c8b5dadd48445989ac3431544fdc34",    "detected_by": 4,    "display_name": "eicar.com",    "file_size": 68,    "file_type": "application/octet-stream",    "file_type_description": "EICAR virus test files",    "process_info": {     "blocked_reason": "Infected",     "progress_percentage": 100,     "result": "Blocked",     "verdicts": [      "Infected"     ]    },    "progress_percentage": 100,    "scan_all_result_a": "No Threat Detected",    "scan_all_result_i": 0,    "scanned_with": 4   }  ],  "first_index": 0,  "page_size": 50 }, "batch_id": "b7cc760038324b02908a5c111cb1563d", "is_closed": false, "process_info": {  "blocked_reason": "Infected",  "file_type_skipped_scan": false,  "profile": "File process",  "result": "Processing",  "user_agent": "mdicapserver",  "username": "LOCAL/admin" }, "scan_results": {  "batch_id": "b7cc760038324b02908a5c111cb1563d",  "scan_all_result_a": "No Threat Detected",  "scan_all_result_i": 0,  "start_time": "2020-03-12T08:37:05.427Z",  "total_avs": 0,  "total_time": -1 }, "user_data": "http://localhost:8899/"}
Copy

Download Signed Batch Result

Download digitally signed status report for the entire batch

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

metadata

string

In JSON format, this can be used to:

Include additional information in the response YML. Currently, one supported field in the metadata is include_vul_info, which can be set to true or false to indicate whether vulnerability processing information should be included or not. It is strongly recommended to apply URL encoding before sending metadata to Metadefender Cluster API Gateway to prevent unexpected issues related to encoding errors or unsafe characters.

Path Params

batchId

string

The batch identifier used to submit files in the batch and to close the batch.

GET /file/batch/{batchId}/certificate

 
curl --get \ --url 'http://localhost:8899/file/batch/{batchId}/certificate' \ --header 'apikey: {apikey}' \ --header 'metadata: {  "include_vul_info": true}'
Copy

Responses

200

Signed batch result and certificate are sent back in response body (YAML format).

No response body

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

500

Unexpected event on server

Response

 
--- batch_id: 092876200fb54cfb80b6e3332c410ae9 user_data: the user data from the header from batch creation cert_sha1_fingerprint: <some cert serial value> batch_files:  batch_count: 1  files_in_batch:  - data_id: 9112b225f0634f189a2bb46ec1a7826f    display_name: New%20Text%20Document.txt    file_size: 5    scan_all_result_i: 0    process_info:      blocked_reason:      result: Allowed    md5: 42b130c3ce46e058f30712838cebf420    sha1: ed94baf55ca851055fb76045f6949bca2f865605    sha256: f4191b3ec6ce93aaf712919a38e52815c5da9c91d2b141df920bc8bcb5cbb8e3    sha512: ""    vulnerabilities:      - cve: CVE-2021-45463        cvss:          score: 6.8        cvss_3_0:          base_score: 7.8      - cve: CVE-2018-12713        cvss:          score: 6.4        cvss_3_0:          base_score: 9.1process_info:  blocked_reason:  file_type_skipped_scan: false  profile: File scan  result: Allowed  user_agent: webscanscan_results:  scan_all_result_a: No Threat Detected  scan_all_result_i: 0  start_time: 2017-05-23T11:22:03.010Z  total_avs: 14  total_time: 995...--- signature: 881d22220c4ca0557d7c7d5c5794d53a8a2780997cd65b27b6e7f1c099a15de03dbcb5edbeaea7aafa6099fab37be07017b39e3e3a7d66c550f44eb59a096c54d5b9555cb28198546fbec57c33b717751d333a09733d95dd876e2798d044c8caef828f4352b91f9a6d057253bb1a9461e0e0e0bf4313a80895998d645bebc81841ff3499589c80ffc4e8a190d1ec9b3e4126d86659d303b0e1f22d9289c9c4671d35532b55ad4620e048a78bb405b573897da63efdd5f036692c934a82d9bdc9b9862e7fea5e8abeeb1444be0689d50373c5c0632484950c0fe0337ed5f91bdf26986f7cff8aa3431bf4bc948fc127c16ba13ec679fe9f67e7586075c1f467454fa8cf40e9cd501291c95d862eb16f4477c17d1711294f0ff2b3a1140bd53dbd1fbb0846af6062e9e4e2e1a09af3448503ed11e342164e535fc268bf7d8fbc28ed946cd2bb8ea075f2295d2fa8392076d41608c3b5decf8fab3a5ec7de190f07583331e0517e5f361735cd59326622dc8b07b10a464028de781a063e408f918c1d5534329140f4e4dc1a717d808d6784410410b00d36cb9a345f5bbc11fa1c58ee28f8e7b863f3ea2c923ec5fb2ac29eaa4ddc0d6d9dfd3f16a97f207dc2858410a577c7f4a92ff01bad3229f5fcdb08e21df9869a113272aa9d96bfdfe8bfb3a50414c174e16a3504e5780c2718779b0757298546f287ef7ea86e67510d48a8 certificate: |  -----BEGIN CERTIFICATE-----  MIIGJzCCBA+gAwIBAgIBATANBgkqhkiG9w0BAQUFADCBsjELMAkGA1UEBhMCRlIx  DzANBgNVBAgMBkFsc2FjZTETMBEGA1UEBwwKU3RyYXNib3VyZzEYMBYGA1UECgwP  d3d3LmZyZWVsYW4ub3JnMRAwDgYDVQQLDAdmcmVlbGFuMS0wKwYDVQQDDCRGcmVl  bGFuIFNhbXBsZSBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkxIjAgBgkqhkiG9w0BCQEW  E2NvbnRhY3RAZnJlZWxhbi5vcmcwHhcNMTIwNDI3MTAzMTE4WhcNMjIwNDI1MTAz  MTE4WjB+MQswCQYDVQQGEwJGUjEPMA0GA1UECAwGQWxzYWNlMRgwFgYDVQQKDA93  d3cuZnJlZWxhbi5vcmcxEDAOBgNVBAsMB2ZyZWVsYW4xDjAMBgNVBAMMBWFsaWNl  MSIwIAYJKoZIhvcNAQkBFhNjb250YWN0QGZyZWVsYW4ub3JnMIICIjANBgkqhkiG  9w0BAQEFAAOCAg8AMIICCgKCAgEA3W29+ID6194bH6ejLrIC4hb2Ugo8v6ZC+Mrc  k2dNYMNPjcOKABvxxEtBamnSaeU/IY7FC/giN622LEtV/3oDcrua0+yWuVafyxmZ  yTKUb4/GUgafRQPf/eiX9urWurtIK7XgNGFNUjYPq4dSJQPPhwCHE/LKAykWnZBX  RrX0Dq4XyApNku0IpjIjEXH+8ixE12wH8wt7DEvdO7T3N3CfUbaITl1qBX+Nm2Z6  q4Ag/u5rl8NJfXg71ZmXA3XOj7zFvpyapRIZcPmkvZYn7SMCp8dXyXHPdpSiIWL2  uB3KiO4JrUYvt2GzLBUThp+lNSZaZ/Q3yOaAAUkOx+1h08285Pi+P8lO+H2Xic4S  vMq1xtLg2bNoPC5KnbRfuFPuUD2/3dSiiragJ6uYDLOyWJDivKGt/72OVTEPAL9o  6T2pGZrwbQuiFGrGTMZOvWMSpQtNl+tCCXlT4mWqJDRwuMGrI4DnnGzt3IKqNwS4  Qyo9KqjMIPwnXZAmWPm3FOKe4sFwc5fpawKO01JZewDsYTDxVj+cwXwFxbE2yBiF  z2FAHwfopwaH35p3C6lkcgP2k/zgAlnBluzACUI+MKJ/G0gv/uAhj1OHJQ3L6kn1  SpvQ41/ueBjlunExqQSYD7GtZ1Kg8uOcq2r+WISE3Qc9MpQFFkUVllmgWGwYDuN3  Zsez95kCAwEAAaN7MHkwCQYDVR0TBAIwADAsBglghkgBhvhCAQ0EHxYdT3BlblNT  TCBHZW5lcmF0ZWQgQ2VydGlmaWNhdGUwHQYDVR0OBBYEFFlfyRO6G8y5qEFKikl5  ajb2fT7XMB8GA1UdIwQYMBaAFCNsLT0+KV14uGw+quK7Lh5sh/JTMA0GCSqGSIb3  DQEBBQUAA4ICAQAT5wJFPqervbja5+90iKxi1d0QVtVGB+z6aoAMuWK+qgi0vgvr  mu9ot2lvTSCSnRhjeiP0SIdqFMORmBtOCFk/kYDp9M/91b+vS+S9eAlxrNCB5VOf  PqxEPp/wv1rBcE4GBO/c6HcFon3F+oBYCsUQbZDKSSZxhDm3mj7pb67FNbZbJIzJ  70HDsRe2O04oiTx+h6g6pW3cOQMgIAvFgKN5Ex727K4230B0NIdGkzuj4KSML0NM  slSAcXZ41OoSKNjy44BVEZv0ZdxTDrRM4EwJtNyggFzmtTuV02nkUj1bYYYC5f0L  ADr6s0XMyaNk8twlWYlYDZ5uKDpVRVBfiGcq0uJIzIvemhuTrofh8pBQQNkPRDFT  Rq1iTo1Ihhl3/Fl1kXk1WR3jTjNb4jHX7lIoXwpwp767HAPKGhjQ9cFbnHMEtkro  RlJYdtRq5mccDtwT0GFyoJLLBZdHHMHJz0F9H7FNk2tTQQMhK5MVYwg+LIaee586  CQVqfbscp7evlgjLW98H+5zylRHAgoH2G79aHljNKMp9BOuq6SnEglEsiWGVtu2l  hnx8SB3sVJZHeer8f/UQQwqbAO+Kdy70NmbSaqaVtp8jOxLiidWkwSyRTsuU6D8i  DiH5uEqBXExjrj0FslxcVKdVj5glVcSmkLwZKbEU1OKwleT/iXFhvooWhQ==  -----END CERTIFICATE-----... 
Copy

Cancel Batch

When cancelling a batch, the connected analysis that are still in progress will be cancelled also.

The cancelled batch will be closed.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Path Params

batchId

string

The batch identifier used to submit files in the batch and to close the batch.

POST /file/batch/{batchId}/cancel

 
curl --request POST \ --url 'http://localhost:8899/file/batch/{batchId}/cancel' \ --header 'apikey: {apikey}'
Copy

Responses

200

Batch cancelled.

object object

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Batch not found (invalid id)

500

Unexpected event on server

Response

 
{ "<<batch_id>>": "cancelled"}
Copy

License

Retrieve the current license information.

GET

/admin/license

Get current license information

Fetch details about the longest expiry active license among all activated licenses.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/license

 
curl --get \ --url 'http://localhost:8899/admin/license' \ --header 'apikey: {apikey}'
Copy

Responses

200

Information about the licensed product (product type, number of activations, deploymentId, expiration date and days left)

object	object	Information about the licensed product (product type, number of activations, deploymentId, expiration date and days left)
days_left	integer	Number of days left before expiration
expiration	string	Expiration date in MM/DD/YYYY format.
licensed_engines	array[string]	List of engine/module identifiers that have been licensed
licensed_to	string	Name of the entity to which the license is issued.
max_agent_count	string	Total number of deployed MetaDefender Agents attached to this MetaDefender Core instance.
online_activated	boolean	Track online/offline activation mode
product_id	string	Official MetaDefender base SKU licensed.
product_name	string	Official MetaDefender base product name licensed.

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "activation_key": "", "days_left": 3731, "deployment": "", "expiration": "09/30/2026", "licensed_engines": "*", "licensed_to": "OPSWAT, Inc.", "max_agent_count": "10", "online_activated": true, "product_id": "MSCL-4-unlimited", "product_name": "Metadefender Core 5 Linux"}
Copy

Stats

Health check and statistics about MetaDefender Core instance usage.

Engine Status

Return the status of the latest engines between the MetaDefender Core instances.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /stat/engines

 
curl --get \ --url 'http://localhost:8899/stat/engines' \ --header 'apikey: {apikey}'
Copy

Responses

200

An array with all the engines and their details.

array	array[object]
abandoned	boolean	Indicates if this engine is abandoned.
active	boolean	If used by at least one engine
def_time	string	The database definition time for this engine
download_progress	integer	The percentage progress of download
download_time	string	When this engine downloaded from the update server.
eng_id	string	Engine internal ID
eng_name	string	Engine name
eng_type	string	Engine type in human readable form
eng_ver	string	Engine's version (format differs from one engine to another).
engine_type	string	Engine's type: av archive filetype Enum: `av`,`archive`,`filetype`
pinned	boolean	Indicate if this engine is pinned.
state	string	Status of the engine: downloading downloaded staging production removed temporary failed permanently failed content invalid download failed Enum: `downloading`,`downloaded`,`staging`,`production`,`removed`,`temporary failed`,`permanently failed`,`content invalid`,`download failed`
type	string	The type of information, whether it is engine or engine's database.

Response

 
[ {  "abandoned": false,  "active": true,  "def_time": "2020-04-17T02:37:05.000Z",  "download_progress": 100,  "download_time": "2020-04-17T08:17:22.810Z",  "eng_id": "clamav_1_linux",  "eng_name": "ClamAV",  "eng_type": "Bundled engine",  "eng_ver": "3.0-43",  "engine_type": "av",  "notified_messages": [],  "pinned": false,  "state": "production",  "type": "engine" }]
Copy

Instance Status Overview

Retrieve status details of all available MetaDefender Core instances.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /stat/nodes

 
curl --get \ --url 'http://localhost:8899/stat/nodes' \ --header 'apikey: {apikey}'
Copy

Responses

200

Status details of MetaDefender Core instances.

object	object
external_nodes_allowed	boolean	Indicates whether external nodes can connect; always true.
max_node_count	integer	Total number of available MetaDefender Core instances.
statuses	array[object]	List of MetaDefender Core instance status details.
address	string	Location of the Core instance; currently always return empty string.
available_mem	integer	The number of available RAM in this system.
cpu_cores	integer	The number of CPU Cores allocated to this Core instance.
current_processing_files	integer	Number of objects currently being processed by the Core instance.
engines	array[object]	Summary of each engine status deployed on this Core.
active	boolean	If used by at least one engine
db_ver	string	The database version for this engine
def_time	string	The database definition time for this engine
download_time	string	The database download time for this engine
eng_name	string	Engine name
eng_ver	string	Engine's version (format differs from one engine to another).
engine_type	string	Engine's type: av archive filetype Enum: `av`,`archive`,`filetype`
id	string	Engine internal ID
free_disk_space	integer	Reported available disk on Core instance (in bytes).
id	string	Identifier of the worker that deployed this Core instance.
info_disk_space	array[object]	Report disk space usage from the host where the MetaDefender Core instance is installed.
free	integer	Free space on the disk (in bytes).
location	string	Disk location.
total	integer	Total space on the disk (in bytes).
issues	array[object]	A list of all potential problems on Core instance.
description	string	Text detailing the issue.
severity	string	How important is the reported issue.
load	integer	Current CPU utilization on Core instance (in percentage).
os	string	Current used OS
scan_queue	integer	Number of objects currently being processed by the Core instance.
scan_queue_details	object	Current load of scan queue in details
archive_scan_queue_ratio	number	Ratio of archive scan queue, always -1 for Core in Cluster mode.
available_slots	integer	The number of slots is available, always -1 for Core in Cluster mode.
extracted_file_slots	integer	Number of child files being processing
file_slots	integer	Number of files taken from REST by the current Core instance
total_scan_queue	integer	Total scan queue, always -1 for Core in Cluster mode.
total_disk_space	integer	The amount of disk space is allocated on Core instance (in Byte).
total_mem	integer	How much memory is allocated on Core instance (in MB).
total_scan_queue	integer	The maximum queue size is allowed, always -1 for Core in Cluster mode.
uptime	integer	How long this Core is in operation (in second).
version	string	Product version

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

Response

 
{ "external_nodes_allowed": true, "max_node_count": 1, "statuses": [  {   "address": "{string}",   "available_mem": 2825,   "cpu_cores": 8,   "current_processing_files": 24,   "engines": [    {     "active": true,     "db_ver": "25050",     "def_time": "2020-04-17T02:37:05.000Z",     "download_time": "2020-04-17T04:32:05.000Z",     "eng_name": "ClamAV",     "eng_ver": "3.0-43",     "engine_type": "av",     "id": "clamav_1_linux",     "issues": []    }   ],   "free_disk_space": 1739928,   "id": "ecc114e4fc0bbb4f8382c881617b4480",   "info_disk_space": [    {     "dirs": [      "core_log_path",      "data",      "dlp",      "installation",      "nginx_log_path",      "quarantine",      "resource",      "sanitized"     ],     "free": 1739928,     "location": "C",     "total": 500000878592    }   ],   "issues": [    {     "description": "1 engines are not deployed to this Core",     "severity": "warning"    }   ],   "load": 14,   "os": "Linux Mint 18.3 Sylvia",   "scan_queue": 24,   "scan_queue_details": {    "archive_scan_queue_ratio": -1,    "available_slots": -1,    "extracted_file_slots": 50,    "file_slots": 10,    "total_scan_queue": -1   },   "total_disk_space": 500000878592,   "total_mem": 40100,   "total_scan_queue": -1,   "uptime": 12791,   "version": "5.15.1"  } ]}
Copy

Get health check status

Fetch current status of system health.

Auth

Query String

verbose

boolean

Optional. Show detailed result of system health.

GET /readyz

 
curl --get \ --url 'http://localhost:8899/readyz' \ --data verbose=true
Copy

Responses

200

System is currently healthy.

object	object	System readiness / health status.
status	boolean	System-wide status, indicate if all components are healthy.
scan_queue	object	Scan queue status.
number_in_queue	integer	Number of objects being processed by the system.
status	boolean	The operational status of the scan process; true if the system contains the required minimum of healthy MetaDefender Core instances.
license	object	License status.
status	string	License status. Enum: `expired`,`invalid`,`ok`
components	object	Core component statuses.
status	boolean	Aggregate component status.
datalake	object	DataLake status.
status	boolean	DataLake overall status.
detail	string	Status detail message
caching	object	Caching status.
status	boolean	Caching overall status.
detail	string	Status detail message.
broker	object	Broker status.
status	boolean	Broker overall status.
detail	string	Status detail message.
filestorage	object	File storage status.
status	boolean	File storage overall status.
detail	string	Status detail message.
identity	object	Identity service status.
status	boolean	Identity service overall status.
detail	string	Status detail message.
ometascan	object	Status of MetaDefender Core instances
status	boolean	MetaDefender Core overall status.
detail	string	Detail message.
instance	array[string]	List of instance status.
callback-service	object	Webhook callback service status.
status	boolean	Callback service overall status.
instance	array[string]	List of instance status.

500

Unexpected event on server

503

System is currently unhealthy.

Response

 
{ "status": true, "scan_queue": {  "number_in_queue": 42,  "status": true }, "license": {  "status": "ok" }, "components": {  "status": true,  "datalake": {   "status": true,   "detail": "Healthy"  },  "caching": {   "status": true,   "detail": "Healthy"  },  "broker": {   "status": true,   "detail": "Healthy"  },  "filestorage": {   "status": true,   "detail": "Healthy"  },  "identity": {   "status": true,   "detail": "Healthy"  } }, "ometascan": {  "status": true,  "detail": "All MetaDefender Core instances healthy.",  "instance": [   "8ff354cb076e154893dbf61734f3cf8e: Healthy",   "a1b2c3d4e5f60718293a4b5c6d7e8f90: Healthy"  ] }, "callback-service": {  "status": true,  "instance": [   "8a5a6bfaad1e4c0caf7da10785fa9e8a: Healthy"  ] }}
Copy

API Gateway v2.6.0Terms of ServiceApache 2.0

Developer Guide

How to Interact with MetaDefender Cluster API Gateway using REST API

File Analysis Process

Authentication

Auth

Authentication APIs

Login

Logout

Analysis

File analysis APIs

Analyze File (Asynchronous mode)

Fetch Analysis Result

Fetch Analysis Result By Hash

Fetching Available Analysis Rules

Download Sanitized Files

Download either sanitized files or DLP processed files

Cancel File Analysis

Query webhook status

Batch

Initiate Batch

Close Batch

Status of Batch Analysis

Download Signed Batch Result

Cancel Batch

License

Get current license information

Stats

Engine Status

Instance Status Overview

Get health check status

API Gateway v2.6.0 Terms of Service Apache 2.0