Metadefender Cloud Public API

About

The Metadefender Cloud offers you the possibility to leverage of our cloud-based multi-scanning technology, Metadefender Core. For scanning files or hash lookups, we do offer free file scans through our web interface for exclusively demo purposes, for commercial use please consult our Licensing page and contact our sales team to have a deeper discussion about which licensing model will suit your needs.

An integration with Metadefender.com multi-scanning technology through the REST API is allowed only for the free service only for:

  • Prototyping the integration with Metadefender
  • Integrated in your solution for demo purposes if and only if:
    • The integration in production will leverage Metadefender Core or Metadefender.com commercial license
    • It's used only to demo the product integration and will not save any data

For the free usage you will be able to consume the scan report from 40+ anti-malware engines, but you will not be allowed to use in any way the data provided by our platform. For the commercial use, the engine list will be limited to the engines we have OEM agreements with. Please consult the list of available engines on our Licensing page.

For more information on how to use this REST API please see our documentation listed below.

  • Each API call requires a Metadefender Cloud API key. To obtain your free Metadefender Cloud API key, please create an account or log into the OPSWAT portal and find the Metadefender Cloud section under 'Licenses'. Expand this section to access your free Metadefender Cloud API key.
  • Free API keys obtained through the OPSWAT Portal allow 25 IP address scans and 25 Application Information lookups per hour. To extend your key to allow additional usage, please contact OPSWAT sales.
  • To use Metadefender Cloud through the web interface, please click here
  • If you experience any issues using Metadefender Cloud through the web interface or through the REST API, please log into the OPSWAT portal, submit a ticket under the 'Support' section, and a member of our support team will be happy to assist with your request.

Definitions

Description of scan_result_i and scan_all_result_i

Value Description Note
0 No Threat Found No threat detection or the file is empty.
1 Infected/Known Threat is found.
2 Suspicious Classified as a possible threat but not identified as a specific threat.
3 Failed To Scan Scanning is not fully performed (e.g., invalid file or no read permission).
4 Cleaned Not Applicable.
5 Unknown Scan result does not exist (only for hash lookups).
6 Quarantined Not Applicable.
7 Skipped Clean Scan is skipped because this file is on the white-list.
8 Skipped Dirty Scan is skipped because this file is on the black-list
9 Exceeded Archive Depth Threat is not found but there are more archive levels which were not extracted.
10 Not Scanned Scan is skipped by the engine either due to update or other engine-specific reason.
11 Aborted All ongoing scans are purged.
12 Encrypted File/buffer is not scanned because the file type is detected as encrypted (password-protected). If the Internal Archive Library is ON, encrypted return type is not going to be returned through Metadefender scan progress callbacks since the engines do not perform any scan operations. If the Internal Archive Library is OFF, Metadefender will pass the encrypted files to the engines directly, bypassing the detection.
13 Exceeded Archive Size The extracted archive is too large to scan.
14 Exceeded Archive File Number There are more files in the archive than configured on the server.

Description of file_type_category

“E” Executable (EXE, DLL, …).
“D” Document (MS Office word document, MS Office excel sheet).
“A” Archive (Zip, Rar, Tar, …).
“G” Graphical format (Jpeg, GIF, TIFF, BMP, …).
“T” Text.
“P” PDF format.
“M” Audio or video format.
“Z” Mail messages (MSG, …).
“O” Other (anything that is not recognized as one of the above).

HTTP Status Codes

Below are all the possible status codes returned by the REST API.
SUCCESS 200 Ok The request has succeeded
  204 No Content The request has succeeded but it was a HEAD request
REDIRECT 301 Moved Permanently If the endpoint was moved
       
CLIENT ERROR 400 Bad Request There was a client error
  401 Not Authorized Authentication failed
  404 Not Found Endpoint was not found
  405 Method Not Allowed CORS configuration missing
  406 Not Acceptable Payload type is not accepted
  408 Request Timeout The request was over 60 seconds
  429 Too Many Requests Rate limit exceeded or too many requests per sec
       
SERVER ERROR 500 Internal Server Error Something went wrong with the API.
Please try again later.
  501 Not Implemented CORS method is not implemented
  503 Service Unavailable 3rd party service is not available
  504 Gateway Timeout The server, while acting as a gateway or proxy, did not receive a timely response from the upstream servers.

Rate Limiting

While communicating with Metadefender Cloud APIs you are obliged to use authentication mechanism for given API endpoint and provide your API key. Each API key has its hourly limits and you can check yours by logging in to OPSWAT Portal with your OPSWAT account. Additionally, Metadefender Cloud server is returning custom headers in the response which will help to track your current API usage.

Description of custom headers

  • X-RateLimit-Limit - Your current limit for given API endpoint.
  • X-RateLimit-Remaining - The number of requests remaining in the current time window, usually set to 1 hour.
  • X-RateLimit-Reset-In - Number of seconds remaining in current time window.
  • X-RateLimit-Used - The number of requests used in current time window.

Scan a file

Overview

Scanning a file starts with uploading file to Metadefender to initiate scan. Although we are trying to keep scanning very fast, scanning using more than 40 engines takes many seconds to many minutes depending on types of files. Scanning a file consists of 3 steps:

  • initiate Scan request by uploading a file
  • retrieve scan report using DATA ID
  • if file is already scanned before, uploading a file for scan does not initiate scan, instead it returns the latest known scan results

In other words, looking up scan results using hash value has same impact while using minimum network bandwidth usage. Therefore it is strongly recommended to do "LOOK UP HASHES" before "SCAN A FILE". In order to rescan a file which was scanned before, you can initiate scan request using file_id. Please note that file_id is not available for every scan results if it was scanned via private API.

Scanning a file by file upload

Initiate scan request

On Metadefender, scans are performed asynchronously and each scan request is tracked by a data id.

Initiate scan request https://scan.metadefender.com/v2/file

HTTP header parameters

apikey API key assigned by OPSWAT. REQUIRED
filename Name of files to preserve extension during scan and meta data. RECOMENDED
archivepwd If submitted file is password protected archive. OPTIONAL
samplesharing This flag is only available to users that have purchased access to private scanning through the Metadefender API. If '0', scanned files will not be stored or shared by Metadefender, although hashed results will remain available. OPTIONAL

Method: POST

HTTP requests must include the contents of the file as HTTP body.

HTTP body Content of the file for scan.

Request error (HTTP status: 40x)

400: Bad request Unsupported HTTP method or invalid http request (e.g., empty body).
401: Invalid API key An invalid API key, or no API key, has been provided
403: scan limit reached The hourly scan limit has been reached for this API key
403 Private scanning not enabled for the provided API key A private scanning request has been made using an API key that does not allow private scanning

Request Error (HTTP status: 50x)

500 Internal error Server temporarily unavailable; please try again later. If the issue persists, please contact OPSWAT.
503 Failed to request scan The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. If the issue persists, please contact OPSWAT.
503 Server is too busy  

Response (HTTP status: 200)

Example of a successful scan request:

    {
      "data_id": "ZzE2MTEyMlMxMkQ1U0dmR3hyeTZ3NVNHR01s",
      "status": "inqueue",
      "in_queue": "2",
      "rest_ip": "api.metadefender.com/v2"
    }

Description:

data_id Data ID used for retrieving scan results. Since multiple scans can potentially be performed for the same files when any engine has a different definition time or when there is an additional engine, this is the identifier for per-scan rather than per-file.
rest_ip Requests for the scan progress using 'data_id' should be made to this address instead of the original address. Once a scan is finished, future requests for this 'data_id' can be made to the original address.
status Status of the scan request. Value inqueue represents state, when scan is being queued for scanning.
in_queue Counter representing the current position of scan in the queue.

Sample code (Node.js)

	var request = require('request');
	var fs = require("fs");

	var formData = {
	  file: fs.createReadStream(__dirname + '/file')
	};

	request.post({
			url: 'https://scan.metadefender.com/v2/file',
			formData: formData,
			headers: {
				apikey: process.env.APIKEY
			}
		},
		function(err, httpResponse, body) {
			if (err) {
				return console.error('upload failed:', err);
			}
			console.log(body);
		}
	);

	

Retrieving scan reports using data id

Retrieve scan results

On Metadefender Cloud, scans are performed asynchronously and each scan request is tracked by a unique data_id. Initiating a file scan and retrieving the scan results needs to be done with two separate API calls. Scan completion can be traced using property scan_results.progress_percentage value from the response. When the value of scan_results.progress_percentage is equal to 100 the scanning is done and you are receiving final scan result. We recommend to periodically check the GET /v2/file/{data_id*} endpoint after you send the file for scanning until the scan is complete.

Check if scan is complete https://api.metadefender.com/v2/file/{data_id*}
Example https://api.metadefender.com/v2/file/103bc4e00b284200991d83d2a95600d9

HTTP header parameters

apikey API key asigned by OPSWAT REQUIRED
file_metadata Show metadata if applicable. If '0', the metadata is not returned. If '1', the metadata is returned. The default value is '0'. When enabled, more metadata will show up in file_info. OPTIONAL

Method: GET

HTTP request must include the parameter:

data_id Get from (scanning a file). REQUIRED

Request error (http status: 40x)

400: Bad request Unsupported HTTP method or invalid HTTP request (e.g., empty body).
401: Invalid API key An invalid API key, or no API key, has been provided

Request Error (HTTP status: 50x)

500: Internal server error Server temporarily unavailable. Try again later.

Response (HTTP status: 200)

Example when a result is not found:

	{
	    "4f84e3b096d54908963d037b5457bf27": "Not Found"
	}
	

Scan Results Description

Example of successful scan request:

	{
		file_id: "506ba4f034a9b5237c20f27d",
		- scan_results: {
			- scan_details: {
				- Ahnlab scan engine: {
					scan_result_i: 0,
					threat_found: "",
					def_time: "2014-07-18T07:00:00Z",
					scan_time: 3447
				},
				+ ArcaVir scan engine: { ... },
				+ AVG scan engine: { ... },
				...
				+ Zoner scan engine: { ... }
			},
			rescan_available: false,
			data_id: "2220460573",
			scan_all_result_i: 0,
			start_time: "2014-07-18T18:29:46Z",
			total_time: 5507,
			total_avs: 34,
			progress_percentage: 100,
			scan_all_result_a: "Clean",
			in_queue: 0
		},
		file_info: {
			display_name: "failed to generate license key.png",
			file_size: 107716,
			upload_timestamp: "2014-07-18T18:29:00Z",
			md5: "9e107d9d372bb6826bd81d3542a419d6",
			sha1: "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
			sha256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
			file_type_category: "G",
			file_type_description: "Portable Network Graphics",
			file_type_extension: "PNG"
		},
		data_id: "2220460573"
	}
file_id Not applicable to hash lookup.
scan_results Global scan results, metadata, and scan report from all engines.
file_info File metadata, hash value, analyzed file types.
data_id Not applicable for hash lookup.
scann_all_result_i See description table.

More levels for file_info level.

upload_timestamp First time the file is uploaded to the server (even if file is rescanned this value will be preserved).
file_type_category High level categorization of the file type. See description table

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v2/file/6d21e9cdfd3b42b49e3c26d79d1e26c2",
	  "headers": {
		"apikey": process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

Rescan a file

Initiate rescan request

Rescan a previously-uploaded file using its "file_id" (see below). If previous scan was done with "samplesharing" flag disabled, this is not available. Once rescan request is made successfully, scan result can be retrieved in the same fashion as when a file is uploaded.

NOTE: When we get scan result of an engine from Metadefender, if scan result is dirty, all non-english characters in threat name will be removed right away.

Initiate rescan request https://api.metadefender.com/v2/rescan/{file_id}

HTTP header parameters

apikey API key assigned by OPSWAT REQUIRED

Method: GET

file_id Get from retrieving scan results.

Request Error (HTTP status: 40x)

400: Bad request Not supported HTTP method or invalid http request.
401 Invalid API key / Exceeded usage Either missing API key or invalid api is passed.

Request Error (HTTP status: 50x)

500 Internal error Server temporary unavailable. Try again later.
503 Service unavailable Server temporary unavailable. There're too many unfinished file in pending queue. Try again later.

Response (HTTP status: 200)

Example of when rescan request is failed:

	{
		"528049058c14f610d48196016" : "Not Found"
	}

Example of when rescan request is successful:

	{
	    "data_id" : "ed3f536f7b384b11bd8285d4cce4d88f",
	    "rest_ip" : "api.metadefender.com/v2"
	}
	

Description

data_id Data ID used for retrieving scan result.
rest_ip Requests for the scan progress using 'data_id' should be made to this address instead of the original address. Once a scan is finished, future requests for this 'data_id' can be made to the original address.

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v2/rescan/b92f5193d01a48a1b6160b16610b6148",
	  "headers": {
		"apikey": process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

Look up hashes

Overview

Metadefender provides two basic ways of looking up scan results using data hashes, MD5, SHA1, and SHA256:

  • single hash lookup
  • multiple hash lookup

While single hash lookup provides full scan results related to hash if found, multiple hash lookup will return condensed results with links (data_ids) to full scan result.

Retrieving scan reports using data hash

URL for hash lookup

	https://api.metadefender.com/v2/hash/{hashvalue}

Hash value - any of the following:

  • SHA1
  • MD5
  • SHA256

e.g. https://api.metadefender.com/v2/hash/BED12FDA073BB386B54700138FB47EEA

HTTP header parameters

apikey API key assigned by OPSWAT. REQUIRED
file_metadata Show metadata if applicable. If '0', the metadata is not returned. If '1', the metadata is returned. The default value is '0'. When enabled, more metadata will show up in file_info. OPTIONAL

Method: GET

HTTP request must include the parameter.

hash_value SHA1 or MD5 or SHA256. REQUIRED

Error (HTTP status: 40x)

400: Bad request Unsupported HTTP method or invalid HTTP request (e.g., empty body).
401 Invalid API key Either missing API key or invalid API is passed.
403 Signature lookup limit reached, try again later The hourly hash lookup limit has been reached for this API key.

Response (HTTP status: 200)

Example of result not found.

	{
		"BED12FDA073BB386B54700138FB47EEA": "Not Found"
	}

Scan Results Description

Top level.

	 {
		file_id: "506ba4f034a9b5237c20f27d",
		- scan_results: {
			- scan_details: {
				- Ahnlab scan engine: {
					scan_result_i: 0,
					threat_found: "",
					def_time: "2014-07-18T07:00:00Z",
					scan_time: 3447
				},
				+ ArcaVir scan engine: { ... },
				+ AVG scan engine: { ... },
				...
				+ Zoner scan engine: { ... }
			},
			rescan_available: false,
			data_id: "2220460573",
			scan_all_result_i: 0,
			start_time: "2014-07-18T18:29:46Z",
			total_time: 5507,
			total_avs: 34,
			progress_percentage: 100,
			scan_all_result_a: "Clean",
			in_queue: 0
		},
		file_info: {
			display_name: "failed to generate license key.png",
			file_size: 107716,
			upload_timestamp: "2014-07-18T18:29:00Z",
			md5: "9e107d9d372bb6826bd81d3542a419d6",
			sha1: "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
			sha256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
			file_type_category: "G",
			file_type_description: "Portable Network Graphics",
			file_type_extension: "PNG"
		},
		data_id: "2220460573"
	}
file_id Not applicable to hash lookup.
scan_results Global scan results, meta data, and scan reports from all engines.
file_info File metadata, hash value, analyzed file types.
data_id Not applicable for hash lookup.
scan_all_result_i See description table

More levels for file_info level.

upload_timestamp First time the file is uploaded to the server (even if file is rescanned this value will be preserved).
file_type_category High level categorization of the file type. See description table

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v2/hash/E71A6D8760B37E45FA09D3E1E67E2CD3",
	  "headers": {
		"apikey": process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

Retrieving scan reports for multiple data hashes

URL for multiple hash lookup

	https://api.metadefender.com/v2/hash

HTTP header parameters

apikey API key assigned by OPSWAT. REQUIRED

Method: POST

HTTP request must include the contents of the file as HTTP body.

HTTP body {"hash" : ["hash_value_1","hash_value_2","hash_value_3"]}

Note: Hash value can be md5, sha1 or sha256.

Request Error (HTTP status: 40x)

400: Bad request Unsupported HTTP method or invalid HTTP request.
401 Invalid API key Either missing API key or invalid API is passed.
403 Signature lookup limit reached, try again later The hourly hash lookup limit has been reached for this API key.

Request Error (HTTP status: 50x)

500: Internal server error Server temporarily unavailable. Try again later.

Response (HTTP status: 200)

Example of input body being empty:

	{
		"err" : "hashes in body content is null or empty"
	}

Example of maximum hashes input:

	{
		"err" : "Exceeded maximum allowed. Allow maximum 1000 hashes"
	}

Example of input body in the wrong format:

	{
	    "err" : "Could not parse body content."
	}

Example of successful request:

	[
		{
		  "hash" : hash_value_1,
          "scan_result_i": 0,
		  "data_id" : data_id_1
		}, {
		  "hash" : hash_value_2,
          "scan_result_i": 1,
		  "data_id" : data_id_2
		}, {
		  "hash" : hash_value_3,
		  "scan_result" : 5,
          "scan_result_i" : 5,
		  "data_id" : null
		}
	]

scan_result The newest final scan result of hash.
data_id The newest data_id of hash.

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "POST",
	  "hostname": "api.metadefender.com",
	  "path": "/v2/hash/",
	  "headers": {
		"apikey": process.env.APIKEY,
		"content-type": "application/json"
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.write(JSON.stringify({ hash:
	   [ '76D5D80B5CA3EED75031EBEE8AF2765C',
		 '196693DCABDAE6E066A804CCA774182B' ] }));
	req.end();

IP Reputation Service

Metadefender Cloud allows users to check IP addresses and domains for malicious behavior using many IP reputation sources. This functionality makes it possible to identify threats like botnets that would not be found through scanning files when accessing content. By providing a standardized interface for the leading IP reputation sources, Metadefender Cloud makes it possible to obtain aggregated data on whether an IP address or domain should be trusted, so that you can monitor your network for possible threats.

Metadefender Cloud provides two basic ways of scanning an IP:

  • single IP scan
  • multiple IP scans

Scanning IP

Initiate scan request

Initiate scan request https://api.metadefender.com/v3/ip/{address*}

e.g., https://api.metadefender.com/v3/ip/177.140.22.150

HTTP header parameters

Authorization API key assigned by OPSWAT, prefixed with string "apikey ". e.g. Authorization: apikey a0b1c1d1e1 REQUIRED

Method: GET

HTTP request must include the parameter.

address IP REQUIRED

Request Error (HTTP status: 40x)

400: Bad request Unsupported HTTP method or invalid HTTP request (e.g., empty body).
400: Non routable IP [IP] Input address is non routable IP.
400: We were unable to retrieve the IP address for your entry: <address> Input address can not be converted into IP
401: Invalid API key Either missing API key or invalid API is passed.
403: IP lookup limit reached, try again later API key reaches the maximum IP lookup per hour.

Request Error (HTTP status: 50x)

503: Internal server error Server temporarily unavailable. Try again later.

Response (HTTP status: 200)

Example of the parameter being empty:

	{
		"err" : "IP/URI is null or empty"
	}

Example of successful scan request.

{
  "success": true,
  "data": {
    "address": "177.140.22.150",
    "start_time": "2016-09-12T20:00:20.540Z",
    "scan_results": [
      {
        "source": "reputation.alienvault.com",
        "results": [
          {
            "alternativeid": "",
            "assessment": "",
            "confident": "",
            "detecttime": "",
            "updatetime": "2016-09-12T20:00:21.467Z",
            "result": "unknown"
          }
        ]
      },
      ...
      {
        "source": "zeustracker.abuse.ch",
        "results": [
          {
            "alternativeid": "",
            "assessment": "",
            "confident": "",
            "detecttime": "",
            "updatetime": "2016-09-12T20:00:21.467Z",
            "result": "unknown"
          }
        ]
      }
    ],
    "detected_by": 0,
    "geo_info": {
      "city": {
        "geoname_id": 3448439,
        "names": {
          "de": "São Paulo",
          "en": "São Paulo",
          "es": "São Paulo",
          "fr": "São Paulo",
          "ja": "サンパウロ",
          "pt-BR": "São Paulo",
          "ru": "Сан-Паулу"
        }
      },
      "continent": {
        "code": "SA",
        "geoname_id": 6255150,
        "names": {
          "de": "Südamerika",
          "en": "South America",
          "es": "Sudamérica",
          "fr": "Amérique du Sud",
          "ja": "南アメリカ",
          "pt-BR": "América do Sul",
          "ru": "Южная Америка",
          "zh-CN": "南美洲"
        }
      },
      "country": {
        "geoname_id": 3469034,
        "iso_code": "BR",
        "names": {
          "de": "Brasilien",
          "en": "Brazil",
          "es": "Brasil",
          "fr": "Brésil",
          "ja": "ブラジル連邦共和国",
          "pt-BR": "Brasil",
          "ru": "Бразилия",
          "zh-CN": "巴西"
        }
      },
      "location": {
        "latitude": -23.4733,
        "longitude": -46.6658,
        "time_zone": "America/Sao_Paulo"
      },
      "registered_country": {
        "geoname_id": 3469034,
        "iso_code": "BR",
        "names": {
          "de": "Brasilien",
          "en": "Brazil",
          "es": "Brasil",
          "fr": "Brésil",
          "ja": "ブラジル連邦共和国",
          "pt-BR": "Brasil",
          "ru": "Бразилия",
          "zh-CN": "巴西"
        }
      },
      "subdivisions": [
        {
          "geoname_id": 3448433,
          "iso_code": "SP",
          "names": {
            "en": "Sao Paulo",
            "es": "São Paulo",
            "pt-BR": "São Paulo"
          }
        }
      ]
    }
  }
}
address This is usually an IP address, URI that is found in feeds of data but is not limited to those data types.
geo_info Geolocation of address.
detected_by Number of blacklisted sources.

More levels for scan_results:

{
  "success": true,
  "data": [
    {
      "address": "198.15.127.170",
      "start_time": "2016-09-12T21:36:39.656Z",
      "scan_results": 
      ...
    },
    {
      "address": "8.8.8.8",
      "start_time": "2016-09-12T21:36:40.657Z",
      "scan_results": [
        {
          "source": "zeustracker.abuse.ch",
          "results": [
            {
              "alternativeid": "",
              "assessment": "",
              "confident": "",
              "detecttime": "",
              "updatetime": "2016-09-12T21:36:42.724Z",
              "result": "unknown"
            }
          ]
        }, ...
      ],
      "detected_by": 0,
      "geo_info": {
        "city": {
          "geoname_id": 5375480,
          "names": {
            "de": "Mountain View",
            "en": "Mountain View",
            "fr": "Mountain View",
            "ja": "マウンテンビュー",
            "ru": "Маунтин-Вью",
            "zh-CN": "芒廷维尤"
          }
        },
        "continent": {
          "code": "NA",
          "geoname_id": 6255149,
          "names": {
            "de": "Nordamerika",
            "en": "North America",
            "es": "Norteamérica",
            "fr": "Amérique du Nord",
            "ja": "北アメリカ",
            "pt-BR": "América do Norte",
            "ru": "Северная Америка",
            "zh-CN": "北美洲"
          }
        },
        "country": {
          "geoname_id": 6252001,
          "iso_code": "US",
          "names": {
            "de": "USA",
            "en": "United States",
            "es": "Estados Unidos",
            "fr": "États-Unis",
            "ja": "アメリカ合衆国",
            "pt-BR": "Estados Unidos",
            "ru": "Сша",
            "zh-CN": "美国"
          }
        },
        "location": {
          "latitude": 37.386,
          "longitude": -122.0838,
          "metro_code": 807,
          "time_zone": "America/Los_Angeles"
        },
        "postal": {
          "code": "94035"
        },
        "registered_country": {
          "geoname_id": 6252001,
          "iso_code": "US",
          "names": {
            "de": "USA",
            "en": "United States",
            "es": "Estados Unidos",
            "fr": "États-Unis",
            "ja": "アメリカ合衆国",
            "pt-BR": "Estados Unidos",
            "ru": "Сша",
            "zh-CN": "美国"
          }
        },
        "subdivisions": [
          {
            "geoname_id": 5332921,
            "iso_code": "CA",
            "names": {
              "de": "Kalifornien",
              "en": "California",
              "es": "California",
              "fr": "Californie",
              "ja": "カリフォルニア州",
              "pt-BR": "Califórnia",
              "ru": "Калифорния",
              "zh-CN": "加利福尼亚州"
            }
          }
        ]
      }
    }
  ]
}
source Source of the feed, usually the domain where the feed is from (e.g., example.com).
alternativeid Usually a URL pointing to the original data point (as a reference id).
assessment See IP Scanning User Guide.
confident See IP Scanning User Guide.
detecttime When the event was detected, most common timestamp formats are valid.
result blacklisted, whitelisted, unknown.

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v3/ip/177.140.22.150",
	  "headers": {
		"Authorization": "apikey " + process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

Scanning list of IPs

Initiate scan request

Initiate scan request https://api.metadefender.com/v3/ip/

HTTP header parameters

Authorization API key assigned by OPSWAT, prefixed with string "apikey ". e.g. Authorization: apikey a0b1c1d1e1 REQUIRED
Content-type application/json REQUIRED

Method: POST

HTTP body {"address":["198.15.127.170","8.8.8.8"]}

Request Error (HTTP status: 40x)

400: Bad request Unsupported HTTP method or invalid HTTP request (e.g., empty body).
401: Invalid API key Either missing API key or invalid API key is passed.
403: IP/URI lookup limit reached, try again later API key reaches the maximum address lookup per hour.

Request Error (HTTP status: 50x)

503: Internal server error Server temporarily unavailable. Try again later.

Response (HTTP status: 200)

Example of list address as null or empty:

	{
		"err" : "IP/URI is null or empty"
	}

Example of header being invalid.

	{
		"err" : "Invalid request header"
	}

Example of input body as wrong format.

	{
		"err" : "Could not parse body content"
	}

Example of maximum addresses input.

	{
		"err" : "Exceeded maximum allowed. Allow maximum 50 addresses"
	}

Example of no valid input address.

	[]

Vulnerability Data

Metadefender Cloud allows users to leverage our threat intelligence platform, by providing an extensive REST API as interface. Since we are able to map the files to each application and its version, we are able to provide vulnerability information at the level of hash.

Through our API you will be able to retrieve all the known vulnerabilities for all the applications reported for that hash. Basically you will be able to know that you might be exposed to potential exploits if any of the existing hashes are belonging to applications with known vulnerabilities. More that that, you will be able to do it directly through hash lookups, which will make your diagnosis way faster.

Vulnerability Data Lookup

Initiate Vulnerability Data request

Initiate application information request https://api.metadefender.com/v3/vulnerability/{hash*}

e.g., https://api.metadefender.com/v3/vulnerability/01C7D28E8828A91C27FFE0F1155CFA835FA6D703

HTTP header parameters

Authorization API key assigned by OPSWAT, prefixed with string "apikey ". e.g. Authorization: apikey a0b1c1d1e1 REQUIRED

Method: GET

HTTP request must include the parameter.

The hash value for which you need Vulnerability information (sha1) REQUIRED

Error Handling

Please check the dedicated section in the API documentation for HTTP Status Codes. HTTP Status Codes

Response (HTTP status: 400)

Example of the parameter being invalid:

	{
	  "success": false,
	  "error": {
		"code": 400033,
		"messages": [
		  "The hash `0000BF66978AA7EA3DF2BE15286026442CF19D52` information does not exist"
		]
	  }
	}
	

Example of successful lookup.

	{
	  "success": true,
	  "data": [
		{
		  "description": "Use-after-free vulnerability in Google Chrome before 8.0.552.215 allows remote attackers to cause a denial of service or possibly have unspecified other impact via vectors involving SVG animations.",
		  "severity": "CRITICAL",
		  "severity_index": 5,
		  "cvss": {
			"generated-on-datetime": "2015-11-13T10:32:35.623-05:00",
			"source": "http://nvd.nist.gov",
			"availablity-impact": "",
			"integrity-impact": "COMPLETE",
			"confidentiality-impact": "COMPLETE",
			"authentication": "NONE",
			"access-complexity": "LOW",
			"access-vector": "NETWORK",
			"score": "10.0"
		  },
		  "references": [
			[
			  {
				"name": "DSA-2188",
				"url": "http://www.debian.org/security/2011/dsa-2188"
			  }
			],
			...
		  ],
		  "last-modified-epoch": 1447432729,
		  "last-modified-datetime": "2015-11-13T11:38:49.100-05:00",
		  "published-epoch": 1291755609,
		  "published-datetime": "2010-12-07T16:00:09.577-05:00",
		  "cwe": "CWE-399",
		  "cve": "CVE-2010-4492",
		  "product_info": {
			"wa_signature_id": "41",
			"wa_product_id": "39",
			"product_version": "37.0.2062.103",
			"product_name": "Google Chrome"
		  },
		  "modified": "2015-11-13T11:38:49.100-05:00",
		  "score": 10
		},
		...
	  ]
	}
	
Parent Field name Details
data description Descriptive vulnerability information for each know vulnerability
data severity Level of importance of this known vulnerability (text).
data severity_index Level of importance of this known vulnerability (index).
cvss generated-on-datetime When this known vulnerability was added.
cvss source The source of the known vulnerability
cvss availablity-impact  
cvss integrity-impact  
cvss confidentiality-impact  
cvss authentication  
cvss access-complexity  
cvss access-vector  
cvss score  
references name The name of the reference
references url The url with more details about the vulnerability.
data last-modified-epoch Last time when it was modified (epoch)
data last-modified-datetime Last time when it was modified (timestamp).
data published-epoch When was published (epoch).
data published-datetime When was published (timestamp).
data cwe CWE identifier.
data cve CVE identifier.
product_info wa_signature_id OPSWAT signature id.
product_info wa_product_id Product signature id.
product_info product_version Application version.
product_info product_name Application name.
data modified Modification timestamp.
data score Severity score.

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v3/vulnerability/01C7D28E8828A91C27FFE0F1155CFA835FA6D703",
	  "headers": {
		"Authorization": "apikey " + process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

Application Information

Metadefender Cloud allows users to leverage our threat intelligence platform, by providing an extensive REST API as interface. The unique data set shared through our platform is collected from millions of live machines. This offers you tremendous insights on the behavior of the application, potentially malware, in order of weeks, from an endpoint used in a live environment by a real user. Comparing this data to a sandbox solution, where everything is running in a controlled and simulated environment for approximate 3 minutes, there is no doubt on the value of these information.

Through our API you will be able to retrieve all the applications that the searched hash belongs to, all the network connections made by that applications and which are the other loaded components that are used by those applications. You will be able to identify, restrict or grant access based on the correlations provided.

Application Information Lookup

Initiate application information request

Initiate application information request https://api.metadefender.com/v3/appinfo/{hash*}

e.g., https://api.metadefender.com/v3/appinfo/9B6AEA1992775510CB9014AD6860D146

HTTP header parameters

Authorization API key assigned by OPSWAT, prefixed with string "apikey ". e.g. Authorization: apikey a0b1c1d1e1 REQUIRED

Method: GET

HTTP request must include the parameter.

The hash value for which you need OESIS info (md5 / sha1 / sha256) REQUIRED

Error Handling

Please check the dedicated section in the API documentation for HTTP Status Codes. HTTP Status Codes

Response (HTTP status: 200)

Example of the parameter being invalid:

	{
	  "success": false,
	  "error": {
		"code": 400033,
		"messages": [
		  "The hash `0000BF66978AA7EA3DF2BE15286026442CF19D52` information does not exist"
		]
	  }
	}
	

Example of successful lookup.

	{
		"success": true,
		"data": [{
			"appinfo_report_date": "2016-05-31T00:00:00.000Z",
			"sha1": "530068C230FE07ABBEC2574642D0973BF4BE1CC0",
			"connection_stats": [{
				"domain_name_count": 29,
				"domain_name": "amazonaws.com",
				"host_name_count": 29,
				"host_name": "compute-1.amazonaws.com",
				"external_ip_count": 29,
				"external_ip": "54.86.89.255"
			},
				...
			],
			"os_infos": [{
				"service_pack": "",
				"wa_os_id": "59",
				"kernel_version": "10.0.10586",
				"language": "Dansk (Danmark)",
				"arch": "64-bit",
				"os_type": 1,
				"os_name_norm": "microsoft windows 10 home",
				"os_name": "Microsoft Windows 10 Home"
			},
				...
			],
			"product_info_stats": [{
				"product_version_norm": "3 12 5",
				"product_name_norm_count": 15559,
				"product_name_norm": "dropbox"
			}],
			"product_infos": [{
				"wa_signature_id": "2543",
				"wa_product_id": "110",
				"product_version": "3.12.5",
				"product_name": "Dropbox"
			}, {
				...
			}],
			"vendor_infos": [{
				"wa_vendor_id": "0",
				"vendor_name": "Dropbox, Inc."
			}, {
				"wa_vendor_id": "97",
				"vendor_name": "Dropbox, Inc."
			}],
			"loaded_component_stats": [{,
				"loaded_component_count": 216,
				"loaded_component": "70BF9B4E96969ABD00772E68DFD92E10B6BF1AD6"
			},
				...
			],
			"categories": [{
				"wa_category_id": "2",
				"category_name": "Backup Client"
			}, {
				"wa_category_id": "0",
				"category_name": "Cloud Storage"
			}, {
				"wa_category_id": "9",
				"category_name": "Cloud Storage"
			}],
			"file_path_stats": [{
				"file_path_count": 37,
				"file_path": "\\users\\...\\appdata\\roaming\\dropbox\\bin\\dropbox.exe"
				},
				...
			],
			"file_infos": [{
				"sha1": "530068C230FE07ABBEC2574642D0973BF4BE1CC0",
				"file_property_version_norm": "3.12.5.0",
				"file_property_version": "3.12.5.0",
				"file_size": 24952456,
				"file_name_lower": "dropbox.exe",
				"file_name": "Dropbox.exe"
			},
				...
			]

		}, {
				...
		}]
	}
	
Parent Field name Details
data appinfo_report_date The timestamp when these application informations where reported
data sha1 The hash (sha1 format) of the file.
connection_stats domain_name The domain name corresponding to the reported IP address.
connection_stats domain_name_count How many times this domain name was reported for the parent applications.
connection_stats host_name The host name corresponding to the
reported IP address.
connection_stats host_name_count How many times this host name
was reported for the parent applications.
connection_stats external_ip The reported IP addresses for the network traffic of the parent applications.
connection_stats external_ip_count How many times this IP
was reported for the parent applications.
os_infos kernel_version The kernel version reported from each endpoint for each running OS.
os_infos service_pack The Service Pack version reported from each endpoint for each running OS.
os_infos language The OS language configuration reported from each endpoint for each running OS.
os_infos arch The system architecture (32/64 bit) reported from each endpoint for each running OS.
os_infos os_name The operating system official name reported from each endpoint for each running OS.
product_info_stats product_version_norm The product version normalized reported for all running applications from each endpoint.
product_info_stats product_name_norm_count How many times this
application version was reported.
product_info_stats product_name_norm The reported product name (normalized).
product_infos product_version The reported product version.
product_infos product_name The reported product name (official).
vendor_infos vendor_name The reported vendor name (official).
loaded_component_stats loaded_component The hash (sha1 format) of one of the components loaded at runtime.
loaded_component_stats loaded_component_count How many times this component was reported as loaded for the applications this files belong to.
categories wa_category_id Internal generated category id.
This corresponds to the applications classified by OESIS framework.
categories category_name Internal generated category name.
This corresponds to the applications classified by OESIS framework.

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v3/appinfo/9B6AEA1992775510CB9014AD6860D146",
	  "headers": {
		"Authorization": "apikey " + process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

CVE Information

Metadefender Cloud allows users to lookup information about specific computer vulnerabilities and exposures (CVEs) by providinging specific identifiers.

CVE Listing

API endpoint GET /cve returns list of supported CVEs in Metadefender Cloud.

Initiate CVE list request https://api.metadefender.com/v3/cve

e.g., https://api.metadefender.com/v3/cve

HTTP header parameters

Authorization API key assigned by OPSWAT, prefixed with string "apikey ". e.g. Authorization: apikey a0b1c1d1e1 REQUIRED

Method: GET

Error Handling

Please check the dedicated section in the API documentation for HTTP Status Codes. HTTP Status Codes

Response (HTTP status: 200)

Example of successful listing.

{
  "data": {
    "cve": [
      "CVE-1999-0354",
      "CVE-1999-0384",
      "CVE-1999-0519",
      "CVE-1999-0999",
      "CVE-1999-1055",
      "CVE-1999-1164",
      "CVE-1999-1474",
      "CVE-1999-1556",
      "CVE-1999-1576",
      "CVE-2000-0049"
    ]
  },
  "success": true
}

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v3/cve",
	  "headers": {
		"Authorization": "apikey " + process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

CVE Information Lookup

Initiate CVE information request

Initiate CVE information request https://api.metadefender.com/v3/cve/{cve}

e.g., https://api.metadefender.com/v3/cve/CVE-2013-2841

HTTP header parameters

Authorization API key assigned by OPSWAT, prefixed with string "apikey ". e.g. Authorization: apikey a0b1c1d1e1 REQUIRED

Method: GET

HTTP request must include the parameter.

cve The CVE identifier. Eg: CVE-2013-2841 REQUIRED

Error Handling

Please check the dedicated section in the API documentation for HTTP Status Codes. HTTP Status Codes

Response (HTTP status: 404)

Example of the parameter being invalid:

{
  "success": false,
  "error": {
    "code": 404009,
    "messages": [
      "Requested CVE does not exist in our records"
    ]
  }
}

Response (HTTP status: 200)

Example of successful lookup.

{
  "success": true,
  "data": {
    "vendor_name_norm": [
      "google inc "
    ],
    "product_name_version_norm": [
      {
        "product_name_norm": "google chrome",
        "product_version_norm": "48 0 2564 109"
      },
      {
        "product_name_norm": "google chrome",
        "product_version_norm": "31 0 1650 63"
      },
      {
        "product_name_norm": "google chrome",
        "product_version_norm": "50 0 2661 102"
      },
      {
        "product_name_norm": "google chrome",
        "product_version_norm": "51 0 2704 103"
      },
    ],
    "cve_info": {
      "severity": "IMPORTANT",
      "severity_index": 4,
      "cvss": {
        "generated-on-datetime": "2013-05-22T11:31:00.000-04:00",
        "source": "http://nvd.nist.gov",
        "availablity-impact": "",
        "integrity-impact": "PARTIAL",
        "confidentiality-impact": "PARTIAL",
        "authentication": "NONE",
        "access-complexity": "LOW",
        "access-vector": "NETWORK",
        "score": "7.5"
      },
      "references": [
        [
          {
            "url": "https://code.google.com/p/chromium/issues/detail?id=227350",
            "name": "https://code.google.com/p/chromium/issues/detail?id=227350"
          }
        ],
        [
          {
            "url": "http://www.debian.org/security/2013/dsa-2695",
            "name": "DSA-2695"
          }
        ],
        [
          {
            "url": "http://googlechromereleases.blogspot.com/2013/05/stable-channel-release.html",
            "name": "http://googlechromereleases.blogspot.com/2013/05/stable-channel-release.html"
          }
        ]
      ],
      "last-modified-epoch": 1383449548,
      "last-modified-datetime": "2013-11-02T23:32:28.300-04:00",
      "published-epoch": 1369229396,
      "published-datetime": "2013-05-22T09:29:56.030-04:00",
      "cwe": "CWE-399",
      "cve": "CVE-2013-2841"
    },
    "sha256": [
      "2C8348611CC5C02CE54B4CFE5C723C735E3BB28A6BF4C9DF8C8910306584801E",
      "F30EBF477F8BE1B540DCE9FCB36264A203D058DFC8F8A37451ED76347098C40C",
      "500717B67FE0EFAC378DC51096BC04229ACE096D18F78D8DDA75C64BF0B06A4B",
      "BE9909239116FCE92046816664619F5BE685430F2A1302C27998946386148E74",
      "4D3E804B89635925C1F3E843817A861DCC199D1AB3A4E7BC82BBC06473E9587F",
      "2AAF4AA8DAAD8C547C9BC0E67A1CEFF3781B71AA6EE1C99B7FF6E1BAB4F9C379",
      "84FB5B438559FB66539DBADD2ADD6A5EE28339C98531D9868EF0B0A4792CBCEA",
      "14D176A668D8F8D1D774B0185184356AE4AADB15483256B53109A2A39CD87CCA",
      "7108546DCF753F60684683A01FCD5B80CF6333526D5CA40CC18BACA74D81D0B7",
      "4720DFC9CAF7FED89E584FB173CAF9391F8535C796EAA5B3D9FF1FB28FE84AE1",
      ...
    ],
    "sha1": [
      "A044DC7F7639848F817505D847AE079A19EABC8E",
      "AEE8B51BB15C4FD9680E6E56C07AFFAABC07AEC3",
      "9E0E0EB7E9137EBDC21CB4BE64450ADDD5AB5936",
      "9A869AD54A1654BA4B99D04BF32D9FB486182FA6",
      "99515340C7F331753140770A4CEDF3CE5D24E884",
      "2F17D03743074FDAAF32C375BBD118A320EAFF5A",
      ...
    ],
    "md5": [
      "15DF272F29CCC86D4FB355007798AE84",
      "00C36AE47C7E16937834705DDA03EF7E",
      "53F053826405F62584EE9423FFA9F086",
      "9AE42BE14C84B6F52FBB533CC3037453",
      "A99FB676E5EB1393BB241FDE05843127",
      "7A5831367567DC889D6348A9210E3F8A",
      ...
    ],
    "appinfo_report_date": "2017-02-05T00:00:00.000Z"
  }
}
Parent Field name Details
data covered_appinfo_report_date The timestamp when this CVE information were reported
data covered_vulnerability_cve CVE vulnerability identifier
data appinfo_report_date The timestamp when this CVE information were reported
data vendor_name_norm Normalized vendor name
data md5 Array of MD5 hashes associated with CVE vulnerability
data sha1 Array of SHA1 hashes associated with CVE vulnerability
data sha256 Array of SHA256 hashes associated with CVE vulnerability
data product_name_version_norm Array of normalized product names and versions associated with CVE vulnerability
product_name_version_norm product_name_norm Normalized product name
product_name_version_norm product_version_norm Normalized product version
cve_info cve CVE vulnerability identifier
cve_info cwe CWE Identifier Number/Name of the weakness type
cve_info published-datetime When was published (timestamp)
cve_info published-epoch When was published (epoch)
cve_info last-modified-datetime Last time when it was modified (timestamp)
cve_info last-modified-epoch Last time when it was modified (epoch)
cve_info references Array of CVE references
references name Referance name
references url Referance URL
cvss score Numerical score
cvss access-vector Shows how a vulnerability may be exploited
cvss access-complexity Describes how easy or difficult it is to exploit the discovered vulnerability
cvss authentication Describes the number of times that an attacker must authenticate to a target to exploit it
cvss confidentiality-impact Describes the impact on the confidentiality of data processed by the system
cvss integrity-impact Describes the impact on the integrity of the exploited system
cvss availablity-impact Describes the impact on the availability of the target system
cvss source The source of the known vulnerability
cvss generated-on-datetime When this known vulnerability was added.
cve_info severity_index Level of importance of this known vulnerability (index).
cve_info severity Level of importance of this known vulnerability (text)

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v3/cve/CVE-2013-2841",
	  "headers": {
		"Authorization": "apikey " + process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

CVE Hashes Lookup

Initiate CVE hashes request

Initiate CVE hashes request https://api.metadefender.com/v3/cve/{cve}/hashes

e.g., https://api.metadefender.com/v3/cve/CVE-2013-2841/hashes

HTTP header parameters

Authorization API key assigned by OPSWAT, prefixed with string "apikey ". e.g. Authorization: apikey a0b1c1d1e1 REQUIRED

Method: GET

HTTP request must include the parameter.

cve The CVE identifier. Eg: CVE-2013-2841 REQUIRED

Error Handling

Please check the dedicated section in the API documentation for HTTP Status Codes. HTTP Status Codes

Response (HTTP status: 404)

Example of the parameter being invalid:

{
  "success": false,
  "error": {
    "code": 404009,
    "messages": [
      "Requested CVE does not exist in our records"
    ]
  }
}

Response (HTTP status: 200)

Example of successful lookup.

{
  "success": true,
  "data": {
    "cve_info": {
      "severity": "IMPORTANT",
      "severity_index": 4,
      "cvss": {
        "generated-on-datetime": "2013-05-22T11:31:00.000-04:00",
        "source": "http://nvd.nist.gov",
        "availablity-impact": "",
        "integrity-impact": "PARTIAL",
        "confidentiality-impact": "PARTIAL",
        "authentication": "NONE",
        "access-complexity": "LOW",
        "access-vector": "NETWORK",
        "score": "7.5"
      },
      "references": [
        [
          {
            "url": "https://code.google.com/p/chromium/issues/detail?id=227350",
            "name": "https://code.google.com/p/chromium/issues/detail?id=227350"
          }
        ],
        [
          {
            "url": "http://www.debian.org/security/2013/dsa-2695",
            "name": "DSA-2695"
          }
        ],
        [
          {
            "url": "http://googlechromereleases.blogspot.com/2013/05/stable-channel-release.html",
            "name": "http://googlechromereleases.blogspot.com/2013/05/stable-channel-release.html"
          }
        ]
      ],
      "last-modified-epoch": 1383449548,
      "last-modified-datetime": "2013-11-02T23:32:28.300-04:00",
      "published-epoch": 1369229396,
      "published-datetime": "2013-05-22T09:29:56.030-04:00",
      "cwe": "CWE-399",
      "cve": "CVE-2013-2841"
    },
    "sha256": [
      "2C8348611CC5C02CE54B4CFE5C723C735E3BB28A6BF4C9DF8C8910306584801E",
      "F30EBF477F8BE1B540DCE9FCB36264A203D058DFC8F8A37451ED76347098C40C",
      "500717B67FE0EFAC378DC51096BC04229ACE096D18F78D8DDA75C64BF0B06A4B",
      "BE9909239116FCE92046816664619F5BE685430F2A1302C27998946386148E74",
      "4D3E804B89635925C1F3E843817A861DCC199D1AB3A4E7BC82BBC06473E9587F",
      "2AAF4AA8DAAD8C547C9BC0E67A1CEFF3781B71AA6EE1C99B7FF6E1BAB4F9C379",
      "84FB5B438559FB66539DBADD2ADD6A5EE28339C98531D9868EF0B0A4792CBCEA",
      "14D176A668D8F8D1D774B0185184356AE4AADB15483256B53109A2A39CD87CCA",
      "7108546DCF753F60684683A01FCD5B80CF6333526D5CA40CC18BACA74D81D0B7",
      "4720DFC9CAF7FED89E584FB173CAF9391F8535C796EAA5B3D9FF1FB28FE84AE1",
      ...
    ],
    "sha1": [
      "A044DC7F7639848F817505D847AE079A19EABC8E",
      "AEE8B51BB15C4FD9680E6E56C07AFFAABC07AEC3",
      "9E0E0EB7E9137EBDC21CB4BE64450ADDD5AB5936",
      "9A869AD54A1654BA4B99D04BF32D9FB486182FA6",
      "99515340C7F331753140770A4CEDF3CE5D24E884",
      "2F17D03743074FDAAF32C375BBD118A320EAFF5A",
      ...
    ],
    "md5": [
      "15DF272F29CCC86D4FB355007798AE84",
      "00C36AE47C7E16937834705DDA03EF7E",
      "53F053826405F62584EE9423FFA9F086",
      "9AE42BE14C84B6F52FBB533CC3037453",
      "A99FB676E5EB1393BB241FDE05843127",
      "7A5831367567DC889D6348A9210E3F8A",
      ...
    ],
    "appinfo_report_date": "2017-02-05T00:00:00.000Z"
  }
}

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v3/cve/CVE-2013-2841/hashes",
	  "headers": {
		"Authorization": "apikey " + process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

CVE Vendors Lookup

Initiate CVE vendors request

Initiate CVE hashes request https://api.metadefender.com/v3/cve/{cve}/vendors

e.g., https://api.metadefender.com/v3/cve/CVE-2013-2841/vendors

HTTP header parameters

Authorization API key assigned by OPSWAT, prefixed with string "apikey ". e.g. Authorization: apikey a0b1c1d1e1 REQUIRED

Method: GET

HTTP request must include the parameter.

cve The CVE identifier. Eg: CVE-2013-2841 REQUIRED

Error Handling

Please check the dedicated section in the API documentation for HTTP Status Codes. HTTP Status Codes

Response (HTTP status: 404)

Example of the parameter being invalid:

{
  "success": false,
  "error": {
    "code": 404009,
    "messages": [
      "Requested CVE does not exist in our records"
    ]
  }
}

Response (HTTP status: 200)

Example of successful lookup.

{
  "success": true,
  "data": {
    "vendor_name_norm": [
      "google inc "
    ],
    "cve_info": {
      "severity": "IMPORTANT",
      "severity_index": 4,
      "cvss": {
        "generated-on-datetime": "2013-05-22T11:31:00.000-04:00",
        "source": "http://nvd.nist.gov",
        "availablity-impact": "",
        "integrity-impact": "PARTIAL",
        "confidentiality-impact": "PARTIAL",
        "authentication": "NONE",
        "access-complexity": "LOW",
        "access-vector": "NETWORK",
        "score": "7.5"
      },
      "references": [
        [
          {
            "url": "https://code.google.com/p/chromium/issues/detail?id=227350",
            "name": "https://code.google.com/p/chromium/issues/detail?id=227350"
          }
        ],
        [
          {
            "url": "http://www.debian.org/security/2013/dsa-2695",
            "name": "DSA-2695"
          }
        ],
        [
          {
            "url": "http://googlechromereleases.blogspot.com/2013/05/stable-channel-release.html",
            "name": "http://googlechromereleases.blogspot.com/2013/05/stable-channel-release.html"
          }
        ]
      ],
      "last-modified-epoch": 1383449548,
      "last-modified-datetime": "2013-11-02T23:32:28.300-04:00",
      "published-epoch": 1369229396,
      "published-datetime": "2013-05-22T09:29:56.030-04:00",
      "cwe": "CWE-399",
      "cve": "CVE-2013-2841"
    },
    "appinfo_report_date": "2017-02-05T00:00:00.000Z"
  }
}

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v3/cve/CVE-2013-2841/vendors",
	  "headers": {
		"Authorization": "apikey " + process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

CVE Products Lookup

Initiate CVE products request

Initiate CVE hashes request https://api.metadefender.com/v3/cve/{cve}/products

e.g., https://api.metadefender.com/v3/cve/CVE-2013-2841/products

HTTP header parameters

Authorization API key assigned by OPSWAT, prefixed with string "apikey ". e.g. Authorization: apikey a0b1c1d1e1 REQUIRED

Method: GET

HTTP request must include the parameter.

cve The CVE identifier. Eg: CVE-2013-2841 REQUIRED

Error Handling

Please check the dedicated section in the API documentation for HTTP Status Codes. HTTP Status Codes

Response (HTTP status: 404)

Example of the parameter being invalid:

{
  "success": false,
  "error": {
    "code": 404009,
    "messages": [
      "Requested CVE does not exist in our records"
    ]
  }
}

Response (HTTP status: 200)

Example of successful lookup.

{
  "success": true,
  "data": {
    "product_name_version_norm": [
      {
        "product_name_norm": "google chrome",
        "product_version_norm": "48 0 2564 109"
      },
      {
        "product_name_norm": "google chrome",
        "product_version_norm": "31 0 1650 63"
      },
      {
        "product_name_norm": "google chrome",
        "product_version_norm": "50 0 2661 102"
      },
      {
        "product_name_norm": "google chrome",
        "product_version_norm": "51 0 2704 103"
      },
    ],
    "cve_info": {
      "severity": "IMPORTANT",
      "severity_index": 4,
      "cvss": {
        "generated-on-datetime": "2013-05-22T11:31:00.000-04:00",
        "source": "http://nvd.nist.gov",
        "availablity-impact": "",
        "integrity-impact": "PARTIAL",
        "confidentiality-impact": "PARTIAL",
        "authentication": "NONE",
        "access-complexity": "LOW",
        "access-vector": "NETWORK",
        "score": "7.5"
      },
      "references": [
        [
          {
            "url": "https://code.google.com/p/chromium/issues/detail?id=227350",
            "name": "https://code.google.com/p/chromium/issues/detail?id=227350"
          }
        ],
        [
          {
            "url": "http://www.debian.org/security/2013/dsa-2695",
            "name": "DSA-2695"
          }
        ],
        [
          {
            "url": "http://googlechromereleases.blogspot.com/2013/05/stable-channel-release.html",
            "name": "http://googlechromereleases.blogspot.com/2013/05/stable-channel-release.html"
          }
        ]
      ],
      "last-modified-epoch": 1383449548,
      "last-modified-datetime": "2013-11-02T23:32:28.300-04:00",
      "published-epoch": 1369229396,
      "published-datetime": "2013-05-22T09:29:56.030-04:00",
      "cwe": "CWE-399",
      "cve": "CVE-2013-2841"
    },
    "appinfo_report_date": "2017-02-05T00:00:00.000Z"
  }
}

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v3/cve/CVE-2013-2841/products",
	  "headers": {
		"Authorization": "apikey " + process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();

Data Sanitization (Content Disarm & Reconstruction)

Metadefender Cloud allows users to leverage our Data Sanitization (Content Disarm and Reconstruction) technology, by providing an extensive REST API as interface.

Through our API you will be able to use data sanitization (CDR) to strip out embedded objects in document files. The Content Disarm and Reconstruction process provides an extra level of insurance against zero-day attacks without effecting the usability of the files. Some targeted attacks may not be detected by traditional anti-malware engines, therefore data sanitization should be performed on document files. Metadefender Cloud leverages Metadefender Core's Workflow Engine for the sanitization process.

Data Sanitization

Initiate data sanitization request

On Metadefender, scans and sanitization requests are performed asynchronously and each scan request is tracked by a data ID. For initiating sanitization, users should use the same endpoint that is used for File scan: POST /v2/file and add additional header user_agent and value mcl-metadefender-rest-sanitize-disabled-unarchive.

Data sanitization is supported for following file types: PDF, DOC(X), XLS(X), PPT(X), RTF, BMP, JPG, EPS, BMP, and TIFF.

Initiate scan request https://scan.metadefender.com/v2/file

HTTP header parameters

apikey API key assigned by OPSWAT. REQUIRED
user_agent Value has to be: mcl-metadefender-rest-sanitize-disabled-unarchive REQUIRED

Method: POST

HTTP requests must include the contents of the file as HTTP body.

HTTP body Content of the file for scan.

Request error (HTTP status: 40x)

400: Bad request Unsupported HTTP method or invalid http request (e.g., empty body).
401: Invalid API key An invalid API key, or no API key, has been provided
403: scan limit reached The hourly scan limit has been reached for this API key
403 Private scanning not enabled for the provided API key A private scanning request has been made using an API key that does not allow private scanning

Request Error (HTTP status: 50x)

500 Internal error Server temporarily unavailable; please try again later. If the issue persists, please contact OPSWAT.
503 Failed to request scan The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. If the issue persists, please contact OPSWAT.
503 Server is too busy  

Response (HTTP status: 200)

Example of a successful scan request:

    {
      "data_id": "ZzE2MTEyMlMxMkQ1U0dmR3hyeTZ3NVNHR01s",
      "status": "inqueue",
      "in_queue": "2",
      "rest_ip": "api.metadefender.com/v2"
    }

Description:

The response is identical with File Scan response. Please see section Response (HTTP status: 200) of File Scan

Sample code (Node.js)

	var request = require('request');
	var fs = require("fs");

	var formData = {
	  file: fs.createReadStream(__dirname + '/file')
	};

	request.post({
			url: 'https://scan.metadefender.com/v2/file',
			formData: formData,
			headers: {
				apikey: process.env.APIKEY,
				'user_agent': 'mcl-metadefender-rest-sanitize-disabled-unarchive'
			}
		},
		function(err, httpResponse, body) {
			if (err) {
				return console.error('upload failed:', err);
			}
			console.log(body);
		}
	);

Retrieving Sanitized Files

Retrieving sanitized files

On Metadefender, scans and sanitization are performed asynchronously and each scan and sanitization request is tracked by a data_id. Initiating a file scan and retrieving the scan results and sanitized files needs to be done with two separate API calls. This request needs to be made multiple times until the scan is complete. Scan completion can be traced using property scan_results.progress_percentage value from the response. Sanitization completion must be traced by using property process_info.progress_percentage

HTTP header parameters

apikey API key asigned by OPSWAT REQUIRED

Method: GET

HTTP request must include the parameter:

data_id Get from (scanning a file). REQUIRED

Response (HTTP status: 200)

Scan results with sanitization description

Example of successful scan and sanitization request:

{
  "file_id": "cDE2MTIxMkIxUXhqdlZuM21n",
  "data_id": "cDE2MTIxMkIxUXhqdlZuM21nU0pOeG92NGgyUWc",
  "sanitized": {
    "file_path": "https://s3-us-west-2.amazonaws.com/p.files.metadefender.com/dt%3D161212/B1QxjvVn3mg.sanitized?AWSAccessKeyId=KEYID&Expires=1481588777&Signature=SIGNATURE%3D&response-content-disposition=attachment%3B%20filename%3DUnknown%20Filename",
    "data_id": "cDE2MTIxMkIxUXhqdlZuM21nU3lQdVZoM1hl",
    "result": "Allowed"
  },
  "process_info": {
    "profile_obj_id": "57e1ff5a64d3191340c72c7c",
    "file_type_skipped_scan": false,
    "blocked_reason": "",
    "result": "Allowed",
    "profile": "Sanitization archive disabled",
    "user_agent": "mcl-metadefender-rest-sanitize-disabled-unarchive",
    "progress_percentage": 100
  },
  "scan_results": {
    "scan_details": {
      "DrWebGateway": {
        "threat_found": "",
        "scan_result_i": 0,
        "def_time": "2016-12-12T00:00:00Z",
        "scan_time": 125
      },
      "Emsisoft": {
        "threat_found": "",
        "scan_result_i": 0,
        "def_time": "2016-12-12T00:00:00Z",
        "scan_time": 516
      },
      "K7": {
        "threat_found": "",
        "scan_result_i": 0,
        "def_time": "2016-12-12T00:00:00Z",
        "scan_time": 31
      },
      "AegisLab": {
        "threat_found": "",
        "scan_result_i": 0,
        "def_time": "2016-12-12T00:00:00Z",
        "scan_time": 1531
      },
      "Agnitum": {
        "threat_found": "",
        "scan_result_i": 0,
        "def_time": "2016-12-12T00:00:00Z",
        "scan_time": 1219
      },
      ...
    },
    "rescan_available": false,
    "data_id": "cDE2MTIxMkIxUXhqdlZuM21nU0pOeG92NGgyUWc",
    "scan_all_result_i": 0,
    "start_time": "2016-12-12T23:35:53.565Z",
    "total_time": 6672,
    "total_avs": 41,
    "total_detected_avs": 0,
    "progress_percentage": 100,
    "in_queue": 0,
    "scan_all_result_a": "Clean"
  },
  "file_info": {
    "file_size": 117956,
    "upload_timestamp": "2016-12-12T23:35:53.565Z",
    "md5": "F7F398105BC380EC35095C31DE52C0EA",
    "sha1": "E52988C8A1BCCAD45ECC17AF989732A5A4C08EAE",
    "sha256": "CFB047CEEECA5D1F0B03D08E1E62C9FF546A261B3E3662F6E6BBD0854EFA91F3",
    "file_type_category": "P",
    "file_type_description": "Adobe Portable Document Format",
    "file_type_extension": "pdf/ai",
    "display_name": "Unknown Filename"
  },
  "top_threat": -1
}

Server response from GET /v2/file is identical with File API response from above. Nonetheless, these are unique properties related to the sanitization.

sanitized.file_path Location of the sanitized file accessible only thourgh this unique link.
sanitized.data_id Data ID used for retrieving scan results of the sanitized file.
sanitized.result Result of the sanitization operation. Allowed stands for succesfull sanitization. If an error occurs during the sanitization step, it will be writen here.
process_info.profile_obj_id Internal ID of workflow profile.
process_info.file_type_skipped_scan Indicates if the input file's detected type was configured to skip scanning.
process_info.blocked_reason Reason for blocked sanitization.
process_info.result Result of the sanitization process.
process_info.profile Profile used for sanitization.
process_info.user_agent User agent associated with workflow.
process_info.progress_percentage Process progress percentage. Once 100%, the process is finished and sanitization result is available.

Sample code (Node.js)

	var http = require("https");

	var options = {
	  "method": "GET",
	  "hostname": "api.metadefender.com",
	  "path": "/v2/file/cDE2MTIxMkIxUXhqdlZuM21nU0pOeG92NGgyUWc",
	  "headers": {
		"apikey": process.env.APIKEY
	  }
	};

	var req = http.request(options, function (res) {
	  var chunks = [];

	  res.on("data", function (chunk) {
		chunks.push(chunk);
	  });

	  res.on("end", function () {
		var body = Buffer.concat(chunks);
		console.log(body.toString());
	  });
	});

	req.end();
Your current browser is not supported. Please go to Browse Happy and download a newer browser.