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>
  - description: <text>
  - if: <script>
  - ignore_failure: <boolean>
  - ignore_missing: <boolean>
  - on_failure: <processor[]>
  - on_success: <processor[]>
  - tag: <string>

Configuration

Field	Required	Default	Description
field	Y	-	Field containing domain/IP to lookup
type	Y	-	Lookup type: forward or reverse
resource_type	N	A	DNS record type for forward lookups: A, AAAA, MX, TXT
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	Cache TTL in minutes
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

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" }