README.rst

Contributed Bro Scripts

The roam.bro script
collects IP-to-MAC mappings (and vice versa) of machines that may have more
than one IP address over time due to a DHCP server in the network.

When keeping per-IP-address state, it could well be that the address becomes
invalid because the client's DHCP lease expired or because it received a new IP
address after rejoining the network. Ideally, this state would roam with the
user. But many Bro script data structures use per-address indices and would
mechanistically instantiate state for a new client even though it merely
reappeared under a new IP address. To incorporate the notion of roaming,
roam.bro makes available two data structures that script writers can use:

::

global ip_to_mac: table[addr] of string

&read_expire = alias_expiration &synchronized;

global mac_to_ip: table[string] of set[addr]

&read_expire = alias_expiration &synchronized;

Event handlers for the dhcp_ack and arp_reply events populate these
tables. For example, the sidejacking script (see below) makes use of
roam.bro to test whether a certain client IP address is an alias of another
IP address:

The sidejack.bro
script detects the reuse of session cookies in different contexts.
Sidejacking is also known as cookie hijacking and means that an
attacker captured a session cookie of a victim to reuse that session.
Off-the-shelf tools like Firesheep implement this attack as a Firefox
extension, which makes this attack accessible to the masses.

In its default settings, the script raises a SessionCookieReuse notice when
the same session cookie is seen from different user agents. If in addition the
IP addresses do not match, a Sidejack notice is being triggered.

There exist various options to tweak the behavior of the script. First, the
notion of a user can be changed. In flat IP address space, it makes sense to
identify a user by its IP address, but this would fail in a NAT environment
where a single IP accommodates several users. For NAT scenarios, one could
define a user as a pair of IP address and USER-AGENT header. For large NATs or
NATs with identically configured machines, this latter notion of user could be
prone to false positives. The user can change the definition of a user via

redef HTTP::user_is_ip = F;

Another issue poses the presence of absence of link-layer context. Consider a
hotspot or coffeeshop network operator with a private IP space. If Bro can see
DHCP or ARP traffic, we can crisply identify a user by its MAC address and do
not have to resort to high-level notions, such as provided by HTTP headers. In
a static setup, however, this context will likely not be available. At the same
time, if a different address reuses a session cookie in a static IP topology,
we probably observed a sidejacking attack. Furthermore, if the same address
uses the same session cookie from a different user agent, we report such
activity. By setting

redef HTTP::use_aliasing = T;

one tells Bro to use keep track of multiple IP addresses for the same host via
roam.bro. It makes only sense to set this flag when Bro actually sees DHCP
or ARP traffic.

There is another subtlety: the cookie header consists of a list of key-value
pairs, yet only a subset of those represent a user session while the others
could be random. Simply comparing the entire cookie string against a value seen
in the past would thus be prone to false negatives. Hence we have to restrict
ourselves to the relevant session-identifying subset. In fact, this is how
Firesheep works: it ships with site-specific handlers that define the cookie
keys to extract and then sets only those to impersonate a user. This motivates
the following design: if a specification for a particular service is available,
restrict the cookie to the relevant fields, and otherwise use the cookie as a
whole. The default set of known services that ships with the detector is based
on all handlers Firesheep currently implements. To extend the detection to all
cookies, one can set

redef HTTP::known_services_only = F;

Finally, the timeout for cookie expiration can be adjusted, e.g.,

redef HTTP::cookie_expiration = 1 day;

If a cookie is not seen after the cookie_expiration, the associated state
is removed. More information about the script can be found at
SidejackingBlogPost.

The mime-attachment.bro script extracts MIME entities
from a STMP session and reports suspicious email attachments, and optionally
saves them to disk. Storing attachment on disk allows for powerful
out-of-the-loop post-processing, such as scanning office documents for
malicious JavaScript or executables for viruses.

The script works by registering a callback handler for the CONTENT-TYPE header
in an SMTP session. Then both MIME type and the name of the attachment is
examined. If either looks suspicious, Bro generates a SensitiveMIMEType or
SensitiveExtension notice. The user can customize the the analyzer behavior
in many ways. To change the directory where the attachments are stored on disk,
one can redefine the attachment_dir variable:

redef Email::attachment_dir = "foo";

The script stores attachments by default, but this behavior can easily changed
via:

The script generates a file of the form <ID>-<filename> where ID is a
unique attachment ID that is monotonically increasing and filename is the
name of the attachment or just the MIME type if the attachment does not have a
name.