DNS Activity - BlueCat Address Manager - 9.3.0

Address Manager API Guide

Locale
English (United States)
Product name
BlueCat Address Manager
Version
9.3.0

The DNS Activity service uses dnstap to provide visibility into the DNS queries and responses, and DDNS updates that are processed by a DNS/DHCP Server. You can use this information to analyze DNS activity, enabling you to monitor the health of your network and identify any anomalies that might indicate malicious activity. For more information on dnstap, refer to https://dnstap.info/.

When enabled, DNS query and response information is collected by the DNS/DHCP Server based on the configured parameters, and sent to a configured destination. You can choose to send the information to a Splunk server or HTTP endpoint, such as a data lake. If you are configuring DNS Activity to send data to a Splunk server, ensure that you have the Splunk HTTP Event Collector (HEC) host and token information.
Attention:
  • You can only enable this service on DNS/DHCP Server v9.3.0.
  • Upon upgrading to DNS/DHCP Server v9.3.0, you must perform a full DNS deployment on the DNS/DHCP Servers that will be configured with the DNS Activity service.
  • Enabling the DNS Activity service can be resource intensive and might affect the performance of the DNS/DHCP Server; however, configuring filters by query or response can greatly improve the QPS performance of the DNS Activity service by up to two times.

Example HTTP endpoint configuration

{
    "version": "1.0.0",
    "services": {
        "dnsActivity": {
            "configurations": [
                {
                    "dnsActivityConfiguration": {
                        "serviceId": "dns-activity",
                        "enable": true,
                        "sinks": [
                            {
                                "type": "http",
                                "uri": "https://10.0.0.1:9002/endpoint",
                                "token": "<bearer_token>",
                                "healthCheck": true,
                                "healthCheckUri": "http://10.0.0.1:9002/endpoint/healthcheck",
                                "buffer": {
                                    "type": "memory",
                                    "maxEvents": 500
                                },
                                "tls": {
                                    "caCert": "<certificate_content>",
                                    "verifyCertificate": true,
                                    "verifyHostname": true
                                }
                            }
                        ],
                        "transforms": [
                            {
                                "eventExcludeFilters": [
                                    {
                                        "category": "source_address",
                                        "value": "2001:10::/32"
                                    },
                                    {
                                        "category": "domain_name",
                                        "value": "example.com"
                                    },
                                    {
                                        "category": "query",
                                        "value": "all"
                                    }
                                ]
                            }
                        ]
                    }
                }
            ]
        }
    }
}

Example Splunk endpoint configuration

{
    "version": "1.0.0",
    "services": {
        "dnsActivity": {
            "configurations": [
                {
                    "dnsActivityConfiguration": {
                        "serviceId": "dns-activity",
                        "enable": true,
                        "sinks": [
                            {
                                "type": "splunk_hec",
                                "host": "https://10.0.0.1:9002",
                                "token": "MghrvMTU4NjIyMzA0NjYxMzpwb3J0YWxVc2Vy",
                                "healthCheck": true,
                                "buffer": {
                                    "type": "disk",
                                    "maxSize": 4000000
                                },
                                "tls": {
                                    "caCert": "<certificate_content>",
                                    "verifyCertificate": true,
                                    "verifyHostname": true
                                },
                            }
                        ],
                        "transforms": [
                            {
                                "eventExcludeFilters": [
                                    {
                                        "category": "source_address",
                                        "value": "2001:10::/32"
                                    },
                                    {
                                        "category": "domain_name",
                                        "value": "example.com"
                                    },
                                    {
                                        "category": "response",
                                        "value": "auth"
                                    }
                                    {
                                        "category": "response",
                                        "value": "forwarder"
                                    }
                                ]
                            }
                        ]
                    }
                }
            ]
        }
    }
}
Parameters
  • serviceId—enter the name of the DNS/DHCP Server Service. This must be set to dns-activity.
  • enable—set to true to enable DNS activity service; set to false to disable DNS activity service.
    Note: When you enabled DNS Activity, the firewall rules on the DNS/DHCP Server are modified to allow egress to the specified URI endpoint. Outbound traffic is allowed for the specified IP address.
    Attention: Enabling the DNS Activity service can be resource intensive and might affect the performance of the DNS/DHCP Server.
  • type—enter where the DNS Activity data will be logged. You can enter http to log data to an HTTP endpoint or splunk_hec to log data to a Splunk server.
    If you enter http, enter the following additional parameters:
    • uri—enter the URI of the HTTP endpoint that will be consuming the DNS query and response information.
      Note:
      • If the domain name is used in the URI, you must ensure that the domain name can be resolved on the DNS/DHCP Server using nslookup or an entry in /etc/hosts.
      • If you change the IP address associated to the URI after you have configured DNS Activity, you must disable and re-enable the DNS Activity service to ensure that the firewall rules on the DNS/DHCP Server are updated to allow egress to the new IP address.
      • If you have round-robin DNS load balancing configured, the firewall is set for all IP addresses returned for the specified domain and outbound TCP connections are allowed for all IP addresses.
    • token—enter the bearer token used to authenticate with the HTTP endpoint. This field is optional.
    • healthCheck—set to true to enable health check service; set to false to disable health check service. Upon initialization, the healthcheck ensure that the downstream service is accessible and can accept the DNS query data.
    • healthCheckUri—enter the URI of the HTTP endpoint that will be consuming the health check information.
    If you enter splunk_hec, enter the following additional parameters:
    • host—enter the URI of the Splunk HEC host. The standard format of the HEC URI in Splunk Enterprise is as follows:
      <protocol>://<host>:<port>
      Note: If the domain name is used in the URI, you must ensure that the domain name can be resolved on the DNS/DHCP Server using nslookup or an entry in /etc/hosts.
    • token—enter the Splunk HEC token.
    • healthCheck—set to true to enable health check service; set to false to disable health check service. Upon initialization, the healthcheck ensure that the downstream service is accessible and can accept the DNS query data.
      Note: When selecting this check box, the DNS/DHCP Server uses the default Splunk healthcheck endpoint at /services/collector/health/1.0.
    Note: The URI of the uri, healthCheckUri, and host fields must follow the format outlined in RFC2396.
  • When configuring buffer settings, enter the following parameters:
    • type—enter the buffer type where DNS events are stored until they are processed. Once the buffer is full, the newest events are dropped.
      The buffer type can be one of the following:
      • memory—DNS activity that has not been processed is stored in the memory of the DNS/DHCP Server. If you select memory, enter the following additional parameter:
        • maxEvents—enter the maximum number of DNS events to be stored in the buffer. The maximum value is 64,000,000.
          Note: You can enter a value for this field based on the highest possible queries per second (QPS) that can be sent to the DNS/DHCP Server and how quickly the endpoint processes events. For example, if the highest possible QPS for your environment is 20,000 QPS, the value of this field can be set to 200,000 to ensure that 10 seconds of events are stored in the DNS Activity buffer in the event that the endpoint processes queries slowly.
      • disk—DNS activity that has not been processed is stored on the disk of the DNS/DHCP Server. If you select disk, enter the following additional parameter:
        • maxSize—enter the maximum amount of disk space (in bytes) to allocate to the buffer. The maximum value is 7,500,000,000 bytes.
  • When configuring tls settings, enter the following parameters:
    • caCert—enter the content of CA certificate used to verify the server certificate during the TLS handshake. The caCert must be in PEM format.
    • verifyCertificate—set to true to force verification of the server certificate during the TLS handshake using the CA certificate that was entered; set to false if you do not want to verify the server certificate.
    • verifyHostname—set to true to validate the hostname section of the URI against the CN (Common Name) or SAN (Subject Alternative Name) of the server certificate during the TLS handshake; set to false if you do not want to perform this validation.
  • When configuring eventExcludeFilters settings, enter the following parameters:
    • category—select the categories of DNS events to exclude from logging. You can exclude DNS events based on domain_name, source_address, query, or response.
    • value—enter the value associated to the category.
      • If the category is set to domain_name, enter domain names that are to be excluded from being logged.
        Note: Domain names only support wildcard characters at the left-most position. For example, *.example.com or *-host.example.com.
      • If the category is set to source_address, enter the IPv4 or IPv6 block in CIDR notation to be excluded from being logged. For example, 192.0.2.0/24 or 2001:6789::/64.
      • If the category is set to query, enter one of the following DNS query message types to exclude:
        • all—excludes all queries, regardless of message type.
        • client—excludes client queries.
        • auth—excludes authoritative queries.
        • resolver—excludes resolver queries.
        • forwarder—excludes forwarder queries.
        • update—excludes update queries.
      • If the category is set to response, enter one of the following DNS response message types to exclude:
        • all—excludes all responses, regardless of message type.
        • client—excludes client responses.
        • auth—excludes authoritative responses.
        • resolver—excludes resolver responses.
        • forwarder—excludes forwarder responses.
        • update—excludes update responses.
        Note: If you configure eventExcludeFilters to filter DNS activity messages, you cannot create filters to exclude both querywith the value set to all and response with the value set to all.