API Introduction

API endpoint:

https://api.zetascan.com/

The Zetascan Query Services "ZQS" was created to facilitate the real-time lookup of IP and Domain threat data into various applications and services. Currently there are dozens of various domain and IP data-feeds available to developers. Many of these feeds are available free of charge and some are paid for services when minimum query levels are exceeded. In addition, there are 2 main problems with trying to incorporate multiple data feed into a solution:

The overlap between data feed providers in the content listed (IPs & URIs), and
The absence of normalized meta-data related to the IPs or Domains.

Because of the above, many developers asked if we could do something to reduce the complexity related to accessing and using threat data as part of their applications - ZQS is our solution. We are introducing a more elegant API for developers, with an affordable pricing model to match.

To start, signup for a developer key and begin to integrate ZQS into your web-apps and mobile applications. A free-trial for 5,000 API queries is available for a 60-day period.

Developer library

To ease implementation Zetascan provides developer libraries in various languages. This provides a straightforward way to add ZQS support into your application.

Go library
- HTTP, text, JSON and JSONx support
- Support for DNS lookups
- Example code provided
PHP library
- HTTP, text, JSON and JSONx support
Python and NodeJS library, coming soon.

Authentication

Authentication to ZQS can be provided via an API key, or by specifying your servers' static IP address.

API key

curl https://api.zetascan.com/?key=YOURAPIKEY

<?
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.zetascan.com/?key=YOURAPIKEY');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);
?>

Make sure to replace YOURAPIKEY with your API key.

To query the ZQS an API key can be specified as an argument. No API key? Signup and receive a key instantly.

ZQS uses API keys to allow access to the service, and expects the API key to be included in all requests, if IP authentication is not provided.

IP authentication

Alternatively, authentication to ZQS can be allowed by providing your servers' IP address via the Zetascan dashboard.

Checking authentication

IP Address:
curl https://api.zetascan.com/v2/check/auth
API Key:
curl https://api.zetascan.com/v2/check/auth?key=YOURAPIKEY

We provide a simple method to check if your requests will be allowed from a given IP or with your API key. You'll get either 'Authorized' or 'Not Authorized'.

API Overview

Query formats

Query end-points include 4 formatting options:

https://api.zetascan.com/v2/check/http/

https://api.zetascan.com/v2/check/text/

https://api.zetascan.com/v2/check/json/

https://api.zetascan.com/v2/check/jsonx/

You can issue requests to our endpoints from virtually any operating system or programming language. REST queries are extremely fast and provide the richest set of information about an item.

Each client has a unique access key, generated by the system. You need to provide this key, if querying from an unregistered static IP address.

There are four types of REST queries:

HTTP - response is returned in HTTP headers
Text - clear text response (comma, semicolon and space delimitated)
JSON - JSON-formatted document
JSONx - JSON-formatted document with additional (eXtended) data about items.

The type of desired query is passed in the HTTP request. The version of the API is now v2. We are constantly adding new features to the API, and increase the API version number. You can use the latest version (recommended), or stick with a previous one.

DNS Queries are another fast and effective way to query ZQS. Using DNS TXT Queries you can get the same response as with a REST TEXT request.

Score calculation

ZQS provides two scoring mechanisms to grade an IP or domain-name for abuse, anti-spam measures and trustworthiness.

A negative score, like -0.1, means that an item was matched on a known trusted white-list.

If a score is 0, the item is not found within Zetascan and can be considered neutral.

A score between 0 - 1.0 is a rating on the specified domain or IP address. Scores above 0.35 should be considered as spam or fraudulent.

Reference the data sources chapter for more information on feeds used to calculate the scores. See the Scoring Factors section for exact values and logic used when generating item's score.

webscore

Webscore is returned by all query methods, except DNS A and AAAA queries. It is used to determine a score for integrating your web-application, mobile-app or protecting your application infrastructure.

score

Score is also returned by all query methods, and it used to check a specified IP or domain-name for anti-spam abuse via SMTP, useful for MTA and spam-filters. This score takes into consideration email abuse, and uses a different algorithm from the 'webscore' key.

Test Cases

IP Addresses

We provide four IPv4 and four IPv6 addresses, which will always return the same answers. Use these for testing and development:

127.9.9.1 - returning as if found in SBL, XBL & CBL
127.9.9.2 - returning as if in PBL
127.9.9.3 - returning as if in SBL subnet
127.9.9.4 - good IP, found in Return Path White List and DNSWL, also contains DNSWL White List data
::1, ::2, ::3, ::4 - returning as above for IPv6, except for ::2, which is found both in PBL and DNSWL (example of a false positive)

Domains

We provide two testing domains:

baddomain.org - returns as if found in all domain DB's: DBL and all URIBL
okdomain.org - returns as if found in White List(s).

Error handling

When querying ZQS, the following error-codes will be returned if the query or authentication failed. Each query format (Text, HTTP, JSON/JSONx) will embed any error messages in the returned data. Examples on handling errors will be provided for each query format example.

Error codes

1 - HTTP 404 - Invalid request - the REST path was wrong, e.g. /v2/check/gson/domain.com (gson instead of json). It appears in the message body and in the x-zetascan-error header. This is the only error that appears like that, others appears in the specified format as per the documentation.

2 - HTTP 404 - Missing IP/Domain argument

3 - HTTP 404 - Failed to parse query's item

4 - HTTP 403 - HTTPS required to supply API key

5 - HTTP 403 - Not authorized (request to invalid host, route, port or method, or API method not supported)

6 - HTTP 403 - Not authorized (request from invalid IP address or with invalid key)

7 - HTTP 403 - Wrong API Key supplied

8 - HTTP 404 - HTTP GET request required for queries

9 - HTTP 403 - Query limit exceeded

Data Sources

Currently we derive our results from several providers, including:

Spamhaus
Spamhaus real time stream - DBL, SBL and ZRD
URIBL - different levels of Domain Black Lists and a Domain White List
DNSWL - IP addresses White List
Return Path - IP addresses and Domains White Lists (black list coming soon)
Seclytics - Threat lists for IP addresses with categorization
Vade Secure - Domains black list

We also apply internal algorithms for de-duplicating, normalizing and scoring each item in our database, providing a seamless and reliable API end-point for your application.

ZQS queries are answered in less than 1 millisecond, and expect no longer then 10 milliseconds for a query reply.

All our sources are updated at very frequent intervals. We are also using real-time streams, so you may rest assured that you get the latest information from ZQS.

IP Addresses sources

We aggregate data from several data streams:

Spamhaus PBL
SBL
XBL
CBL
Spamhaus Real-time stream.
DNSWL IP addresses White List
Return Path IP addresses White List
Seclytics Black Lists

On the other hand, we have also information about White Lists presence of IP address, for example DNSWL.

Unlike other lists, ZQS analyzes the data about each IP address and provides normalized, de-duplicated, and pre-processed information about each IP address, containing internally calculated score (reputation), last modified timestamp, list of BL / WL where the item appears, etc.

Domains sources

At this stage we aggregate data from two main Domain providers:

Spamhaus DBL Black List
Real-time Spamhaus ZRD (Zero Reputation Domains) list
URIBL Black Lists
Vade Secure Black List
URIBL White List
Return Path White List

More providers will be added in the near future. Stay tuned!

HTTP Format

curl -i https://api.zetascan.com/v2/check/http/baddomain.org?key=YOURAPIKEY

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
x-zetascan-items: baddomain.org
x-zetascan-status: success
x-zetascan-score: 1
x-zetascan-sources: DBL;RED;GREY;GOLD;BLACK
x-zetascan-wl: null
x-zetascan-time: 1500970900
x-zetascan-webscore: 0.6
x-zetascan-fromParent: null

<?
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.zetascan.com/v2/check/http/baddomain.org?key=YOURAPIKEY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Request headers only
curl_setopt($ch, CURLOPT_HEADER, true); 
curl_setopt($ch, CURLOPT_NOBODY, true);

$response = curl_exec($ch);

// Lookup the HTTP status code
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Check status codes for a match
if($status == 204) {
    echo "No match in Zetascan blacklist or white-list";

} else if($status == 403)   {
    echo "Request forbidden, check API-key or IP registered";

} else if($status == 200) {

    $headers = array();    
    $data = explode("\n",$response);

    $headers['status'] = $data[0];

    // Take the HTTP response out, first element
    array_shift($data);

    // Build an array for our headers
    foreach($data as $part){
        $middle=explode(":",$part);
        $headers[trim($middle[0])] = trim($middle[1]);
    }

    // Display the score if blacklisted, otherwise if a whitelist
    if( $headers[x-zetascan-score] > 0 || $headers[x-zetascan-webscore] > 0)    {
        echo "Item blacklisted, score " . $headers[x-zetascan-score] . " webscore " . $headers[x-zetascan-webscore];
    } else {
        echo "Item white-listed";
    }
}
?>

HTTP returns a very simple response - found or not, via HTTP response code. If found, the response will be 200 (OK).

If the item is not present in any black-list/white-list, then the answer will be 204 (No Content).

Additional information about the item is found in the response headers.

Response headers

If the query matches, the following HTTP headers will be supplied for additional information.

Example HTTP header response:

x-zetascan-items:querydomain.org
x-zetascan-score:1
x-zetascan-webscore:0.6
x-zetascan-sources:DBL;RED;GREY;GOLD;BLACK
x-zetascan-time:1500970900
x-zetascan-wl:null
x-zetascan-status:success

HTTP Header	Description
x-zetascan-items	The argument used to query ZQS
x-zetascan-score	The score returned for the query, used for MTA and SMTP anti-spam measures
x-zetascan-webscore	The score returned for the query, used for Web and application anti-abuse. Note the differences between web-score and score, see the score calculation for more information.
x-zetascan-sources	A list of sources the query is obtained from, delimitated by a semicolon. See the source references for more information.
x-zetascan-time	EPOCH time of response for the query
x-zetascan-wl	A list of sources matched if the query is listed in a white-list.
x-zetascan-status	Returns "success", otherwise "forbidden" or "error"

Error handling

Example HTTP error response:

x-zetascan-errorCode:7
x-zetascan-errorMessage:Wrong API Key
x-zetascan-status:forbidden

HTTP Header	Description
x-zetascan-errorCode	The returned error-code. If present, the query has failed.
x-zetascan-errorMessage	A detailed explanation of the failure
x-zetascan-status	Returns "forbidden" if authentication denied, or "error" for all other error codes.

Multiple items

http://api.zetascan.com/v2/check/http/127.9.9.1,127.9.9.2

x-zetascan-items: 127.9.9.1,127.9.9.2
x-zetascan-status: success,success
x-zetascan-score: 0.95,0.2
x-zetascan-sources: XBL;SBL,PBL
x-zetascan-wl: null,null
x-zetascan-time: 1500970900,1500970900
x-zetascan-webscore: 0.6,null
x-zetascan-fromParent: null,null

You can send multiple items in a single request by sedning a comma-separated list of IP's or domains. This will speed up the overall time for answering your query.

The HTTP headers will contain a response for each query, as a comma-separated list in the same sequence as in the query.

Text Format

curl https://api.zetascan.com/v2/check/text/baddomain.org?key=YOURAPIKEY

<?
// Text method
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.zetascan.com/v2/check/text/baddomain.org?key=YOURAPIKEY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

// Lookup the HTTP status code
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Check status codes for a match
if($status == 204) {
    echo "No match in Zetascan blacklist or white-list";

} else if($status == 403)   {
    echo "Request forbidden, check API-key or IP registered";

} else if($status == 200) {

        // Read the body and split from the specified API formatting
        $head = explode(":", $response);

        if($head[0] == "error") {

            echo "An error occurred " . $head[1];

        } else {

            $str = explode(",", $head[1]);

            // $str will contain each field as specified below
            echo "Blacklist hit => " . $str[0] . "\n";
            echo "Whitelist hit => " . $str[1] . "\n";
            echo "Whitelist data => " . $str[2] . "\n";
            echo "Score => " . $str[3] . "\n";
            echo "WebScore => " . $str[4] . "\n";

            echo "Sources => ";

            // List all sources, comma separated
            for($i = 5; $i < count($str); $i++) {
                echo $str[$i] . ",";
            }

        }

}
?>

The above example returns text in the format:

baddomain.org:true,false,,1,0.6,dbl,red,gold,grey,black

TEXT returns space separated blocks of information about the lists where the item is found.

Text example - replace 'baddomain.com' with your query - IP or domain:

Format

Items are separated by space. The format for each item is:

item;parent:bool,bool,wldata,score,webscore,source

Where:

item or item;parent is the item from the request, or the item and its parent domain (see FQDN below).
the first bool is true, if found in any black or white list.
the second bool is true, if found in any white list.
wldata contains the data from the white list (if preent)
score, returns the score used for MTA/anti-spam abuse.
webscore, the returned score for web/application abuse.
sources, a comma-separated list of sources where the item was found.

Error handling

If an error occurs using the text query, the data returned will contain the item, the string 'error', an error message and a specific error-code.

Example authentication error:

127.9.9.1:error:Wrong_API_Key;7

Malformed query:

127.a.b.4:error:Failed_to_parse_query's_item;3

Multiple items

http://api.zetascan.com/v2/check/text/127.9.9.1,127.9.9.2

127.9.9.1:true,false,,0.95,0.6,xbl,sbl 127.9.9.2:true,false,,0.2,0,pbl

You can send multiple items in a comma-separated list of IP's or domains. This will speed up the overall time for answering your query.

The text format will contain a response for each query, delimited by space.

JSON Format

curl https://api.zetascan.com/v2/check/json/baddomain.org?key= YOURAPIKEY

<?
// PHP example with multi-query support, error checking, and JSON data presented
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.zetascan.com/v2/check/json/baddomain.org,okdomain.org,badquery?key=YOURAPIKEY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

// Lookup the HTTP status code
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Check status codes for a match
if($status == 403)   {
    echo "Request forbidden, check API-key or IP registered";

} else if($status == 200) {

    $json = json_decode($response, true);

    // Check for any error messages, auth failure, API-key incorrect, etc.
    if( !empty($json["error"]["message"])) {
        echo "An error occurred " . $json["error"]["message"];
    } 

    // Loop through each response ( multiple queries can be delimitated by a comma)
    for($i = 0; $i < count($json["results"]); $i++) {

        echo "Query => " . $json["results"][$i]["item"] . "\n";

        // Check for an error message
        if($json["results"][$i]["error"]) {
            echo "An error occurred " . $json["results"][$i]["error"]["message"] . "\n";
            continue;
        }

        // Display the results
        print_r($json["results"][$i]);

    }

}
?>

Example JSON return string:

{
    "results":[{
        "item":"baddomain.org",
        "found":true,
        "score":1,
        "webscore":0.6,
        "fromSubnet":false,
        "sources":
            ["shDBL","ubGrey","ubGold","ubRed","ubBlack"],
        "wl":false,
        "wldata":"",
        "lastModified":1500972200
        }],
    "executionTime":2,
    "status":"success"
}

The query will return a JSON response including if the item is found on a black-list/white-list, score, sources, etc. Refer to the table below for each field explanation.

JSON response

Parameter	Description
Item	Query value (IP or domain)
Found	True/False if matched in a white-list/black-list.
Score	Score between a negative decimal number like -0.2 to 1.0 for MTA/Anti-spam abuse. See score information
WebScore	Score between a negative decimal number to 1.0 for Web/application abuse.
FromSubnet	Will be true, if the IP address was found in a subnet (PBL, SBL)
Sources	Black-Lists matched from ZQS. See list information.
Wl	If the item matches a white-list.
Wldata	White-Lists matched from ZQS. See list information.
ExecutionTime	Time in ms for server response
Status	Success or failure

Error handling

Example authentication error:

{"error":{"message":"Wrong API Key","errorCode":7}}

Malformed query:

{"results":
    [{"item":"malformedquery",
      "error":{
        "message":"Failed to parse query's item",
        "errorCode":3
        }
    }],
    ...
}

If an error occurred, the JSON response will return an errorCode, message and status within the JSON object.

It is highly recommended to test against the specified error-codes during implementation. Reference the error handling section for more information.

Multiple items

http://api.zetascan.com/v2/check/json/127.9.9.1,127.9.9.2

{"results":
    [{
    "item":"127.9.9.1",
    ...
    },{
    "item":"127.9.9.2",
    ...
    }],
"executionTime":1,
"status":"success"
}

You can send multiple items in a single request by passing comma-separated list of IP's or domains. This will speed up the overall time for answering your query.

The JSON format, will contain a response for each query within the results array.

JSONx Format

curl https://api.zetascan.com/v2/check/jsonx/baddomain.org?key=yourkeygoeshere

<?
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.zetascan.com/v2/check/jsonx/127.9.9.1?key=YOURAPIKEY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

// Lookup the HTTP status code
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Check status codes for a match
if($status == 403)   {
    echo "Request forbidden, check API-key or IP registered";

} else if($status == 200) {

    $json = json_decode($response, true);

    // Display the array
    print_r($json);

    // Display extended information
    print_r($json["results"][0]["extended"]);

}
?>

JSONx will return also a JSON document, extended with additional information about the last known activity of an fraudulent IP address. The JSONx format only supports IP addresses and not domain queries.

JSONx response

Responses include additional information about an IP address with fraudulent activity.
This information is found in the 'extended' and 'extendedSecl' fields.
The 'extended' element contains data from Spamhaus,
while 'extededSecl' contains information from Seclytics.

"extended": {
      "ASNum": "23969",
      "route": "1.0.200.0/24",
      "country": "AU",
      "domain": "veridas.net",
      "state": "",
      "time": "1486447729",

      "reason": {
        "class": "BOT",
        "rule": "9904",
        "type": "sinkhole"
        "name": "conficker",
        "source": "104.244.14.252",
        "port": "80",
        "sourceport": "23915",
        "destination": "1"
      },
      "emailslastday":"123"
    },

    "extendedSecl":[
        {"
        cidr":"62.196.0.0/16",
        "asn":3302,
        "first_seen":"2017-01-17",
        "last_seen":"2017-10-23",
        "categories":["scanner","spam"]
        }
    ]

Extended element

Parameter	Description
ASNum	The autonomous system number of the ISP;
route	The address of the network / subnet from which the activity originated;
country	The location of the above network;
domain	The associated domain with the ip address;
state	Display the state (if available);
time	The last registered activity timestamp in unix epoch format;
emailsdaily	Contains the number of detected spam emails in the last 24 hours;

In addition, the reason object contains additional detection information about the queried IP. Results include:

Bot
Sinkhole
Web-Server Compromises
Web-Server Attacks
Miscellaneous
Unknown

Details for each response is provided below:

Bot

JSONX provides extended information to protect your web-site or mobile application, especially for user signup forms, login and integrations to your application.

JSONX returns a BOT class, which represents one of the following 5 types:

Sinkhole

{"class":"BOT", "rule":"9091", "type":"sinkhole", "name":"marcher", "source":"216.218.185.162", "port":"80", "sourceport":"n/a", "destination":"onoven.com"}

Parameter	Description
Rule	The detection rule ID
Type	Sinkhole
Source	Source IP
Port	Source Port

Web-Server Compromises

{"class":"BOT", "rule":"20062", "type":"spamlink", "domain":"www.thefashionic.com", "source":"1.53.132.24", "name":"gamut", "link":"https://www.thefashionic.com/wp-content/themes/thevoux-wp/f3ebf56b6f.html", "redirect":"https://targetsale.name"}

Parameter	Description
Rule	The detection rule ID
Type	Spamlink
Domain	Spam domain
Source	Source IP
Link	Typed link, e.g. as it appears to user
Redirect	Real link destination

Web-Server Attacks

{"class":"BOT", "rule":"9051", "type":"web server attack", "name":"commentspammer"}

Parameter	Description
Rule	The detection rule ID
Type	Web Server Attack
Name	Extended Information

Miscellaneous

In this case, attempted user and password are also listed. Note that these fields are not always present.

{"class":"BOT", "rule":"9803", "type":"miscellaneous", "name":"iotwopbot", "user":"root", "password":"anko", "port":"5358", "source":"198.133.159.133", "sourceport":"53234", "domain":"-"}

Parameter	Description
Rule	The detection rule ID
Type	Miscellaneous
Name	Attack name
User	Attempted username login
Pass	Attempted password
Port	Port address
Source	Source IP
SourcePort	Source Port address
Domain	Domain specified

Unknown

{"class":"BOT", "rule":"3013", "type":"unknown", "name":"unknown3013", "halo":"pharmaccccyyy.ca"}

Parameter	Description
Rule	The detection rule ID
Type	Unknown
Name	Attack name
Halo	SMTP Halo specified

Extended - SMTP

If using ZQS for MTA/SMTP security, JSONx provides extended information that can assist with spam detection and email security for end-user mailboxes. Check the class key in the reason sub-object.

LOC

{"class":"LOC", "type":"helos as destination server"}

Parameter	Description
LOC	SMTP "helos" as destination server

MPD

{"class":"MPD", "type":"helos as multiple unrelated domains", "heloscount":"16", "domainscount":"16", "domains":["daycoonline.net", "e-apollo.lv", "exitprofit.com", "flammhotclicks.com", "ftc-i.net", "happyhumans.com", "hctc.net", "heronaerospace.com", "hi.nl", "hot.dog.cx", "i-love-cats.com", "investonline.biz", "kafen.com"]}

Parameter	Description
MPD	helos as multiple unrelated domains
heloscount	Number of unique HELO attempts
domainscount	Number of unique domains on HELO attempts
domains	JSON array for the domains used for HELO attempts

Never

{"class":"NEVER", "type":"forged helos", "halo":"hotmail.com"}

Parameter	Description
NEVER	Usually forged helos

Misc

{"class":"MISC", "type":"specific broken helos", "halo":"device.lan"}

Parameter	Description
MISC	Usually specific broken helos

Bogus

{"class":"BOGUS", "type":"multiple illegal helos", "halos":["impedibilityz","recanterp","stanchedb"]}

Parameter	Description
BOGUS	Multiple illegal helos
Halos	JSON array of malformed domains that do not comply with RFC822

BSIP

{"class":"BSIP", "type":"illegal helo as IP", "halo":"109.242.179.132"}

Parameter	Description
BSIP	Illegal helo`ing as IP
Halo	Malformed IP address used to HELO

SSIP

{"class":"SSIP", "type":"illegal helo as own IP", "halo":"120.215.192.35"}

Parameter	Description
SSIP	Illegal helo`ing as own IP
Halo	Source IP address

LH

{"class":"SSIP", "type":"illegal helo as own IP", "halo":"120.215.192.35"}

Parameter	Description
* LH	Variations on localhost

FAM

{"class":"FAM", "type":"helos as someone we know they`re not", "rdns":"ppp-93-104-64-20.dynamic.mnet-online.de", "halo":"striker.ottawa.on.ca"}

Parameter	Description
FAM	Helos as someone we know they're not
rdns	Reverse dns of the offending IP

NOHELO

{"class":"NOHELO"}

Parameter	Description
NOHELO	Missing Helo

HELI

{"class":"HELI", "type":"special category", "halo":"test654.com"}

Parameter	Description
HELO	Special category for development purposes.

ExtendedSecl element

This element contails information about the category of the threat, its IP address, ASN and CIDR, when it was first detected and when was the last activity from this IP address. The possible categories are:

Parameter	Description
unknown	Unknown category
malware, malicious, ransomware	Varius malicious software, viruses, ransomware
ddos, bot, botnet	Botnets
phishing, defacement	Phishing, defaced web sites
spam, backscatter	Known spam sources
scanner	Port scanner
proxy, tor_list, tor	Anonymous proxies
dyndns
suspicious	Suspicious activity

Error handling

Error handling for the JSONx query type is the same as the JSON error handling section.

Multiple items

JSONx support multiple items for a single query, and matches the JSON multiple-item format.

FQDN Queries

test.baddomain.org;baddomain.org:true,false,,1,0.6,dbl,red,gold,grey,black

{"results":[{"item":"test.baddomain.org","found":true,"score":1,"webscore":0.6,"fromSubnet":false,"sources":["shDBL","ubGrey","ubGold","ubRed","ubBlack"],
"wl":false,"wldata":"","lastModified":1500970900,"fromParent":"baddomain.org"}],"executionTime":1,"status":"success"}

x-zetascan-fromParent: baddomain.org
x-zetascan-items: test.baddomain.org

We now support sub-domains (FQDN queries). Some BL’s and White Lists have sub-domains listed. If the item is not a direct hit, we will check the parent domain. For example:

https://api.zetascan.com/v2/check/{json/jsonx/http/text}/test.baddomain.org

Check the fromParent key with JSON / JSONx, the x-zetascan-fromParent header with HTTP and the item part in a TEXT query, where the parent will appear separated by semicolon.

DNSWL data format

The White List data can have two formats:

"wldata":"1004" or "wldata":"med;domain.com;id". 1004 is a special case of so-called auto-promoted IP addresses. Their reputation is based on automatic detection.

The second format has 3 parts: ranking, domain and ID.

Ranking can be low, med or high;
Domain is the registered DNS name of the IP address owner;
ID can be used to find out more information about the organization at https://www.dnswl.org/s/?s=ID

"wldata" field will have empty string or may be missing, if "wl" is false.

Browser access

Alternatively, you can test the ZQS using your web-browser. This should be used for test purposes only.

Point your browser to https://zetascan.com/query
Enter one or more IP addresses or domain names;

The service will return list of results with details on where the items were found, query time, and calculated score.

Note: a 5 second delay is applied to all anonymous user queries. Please register for an API key to remove this delay.

Alternatively, you can issue a query to our API directly from the browser address bar by entring the query REST URL:

https://api.zetascan.com/v2/check/text/baddomain.org?key=YOURAPIKEY

You can then use Developers Tools (usually F12) in your browser to examine the result.

DNS API

ZQS provides an rbldns service that combines the information from all the sources we aggregate.

Multiple query formats are supported, with DNS type records A (ipv4), AAAA (ipv6) and TXT returned.

Lookup access

ZQS provides lookup access for a domain or IP address against the *.{APIKEY}.api.zetascan.com FQDN.

This end-point can be used by MTA/SMTP software such as Exim, Postfix, Sendmail and more, for Anti-spam lookups and abuse prevention. Zetascan is a drop-in replacement for existing RBL services to provide a seamless anti-spam service.

Domain query

Domain query:

 dig A baddomain.org.{key}.api.zetascan.com

 IPv4 query (213.189.1.4), note the IP must be reversed:

dig TXT 4.1.189.213.{key}.api.zetascan.com

IPv6 query, note the IP must be reversed and expanded:

 dig AAAA 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.c.b.a.9.8.7.6.5.4.3.2.1.{key}.api.zetascan.com

Direct access

Alternatively, you can query api.zetascan.com directly as a nameserver and retrieve results. Your IP address must be specified within the Zetascan dashboard for access to be granted.

Domain query:

dig A @api.zetascan.com baddomain.org

IPv4 query, note, IP is not reverse formatted.

dig TXT @api.zetascan.com 127.9.9.4

IPv6 query:

dig AAAA @api.zetascan.com ::1

PTR IPv4 query (used for reverse IP lookups):

dig PTR @api.zetascan.com PTR 1.9.9.127.in-addr.arpa.

PTR IPv6 query (used for reverse IP lookups):

dig PTR @api.zetascan.com 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.c.b.a.9.8.7.6.5.4.3.2.1.ip6.arpa

DNS Response codes

When querying ZQS via DNS two formatting options are returned, TXT or (A, AAAA, PTR)

TXT format

When querying for the DNS TXT type, if the domain/IP is matched, extended information will be returned for the query.

Query:

dig +short TXT @api.zetascan.com 127.9.9.4

Returned response:

"127.9.9.4:true,true,10;med;zetascan.com;99999,-0.1,-0.1,dnswl"

The response will be the same format as the REST TEXT Query.

The format for each item is:

item;parent:bool,bool,wldata,score,webscore,sources

Where:

item or item;parent is the item from the request, or the item and its parent domain (see FQDN).
the first bool is true, if found in any black list.
the second bool is true, if found in any white list.
wldata contains the data from the white list (if present)
score, returns the score used for MTA/anti-spam abuse.
webscore, the returned score for web/application abuse.
sources, a comma separated list of which lists the query was matched on.

A, AAAA, PTR format

When querying via DNS using the A, AAAA, or PTR record types, the following IP addresses will be returned, indicating a match on a specified black-list/white-list and extended reasons. Querying with AAAA will return the IPv6 equivalent of the IPv4 responses described below. See IPv6 Responses.

Sample dig syntax:

dig +short 4.9.9.127.{APIKEY}.api.zetascan.com A

Returned data:

127.8.10.3

The IP returned in the 127.X.X.X format is based on the real-time blacklist RBL syntax, pioneered by anti-spam and MTA software.

Values for each response type listed below:

127.0.0.x - Spamhaus IP lists

Parameter	Description
127.0.0.10	PBL (Public/residential) IP addresses, reported by ISP
127.0.0.11	PBL detected by Spamhaus
127.0.0.4	XBL Illegal 3rd party exploits, including proxies, worms and trojan exploits
127.0.0.2	SBL Spamhaus SBL Data
127.0.0.3	SBL Spamhaus SBL CSS Data
127.0.0.9	SBL Spamhaus DROP/EDROP Data

127.0.1.x - Spamhaus Domain Lists

Parameter	Description
127.0.1.2	spam domain
127.0.1.4	phish domain
127.0.1.5	malware domain
127.0.1.6	botnet C&C domain
127.0.1.102	abused legit spam
127.0.1.103	abused spammed redirector domain
127.0.1.104	abused legit phish
127.0.1.105	abused legit malware
127.0.1.106	abused legit botnet C&C
127.0.1.200	Zero reputation domains

127.1.0.x - URIBL Domain lists

Parameter	Description
127.1.0.1	Black
127.1.0.2	Gold
127.1.0.3	Grey
127.1.0.4	Red
127.1.0.5	White - a Domain White List from URIBL

127.3.0.1 - Return Path White Lists (Domain or IP)

127.8.0.x - DNSWL (IP White List)

Parameter	Description
127.8.x.1	None, auto-discovered
127.8.x.2	Low ranking
127.8.x.3	Medium ranking
127.8.x.4	High ranking

Where the third digit (x) means the type of industry:

Parameter	Description
2	Financial services
3	Email Service Providers
4	Organizations (both for-profit [i.e. companies] and non-profit)
5	Service/network providers
6	Personal/private servers
7	Travel/leisure industry
8	Public sector/governments
9	Media and Tech companies
10	Some special cases
11	Education, academic
12	Healthcare
13	Manufacturing/Industrial
14	Retail/Wholesale/Services
15	Email Marketing Providers
20	Added through Self Service without specific category

127.2.0.x - Seclytics Black Lists

Where the last digit (x) means the category of the threat:

Parameter	Description
0	unknown
1	malware
2	botnet
3	phishing
4	malicious
5	spam
6	scanner
7	proxy
8	ddos
9	bot
10	ransomware
11	dyndns
12	defacement
13	tor_list
14	backscatter
15	suspicious
16	tor

IPv6 Responses

Each of the above responses can be returned as IPv6 address, if you issue AAAA DNS query, in the following format:

The 127 octet is replaced by 2002 hextet.
The last three hextets are equal to the last three octets in the IPv4 format.
The rest of the hextets are zeros.
For example: Seclytics malicious code 127.2.0.4 becomes 2002::0002:0000:0004

Scoring factors

Providers

Spamhaus

Source	Score (SPAM)	Web Score
SBL	0.4	0.2
DBL	0.45	0.1
XBL	0.4	0.1
PBL	0.2	0
CBL Web Attacks	0.2	0.3
CBL Web Server Compromises	0.2	0.2
CBL Sinkhole	0.2	0.1
CBL Others	0.2	0.05
ZRD	0.25	0.25
BOTNET	1	1
DROP	1	1

URIBL

Source	Score (SPAM)	Web Score
Black	0.3	0.2
Gold	0.15	0.1
Red	0.1	0.1
Gray	0.05	0.05
White	-0.1	-0.1

Seclytics

Source	Score (SPAM)	Web Score
malware	0.9	0.9
botnet	0.7	0.7
phishing	0.5	0.5
malicious	0.6	0.6
spam	0.4	0.3
scanner	0.2	0.2
proxy	0.3	0.3
ddos	0.8	0.8
bot	0.3	0.4
ransomware	0.7	0.7
dyndns	0.2	0.2
defacement	0.3	0.3
tor_list	0.3	0.4
backscatter	0.4	0.2
suspicious	0.1	0.1
tor	0.3	0.4
unknown	0.1	0.1

Vade Secure

Source	Score (SPAM)	Web Score
Domains BL	0.8	0.4
IP BL	0.85	0.45

DNSWL

Source	Score (SPAM)	Web Score
IP WL	-0.1	-0.1

Return Path - White List

Source	Score (SPAM)	Web Score
IP WL	-0.1	-0.1
Domains WL	-0.1	-0.1

Multiple matches

If an item is found in more than one source, a score of 0.05 is added to the total calculated as per the tables above. For example, an item found in Spamhaus' SBL and PBL, and Seclytics' Suspicious category, will have score of 0.8 (0.4 + 0.1 + 0.2 + (2x0.05)) This is also true for White Lists, so an item found in two White Lists will have a score of -0.25.

Propagation

In the upcoming release we will provide a Propagation score, measuring the speed of detection of new threats, based on internal information we have and rate of updates and queries for a given item.

Code snippets

Python

from requests import Session
session = Session()
session.head('https://api.zetascan.com/v2/check/json/127.9.9.1?key=yourkeygoeshere')
response = session.get(
  url='https://api.zetascan.com/v2/check/json/127.9.9.1?key=yourkeygoeshere'
)
print(response.text)

Node.js

var request = require('request');
var options = {
  url: 'https://api.zetascan.com/v2/check/json/127.9.9.1?key=yourkeygoeshere',
  json: true
};

request(options, function(error, response, body) {
  console.log(body);
});

Javascript

jQuery(document).ready(function($) {
  $.ajax({
    type: 'GET',
    url: 'https://api.zetascan.com/v2/check/json/127.9.9.1?key=yourkeygoeshere',
    dataType: 'JSON',
    success: function(response) {
      console.log(response);
    },
    error: function(xhr, status, error) {
      console.log(error.toString());
    }
  });
});