Skip to content

Private API

Note

Are you looking to use the public PassiveDNS database API? Please see the simplified PassiveDNS Integration Guide for external users.

Tip

The OpenAPI Reference is always up-to-date and lets you try out any query with your user session or an API-key.

Introduction

Passive Domain Name System (PDNS) is a database consisting of domain names as used by different IPs. The PDNS service exposes three different endpoints that can be used to search on these records. These are described below. Each record is marked with a TLP, indicating the sensitivity of the record. Records with TLP white are publicly accessible.

Finally, there is an endpoint that can be used to submit PDNS records in bulk. This is described towards the bottom of this document.

DNS
Domain Name System
Passive DNS
DNS records that the PDNS service collects
TLP
Traffic Light Protocol
Submission
Refers to a DNS record submitted to the PDNS REST API

Simple query

To perform a simple PDNS query, use:

1
https://api.mnemonic.no/pdns/v3/<query>?parameters

where <query> is a DNS query or answer string to lookup, for example:

1
https://api.mnemonic.no/pdns/v3/cnn.com?rrType=a

Query parameters

There are multiple query parameters that can be passed along:

Parameter Possible values Default value Description
limit [0-maxint] 25 Limit the number of returned values.

The default value of 25 is set to avoid that a queried record with a huge result set is streamed back to the client unnecessarily.

A value of 0 means that the client explicitly requests an unlimited result set.

The result will return a 412 error code if the limit is set to be more than the server allows. This is 10 000 for authenticated users, while public use has its limit set to 1000.
offset [0-maxint] 0 Skip the initial offset number of values in the result set.

Together with the parameter limit, this allows a client to perform pagination of the results.
rrClass Any DNS record class any The most probable record class is in.

By default, this field is not filtered.
rrType Any DNS record type any The most used record classes are a, aaaa, ptr, cname and mx, but any supported DNS record name can be used here.

By default, this field is not filtered.

In addition, The following options are meaningful for use with private PDNS data:

Parameter Possible values Default value Description
customerID [0-maxint] <any> If the user is authenticated, and has access to private PDNS data, this filter can limit which customers to return data for.

Only records from customers the user has access to will be affected by this filter.

Public data from other customers are anonymous, and can be filtered out using the parameter includeAnonymous.
tlp white, green, amber, red <any> If set, limit the returned records by TLP.

For customers which the user does not have access to private data, only TLP white records will be returned.

If the user is not authenticated, then only TLP white records will be returned.
aggregate true, false true The PDNS service contains data from multiple customers, and PDNS records are stored per customer.

By default, any data returned by the service will be aggregated into one record per query/answer tuple.

If aggregate is set to false, the service will return each non-anonymous record separately.
includeAnonymous true, false true If true (default), any public data in the PDNS service will be included in the query results.

If set to false, only data from customers the user has access to will be included.

Result format

The result format is JSON, and consists of a result container, and a number of results. The results are sorted based on the lastSeenTimestamp in descending order.

The result container has the following format:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "responseCode": 200, # the response code. Normal responses should return HTTP code 200
    "count": 20,         # the total number of matching records. If this value is lower than the imposed limit, the result set is truncated!
    "limit": 25,         # the limit imposed on the query results (default is 25). Use the limit parameter in the request to set a higher limit.
    "offset": 0,         # the offset applied on the query results (default i 0)
    "currentPage": 1,    # the current "page" (calculated from limit/offset)
    "size": 20,          # the size of the current result set (should be same as count or limit)
    "data": [],          # the list of query result objects
    "messages": [],      # any server messages
    "metaData": {},      # any server metadata
}

Each query result has the following format:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "rrclass": "in",                      # the DNS record class
    "rrtype": "a",                        # the DNS record type
    "query": "cnn.com.",                  # the DNS record query part
    "answer": "157.166.255.19",           # the DNS record answer part
    "firstSeenTimestamp": 1340308340000,  # the first registered timestamp for this record 
    "lastSeenTimestamp": 1377520248000,   # the last registered timestamp for this record
    "maxTtl": 300,                        # the maximum TTL observed for this record
    "minTtl": 300,                        # the minimum TTL observed for this record
    "times": 675,                         # the number of times this record has been observed
    "tlp": "white",                       # the TLP of this record. Public records have TLP "white"
    "customer": null,                     # the customer owning this record. Public records have value null.
    "createdTimestamp": 0,                # always returns 0
    "lastUpdatedTimestamp": 0,            # always returns 0
}

Examples

Query Description
https://api.mnemonic.no/pdns/v3/cnn.com Query for any record concerning the domain cnn.com.

Includes both DNS records for queries for cnn.com and DNS records returning the value cnn.com.

Does not contain subdomains of cnn.com.
https://api.mnemonic.no/pdns/v3/cnn.com?limit=0 Query for any record concerning the domain cnn.com.

Return all results, no matter how big the resultset is.
https://api.mnemonic.no/pdns/v3/cnn.com?rrType=a Query for a records for the domain cnn.com.
https://api.mnemonic.no/pdns/v3/cnn.com?rrType=A&rrType=mx Query for a records and mx record for the domain cnn.com.
https://api.mnemonic.no/pdns/v3/157.166.255.19 Query for any record for the IPv4 address 157.166.255.19.
https://api.mnemonic.no/pdns/v3/2a04:4e42:400::323 Query for any record for the IPv6 address 2a04:4e42:400::323.

Output in COFF

The PDNS API also supports the PassiveDNS Common Output Format, as specified in https://datatracker.ietf.org/doc/draft-dulaunoy-dnsop-passive-dns-cof/

To retrieve results in the Common Output Format, please use the endpoint https://api.mnemonic.no/pdns/v3/cof/

The query input format is the same as for the simple query endpoint, as described above.

JSON query format

An alternative to a simple GET-string is a POST query with a JSON query format to the URL 

1
https://api.mnemonic.no/pdns/v3/search

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
curl -X POST https://api.mnemonic.no/pdns/v3/search -d '
{
  "query": "cnn.com",
  "rrClass": [
    "in"
  ],
  "rrType": [
    "a"
  ],
  "limit": 0,
  "offset": 0
}'

Note

The POST-query is currently permitting the same parameters as the GET query, but new future parameters or advanced/nested parameters may be added only to the JSON query format as an "advanced format".

Querying if a PDNS record has been seen

If you only need to know whether a record matches the search criteria, you can use the seen endpoint:

1
https://api.mnemonic.no/pdns/v3/<query>/seen?parameters

where "<query>" is a DNS query or answer string to lookup, for example.

1
curl https://api.mnemonic.no/pdns/v3/<query>/seen?ignoreOwnRecords=false

This endpoint will return a boolean, true or false, indicating whether a matching record exists.

Query parameters

There are multiple query parameters that can be passed along:

Parameter Possible values Default value Description
tlp white, green, amber, red white Only search in records matching any of the specified TLPs. Multiple values can be submitted.
ignoreOwnRecords true, false true Whether to ignore user's customer's own records, defaults to true.

Result format

The result format is JSON, and consists of a result container, and a number of results.

The result container has the following format

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "responseCode": 200, # the response code. Normal responses should return HTTP code 200
    "count": 0,          # will always be 0 for this endpoint
    "limit": 0,          # will always be 0 for this endpoint
    "offset": 0,         # the offset applied on the query results (default i 0)
    "size": 20,          # the size of the current result set (should be same as count or limit)
    "data": {            # the query result 
        "exists": false  # a boolean indicating whether any matching record(s) was found
    },
    "messages": [],      # any server messages
    "metaData": {},      # any server metadata
}

Authenticated queries

The PDNS API is publicly available, and does not require authentication.

However, unauthenticated queries are limited to see only public data (TLP white), and are limited to 1000 requests per day (currently).
To acquire higher resource limits, you need to perform authenticated queries.

To request an API key from mnemonic, contact mss@mnemonic.no.

To access private data (granted that mnemonic is collecting PDNS data from your customer), see the full PassiveDNS Integration Guide in the Argus API integration documentation.

If you have an API-key, you can a HTTP header to your request:

1
Argus-API-Key: 1234/1/abcd1234ef012

Example:

1
curl -H "Argus-API-Key: 1234/1/abcd1234ef012" -X GET https://api.mnemonic.no/pdns/v3/cnn.com

Resource limits

All users are subject to resource limitations.

  • Unauthenticated users are limited to 10 requests per minute, and 1000 requests per day.
  • Authenticated users are limited according to their agreement with mnemonic.

If you hit the resource limit, Argus will return a 402 error, with the following JSON response: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "responseCode": 402,
    "data": null,
    "messages": [
        {
            "message": "Resource limit exceeded",
            "messageTemplate": "resource.limit.exceeded",
            "type": "ACTION_ERROR"
        }
    ],
    "metaData": {
        "millisUntilResourcesAvailable": 558
    }
}

The resource limit is calculated both per minute and per day.

  • If you reach the per-minute (short-term) resource limit, you will typically be rejected for a short period, to save resources on our end.
  • If you reach the per-day (long-term) resource limit, you will typically be rejected for a period up to 24 hours. This means you have exhausted the data quota granted by mnemonic.

Tip

If you find yourself reaching the per-day resource limit a lot, you may want to request a higher resource quota from mnemonic

Note

Please use the metadata key millisUntilResourcesAvailable to let your client back off gracefully.

Submit PassiveDNS records in bulk operation

PassiveDNS records can be submitted to the collector by using the POST endpoint /record in the API and will accept a list of multiple records. The minimum information in these records are the fields query, answer, firstSeen, times, 'minTtl', maxTtl, tlp and recordType, or the request will be considered invalid. If not given the field recordClass defaults to IN, while lastSeen will be the submission time unless a timestamp is given.

If any of the records are invalid, the default behaviour is to fail the entire request and return the reasons why to the user. This can however be overwritten by using the field 'ignoreOnFailed', in which case the valid records are submitted while the invalid ones are ignored, though the response will contain a list of those that failed the validation and why.

It should also be noted that unless query or answer is written as IP addresses, they are expected to end with a period(.). If one is missing then the endpoint will add one before they are stored.

Below is a minimal request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/pdns/v3/record -d '{
 "records": [ 
    {
        "query": "192.168.10.15",
        "answer": "192.168.10.16",
        "firstSeen": 1576589261000,
        "times": 12,
        "minTtl": 1,
        "maxTtl": 2,
        "tlp": "white",
        "recordType": "aaaa"
    }
 ]
}'

Tip

1
                                                                                                                 |

You can check the OpenAPI Reference for a more detailed description of the endpoint and the values that can be used in the Json object.

Another request using strings for query and 'answer', and an ISP-8601 timestamp for firstSeen:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/pdns/v3/record -d '{
 "records": [
    {
        "query": "mnemonic.no",
        "answer": "not-mnemonic.no.",
        "firstSeen": "2016-11-30T15:47:00Z",
        "times": 12,
        "minTtl": 1,
        "maxTtl": 2,
        "tlp": "white",
        "recordType": "aaaa"
    }
 ]
}'

Tip

You can check the OpenAPI Reference for a more detailed description of the endpoint and the values that can be used in the Json object.