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