Description

This plugin allows for directly integrating DNS auditing into Gravwell. The plugin acts as an integrated ingester and ships DNS requests and responses directly to a Gravwell instance.

DNS Requests and responses can be encoded as text, JSON, or as a packed binary format.

Syntax

gravwell {
    Ingest-Secret IngestSecretToken
    Cleartext-Target 192.168.1.1:4023
    Tag dns
    Encoding json
    Log-Level INFO
    #Cleartext-Target 192.168.1.2:4023 #second indexer
    #Ciphertext-Target 192.168.1.1:4024
    #Insecure-Novalidate-TLS true #disable TLS certificate validation
    #Ingest-Cache-Path /tmp/coredns_ingest.cache #enable the local ingest cache
    #Max-Cache-Size-MB 1024
}

• Ingest-Secret defines the token used to authenticate with indexers. Ingest-Secret is required.
• Cleartext-Target defines the address and port for a remote indexer using a TCP connection. IPv4 and IPv6 addresses as well as host names are supported.
• Ciphertext-Target defines the address and port for a remote indexer using a TLS connection. IPv4 and IPv6 addresses as well as host names are supported.
• Tag specifies the tag that DNS audit logs are assigned. Can be any alphanumeric value without special characters or spaces. A valid Tag value is required.
• Encoding specifies the format of transported DNS audit logs. Options are json or text. Deafult is json.
• Insecure-Novalidate-TLS toggles certificate validation on TLS connections. Validation is on by default.
• Log-Level specifies the logging verbosity over the integrated gravwell tag. Options are OFF INFO WARN ERROR. Default is ERROR.
• Ingest-Cache-Path specifies a file path for the cache system which engages when indexer connectivity is lost. Path must be an absolute path to a writable file.
• Max-Cache-Size-MB specifies in megabytes the maximum size of the cache file. This is used as a safty net. Zero value is the default and represents unlimited.

Examples

No local cache with single indexer over TCP

A sample Corefile which sends DNS requests to a single indexer over an unencrypted connection. Local cache is disabled.

gravwell {
    Ingest-Secret IngestSecretToken
    Cleartext-Target 192.168.1.1:4023
    Tag dns
  }

TLS connection to two indexers with no TLS validation

A sample Corefile which sends DNS requests to two indexers over a TLS connection and accepts unsigned certificates. Local cache is disabled. IPv4 and IPv6 addresses are supported for both the Cleartext and Ciphertext targets. IPv6 addresses must be enclosed in brackets.

gravwell {
    Ingest-Secret IngestSecretToken
    Ciphertext-Target 192.168.1.1:4024
    Ciphertext-Target [fe80::dead:beef:feed:febe%p1p1]:4024 #connecting to link local address via device p1p1
    Tag dns
    Encoding json
    Log-Level INFO
  }

TLS connection to two indexers with no TLS validation

A sample Corefile which sends DNS requests to two indexers over a TLS connection and accepts unsigned certificates. Local cache is disabled.

gravwell {
    Ingest-Secret IngestSecretToken
    Ciphertext-Target 192.168.1.1:4024
    Ciphertext-Target [dead::beef]:4024
    Insecure-Novalidate-TLS true
    Tag dns
    Encoding json
    Log-Level INFO
  }

Local cache for high reliability operation

A sample Corefile which sends DNS requests to two indexers and enables a local cache should indexer communication fail. Up to 1GB of data can be locally cached.

gravwell {
    Ingest-Secret IngestSecretToken
    Cleartext-Target 192.168.1.1:4023
    Ciphertext-Target 192.168.1.2:4024
    Insecure-Novalidate-TLS true
    Ingest-Cache-Path /tmp/coredns_ingest.cache
    Max-Cache-Size-MB 1024
    Tag dns
    Encoding json
    Log-Level INFO
  }

See Also

Getting started with Gravwell Community Edition Community Edition Licenses Ingest API and code