Back

Trigger Scripts

A trigger action is a parameterised shell script, which nifpan executes for every event that matches its filter (which reduces to every event, if there is no filter).

The script's parameter tokens are substituted by values associated with the current packet, and the resulting string is then executed as a shell script. The Bourne shell is used, unless the SHELL environment variable is set.
The output from a trigger script goes to standard-output (immediately following the packet's printout), unless it makes its own provisions for redirection.

Syntax

 Trigger scripts use a similiar syntax to the printf() format argument, with single-character conversion specifications introduced by the percent-sign (%) character.
The following conversion specifications are understood:
 
A The event date, in DD/MM/YYYY format
B The event time, in hh:mm:ss.uuu format, where uuu represents milliseconds
C The event number within the logfile, starting from 1.
a Ethernet source address
b Ethernet destination address
c Ether Type
d LLC protocol
e LLC source address
f LLC destination address
g LLC control field
h SNAP OUI field
i IP source address
j IP destination address
k IP protocol
l IP Datagram ID
m IP datagram/fragment size, in bytes
n ICMP Type field
o ICMP Code field
p TCP sequence number number
q TCP Acknowledgement number
r TCP flags
s TCP or UDP source port
t TCP or UDP destination port
u ARP Operation ID
v ARP's target IP address
w For text-based protocols, eg. HTTP, this represents the entire protocol string conveyed by the current packet.

If the packet field referenced by a parameter is not present (eg. the %n parameter, for a non-ICMP packet), then the text n/a will be substituted instead.

Addresses are rendered in the same format as in the packet printout (ie. symbolic or numeric).

Example

 This trigger script simply prints out selected fields for each packet, appending its output to the file /tmp/trig.out
This script code is too large to supply as an argument to nifpan's -a switch, so it would be stored in a script file, whose pathname is supplied to nifpan's -A switch instead. Note that this input script is unmodified by nifpan.
cat << _EOF_ >>/tmp/trig.out
DATE: %A
TIME: %B
COUNT: %C

ETHSRC: %a
ETHDST: %b
IPSRC: %i
IPDST: %j

_EOF_
exit 0
More ambitious scripts could potentially be used to raise specific alarms, or as a crude form of intrusion detection, etc.

Back