DNS Activity - BlueCat Integrity - 9.5.0

Address Manager Legacy v1 API Guide

Locale
English
Product name
BlueCat Integrity
Version
9.5.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 an HTTP endpoint, Splunk server, Kafka cluster, or Elasticsearch server. 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 or greater.
  • Upon upgrading to DNS/DHCP Server v9.3.0 or greater, 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.
  • Output to Kafka clusters and Elasticsearch servers can only be configured on DNS/DHCP Server v9.5.0.

Example http 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": "https://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_hec 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": "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": "response",
                                        "value": "auth"
                                    },
                                    {
                                        "category": "response",
                                        "value": "forwarder"
                                    }
                                ]
                            }
                        ]
                    }
                }
            ]
        }
    }
}

Example kafka configuration

{
    "version": "1.0.0",
    "services": {
        "dnsActivity": {
            "configurations": [
                {
                    "dnsActivityConfiguration": {
                        "serviceId": "dns-activity",
                        "enable": true,
                        "sinks": [
                            {
                                "type": "kafka",
                                "bootstrap_servers": "10.14.22.123:9092,10.14.23.332:9092",
                                "topic": "topic-1234",
                                "key_field":"user_id",
                                "healthCheck": true,
                                "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": "response",
                                        "value": "auth"
                                    },
                                    {
                                        "category": "response",
                                        "value": "forwarder"
                                    }
                                ]
                            }
                        ]
                    }
                }
            ]
        }
    }
}

Example elasticsearch configuration

{
    "version": "1.0.0",
    "services": {
        "dnsActivity": {
            "configurations": [
                {
                    "dnsActivityConfiguration": {
                        "serviceId": "dns-activity",
                        "enable": true,
                        "sinks": [
                            {
                                "type": "elasticsearch",
                                "endpoint": "http://10.24.32.122:9000",
                                "user": "user1",
                                "password": "pass123",
                                "index": "testIndex",
                                "healthCheck": true,
                                "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": "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 log data to an HTTP endpoint, Splunk server, Kafka cluster, or Elasticsearch 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:
      • BlueCat recommends entering the IP address of the endpoint in this field. If you are entering a hostname, you must use a different DNS server as the resolver for that host. The DNS/DHCP server you are configuring DNS activity on can still be used as a resolver for clients, but cannot be used as a resolver for its own OS related lookups.
      • If the domain name is used in the URI, you must ensure that the domain name can be resolved on the DNS/DHCP Server.
      • The URI for the uri field must follow the format outlined in RFC2396.
    • 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.
      Note: The URI for the healthCheckUri field must follow the format outlined in RFC2396.
    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>://<FQDN or IP address of the host only>:<port>
      Note:
      • BlueCat recommends entering the IP address of the endpoint in this field. If you are entering a hostname, you must use a different DNS server as the resolver for that host. The DNS/DHCP server you are configuring DNS activity on can still be used as a resolver for clients, but cannot be used as a resolver for its own OS related lookups.
      • If the domain name is used in the URI, you must ensure that the domain name can be resolved on the DNS/DHCP Server.
      • Ensure that the HEC URI format is followed exactly as described above without adding or omitting any pieces. The port is required, even if default. Do not include extra slashes or folders in the URI.
      • The URI for the host field must follow the format outlined in RFC2396.
    • 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.
    If you enter kafka, enter the following additional parameters:
    • bootstrap_servers—enter a comma-separated list of host and port pairs that are the addresses of the Kafka brokers in a “bootstrap” Kafka cluster that a Kafka client connects to initially to bootstrap itself. This field supports IPv4, IPv6 and FQDN values.

      Example: 10.14.22.123:9092,10.14.23.332:9092

      Note:
      • BlueCat recommends using IP addresses in this field. If you are entering a hostname, you must use a different DNS server as the resolver for that host. The DNS/DHCP server you are configuring DNS activity on can still be used as a resolver for clients, but cannot be used as a resolver for its own OS related lookups.
      • Do not include http or https in the addresses of the Kafka brokers.
      • If a domain name is used, you must ensure that the domain name can be resolved on the DNS/DHCP Server.
    • topic—enter the name of the Kafka topic to write events to.
    • key_field—enter the log field name or tags key to use for the topic key. If the field does not exist in the log or in tags, a blank value will be used. If unspecified, the key is not sent. Kafka uses a hash of the key to choose the partition or uses round-robin if the record has no key. 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.
      Note: The health check URI is configured based on the Kafka Broker address.
    If you enter elasticsearch, enter the following additional parameters:
    • endpoint—enter the Elasticsearch endpoint to send logs to. This field supports IPv4, IPv6, and FQDN values.

      Example: http://10.24.32.122:9000

      Example: https://example.com

      Example: https://user:password@example.com

      Note:
      • BlueCat recommends using the IP address of the endpoint in this field. If you are entering a hostname, you must use a different DNS server as the resolver for that host. The DNS/DHCP server you are configuring DNS activity on can still be used as a resolver for clients, but cannot be used as a resolver for its own OS related lookups.
      • If the domain name is used, you must ensure that the domain name can be resolved on the DNS/DHCP Server.
    • user—enter the basic authentication user name.
    • password—enter the basic authentication password.
    • index—enter Elasticsearch index name to write events to.
    • 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: The health check URI is configured based on the Elasticsearch instance.
  • 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.
      Attention: Buffer settings change in DNS/DHCP Server v9.4.0

      Starting in DNS/DHCP Server v9.4.0, the disk buffer setting is no longer available. If you previously had DNS Activity service configured with the disk buffer setting on DNS/DHCP Server v9.3.0 and you upgrade the DNS/DHCP Server v9.4.0 or greater, the buffer setting will be updated to memory upon reconfiguring DNS Activity service.

      • memory—DNS activity that has not been processed is stored in the memory of the DNS/DHCP Server.
        • 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.
  • When configuring tls settings, enter the following parameters:
    Attention: If you enter a HTTPS endpoint in the uri, healthCheckUri, host, bootstrap_servers, or endpoint field when configuring output, you must select this check box and enter TLS information.
    • caCert—enter the content of CA certificate (trusted third party or self-signed) that will be used to authenticate the CA signature on the TLS server certificate of the remote host.
      Note: The CA certificate or certificate bundle must be in PEM format. To ensure a successful TLS handshake, the CA certificate provided to the client (BDDS) should be the same CA certificate (and intermediate certificates if applicable) used by the server to authenticate the CA signature of its TLS server certificate. The CA certificate can be acquired via browser export or other trusted source, and converted to PEM format.
    • verifyCertificate—set to true to attempt a TLS handshake using the provided CA certificate with the remote host's TLS server certificate.
      Note: verifyCertificate does not verify the authenticity of the provided certificate. verifyCertificate in this context only checks if the CA certificate matches correctly with the TLS server certificate to create a successful handshake.
      Note: If encountering errors with Verify Certificate, the CA/chain-CA certificates may have to be installed manually on the DNS/DHCP Server. Refer to KB-17944 on the BlueCat Customer Care portal for manual installation instructions.
    • 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.
      Note: If using self-signed certificates, users are advised to add a subject alternative name with the IP address (see RFC 5280 4.2.1.6), or disable the verifyHostname check.
  • 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.