Virusdie external website malware and security scanner API #

By using this API you can check if website blacklisted by Virusdie and get additional security info about it:

2018-09-24

API requests format #

Use HTTP requests to the server sitescan.virusdie.com. All request types are described below.
If any error occurs, the service will respond with corresponding HTTP status code and basic error description.

Authorization #

You should use your personal API key to authorize any request.
API key should be transferred via cookie named apikey (apikey=Your_API_key).
The service will reject an unauthorized request with 403 status code.

Lookup single domain #

You can request status of any (single) domain from virusdie’s database:

GET /lookup/<domain> ? [&bldetails[=int]] [&lang=str]

Response #

The response body contains complete information about all threats found on requested site. It is a JSON encoded object described below:

{
  "datescanned": int,
  "datechanged": int,
  "errors": int,
  "status": int,
  "domain": "string",
  "results": [
    [ "Page URL", Threat ID, "Threat name", This is suspicious, "Code fragment" ],
    ...
  ],
  "phishing_urls": [ "phishing_url", ... ],
  "blacklisted": [ "Google Safebrowsing", "Yandex Safebrowsing", ... ],
  "blacklistchecked": int,
  "blacklistscanned": int,
  "blacklistchanged": int
}

Example #

GET /lookup/example.com

{
  "datescanned": 1485966334,
  "datechanged": 1485966334,
  "errors": 0,
  "status": 2,
  "domain": "example.com",
  "results": [
    [ "/page.php?id=5", 101, "JS.Eval.1",   0, "Abc=" ],
    [ "/js/script.js",  102, "JS.Trojan.2", 1, "Def=" ]
  ],
  "phishing_urls": [ "http://compromised-domain.com/bank.php" ],
  "blacklisted": [ "Google Safebrowsing", "Yandex Safebrowsing" ],
  "blacklistchecked": 1485966334,
  "blacklistscanned": 1485960000,
  "blacklistchanged": 1485966334
}

Example with detailed blacklists info (&bldetails) #

GET /lookup/example.com/?bldetails

{
  "datescanned": 1485966334,
  "datechanged": 1485966334,
  "errors": 0,
  "status": 2,
  "domain": "example.com",
  "results": [
    [ "/page.php?id=5", 101, "JS.Eval.1",   0, "Abc=" ],
    [ "/js/script.js",  102, "JS.Trojan.2", 1, "Def=" ]
  ],
  "phishing_urls": [ "http://compromised-domain.com/bank.php" ],
  "blacklisted": {
    "Google Safebrowsing": {
      "detected": true,
      "result": "malicious site",
      "detail": "http://google.com/..."
    },
    "Yandex Safebrowsing": {
      "detected": true,
      "result": "malware site",
      "detail": "http://yandex.ru/..."
    }
  },
  "blacklistchecked": 1485966334,
  "blacklistscanned": 1485900000,
  "blacklistchanged": 1485966334
}

The .blacklisted list contains positive results only. So the values of .blacklisted.*.detected will always be TRUE.
The fields .blacklisted.*.result and .blacklisted.*.detail can be empty if not provided by safe browsing service.

Example with detailed blacklists info + unblock instructions (&bldetails=1) #

GET /lookup/example.com/?bldetails=1

{
  "datescanned": 1485966334,
  "datechanged": 1485966334,
  "errors": 0,
  "status": 2,
  "domain": "example.com",
  "results": [
    [ "/page.php?id=5", 101, "JS.Eval.1",   0, "Abc=" ],
    [ "/js/script.js",  102, "JS.Trojan.2", 1, "Def=" ]
  ],
  "phishing_urls": [ "http://compromised-domain.com/bank.php" ],
  "blacklisted": {
    "Google Safebrowsing": {
      "detected": true,
      "result": "malicious site",
      "detail": "http://google.com/...",
      "unblock_url": "http://google.com/...",
      "unblock_email": "mail@example.com",
      "unblock_instructions": "Text..."
    }
  },
  "blacklistchecked": 1485966334,
  "blacklistscanned": 1485900000,
  "blacklistchanged": 1485966334
}

With &bldetails=1 the instructions on how to unblock the domain will be sent in response (if such info is known for the scanning engine):

The .blacklisted.*.unblock_instructions value will be localized depending on the value of the &lang request argument.

Re-scan single domain #

It is possible to start the scan process for any domain you want.

GET /forcelookup/<domain> ? [&bldetails[=int]] [&lang=str]

Response #

The response body is a JSON encoded object similar to described in section Lookup single domain.
Response contains the current information about this domain, scan process will run in background.
The results of the scheduled scan will be available in several minutes.
You can request the updated results using the Lookup single domain method later.

Example #

GET /forcelookup/example.com

{
  "datescanned": 0,
  "datechanged": 0,
  "errors": 0,
  "status": 0,
  "domain": "example.com",
  "results": [],
  "phishing_urls": []
  // blacklists fields....
}

Response contains results of previous scan. If domain wasn’t scanned before then the fields will contain empty values.
After this, the scan process of example.com will be run in the background immediatelly.

Get the scan results when the scan process completes:

GET /lookup/example.com

{
  "datescanned": 1485966334,
  "datechanged": 1485966334,
  "errors": 0,
  "status": 2,
  "domain": "example.com",
  "results": [
    [ "/page.php?id=5", 101, "JS.Eval.1",   0, "Abc=" ],
    [ "/js/script.js",  102, "JS.Trojan.2", 1, "Def=" ]
  ],
  "phishing_urls": [ "http://compromised-domain.com/bank.php" ]
  // blacklists fields....
}

Get recent changes #

You can get the changes history from virusdie’s database.
The service will show you the feed containing information about domains on which there were any changes after the time specified.

GET /feed/<time>

Response #

The response body contains the array of objects similar to described in section Lookup single domain.
The blacklists/phishing data will not be added to the response.
The list is ordered by the time of the last modification (datechanged field).
The size of this list is limited to 10000 items. So, you can request the next part by passing the datechanged value of the last item to /feed/ method again.

Example #

GET /feed/1485900000

[
  {
    "datescanned": 1485900011,
    "datechanged": 1485900011,
    "errors": 0,
    "status": 2,
    "domain": "example1.com",
    "results": [
      [ "/page.php?id=5", 101, "JS.Eval.1",   0, "Abc=" ],
      [ "/js/script.js",  102, "JS.Trojan.2", 1, "Def=" ]
    ]
  },
  {
    "datescanned": 1485900022,
    "datechanged": 1485900022,
    "errors": 0,
    "status": 0,
    "domain": "example2.com",
    "results": []
  },
  {
    "datescanned": 1485900033,
    "datechanged": 1485900033,
    "errors": 1,
    "status": 0,
    "domain": "example3.com",
    "results": []
  }
]

Example response description #