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.
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:
[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.
The modules provides one redefinable variable:
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", }.
The DNS module supplies the following event handlers:
[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.