The DNS Filtering module limits the number of domain-based threats in your environment by allowing and blocking access across the network. Each time this occurs, a record is generated. Use these APIs to export the DNS activity and search through the logs.
openapi: 3.2.0
info:
title: ThreatDown DNS Logs API
description: '# Introduction
ThreatDown Nebula API lets you remotely manage the security of your `Endpoints`, analyze their `assets`, perform advanced analysis on `Detections` of `Malware`, `Ransomware`, `Exploits` and other threats found by the `ThreatDown Endpoint Agent`, and issue jobs like `Scan`, `Isolate`, `Remediate` or `Reboot`.
To get started, you need a client credential pair (OAuth2 application). You can get a valid application through our sales team.
You can retrieve your `client_id` and `client_secret` credentials pair in your Nebula console by going to the Integrate page in Nebula. You must also know your Nebula `account_id`.
## Cross-Origin Resource Sharing
This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with [W3C spec](https://www.w3.org/TR/cors/).
This allows cross-domain communication from the browser.
All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.
## Authentication
ThreatDown API uses OAuth2, an open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications.
See the Authentication section for specific information about supported grants.
## Access'' scopes
When creating a new application, you can decide the level of access it has to your account''s data. This utility allows you to restrict the scope of access to your account''s data depending on the application''s needs. For example, if you only need to analyze detections found on your endpoint, the read scope will be enough to prevent that application from modifying data or issuing jobs.
Specifying access scopes gives you more control over the access of your data. For example, you may want your company''s IT department to be able to isolate infected endpoints, while you may want your analysts to only read data for generating reports. To do so, you can create two applications using different scopes, and provide the right people with the right pair of credentials for programmatic access.
## User permissions
The user associated with the client (i.e. the user that created the OAuth2 application) must have the required permissions to perform the requested operation. If the user does not have sufficient permissions, the API will respond with a `403 Forbidden` status code.
For each API, you can find the required permissions in the AUTHORIZATIONS dropdown, under `user_permissions`.
Some API requires additional permissions based on the data in the body:
- **jobs** issue API requires `<entity>.performActions` depending on the `command` (\<entity\> can be `endpoints`, `softwareInventory`, or `detections`)
- **notifications** create/update API requires `<entity>.view` depending on the `category`
- **reports** create/update API requires `<entity>.view` depending on the `type`
## Rate Limiting
ThreatDown API implements a rate-limiting mechanism to prevent abuse. The rate-limiting mechanism is implemented using a leaky bucket algorithm. Once you exceed the available limit, our server will respond with a `429` status code. You can throttle your requests and retry them later.
The current limit, which you can see in the table below, has shown to be enough for most use cases. If you encounter `429` error codes, consider taking the following actions to minimize your APIs usage:
- Subscribe to webhooks events instead of polling the API for reacting to changes.
- Throttle the requests you send to the ThreatDown API for not exceeding the limit.
- Batch requests when possible.
- Contact us and request to increase the API quota for your application.
Currently, the default available quota is `360` requests per minute.
'
version: 1.0.0
x-logo:
altText: ThreatDown logo
url: https://assets.threatdown.com/hermes/ThreatDown_Horizontal_Navy.png
backgroundColor: '#FFFFFF'
servers:
- url: https://api.threatdown.com
tags:
- name: DNS Logs
description: 'The DNS Filtering module limits the number of domain-based threats in your environment by allowing and blocking access across the network. Each time this occurs, a record is generated.
Use these APIs to export the DNS activity and search through the logs.'
paths:
/nebula/v1/dns/export:
post:
description: "Export DNS data. Specify your interested fields and the output format.\n\nSupported output formats: csv, xlsx, json.\n\n## Settings\n\n| Name | Description |\n|------|-------------|\n| groups | List of queries. The constraints accepted are the same accepted by the search assets software route. Refer to [Search DNS API](#operation/api.nebula.search.dns) for more information about the constraints accepted. |\n| download | If set to true, the server will set the `Content-Disposition` header using the `filename` and `format` |\n| select | Which fields to select, and which field name to map to. See request schema for allowed values |\n| type | Output encoding (for `csv` and `json` format) |\n| filename | Name of the file to be set in `Content-Disposition` header if `download` = true |\n\n## Examples\n\n### Download CSV file\n\nA request with this body sent by a browser will download a file called `nameofthefile.cvs`, displaying a table with columns: `accountId`, `groupId`, `groupName`, `Domain`, `IP_address` for all the dns logs of machine_id `1514cd0a-2ef3-4db3-b8a4-c89894d9aa34`:\n\n```json\n{\n \"groups\": [\n { \"machine_id\": \"1514cd0a-2ef3-4db3-b8a4-c89894d9aa34\" }\n ],\n \"format\": \"csv\",\n \"type\": \"string\",\n \"filename\": \"nameofthefile\",\n \"download\": true,\n \"select\": [\n {\"field\": \"account_id\", \"newField\": \"accountId\"},\n {\"field\": \"group_id\", \"newField\": \"groupId\"},\n {\"field\": \"group_name\", \"newField\": \"groupName\"},\n {\"field\": \"log.query_name\", \"newField\": \"Domain\"},\n {\"field\": \"log.dst_ip\", \"newField\": \"IP_address\"}\n ]\n}\n```\n"
summary: Export DNS Log data
security:
- client_credentials:
- execute
- user_permissions:
- dnsFiltering.view
status:
outage:
- auth
- search_stateless
parameters:
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
requestBody:
content:
application/json:
schema:
type: object
title: Export request
required:
- groups
- select
- format
properties:
format:
type: string
title: The output file
enum:
- csv
- xlsx
- html
- ods
- txt
- rtf
- json
download:
type: boolean
title: Whether to instruct the client to download the response as a file. Only clients like browsers are supported
type:
type: string
title: The encoding of the output
enum:
- string
- base64
- binary
default: string
select:
type: array
title: Which fields to select from the response
items:
type: object
title: Field
required:
- field
- newField
properties:
newField:
type: string
title: the new value
field:
type: string
title: The response field to map to a new value
enum:
- rule_id
- rule_name
- resolved_ips
- machine_id
- group_id
- group_name
- account_name
- machine_name
- policy_id
- policy_name
- account_id
- parent_account_id
- action
- log.policy_id
- log.policy
- log.protocol
- log.query_name
- log.query_name_reversed
- log.resolver_decision
- log.user_id
- log.colo_id
- log.dst_port
- log.query_category_ids
- log.query_size
- log.query_type
- log.src_port
- log.dst_ip
- log.src_ip
- timestamp
- log.datetime
- agent.at
- agent.last_user
- agent.fully_qualified_host_name
- agent.started_at_local
- agent.started_at_offset
- agent.os_info.os_type
- agent.os_info.os_version
- agent.os_info.os_platform
- agent.os_info.os_architecture
- agent.os_info.os_release_name
- agent.domain_name
- agent.engine_version
- agent.policy_etag
- agent.host_name
- agent.nics.ips
- agent.nics.mac_address
- machine.tags.alias
- agent.has_alerts
- agent.machine_ip
- agent.object_guid
- agent.plugins.endpoint_protection.sdk_version
- agent.plugins.endpoint_protection.component_package_version
- agent.source_location.city
- agent.source_location.country
- agent.source_location.country_iso
- agent.source_location.continent
- agent.source_location.time_zone
- agent.source_location.postal_code
- agent.source_location.subdivisions
- agent.source_location.anonymous_proxy
- agent.serial_number
- active_directory.user.display_name
- active_directory.user.sam_account_name
- active_directory.user.ou
- active_directory.machine.display_name
- active_directory.machine.sam_account_name
- active_directory.machine.ou
groups:
type: array
title: List of queries
items:
type: object
title: Query to fetch DNS Logs
allOf:
- type: object
title: Search DNS Logs request. Leading wildcards are not supported for constraint fields without '.keyword' suffix.
allOf:
- type: object
title: Agent constraints
description: The Agents constraints.
properties:
nics.mac_address:
type: string
title: nics.mac_address
not.nics.mac_address:
type: string
title: not.nics.mac_address
nics.mac_address.keyword:
type: string
title: nics.mac_address.keyword
not.nics.mac_address.keyword:
type: string
title: not.nics.mac_address.keyword
nics.description:
type: string
title: nics.description
not.nics.description:
type: string
title: not.nics.description
nics.description.keyword:
type: string
title: nics.description.keyword
not.nics.description.keyword:
type: string
title: not.nics.description.keyword
os_info.os_type:
type: string
title: os_info.os_type
not.os_info.os_type:
type: string
title: not.os_info.os_type
os_info.os_type.keyword:
type: string
title: os_info.os_type.keyword
not.os_info.os_type.keyword:
type: string
title: not.os_info.os_type.keyword
os_info.os_version:
type: string
title: os_info.os_version
not.os_info.os_version:
type: string
title: not.os_info.os_version
os_info.os_version.keyword:
type: string
title: os_info.os_version.keyword
not.os_info.os_version.keyword:
type: string
title: not.os_info.os_version.keyword
os_info.os_platform:
type: string
title: os_info.os_platform
not.os_info.os_platform:
type: string
title: not.os_info.os_platform
os_info.os_platform.keyword:
type: string
title: os_info.os_platform.keyword
not.os_info.os_platform.keyword:
type: string
title: not.os_info.os_platform.keyword
os_info.os_architecture:
type: string
title: os_info.os_architecture
not.os_info.os_architecture:
type: string
title: not.os_info.os_architecture
os_info.os_architecture.keyword:
type: string
title: os_info.os_architecture.keyword
not.os_info.os_architecture.keyword:
type: string
title: not.os_info.os_architecture.keyword
os_info.os_release_name:
type: string
title: os_info.os_release_name
not.os_info.os_release_name:
type: string
title: not.os_info.os_release_name
os_info.os_release_name.keyword:
type: string
title: os_info.os_release_name.keyword
not.os_info.os_release_name.keyword:
type: string
title: not.os_info.os_release_name.keyword
host_name:
type: string
title: host_name
not.host_name:
type: string
title: not.host_name
host_name.keyword:
type: string
title: host_name.keyword
not.host_name.keyword:
type: string
title: not.host_name.keyword
fully_qualified_host_name:
type: string
title: fully_qualified_host_name
not.fully_qualified_host_name:
type: string
title: not.fully_qualified_host_name
fully_qualified_host_name.keyword:
type: string
title: fully_qualified_host_name.keyword
not.fully_qualified_host_name.keyword:
type: string
title: not.fully_qualified_host_name.keyword
plugins.asset_manager.plugin_version:
type: string
title: plugins.asset_manager.plugin_version
not.plugins.asset_manager.plugin_version:
type: string
title: not.plugins.asset_manager.plugin_version
plugins.asset_manager.plugin_version.keyword:
type: string
title: plugins.asset_manager.plugin_version.keyword
not.plugins.asset_manager.plugin_version.keyword:
type: string
title: not.plugins.asset_manager.plugin_version.keyword
plugins.asset_manager.reboot_reasons:
type: string
title: plugins.asset_manager.reboot_reasons
not.plugins.asset_manager.reboot_reasons:
type: string
title: not.plugins.asset_manager.reboot_reasons
plugins.asset_manager.reboot_reasons.keyword:
type: string
title: plugins.asset_manager.reboot_reasons.keyword
not.plugins.asset_manager.reboot_reasons.keyword:
type: string
title: not.plugins.asset_manager.reboot_reasons.keyword
plugins.endpoint_protection.plugin_version:
type: string
title: plugins.endpoint_protection.plugin_version
not.plugins.endpoint_protection.plugin_version:
type: string
title: not.plugins.endpoint_protection.plugin_version
plugins.endpoint_protection.plugin_version.keyword:
type: string
title: plugins.endpoint_protection.plugin_version.keyword
not.plugins.endpoint_protection.plugin_version.keyword:
type: string
title: not.plugins.endpoint_protection.plugin_version.keyword
plugins.endpoint_protection.sdk_version:
type: string
title: plugins.endpoint_protection.sdk_version
not.plugins.endpoint_protection.sdk_version:
type: string
title: not.plugins.endpoint_protection.sdk_version
plugins.endpoint_protection.sdk_version.keyword:
type: string
title: plugins.endpoint_protection.sdk_version.keyword
not.plugins.endpoint_protection.sdk_version.keyword:
type: string
title: not.plugins.endpoint_protection.sdk_version.keyword
plugins.endpoint_protection.component_package_version:
type: string
title: plugins.endpoint_protection.component_package_version
not.plugins.endpoint_protection.component_package_version:
type: string
title: not.plugins.endpoint_protection.component_package_version
plugins.endpoint_protection.component_package_version.keyword:
type: string
title: plugins.endpoint_protection.component_package_version.keyword
not.plugins.endpoint_protection.component_package_version.keyword:
type: string
title: not.plugins.endpoint_protection.component_package_version.keyword
plugins.endpoint_protection.update_package_version:
type: string
title: plugins.endpoint_protection.update_package_version
not.plugins.endpoint_protection.update_package_version:
type: string
title: not.plugins.endpoint_protection.update_package_version
plugins.endpoint_protection.update_package_version.keyword:
type: string
title: plugins.endpoint_protection.update_package_version.keyword
not.plugins.endpoint_protection.update_package_version.keyword:
type: string
title: not.plugins.endpoint_protection.update_package_version.keyword
plugins.endpoint_protection.reboot_reasons:
type: string
title: plugins.endpoint_protection.reboot_reasons
not.plugins.endpoint_protection.reboot_reasons:
type: string
title: not.plugins.endpoint_protection.reboot_reasons
plugins.endpoint_protection.reboot_reasons.keyword:
type: string
title: plugins.endpoint_protection.reboot_reasons.keyword
not.plugins.endpoint_protection.reboot_reasons.keyword:
type: string
title: not.plugins.endpoint_protection.reboot_reasons.keyword
plugins.endpoint_detection_and_response.plugin_version:
type: string
title: plugins.endpoint_detection_and_response.plugin_version
not.plugins.endpoint_detection_and_response.plugin_version:
type: string
title: not.plugins.endpoint_detection_and_response.plugin_version
plugins.endpoint_detection_and_response.plugin_version.keyword:
type: string
title: plugins.endpoint_detection_and_response.plugin_version.keyword
not.plugins.endpoint_detection_and_response.plugin_version.keyword:
type: string
title: not.plugins.endpoint_detection_and_response.plugin_version.keyword
plugins.endpoint_detection_and_response.reboot_reasons:
type: string
title: plugins.endpoint_detection_and_response.reboot_reasons
not.plugins.endpoint_detection_and_response.reboot_reasons:
type: string
title: not.plugins.endpoint_detection_and_response.reboot_reasons
plugins.endpoint_detection_and_response.reboot_reasons.keyword:
type: string
title: plugins.endpoint_detection_and_response.reboot_reasons.keyword
not.plugins.endpoint_detection_and_response.reboot_reasons.keyword:
type: string
title: not.plugins.endpoint_detection_and_response.reboot_reasons.keyword
plugins.incident_response.plugin_version:
type: string
title: plugins.incident_response.plugin_version
not.plugins.incident_response.plugin_version:
type: string
title: not.plugins.incident_response.plugin_version
plugins.incident_response.plugin_version.keyword:
type: string
title: plugins.incident_response.plugin_version.keyword
not.plugins.incident_response.plugin_version.keyword:
type: string
title: not.plugins.incident_response.plugin_version.keyword
plugins.incident_response.reboot_reasons:
type: string
title: plugins.incident_response.reboot_reasons
not.plugins.incident_response.reboot_reasons:
type: string
title: not.plugins.incident_response.reboot_reasons
plugins.incident_response.reboot_reasons.keyword:
type: string
title: plugins.incident_response.reboot_reasons.keyword
not.plugins.incident_response.reboot_reasons.keyword:
type: string
title: not.plugins.incident_response.reboot_reasons.keyword
plugins.siem.plugin_version:
type: string
title: plugins.siem.plugin_version
not.plugins.siem.plugin_version:
type: string
title: not.plugins.siem.plugin_version
plugins.siem.plugin_version.keyword:
type: string
title: plugins.siem.plugin_version.keyword
not.plugins.siem.plugin_version.keyword:
type: string
title: not.plugins.siem.plugin_version.keyword
plugins.browser_phishing_protection.plugin_version:
type: string
title: plugins.browser_phishing_protection.plugin_version
not.plugins.browser_phishing_protection.plugin_version:
type: string
title: not.plugins.browser_phishing_protection.plugin_version
plugins.browser_phishing_protection.plugin_version.keyword:
type: string
title: plugins.browser_phishing_protection.plugin_version.keyword
not.plugins.browser_phishing_protection.plugin_version.keyword:
type: string
title: not.plugins.browser_phishing_protection.plugin_version.keyword
plugins.browser_phishing_protection.reboot_reasons:
type: string
title: plugins.browser_phishing_protection.reboot_reasons
not.plugins.browser_phishing_protection.reboot_reasons:
type: string
title: not.plugins.browser_phishing_protection.reboot_reasons
plugins.browser_phishing_protection.reboot_reasons.keyword:
type: string
title: plugins.browser_phishing_protection.reboot_reasons.keyword
not.plugins.browser_phishing_protection.reboot_reasons.keyword:
type: string
title: not.plugins.browser_phishing_protection.reboot_reasons.keyword
plugins.siem.reboot_reasons:
type: string
title: plugins.siem.reboot_reasons
not.plugins.siem.reboot_reasons:
type: string
title: not.plugins.siem.reboot_reasons
plugins.siem.reboot_reasons.keyword:
type: string
title: plugins.siem.reboot_reasons.keyword
not.plugins.siem.reboot_reasons.keyword:
type: string
title: not.plugins.siem.reboot_reasons.keyword
engine_version:
type: string
title: engine_version
not.engine_version:
type: string
title: not.engine_version
engine_version.keyword:
type: string
title: engine_version.keyword
not.engine_version.keyword:
type: string
title: not.engine_version.keyword
domain_name:
type: string
title: domain_name
not.domain_name:
type: string
title: not.domain_name
domain_name.keyword:
type: string
title: domain_name.keyword
not.domain_name.keyword:
type: string
title: not.domain_name.keyword
policy_etag:
type: string
title: policy_etag
not.policy_etag:
type: string
title: not.policy_etag
policy_etag.keyword:
type: string
title: policy_etag.keyword
not.policy_etag.keyword:
type: string
title: not.policy_etag.keyword
last_user:
type: string
title: last_user
not.last_user:
type: string
title: not.last_user
last_user.keyword:
type: string
title: last_user.keyword
not.last_user.keyword:
type: string
title: not.last_user.keyword
serial_number:
type: string
title: serial_number
not.serial_number:
type: string
title: not.serial_number
serial_number.keyword:
type: string
title: serial_number.keyword
not.serial_number.keyword:
type: string
title: not.serial_number.keyword
- type: object
title: Active Directory Search Filters
# --- truncated at 32 KB (229 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-dns-logs-api-openapi.yml