Passive DNS API

The Passive DNS API facilitates queriese into the Spamhaus Passive DNS database via HTTPS GET commands. Two parameters, and opitionally a third must be sent to the server to make a query.

Parameters

	*queryType - The type of query you are making
	*target - The record you are searching for
	*output (optional) - The format the response comes back in.

Supported queryType:

queryType Description
CHECK_QUOTA Query to find information regarding your quotas
IP Query an IP/CIDR for hostnames
HOSTDOM Query an IP/CIDR for domains
HOST Query a hostname for IP addresses
NS Query a nameserver for authoritative domains
DOMAIN Query a domain for authoritative nameservers
DOMSEARCH Query a domain for associated hosts
MXD Query a host/domain for its MX records
MX Query an MX target for all clients
CNAME Query canonical names for a host/domain
CHOST Query a host/domain for cname records

Supported output:

output= Description
CSV A pipe ("|") separated list (default)
JSON A series of JSON objects, one for each result
JOBJECT A singular JSON object

Example URL

To query the IP address 192.168.0.1, with the return format of CSV, create a url with “queryType=ip”, “target=192.168.0.1”, “output=csv”. https://pdnsapi.deteque.com/api/query?queryType=IP&target=192.168.0.1&output=csv

Note: The default output is CSV, so it will return as CSV without the output specified as well.

Example Curl Command

On the CLI a simple Curl command can be used to access the API using this syntax:

url --user <user>:<password> "https://pdnsapi.deteque.com/api/query? queryType=IP&target=192.168.0.1&output=csv"

Query Type CHECK_DATA

This query type shows how many queries your company has done for the day and month, as well as how many queries you are allowed in total for those time periods. This query type does not require the “target” parameter and only has the output in a JSON object format. This query will not be included in your daily/monthly query allowance.

Output:

{"User": "example", 
"CustomerID":
"11111111",
"DailyQueries": 7854,
"DailyQuota": 10000000,
"MonthlyQueries": 41582,
"MonthlyQuota": 100000000
}

Query Type IP

This query type is used to identify hosts seen on a given IP address or within a given subnet. The largest subnet queryable is a /16 for IPv4 or /32 for IPv6. All results will return the “last seen” instance for each host, sorted in alphabetical order by host. Additionally, the system will limit the number of records returned to 10,000.

Sample type IP queries would be:

	target=192.168.0.1 
	target=192.168.0.0/24 
	target=2606:100:a::1 
	target=2606:100:a::/48

Output - CSV:

192.168.0.1|example.com|1610192823

Output - JSON:

{"ip": "192.168.0.1", "host": "example.com", "ts": 1610192823}

Output - JOBJECT:

{
	"query": "192.168.0.1",
	"queryType": "ip", 
	"returned": 1,
	"query_time":
	0.005918, 
	"results": [
	{"ip": "192.168.0.1", "host": "example.com", "ts": 
	1610192823}
	]
}

Query Type HOST

This query type is used to identify IPs (IPv4 and IPv6) seen for a given host. All results will return the “last seen” instance for each host, sorted by IP. Additionally, the system will limit the number of records returned to 10,000.

Sample type HOST queries would be:

	target=example.com 
	target=www.example.com 

Output - CSV:

193.192.168.0.1|example.com|1610192823

Output - JSON:

{"ip": "192.168.0.1", "host": "example.com", "ts": 1610192823}

Output - JOBJECT:

{
	"query": "example.com",
	"queryType": "host", 
	"returned": 1,
	"query_time":
	0.017886, 
	"results": [
	{"host": "example.com", "ip": "192.168.0.1", "ts": 
	1610192823}
	]
}

Query Type DOMSEARCH

This query type is used to identify hosts found within a given domain. All results will return the “last seen” instance for each host, sorted by subdomain. Additionally, the system will limit the number of records returned to 10,000. Sample type DOMSEARCH queries would be: target=example.com Output - CSV: Sample type DOMSEARCH queries would be:

	target=example.com

Output - CSV:

example.com|192.168.0.1|1610192823

Output - JSON:

{"host": "example.com", "ip": "192.168.0.1", "ts": 1610192823}

Output - JOBJECT:


{
	"query": 
	"example.com", 
	"queryType":
	"domsearch", 
	"returned": 1,
	"query_time":
	0.037311, 
	"results": [
	{"host": "example.com", "ip": "192.168.0.1", "ts": 
	1610192823}
	]
}

Query Type DOMAIN

This query type is used to identify authoritative nameservers for a given domain. All results will return the “last seen” instance for each host, sorted by namesever. Additionally, the system will limit the number of records returned to 10,000. Sample type DOMAIN queries would be:

	target=example.com 

Output - CSV:

example.com|ns1.example.com|1610704457

Output - JSON:

{"domain": "example.com", "nameserver": "ns1.example.com", "ts": 
1610704457}

Output - JOBJECT:

{
	"query":
	"example.com", 
	"queryType": 
	"domain", 
	"returned": 1,
	"query_time":
	0.016380, 
	"results": [
	{"domain": "example.com", "nameserver": "ns1.example.com", 
	"ts":
	1610704457}
	]
}

Query Type NS

This query type is used to identify domains that a given nameserver is authoritative for. All results will return the “last seen” instance for each host, sorted by domain. Additionally, the system will limit the number of records returned to 10,000.

Sample type NS queries would be:

	target=ns1.example.com 

Output - CSV:

ns1.example.com|example.com|1610704457

Output - JSON:

{"nameserver": "ns1.example.com", "domain": "example.com", "ts": 
1610704457}

Output - JOBJECT:

{
	"query": "ns1.example.com",
	"queryType": "ns", 
	"returned": 1,
	"query_time":
	0.004636, 
	"results": [
	{"nameserver": "ns1.example.com", "domain": 
	"example.com", "ts":
	1610704457}
	]
}

Query Type MXD

This query type is used to identify MX records for a given domain/host. All results will return the “last seen” instance for each host, sorted by priority. Additionally, the system will limit the number of records returned to 10,000.

Sample type MXD queries would be:

target=example.com 

Output - CSV:

example.com|10 mail1.example.com|1610725173

Output - JSON:

{"mail_destination": "example.com", "mx": "10 mail1.example.com", 
"ts": 1610725173}

Output - JOBJECT:


{
	"query": "example.com",
	"queryType": "mxd", 
	"returned": 1,
	"query_time":
	0.006335, 
	"results": [
	{"mail_destination": "example.com", "mx": "10 
	mail1.example.com", "ts":
	1610725173}
	]
}

Query Type MX

This query type is used to identify hosts/domains for a given MX. All results will return the “last seen” instance for each host, sorted alphabetically by host. Additionally, the system will limit the number of records returned to 10,000.

Sample type MX queries would be:

target=mail1.example.com 

Output - CSV:

mail1.example.com|example.com|1610725173

Output - JSON:

{"mx": "mail1.example.com", "mail_destination": "example.com", "ts": 
1610725173}

Output - JOBJECT:

{
	"query":
	"mail1.example.com", 
	"queryType": "mx",
	"returned": 1,
	"query_time":
	0.027743, 
	"results": [
	{"mx": "mail1.example.com", "mail_destination": 
	"example.com", "ts":
	1610725173}
	]
}

Query Type CNAME

This query type is used to identify hosts for a given canonical name. All results will return the “last seen” instance for each host, sorted by host. Additionally, the system will limit the number of records returned to 10,000.

Sample type CNAME queries would be:

target=www.example.com 

Output - CSV:

www.example.com|example.com|1591595634

Output - JSON:

{"cname": "www.example.com", "host": "example.com", "ts": 1591595634}

Output - JOBJECT:

{
	"query": 
	"www.example.com",
	"queryType": "cname", 
	"returned": 1,
	"query_time":
	0.030969, 
	"results": [
	{"cname": "www.example.com", "host": "example.com", "ts":
	1591595634}
	]
}

Query Type CHOST

This query type is used to identify canonical names for a given host. All results will return the “last seen” instance for each host, sorted by CNAME. Additionally, the system will limit the number of records returned to 10,000.

Sample type CHOST queries would be:

target=example.com

Output - CSV:

example.com|www.example.com|1591595634

Output - JSON:

{"host": "example.com", "cname": "www.example.com", "ts": 1591595634}

Output - JOBJECT:

{
	"query": 
	"www.example.com",
	"queryType": "chost", 
	"returned": 1,
	"query_time":
	0.017571, 
	"results": [
	{"host": "example.com", "cname": "www.example.com", "ts":
	1591595634}
	]
}

Query Type HOSTDOM

This query type is used to identify domains for a given IP/CIDR. All results will be “deduped” and sorted by domain. Additionally, the system will limit the number of records returned to 10,000.

Sample type HOSTDOM queries would be:

target=192.168.0.1 

Output - CSV:

example.com 
example.edu 
example.net 
example.org

Output - JSON:

{"domain": "example.com"}
{"domain": "example.edu"}
{"domain": "example.net"}
{"domain": "example.org"}

Output - JOBJECT:

{
	"query": "192.168.0.1",
	"queryType":
	"hostdom", 
	"returned": 4,
	"query_time":
	0.003902, 
	"results": [
	"example.com", 
	"example.edu", 
	"example.net", 
	"example.org"
	]
}