The dns Module
Keywords: doc-html

Next: The finger Analyzer Up: Analyzers and Events Previous: The demux Module Contents Index
Subsections

- The `dns_mapping` record
- `dns` variables
- `dns` event handlers

#
The `dns` Module

The `dns` module deals with Bro's internal mapping of hostnames to/from IP addresses. Deficiency: There is no DNS protocol analyzer available at present. Furthermore, Deficiency: the lookup mechanisms discussed here are not available to the Bro script writer, other than implicitly by using hostnames in lieu of addresses in variable initializations (§ ).

The module's function is to handle different events that can occur when Bro resolves hostnames upon startup. Bro maintains its own cache of DNS information which persists across invocations of Bro on the same machine and by the same user. The role of the cache is to allow Bro to resolve hostnames even in the face of DNS outages; the philosophy is that it's better to use old addresses than none at all, and this helps harden Bro against attacks in which the attacker causes DNS outages in order to prevent Bro from resolving particular sensitive hostnames (e.g., `hot_srcs`). The cache is stored in the file ```.bro-dns-cache`'' in the user's home directory. You can delete this file whenever you want, for example to purge out old entries no longer needed, and Bro will recreate it next time it's invoked using `-P`.

Currently, all of the event handlers are invoked upon comparing the results of a new attempt to look up a name or an address versus the results obtained the last time Bro did the lookup. When Bro looks up a name for the first time, no events are generated.

Also, Bro currently only looks up hostnames to map them to addresses. It does not perform inverse lookups.

##
The `dns_mapping` record

Figure 7.5: Definition of the `dns_mapping` record.

All of the events handled by the module include at least one record of DNS mapping information, defined by the `dns_mapping` type shown in Figure 7.12.1. The corresponding fields are:

  [`creation_time`] When the mapping was created.

  [`req_host`] The hostname looked up, or an empty string if this was not a hostname lookup.

  [`req_addr`] The address looked up (reverse lookup), or `0.0.0.0` if this was not an address lookup.

  [`valid`] True if an answer was received for a lookup (even if the answer was that the request name or address does not exist in the DNS).

  [`hostname`] The hostname answer in response to an address lookup, or the string `"`<`none`>"`` if an answer was received but it indicated there was no PTR record for the given address.

  [`addrs`] A set of addresses in response to a hostname lookup. Empty if an answer was received but it indicated that there was no A record for the given hostname.

##
`dns` variables

The modules provides one redefinable variable:

  [``dns_interesting_changes : set[string]``] The different DNS events have names associated with them. If the name is present in this set, then the event will be logged, otherwise not.

  One exception to this list is that DNS changes involving the loopback address `127.0.0.1` are always considered log-worthy, since they may reflect DNS corruption.

  Default: `{ "unverified", "old name", "new name", "mapping", }`.

##
`dns` event handlers

The DNS module supplies the following event handlers:

  [``dns_mapping_valid (dm: dns_mapping)``] The given request was looked up and it was identical to its previous mapping.

  [``dns_mapping_unverified (dm: dns_mapping)``] The given request was looked up but no answer came back.

  [``dns_mapping_new_name (dm: dns_mapping)``] In the past, the given address did not resolve to a hostname; this time, it did.

  [``dns_mapping_lost_name (dm: dns_mapping)``] In the past, the given address resolved to a hostname; now, that name has gone away. (An answer was received, but it stated that there is no hostname corresponding to the given address.)

  [``dns_mapping_name_changed (old_dm: dns_mapping, new_dm: dns_mapping)``] The name returned this time for the given address differs from the name returned in the past.

  [``dns_mapping_altered (dm: dns_mapping, old_addrs: set[addr], new_addrs: set[addr])``] The addresses associated with the given hostname have changed. Those in `old_addrs` used to be part of the set returned for the name, but aren't any more; while those in `new_addrs` didn't used to be, but now are. There may also be some unchanged addresses, which are those in `dm$addrs` but not in `new_addrs`.

Next: The finger Analyzer Up: Analyzers and Events Previous: The demux Module Contents Index