Passive DNS API

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

Authentication

Authentication is done using Basic Authentication.

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

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
TXT	Query a host/domain for TXT records
NEW_DOMAIN	Query a domain for the first time it was seen

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 Output 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.

Optional Query Limit

The default query limit is 100,000 records. If the “query_limit” parameter is set the maximum number of records can be changed to lower the volume. A higher query limit cannot be used.

Example Query Limit URL

https://pdnsapi.deteque.com/api/query?queryType=IP&target=192.168.0.1&query_limit=1000

Query Type CHECK_QUOTA

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:

{
  "account": {
    "sub": "3534543",
    "usr": "[email protected]"
  },
  "limits": {
    "qpm": 25000,
    "qpd": 2500,
    "rl_qph": 50000,
    "rl_qpm": 2000,
    "rl_qps": 500
  },
  "current": {
    "qpm": 18,
    "qpd": 1,
    "rl_qph": 0,
    "rl_qpm": 0,
    "rl_qps": 0
  }
}

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 TXT

This query type is used to identify TXT records for a given host/domain. All results will return the “last seen” instance for each host, sorted by TXT record. Due to the freeform nature of TXT records we recommend not using the CSV output for this querytype.

Sample type TXT queries would be:

target=example.com

Output - CSV:

example.com|1685480276|v=spf1 -all

Output - JSON:

{"qname": "example.com", "txt": "v=spf1 -all", "ts": 1685480276}

Output - JOBJECT:

{
	"query": "example.com",
	"queryType": "txt",
	"returned": 1,
	"query_time": 0.003830,
	"results": [
		{"qname": "example.com", "txt": "v=spf1 -all", "ts": 1685480276},
	]
}

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.

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"
	]
}

Query Type NEW_DOMAIN

This query type is used to identify the first time a domain was seen. Only one result will be returned by this query type, which will show the the “first seen” timestamp of the domain and the domain.

Sample type NEW_DOMAIN queries would be:

target=example.com

Output - CSV:

1580527716|example.com

Output - JSON:

{"domain": "example.com", "ts": 1580527716}

Output - JOBJECT:

{
	"query": "example.com",
	"queryType": "new_domain",
	"returned": 1,
	"query_time": 0.005122,
	"results": [
		{"domain": "example.com", "ts": 1580527716}
	]
}