The hot Analyzer
Keywords: doc-html

Next: The scan Analyzer Up: Analyzers and Events Previous: Site-specific information Contents Index
Subsections

- `hot` variables
- `hot` functions

#
The `hot` Analyzer

The standard `hot` script defines policy relating to fairly generic notions of allowed and prohibited connections. It defines a number of variables that you will need to refine to customize your site's policies. It also provides two functions for checking connections against the policies, which can be used by other of the standard scripts.

##
`hot` variables

The standard `hot` script defines the following variables, all redefinable:

  [``same_local_net_is_spoof : bool``] If true, then a connection with a local originator address and a local responder address is considered by `check_spoof` to have been spoofed. Deficiency: The name is poorly chosen (and may be changed in the future) to something more accurate like `both_local_nets_is_spoof`.

  In general, you want to use true for a Bro that is monitoring Internet access links (DMZs) and false for internal monitors.

  Default: `F`.

  [``allow_spoof_services : set[port]``] Defines a set of services (responder ports) for which Bro should not generate alerts if it sees apparent spoofed traffic.

  Default: `110/tcp` (POP version 3; [RFC1939]). This default was chosen because in our experience one common form of benign spoof is an off-site laptop attempting to read mail while still configured to use its on-site address.

  [``allow_pairs : set[addr, addr]``] Defines pairs of source and destination addresses for which the source is allowed to connect to the destination. The intent with this variable is that the source or destination address will be a sensitive host (such as defined with `hot_srcs` or `hot_dsts`), for which this particular access should be allowed.

  Default: empty.

  [``allow_16_net_pairs : set[addr, addr]``] Defines pairs of source and destination /16 networks for which the source is allowed to connect to the destination, similar to `allow_pairs`. Note: The set is defined in terms of `addr`'s and not `net`'s. So, for example, rather than specifying `128.32.`, which is a `net` constant, you'd use `128.32.0.0` (an `addr` constant).

  Default: empty.

  [``hot_srcs : table[addr] of string``] Defines source addresses that should be considered ``hot''. A successfully established connection from such a source address is logged, unless one of the access exception variables such as `allow_pairs` also matches the connection. The value of the table gives an explanatory message as to why the source is hot; for example, `"known attacker site"`. Note: This value is not currently used, though it aids in documenting the policy script.

  Default: empty.

  Example: redefining `hot_srcs` using

      redef hot_srcs: table[addr] of string = {
          [ph33r.the.eleet.com] = "script kideez",
      };

  would result in Bro alerting on any traffic coming `ph33r.the.eleet.com`.

  [``hot_dsts : table[addr] of string``] Same as `hot_srcs`, except for destination addresses.

  Default: empty.

  [``hot_src_24nets : table[addr] of string``] Defines /24 source networks should be considered ``hot,'' similar to `hot_srcs`. Deficiency: Other network masks, particularly /16, should be provided.

  Default: empty.

  Example: redefining `hot_src_24nets` using

      redef hot_src_24nets: table[addr] of string = {
          [198.81.129.0] = "CIA incoming!",
      };

  would result in Bro alerting on any traffic coming from the `198.81.129/24` network.

  [``hot_dst_24nets : table[addr] of string``] same as `hot_src_24nets`, except for destination networks.

  Default: empty.

  [``allow_services : set[port]``] Defines a set of services that are always allowed, regardless of whether the source or destination address is ``hot.''

  Default: `ssh`, `http`, `gopher` `ident`, `smtp`, `20/tcp` (FTP data).

  Note: The defaults are a bit unusual. They are intended for a quite open site with many services.

  [``allow_services_to : set[addr, port]``] Defines a set of services that are always allowed if the server is the given host, regardless of whether the source or destination address is ``hot.''

  Default: empty.

  Example: redefining `allow_services_to` using

      redef allow_services_to: set[addr, port] += {
          [ns.mydomain.com, [domain, 123/tcp]],
      } &redef;

  would result in Bro not alerting on any TCP DNS or NTP traffic heading to `ns.mydomain.com`. You might add this if `ns.mydomain.com` is also in `hot_dsts`, because in general you want to consider any access (other than DNS or NTP) as sensitive.

  [``allow_services_pairs : set[addr, addr, port]``] Defines a set of services that are always allowed if the connection originator is the first address and the responder (server) the second address.

  Default: empty.

  Example: redefining `allow_services_pairs` using

      redef allow_services_pairs: set[addr, addr, port] += {
          [ns2.mydomain.com, ns.mydomain.com, [domain, 123/tcp]],
      } &redef;

  would result in Bro not alerting on any TCP DNS or NTP traffic initiated from `ns2.mydomain.com` to `ns.mydomain.com`.

  [``flag_successful_service : table[port] of string``] The opposite of `allow_services`. Defines a set of services that should always be flagged as sensitive, even if neither the source nor the destination address is ``hot.'' The `string` value in the table gives the reason for why the service is considered hot. Note: Bro currently does not use these explanatory messages.

  Default: `31337/tcp` (a popular backdoor because in stylized lettering it spells `ELEET`) and `2766/tcp` (the Solaris `listen` service, in our experience rarely used legitimately in wide-area traffic).

  Note: Bro can flag these services erroneously when a server happens to run a different service on the same port. For example, if you're not running the FTP analyzer, then Bro won't know that FTP data connections using ephemeral ports in fact belong to legitimate FTP traffic, and will flag any that coincide with these services. A related problem arises when a user has configured their SSH access to tunnel FTP control channels through the FTP connection, but not the corresponding data connections (so they don't pay the expense of encrypting the data transfers), so again Bro can't recognize that the ephemeral ports used for the data connections does not reflect the presumed sensitive service.

  Example: redefining `flag_successful_service` using

      redef flag_successful_service: table[port] of string += {
              [1524/tcp] = "popular backdoor",
      };

  would result in Bro also alerting on any successful connection to a server running on TCP port 1524.

  [``flag_successful_inbound_service : table[port] of string``] The same as `flag_
  [0]successful_
  [0]service`, except only applies to connections with a remote initiator and a local responder (determined by finding the responder address in `local_nets`).

  Default: `1524/tcp` (`ingreslock`, a popular backdoor because an attacker can place an entry for the backdoor in /etc/inetd.conf using a service name rather than a raw port number, and hence more likely to appear legitimate to casual inspection). Note: There's no compelling reason why `ingreslock` is in this table rather than the more general `flag_successful_service`, though it does tend to result in a few more false hits than the others, presumably because it's a lower port number, and hence more likely on some systems to be chosen for an ephemeral port. `ingreslock`

  Note: Symmetry would call for `flag_successful_outbound_service`. This hasn't been implemented in Bro yet simply because the Bro development site has a threat model structured primarily around external threats.

  [``terminate_successful_inbound_service : table[port] of string``] The same as `flag_
  [0]successful_
  [0]inbound_
  [0]service`, except invokes `terminate_connection` in an attempt to terminate the connection.

  Default: empty.

  Note: As for `flag_
  [0]successful_
  [0]inbound_
  [0]service`, it would be symmetric to have `terminate_
  [0]successful_
  [0]outbound_
  [0]service`, and also to have a more general `terminate_
  [0]successful_
  [0]service`.

  [``flag_rejected_service : table[port] of string``] Similar to `flag_successful_service`, except applies to connections that a server rejects. For example, you could detect a particular, failed Linux mountd attack by adding `10752/tcp` to this table, since that happens to be the port used by the commonly available version of the exploit for its backdoor if the attack succeeds. Note: You would of course likely also want to put `10752/tcp` in `flag_successful_service`; or put the entire `flag_rejected_service` table into `flag_successful_service`, as discussed in § .

  Default: none.

  Deficiency: It might make sense to have `flag_attempted_service`, which doesn't require that a server actively reject the connection, but Bro doesn't currently have this.

##
`hot` functions

The `hot` module defines two functions for external use:

  [``check_spoof`(c: connection): bool``` ] checks the originator and responder addresses of the given connection to determine if they are both local (and the connection is not explicitly allowed in `allow_spoof_services`). If so, and if `same_local_net_is_spoof` is true, then marks the connection as ``hot''.

  The function also checks for a specific denial of service attack, the ``Land'' attack, in which the addresses are the same and so are the ports. If so, then it generates a `conn_weird` event with a name of `"Land_attack"`. It makes this check even if `same_local_net_is_spoof` is false.

  Returns: true if the connection is now hot (or was upon entry), false otherwise.

  [``check_hot`(c: connection, state: count): bool``` ] checks the given connection against the various policy variables discussed above, and bumps the connection's `hot` field if it matches the policies for being sensitive, and does not match the various exceptions. It also uses `check_spoof` to see if the connection reflects a possible spoofing attack; and terminates the connection if `terminate_successful_service` indicates so.

  Table 7.3: Different connection states to use when calling `check_hot`.
  State | Meaning | Tests
  `CONN_ATTEMPTED` | Connection attempted, no reply seen. Note that you should also use this value for scans with indeterminant state, such as possible stealth scans. For example, `connection_half_finished` does this. | `check_spoof`.
  `CONN_ESTABLISHED` | Connection established. Also used for connections apparently established, per `partial_connection`. | `check_spoof`, `flag_successful_service`, `flag_successful_inbound_ [0]service`, `allow_services_to`, `terminate_successful_ [0]inbound_ [0]service`.
  `APPL_ESTABLISHED` | The connection has reached application-layer establishment. For example, for Telnet or Rlogin, this is after the user has authenticated. | `allow_services_to`, `allow_service_pairs`, `allow_pairs`, `allow_16_net_pairs`, `hot_srcs`, `hot_dsts`, `hot_src_24nets`, `hot_ [0]dst_ [0]24nets`.
  `CONN_FINISHED` | The connection has finished, either cleanly or abnormally (for example, `connection_reset`). | Same as `APPL_ESTABLISHED`, if the connection exchanged non-zero amounts of data in both directions, and if the service wasn't one of the ones that generates `APPL_ESTABLISHED`.
  `CONN_REJECTED` | The connection attempt was rejected by the server. | `check_spoof`, `flag_rejected_service`.

  The caller indicates the connection's state in the second parameter to the function, using one of the values given in Table 7.5.2. As noted in the Table, the processing differs depending on the state.

  In general, the pattern is to make one call when the connection is first seen, either `CONN_ATTEMPTED`, `CONN_ESTABLISHED`, or `CONN_REJECTED`. If the application is one for which connections should only be considered ``established'' after a successful pre-exchange between originator and responder, then a subsequent call is made with a state of `APPL_ESTABLISHED`. The idea here is to provide a way to filter out what are in fact not really successful connections so that they are not analyzed in terms of successful service. Finally, for services that don't use `APPL_ESTABLISHED`, a call is made instead when the connection finishes for some reason, using state `CONN_FINISHED`. Note: This approach delays alerting until the connection is over, which might be later than you want, in which case you may need to edit `check_hot` to provide the desired functionality.

  Returns: true if the connection is now hot (or was upon entry), false otherwise.

Next: The scan Analyzer Up: Analyzers and Events Previous: Site-specific information Contents Index