DNS Lookup

Enrich Cribl Compatible

Synopsis

Performs DNS lookups on domains or IP addresses, and caches the results.

Schema

- dns_lookup:
    field: <ident>
    type: <string>
    resource_type: <string>
    target_field: <ident>
    dns_server: <string>
    cache_ttl: <number>
    lookup_timeout: <number>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Field containing domain/IP to lookup
type	Y	-	Lookup type: forward or reverse
resource_type	Y*	-	DNS record type for a forward lookup: A, AAAA, MX or TXT, matched case-insensitively. There is no default — omitting it on a forward lookup fails with unsupported record type. Not read for a reverse lookup
target_field	N	field	Field to store lookup results
dns_server	N	-	Custom DNS server (e.g., "8.8.8.8:53")
cache_ttl	N	30	How long a result is cached, in minutes. -1 is a special value meaning five seconds, for testing against a record that is changing. 0 means "unset" and gives the 30-minute default
lookup_timeout	N	5	How long a single lookup may take, in seconds. 0 means "unset" and gives the default
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue if lookup fails
ignore_missing	N	false	Continue if source field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

* = Required for a forward lookup.

Details

The processor does both forward and reverse lookups, and can handle multiple DNS record types and custom DNS servers. IPv6 addresses are fully supported for both forward and reverse lookups.

note

Private IP addresses typically won't have PTR records.

All results are cached to improve performance.

note

Cache entries expire based on the configured TTL. Large cache sizes can impact memory usage.

Multiple results are returned as arrays. Non-string field values will cause errors. Conditional execution and success/failure handling are also supported.

warning

DNS lookups can introduce latency to event processing.

Examples

Forward

Looking up IPv4 addresses for a domain...	{ "domain": "example.com" } - dns_lookup: field: domain type: forward resource_type: A target_field: ip_addresses cache_ttl: 30
adds the resolved IPs to the event:	{ "domain": "example.com", "ip_addresses": ["93.184.216.34"] }

IPv4 Reverse

Looking up the hostname for IPv4 address...	{ "ip": "8.8.8.8" } - dns_lookup: field: ip type: reverse target_field: hostname
adds the resolved hostname to the event:	{ "ip": "8.8.8.8", "hostname": ["dns.google"] }

IPv6 Reverse

Looking up the hostname for IPv6 address...	{ "ip": "2001:4860:4860::8888" } - dns_lookup: field: ip type: reverse target_field: hostname
resolves the IPv6 address to the hostname:	{ "ip": "2001:4860:4860::8888", "hostname": ["dns.google"] }

MX Record

Looking up mail servers for a domain...	{ "domain": "gmail.com" } - dns_lookup: field: domain type: forward resource_type: MX target_field: mail_servers
adds the MX records to the event:	{ "domain": "gmail.com", "mail_servers": [ "alt1.gmail-smtp-in.l.google.com 10", "alt2.gmail-smtp-in.l.google.com 20" ] }

Custom Server

Using Cloudflare DNS for lookups...	{ "domain": "example.com" } - dns_lookup: field: domain type: forward resource_type: A dns_server: "1.1.1.1:53" target_field: ip_addresses
resolves the specified DNS server:	{ "domain": "example.com", "ip_addresses": ["93.184.216.34"] }

Private IPs

Handling lookup failures for private IPs...	{ "ip": "192.168.1.1" } - dns_lookup: field: ip type: reverse target_field: hostname ignore_failure: true
continues the execution:	{ "ip": "192.168.1.1" }

Conditionals

Performing the look up only for debug events...	{ "ip": "8.8.8.8", "level": "info" } - dns_lookup: field: ip type: reverse target_field: hostname if: "ctx.level == 'debug'"
skips irrelevant information:	{ "ip": "8.8.8.8", "level": "info" }