N Code Triggers
Home ] Up ] N Code Execution Model ] N Code Language ] N Code Data Types ] N Code Expressions ] N Code Statements ] N Code Variables and Scoping Rules ] N Code Filters ] N Code Function Definition ] N Code Tools ] [ N Code Triggers ]


N Code Triggers

[ identA = ] identB ( [ identC | identD : expression ] [ , identE | ... ].. )

IdentA will be assigned the internal cookie value representing the trigger condition. That value may be used in the 'off' statement, to delete the trigger.

IdentB identifies the trigger family. Currently the families are 'packet', 'ip', 'upd', and 'tcp'. Shortly, 'icmp' will also be added.

Within the parenthesis are comma separated lists of qualifiers for the trigger. The qualifier names, and their values are controlled by the trigger family, allowing an extensible way of describing details about the particular event the trigger is intended to monitor. There are two forms for any qualifier, the first form is simply an identifier name, the second form associates an expression with an identifier. That expression can by of any type, but the trigger family will check for the semantics of the expression when the trigger is constructed.

Triggers appear in two places in the syntax of .nfr. The first is inside the `filter' descriptions. The second is in the 'on' statement. Although these two forms are very similar, there is a minor difference; the 'filter' form of the trigger must be evaluated at the time the procedure is declared, and must therefore contain expressions which can be evaluated at compile time. The expressions which appear on the 'on' statement will be evaluated when the 'on' statement is performed. The expressions on the 'on' trigger can have values computed during the execution of the .nfr code.

Triggers describe network sniffing events, for example, packet arrival, or udp packet on port 23 arrival, or more data in a tcp stream.... etc. The syntax for triggers is very rich.

Examples: udp ( port : 23 ), packet (), tcp( start: "GET " )

The syntax for triggers looks like:

tname ( [ tid : tvalue [ , tid : tvalue ] ] )

The `tname' is the name of some component protocol stack, which recognizes triggers. Current examples include, packet, udp, tcp. The `tid's are recognized as part of the protocol stack, and will vary depending on the value of `tname'.

Here are udp's trigger

`tid's:

sport : match the expression `tvalue' with the source port of the udp packet.
dport : match the expression `tvalue' with the destination port of the udp packet.
port : match the expression `tvalue' with the source or the destination port of the udp packet.
src : match the expression `tvalue' with the source host address of the udp packet.
dst : match the expression `tvalue' with the destination host address of the udp packet.
host : match the expression `tvalue' with the source address or the destination host address of the udp packet.

Having no parameters-pairs inside the parentheses is also legal, and matches every packet. Here's some examples:

udp ( host : 122.12.34.4 )
This matches for exactly the host as either the source address or the destination address.

udp ( host : 122.12.3.4:255.255.255.0 )
This matches for the network 122.12.3.4:255.255.255.0 as either the source address or the destination address.

udp ( host : [ 122.12.3.0:255.255.255.0 , 141.12.4.23:255.255.255.0 ] )
This matches for one of two networks which the packet is either destined for, or coming from.

`tvalue' expressions are evaluated either at the time the filter is created, or when the `on' statement is executed.

Complicated expressions can be included even as part of the filter declaration, but every value must be evaluated at the time of compilation for the filter trigger to be used. Examples are provided in the following Filter section and in the On Statement section.

Tcp's triggers


port: match against the port.
sport: match against the source port.
dport: match against the source port.
src: match against the source address.
dst: match against the dest address.
host: match against the address ...
net: match against the network address ...
match: string match against the stream.
start: string match against the stream, trigger is called for all data in the stream starting at start. If you only include start, then the data is delivered to the trigger after the start pattern matches, while there's data to deliver in the stream.
end: string match against the stream, trigger is called between data matching start, and ending the end pattern. it ought to be legal to only match the end token. That would mean you get the end match, but you never start matching again.
client: when matching, compare against the requestor stream. the requestor path is the one performing the SYN.
server: when matching, compare against the server stream. (which is the destination port address)
opensession: when the engine notices the session
closesession: when the engine discards the session
save_length: the number of characters to match when we start finding characters in the stream. Other parameters salt the value.... which appears in tcp.connSave

Packet triggers

You can use 'packet' as a tname, but currently there are no tid's associated with packets. We may decide to include some triggers, depending on arising needs. For example, trigger on packet length, or packet type (ie: ethernet).

Timeout triggers

Timeout triggers provide a preliminary mechanism to have procedures called at specific time intervals. A common usage would be to have some code executed once a minute, or once an hour.

sec: seconds. msec: milliseconds. usec: (don't have any faith that it works for small values of usec) repeat: keep firing. once: perform the code associated with the trigger once.


Back ] Home ] Up ]