Returns a total count of logged DNS queries for a given siteName. You can use optional filters, such as record key (search for records older or newer than the specified key), start time, and end time.
GET https://api-<BlueCat.edge.url>/v3/api/dnsQueryLogs?siteId={siteId}&batchSize={size}&key={key}
&order={DESC | ASC}&startTime={utc}&endTime={utc}&hasMatchedPolicy=
{true|false}&sourceIp={sourceIp1, sourceIp2}&queryType={queryRecordType}&
queryName={queryDomainName}&policyAction={policyAction1, policyAction2}&policyType=
{policyType}&policyId={policyId}&threatType={threatType}&threatIndicator=
{threatIndicator}&responseCode={responseCode1, responseCode2}&protocol={queryProtocol1,
queryProtocol2}&namespaceId={namespaceId1, namespaceId2}&latencyFrom={latencyFrom}&latencyTo=
{latencyTo}&responseIp={responseIp1, responseIp2}
Authorization: Bearer tokenParameters
| Name | Description | Type | Required |
| siteId | The ID of the site for which you want to query logs. If no site ID is provided, an error is returned. If there is no site with that ID, an empty list is returned. | List of strings | Optional |
| batchSize | The maximum number of records to return. If this isn't included, the
response will be limited to 400 entries. Note: The maximum configurable
batchSize is 10000.
|
String | Optional |
| key | The key is the record ID of the DNS Query Log record for which you want to receive older or newer records. | String | Optional |
| order | Specify whether to retrieve results in DESC (most recent records first) or ASC (oldest records first) order. If this isn't included, the records will be listed in descending order. | String | Optional |
| startTime | To filter results for a specific time period, including the start time, in milliseconds since the Unix Epoch. | String | Optional |
| endTime | To filter results for a specific time period, in milliseconds since the Unix Epoch. The filter results will only include DNS queries with a timestamp leess than the endTime value. | String | Optional |
| hasMatchedPolicy | If hasMatchedPolicy is true then only DNS queries matching policies will be displayed. | String | Optional |
| sourceIp | Filters results for the specified source IP address(es). | List of strings | Optional |
| queryType | The query record type you want to search for. | List of strings | Optional |
| queryName | The domain name you want to search for queries on. | List of strings | Optional |
| policyAction | If one or more policy actions are provided, then only policies matching the actions are returned. Valid actions are allow, block, redirect, and monitor. | List of strings | Optional |
| policyName | If a policy name is provided, then only policies matching the name are returned. | List of strings | Optional |
| policyId | If a policy ID is provided, then only policies matching the ID are returned. | List of strings | Optional |
| threatType | Returns queries that match the specified threat type. Valid threat types are DGA and DNS_TUNNELING. | List of strings | Optional |
| threatIndicator | Returns queries that match the specified threat indicator. Valid threat indicators are ENTROPY, UNIQUE_CHARACTER, EXCEEDING_LENGTH, UNCOMMON_QUERY_TYPE, VOLUMETRIC_TUNNELING, SUSPECT_DNS, and SUSPECT_TLD. | List of strings | Optional |
| responseCode | Returns DNS queries that match the specified response codes. | List of strings | Optional |
| protocol | Returns DNS queries that match the specified protocol (usually UDP or TCP). | List of strings | Optional |
| namespaceId | Returns DNS queries that were queried against the specified namespace IDs. | List of strings | Optional |
| latencyFrom | Returns DNS queries with latencies greater than or equal to this value (in milliseconds). | String | Optional |
| latencyTo | Returns DNS queries with latencies less than or equal to this value (in milliseconds). | String | Optional |
| responseIp | Returns the DNS events resolving to either of the specified IPv4 and/or IPv6 address(es). Must be valid IPv4 or IPv6 address(es). | List of Strings | Optional |
Successful response
200 OK
Content-Type: application/JSON
[
{
"time": 1588863296043,
"source": "197.210.227.230",
"siteId": "91d9e73b-c5ce-4f92-a419-5d421e8fef25",
"query": "VERSION.BIND.",
"queryType": "TXT",
"actionTaken": "query-response",
"response": "NOERROR",
"id": "1588863296043BF913F410812953C6909E622C4702754",
"matchedPolicies": [],
"answers": [
{
"domainName": "VERSION.BIND.",
"recordType": "TXT",
"parsed": true,
"rData": "1.0.0"
}
],
"authority": [],
"queryProtocol": "UDP",
"threats": [],
"queriedNamespaces": [
{
"id": "9bba84cc-00eb-4a6a-985b-b9cadb9de93a",
"name": "Umbrella",
"rCode": "NOERROR",
"responseData": null,
"latency": 0,
"cycle": 0
},
....
],
"latency": 2,
"queryId": 18157,
"queryClassId": 1,
"queryEdnsOptions": [
{
"code": 8,
"value": "2600:1f18:1321:3900::/64/0"
}
],
"responseEdnsOptions": [
{
"code": 8,
"value": "2600:1f18:1321:3900::/64/0"
}
],
"identity":
{
"identityId": "identity_id_example",
"userId": "example@test.bluecat.com"
},
"appliedPolicyId": null,
"redirectDomain": null
}
Returns the following information:
- Time: Unix time (in milliseconds) when the DNS query was made. (This is the request time, not the response time or logging time.)
- Source: The IP address of the client making the DNS query.
- Site: The site name of the service point handling the query.
- Query: The domain name being queried.
- Query Type: The query type.
- Response: The response code (for example NXDOMAIN, NOERROR or SERVFAIL).
- ID: An identifier that can be passed to key in subsequent requests (used for paging through lots of data)
- Action Taken: If no policy was matched, this will be "query-response", otherwise this will be either block,redirect, or monitor
- Matched Policies: List of policy IDs and names that matched the given query
The number of entries in the list depends on the number of queries within specified period. The list returned may be empty.
- Authority: The authority assigned to the DNS query.
- Query Protocol: The protocol of the DNS query (usually UDP or TCP).
- Threats: The list of possible threats detected during the query analysis.
- Queried Namespaces: The list of namespaces the DNS query was queried against. This includes the ID of the namespace, name of the namespace, the response code that was returned, the rdata of the response, and the latency of the response.
- Latency: The latency (in milliseconds) of the DNS query.
- Query ID: The query ID.
- Query Class ID: The ID of the DNS record class.
- Query EDNS Options: A list of EDNS query options returned. Currently, only EDNS Client Subnet (ECS) query option information is returned.
- Response EDNS Options: A list of EDNS response options returned. Currently, only EDNS Client Subnet (ECS) response option information is returned.
- Identity: Contains information about the user that initiated the query. This information is only available if you have the identity service enabled and the Add identity information to queries option enabled on the site.
- Applied Policy ID: The policy that took action on the query.
- Redirect Domain: The domain that the query was redirected to.
Response on unsuccessful authorization
401 Unauthorized
Content-Type: application/JSON
{"code": "UNAUTHORIZED", "brief": "You are not authorized to perform this action"}Possible error codes
- INPUT_ERROR
- ANALYTICS_UNEXPECTED_ERROR