nwatch - watch an interface for TCP/IP traffic, storing the results in an nmap- and NDiff-compatible format.

 nwatch [-o|-output <filename-or-:tag>] [-p|-ports <port list>] 
        [-fi|-flush-interval <seconds>] [-si|-sample-interval <seconds>]
        [-h|-host <specification> ... -h|-host <specification N>]
        [-d|-device <device-name> ]

      <specification> = 
            [!]<host spec>[:<port spec>]

NWatch is a sniffer but can be conceptualized as a passive port scanner, in that it is only interested in IP traffic and it organizes results as a port scanner would. This adds the benefit that any tool which operates on such output (NDiff) can use the data. NWatch differs from an actual port scanner in many ways. For example, it will catch ports that are opened only transiently, something which a port scanner would likely miss. For network security NWatch is an excellent complement to regular port-scanning of your networks.

By default NWatch stays active indefinitely until it receives a SIGINT (CTRL-c). During that time it watches the default interface (eth0), tracking each IP host/port combination it discovers. The set of interesting hosts may be limited by supplying host specs described below; otherwise all traffic is tracked. The latter case would typically be useful for spying or perhaps sampling and analysis of net usage patterns rather than security monitoring.

The flush and sample intervals may be specified on the command line. The flush interval is the interval at which the tracked information will be written to disk. Flushing can also be triggered by sending the nwatch process a SIGHUP, or cancelling execution with SIGINT. SIGHUP will not interrupt execution of NWatch.

The sample interval is the length of time information is accumulated from the interface. Upon expiration of the interval, the data is flushed to disk, cleared, and sampling begins anew with a clean slate. This is useful if you want to store hourly, daily, etc. samples separately on disk.

Meaningful use of the sample interval requires a naming convention for the samples, such that the name will change each time a new sample is created. For example, with a daily sample, one would desire the date be embedded in the sample name. In NWatch, this is achieved by supplying an output string (-o option) containing %-style substitutions, as described in SUBSTITUTIONS below.

NWatch must have access to the watched interface; typically this means root.

NWatch requires NDiff, libpcap and the perl Net::Pcap module. See the documentation in the NWatch distribution for details.

-d <device-name>

-device <device-name>

Specifies the device to try to open. If not specified, nwatch (libpcap) will choose an interface.

-o <filename-or-:tag>

-output <filename-or-:tag>

Specifies the output filename, or optionally a data store tag, if begins with a colon (:). See DATA STORES below for more information. The default is %F-observed-%D%m%Y which evaluates to a string containing the hostname and date.

-h [!]<host ranges>[:<port ranges>]

-host [!]<host ranges>[:<port ranges>]

Adds a host or range of interesting hosts. NWatch will store information only for these hosts, ignoring all other traffic. For example-

    -h 192.168.2.2                   # one host
    -h 10.0.2.0-64                   # 65 hosts
    -host 192.168.1.0/26             # 64 hosts
    -host 192.168.*.*                # 65536 hosts

Port ranges are currently unsupported but the following discussion is included since the functionality will be added in an upcoming release. The above examples add hosts with all ports in a closed state. To restrict to a specific set of ports for the host, append a colon and a port spec. For example to add localhost with tcp ports 80 and 53.

    -host 127.0.0.1:80,53

Flags may be appended to change the protocol or state for a given port, for example:

    -host 127.0.0.1:7u

which adds echo service, udp port 7. The full list of port flags are as follows:

    t - tcp port  (default)
    u - udp port

NWatch defaults all ports to the unkown psuedo-state. A host spec is treated as a negation if it starts with !. If ports are specified as part of the host spec, those ports are deleted from any hosts previously added which fall in the host range. Host specs are applied in order as they appear on the command line, and their effects are cumulative.

[-fi|-flush-interval <seconds>]

Sets the flush interval to <seconds>. Default is 300 (5 minutes).

[-si|-sample-interval <seconds>]

Sets the sampling interval to <seconds> Default is 3600 * 24 (1 day).

NWatch uses NDiff's data storage facilities, which can manipulate results in regular nmap-format files, or can instead can handle storing and organizing the data on behalf of the user through a user-configurable data store. Whenever you precede a results tag with a colon (:), the tag will be treated as a unique key into a data store, identifying the results set. Currently the only supported data store is nmap format files placed in a preconfigured directory. Other types may be added at a later date. A legal tag may contain any alphanumeric string, plus dash, underscore, and dot. %-style substitutions in the ilk of the date command are also supported, allowing a tag to contain date, time, or the local hostname. See SUBSTITUTIONS below for more information.

When you specify an output filename or tag with NWatch's -o switch, you may embed %-style substitutions, which will be interpreted and replaced in the string.

%H = hour

%M = minute

%S = second

%D = day of month

%m = month of year (01-12)

%Y = year, four digits

%j = day of year, three digits

%w = day of week (0-6) one digit

Except where noted, the above items are two digits, and local time. All are zero-padded as appropriate. In addtion- For example, the default output string is %F-observed-%D%m%Y - if the hostname is pow and the date is 12 April, 2000, the result would be pow-observed-12042001.

Presently port specifications from the command line are ignored. Only host specifications are used to limit what traffic is tracked. The Pcap timeout facility is apparently broken, at least on linux. The result is that execution blocks until a packet is received. Therefore all signals and timed events trigger only after a packet has arrived. In particular, breaking with CTRL-C, the flush- and sample-interval, SIGHUP are affected. No support for human-readable hostnames and portnames. The state machines design is still evolving - nwatch can be fooled by deliberate spoofing as well as by certain specific everyday occurances. State machines are not garbage-collected so the nwatch process can grow rather large over time on a busy, varied network. The model for detecting filtered TCP and closed UDP ports is still rather simplistic. In addition, such ports will not be detected and flushed until NWatch exits.

James Levine <jdl@vinecorp.com>