The scan Analyzer
Keywords: doc-html

Next: The port-name Module Up: Analyzers and Events Previous: The hot Analyzer Contents Index
Subsections

- `scan` variables
- `scan` functions
- `scan` event handlers

#
The `scan` Analyzer

The `scan` analyzer detects connection attempts to numerous machines (address scanning), connection attempts to many different services on the same machine (port scanning), and attempts to access many different accounts (password guessing). The basic methodology is to use tables to keep track of the distinct addresses and ports to which a given host attempts to connect, and to trigger alerts when either of these reaches a specified size. Deficiency: As currently written, the analyzer will not detect distributed scans, i.e., when many sites are used to probe individually just a few, but together a large number, of ports or addresses.

A powerful technique that Bro potentially provides is dropping border connectivity with remote scanning sites, though you must supply the magic script to talk with your router and effect the block. See `drop_address` below for a discussion of the interface provided. Note: Naturally, providing this capability means you might become vulnerable to denial-of-service attacks in which spoofed packets are used in an attempt to trigger a block of a site to which you want to have access.

##
`scan` variables

In addition to internal variables for its bookkeeping, the analyzer provides the following redefinable variables:

  [``report_peer_scan : set[count]``] Generate a log message whenever a remote host (as determined by `is_local_addr`) has attempted to connect to the given number of distinct hosts.

  Default: `{ 100, 1000, 10000, }`. So, for example, if a remote host attempts to connect to 3,500 different local hosts, a report will be generated when it makes the 100th attempt, and another when it makes the 1,000th attempt.

  [``report_outbound_peer_scan : set[count]``] The same as `report_peer_scan`, except for connections initiated locally.

  Default: `{ 1000, 10000, }`.

  [``possible_port_scan_thresh : count``] Initially, port scan detection is done based on how many different ports a given host connects to, regardless of on which hosts. Once this threshold is reached, however, then the analyzer begins tracking ports accessed per-server, which is important for reducing false positives. Note: The reason this variable exists is because it is very expensive to track per-server ports accessed for every active host; this variable limits such tracking to only active hosts contacting a significant number of different ports.

  Default: `25`.

  [``report_accounts_tried : set[count]``] Whenever a remote host has attempted to access a number of local accounts present in this set, generate a log message. Each distinct username/password pair is considered a different access.

  Default: `{ 25, 100, 500, }`.

  [``report_remote_accounts_tried : set[count]``] The same, except for access to remote accounts rather than local ones.

  Default: `{ 100, 500, }`.

  [``skip_accounts_tried : set[addr]``] Do not do bookkeeping for account attempts for the given hosts.

  Default: empty.

  [``skip_outbound_services : set[port]``] Do not do outbound-scanning bookkeeping for connections involving the given services.

  Default: `allow_services`, `ftp`, `addl_web` (see next item).

  [``addl_web : set[port]``] Additional ports that should be considered as Web traffic (and hence skipped for outbound-scan bookkeeping).

  Default: `{ 81/tcp, 443/tcp, 8000/tcp, 8001/tcp, 8080/tcp, }`.

  [``skip_scan_sources : set[addr]``] Hosts that are allowed to address-scan without complaint.

  Default: `scooter.pa-x.dec.com`, `scooter2.av.pa-x.dec.com` (AltaVista crawlers; you get the idea.)

  [``skip_scan_nets_24 : set[addr, port]``] /24 networks that are allowed to address scan for the given port without complaint.

  Default: empty.

  [``can_drop_connectivity : bool``] True if the Bro has the capability of dropping connectivity, per `drop_address`.

  Default: false.

  [``shut_down_scans : set[port]``] Scans of these ports trigger connectivity-dropping (if the Bro is capable of dropping connectivity), unless `shut_down_all_scans` is defined (next item).

  Default: empty.

  [``shut_down_all_scans : bool``] Ignore `shut_down_scans` and simply drop all scans regardless of service.

  Default: false.

  [``shut_down_thresh : count``] Shut down connectivity after a host has scanned this many addresses.`

  Default: `100`.

  [``never_shut_down : set[addr]``] Purported scans from these addresses are never shut down.

  Default: the root name servers (`a.root-servers.net` through `m.root-servers.net`).

##
`scan` functions

The standard `scan` script provides the following functions:

  [``drop_address`(a: addr, msg: string)``` ] Drops external connectivity to the given address and logs a notification using the given message.

  Dropping connectivity requires all of the following to be true:

  - `can_drop_connectivity` is true.
  - The address is neither local nor a neighbor (§ ).
  - The address is not in `never_shut_down`.
  If these checks succeed, then the script simply attempts to invoke a shell script drop-connectivity with a single argument, the IP address to block. It is up to you to provide the script, using whatever interface to your router/firewall you have available.

  The function does not return a value.

  [``check_scan`(c: connection, established: bool, reverse: bool): bool``` ] Updates the analyzer's internal bookkeeping on the basis of the new connection `c`. If `established` is true, then the connection was successfully established, otherwise not. If `reverse` is true, then the function should consider the originator/responder fields in the connection's record as reversed. Note: This last is needed for some unusual new connections that may reflect stealth scanning. For example, when the event engine sees a SYN-ack without a corresponding SYN, it instantiates a new connection with an assumption that the SYN-ack came from the responder (and it missed the initial SYN either due to split routing (§ ), a packet drop (§ ), or Bro having started running after the initial SYN was sent).

  If the originating host's activity matches the policy defined by the variables above, then the analyzer logs this fact, and possibly attempts to drop connectivity to the originating host. The function also schedules an event for 24 hours in the future (or when Bro terminates) to generate a summary of the scanning activity (so if the host continues scanning, you get a report on how many hosts it wound up scanning). Deficiency: This time interval should be selectable.

  Note: Purported scans of the FTP data port (`20/tcp`) or the `ident` service (`113/tcp`) are never reported or dropped, as experience has shown they yield too many false hits.

  The function does not return a value.

##
`scan` event handlers

The standard `scan` script defines one event handler:

  [``account_tried (c: connection, user: string, passwd: string)``] The given connection made an attempt to access the given username and password. Each distinct username/password pair is considered a new access. The event handler generates a log message if the access matches the logging policy outlined above.

  Note: `account_tried` events are generated by `login` and `ftp` analyzers.

Next: The port-name Module Up: Analyzers and Events Previous: The hot Analyzer Contents Index