Manual Reference Pages - SHOKI.FILTERS (5)

NAME

shoki.filters - format of shoki filter rules files

Synopsis
Description
Examples
Authors
Bugs

SYNOPSIS

filter {

action = ACTION;

id = "STRING";

name = "STRING";

pcap = "PCAP";

[duration = INTEGER;]

[hex = STRING ];

[ip_options = STRING ];

[literal = STRING ];

[pcre = PCRE ];

[regex = REGEX ];

[scan_field = STRING ];

[severity = INTEGER;]

[severity = PRIORITY;]

[snaplen = INTEGER;]

[tcp_options = STRING ];

[threshold = INTEGER;]

[type = STRING ];

[quiet = INTEGER;]

[xref = STRING ];

};

DESCRIPTION

A shoki filter file contains a list of filter expressions for widgets which handle raw packet data (i.e., the lexer(1) widget). Each filter consists of the keyword `filter' followed by a filter declaration enclosed in curly braces and terminated with a semicolon. Non-quoted whitespace is ignored.
In the descriptions below: STRING refers to a double quoted string of arbitrary, non-newline characters. The double quote itself may be included as part of such a string by escaping it with a slash; INTEGER is an unquoted integer expression.
The following declarations are valid within a filter declaration:

action = ACTION;
The action declaration specifies the mode of operation of the filter. The Valid options are:

COUNT Count the number of times the filter matches in the input data. If the filter also contains a threshold declaration, the count will not be reported unless it is at least equal to the threshold value.

IGNORE
Ignore packets matching the given pcap expression. IGNORE filter rules have precidence over other filter rules.

INVERSE
Filter matches only if the filter expression does not match any of the packets in the input data.

LOG Log packets matching the given pcap expression.

NULL Take no action with packets matching the given pcap expression.

SAMPLE
Log a random sample of packets matching the given pcap expression and matching no other filter rule.

SCAN Log scans. Only meaningful in rules also containing a threshold declaration (not to be confused with the THRESHOLD action), a duration declaration, and a scan_field declaration.

SEARCH
Log packets matching the given pcap expression and the given search expression. Only meaningful in rules also containing a hex declaration, a literal declaration, a pcre declaration, or a regex declaration.

THRESHOLD
Log a single event when a specified number of packets matching the given pcap expression are seen within a specified time. Only meaningful in rules also containing a threshold declaration and a duration declaration.

id = STRING ;
Sets the unique identifier of the filter to STRING. Used primarily in disambiguation between rules (i.e., as an nonce in database lookups).

name = STRING ;
Sets the filter name to STRING. This is the text which is generally reported in conjunction with events generated by filter matches; the human-readable event identifier.

pcap = PCAP ;
Sets the pcap expression for the filter.

duration = INTEGER;
Only meaningful in SCAN and THRESHOLD rules, this defines the length of time the filter covers. See also the threshold declaration.

hex = STRING ;
Defines a hex literal search expression. Only meaningful in SEARCH filter rules.

ip_options = STRING ;
The rule will only match packets containing the IP options defined in STRING, which should be a semicolon-delimited list of valid IP options. Valid options are:

EOL (or END)
End of options list.

NOP (or NOOP)
No operation.

RR Record packet route.

TS (or TIMESTAMP)
Timestamp

SECURITY (or SEC)
Provide s, c, h, tcc.

LSRR Loose source routing.

SATID (or SID)
Satnet ID.

SSRR Strict source routing.

literal = STRING ;
Defines a literal search expression. Only meaningful in SEARCH filter rules.

pcre = PCRE ;
Defines a pcre search expression. PCRE must be a valid perl-compatible regular expression. Only meaningful in SEARCH rules.
NOTE: pcre support is not compiled in by default. If pcre support is not present, pcre search expressions will always return false (i.e., filters containing pcre expressions will never be matched).

regex = REGEX ;
Defines a regex search expression. REGEX must be valid POSIX extended regular expression. Only meaningful in SEARCH filter rules.

scan_field = STRING ;
Defines which packet header field is to be used in scan detection. Only meaningful in SCAN rules. Valid values are:

IP_V
IP_HL
IP_TOS
IP_LEN
IP_ID
IP_OFF
IP_TTL
IP_P
IP_SUM
IP_SRC
IP_DST
TH_SPORT (or TCP_SPORT)
TH_DPORT (or TCP_DPORT)
TH_SEQ (or TCP_SEQ)
TH_ACK (or TCP_ACK)
TH_OFF (or TCP_OFF)
TH_FLAGS (or TCP_FLAGS)
TH_RFLAGS (or TCP_RFLAGS)
TH_WIN (or TCP_WIN)
TH_SUM (or TCP_SUM)
TH_URP (or TCP_URP)
UH_SPORT (or UDP_SPORT)
UH_DPORT (or UDP_DPORT)
UH_ULEN (or UDP_ULEN)
UH_SUM (or UDP_SUM)
ICMP_TYPE
ICMP_CODE
ICMP_CKSUM
SPORT
DPORT

severity = INTEGER;
severity = PRIORITY;
Defines the severity level of the rule. The severity level semantics follow standard syslog(2) conventions. Either the name or number may be used.

EMERG (or 0)
ALERT (or 1)
CRIT (or 2)
ERR (or 3)
WARNING (or 4)
NOTICE (or 5)
INFO (or 6)
DEBUG (or 7)

tcp_options = STRING ;
The rule will only match packets containing the TCP options defined in STRING, which should be a semicolon-delimited list of valid TCP options. Valid options are:

EOL End of options list.

NOP No operation.

MAXSEG
Maximum segment size.

WINDOW (or WSCALE)
TCP window.

SACK_PERMITTED (or SACK_OK)
Selective ACK permitted.

SACK Selective ACK.

ECHO TCP echo request.

ECHOREPLY
TCP echo reply.

TIMESTAMP (or TS)
Timestamp.

threshold = INTEGER;
In SCAN and THRESHOLD rules this defines the number of matches that must occur within the specified time period. See also the duration declaration. NOTE: Threshold values of zero and one are ignored; use a LOG rule instead.
In COUNT rules, this defines the minimum count that will be logged.

type = STRING ;
Set the filter type to STRING. This is used primarily for grouping of filter rules.

quiet = INTEGER;
Not currently implemented. Sets the minimum length of time between successive matches of the filter.

xref = STRING ;
Defines a external reference. Any well-formatted string is accepted, but only CVE/CAN numbers are currently meaningful.

EXAMPLES

Match all IP packets:
filter {

name = "Example 1a (All IP)";

id = "EX1A";

action = LOG;

pcap = "ip";

};
Note that this is equivalent to:
filter { action=LOG; id="EX1A"; name="Example 1a (ALL IP)"; pcap="ip"; };
Match all TCP packets with destination port 25, the SYN flag set, and with a destination of any host in the 192.168.1.0/24 network except host 192.168.1.10:
filter {

name = "Example 1b (Mail traffic not to mail server)";

id = "EX1B";

action = LOG;

pcap = "(tcp[13] & 2 != 0) and (dst port 25) and (dst net 192.168.1.0 mask 255.255.255.0) and (not host 192.168.1.10)";

};
Match TCP packets containing the literal string foobar:
filter {

id = "EX2A";

name = "Example 2a (TCP search)";

action = SEARCH;

literal = "foobar";

pcap = "tcp";

};
Match TCP packets to port 80 containing the hex literal 485454502f312e31:
filter {

id = "EX2B";

name = "Example 2b (TCP hex search)";

action = SEARCH;

hex = "485454502f312e31";

pcap = "tcp and dst port 80";

};
Match TCP packets to ports 80 and 443 containing http:// or https://:
filter {

id = "EX2C";

name = "Example 2c (TCP regex search)";

action = SEARCH;

regex = "http[s]*://";

pcap = "tcp and (dst port 80 or dst port 443)";

};
Match when five (5) TCP packets with only the SYN flag set are seen within three (3) seconds:
filter { id = "EX3";

name = "Example 3 (SYN threshold)";

pcap = "tcp[13] == 2";

action = THRESHOLD;

threshold = 5;

duration = 3;

};
Match when TCP or UDP packets with seven (7) different destination ports are directed at 192.168.1.10 within four (4) seconds:
filter {

name = "Example 4 (Port scan)";

id = "EX4";

pcap = "(tcp or udp) and dst host 192.168.1.10";

action = SCAN;

scan_field = "TH_DPORT";

threshold = 7;

duration = 4;

};
Match any TCP packet with the MAXSEG, SACK_OK, and TCPOPT_TS TCP option set (in that order):
filter {

name = "Example 5 (TCP options)";

id = "EX5";

action = LOG;

pcap = "tcp";

tcp_options = "MAXSEG;SACK_OK;TCPOPT_TS";

};

AUTHORS

.An Stephen P. Berry <spb@meshuggeneh.net>
More information can be found at the shoki homepage:

BUGS

Check the README at the top of the source tree.

November 27, 2003

SHOKI.FILTERS (5)

shoki

Generated by manServer 1.07 from shoki.filters.5 using doc macros.

	action = ACTION;
	id = "STRING";
	name = "STRING";
	pcap = "PCAP";
	[duration = INTEGER;]
	[hex = STRING ];
	[ip_options = STRING ];
	[literal = STRING ];
	[pcre = PCRE ];
	[regex = REGEX ];
	[scan_field = STRING ];
	[severity = INTEGER;]
	[severity = PRIORITY;]
	[snaplen = INTEGER;]
	[tcp_options = STRING ];
	[threshold = INTEGER;]
	[type = STRING ];
	[quiet = INTEGER;]
	[xref = STRING ];

action = ACTION;
	The action declaration specifies the mode of operation of the filter. The Valid options are:

COUNT	Count the number of times the filter matches in the input data. If the filter also contains a threshold declaration, the count will not be reported unless it is at least equal to the threshold value.
IGNORE
	Ignore packets matching the given pcap expression. IGNORE filter rules have precidence over other filter rules.
INVERSE
	Filter matches only if the filter expression does not match any of the packets in the input data.
LOG	Log packets matching the given pcap expression.
NULL	Take no action with packets matching the given pcap expression.
SAMPLE
	Log a random sample of packets matching the given pcap expression and matching no other filter rule.
SCAN	Log scans. Only meaningful in rules also containing a threshold declaration (not to be confused with the THRESHOLD action), a duration declaration, and a scan_field declaration.
SEARCH
	Log packets matching the given pcap expression and the given search expression. Only meaningful in rules also containing a hex declaration, a literal declaration, a pcre declaration, or a regex declaration.
THRESHOLD
	Log a single event when a specified number of packets matching the given pcap expression are seen within a specified time. Only meaningful in rules also containing a threshold declaration and a duration declaration.

id = STRING ;
	Sets the unique identifier of the filter to STRING. Used primarily in disambiguation between rules (i.e., as an nonce in database lookups).
name = STRING ;
	Sets the filter name to STRING. This is the text which is generally reported in conjunction with events generated by filter matches; the human-readable event identifier.
pcap = PCAP ;
	Sets the pcap expression for the filter.
duration = INTEGER;
	Only meaningful in SCAN and THRESHOLD rules, this defines the length of time the filter covers. See also the threshold declaration.
hex = STRING ;
	Defines a hex literal search expression. Only meaningful in SEARCH filter rules.
ip_options = STRING ;
	The rule will only match packets containing the IP options defined in STRING, which should be a semicolon-delimited list of valid IP options. Valid options are:
EOL (or END)
	End of options list.
NOP (or NOOP)
	No operation.
RR	Record packet route.
TS (or TIMESTAMP)
	Timestamp
SECURITY (or SEC)
	Provide s, c, h, tcc.
LSRR	Loose source routing.
SATID (or SID)
	Satnet ID.
SSRR	Strict source routing.

literal = STRING ;
	Defines a literal search expression. Only meaningful in SEARCH filter rules.
pcre = PCRE ;
	Defines a pcre search expression. PCRE must be a valid perl-compatible regular expression. Only meaningful in SEARCH rules. NOTE: pcre support is not compiled in by default. If pcre support is not present, pcre search expressions will always return false (i.e., filters containing pcre expressions will never be matched).
regex = REGEX ;
	Defines a regex search expression. REGEX must be valid POSIX extended regular expression. Only meaningful in SEARCH filter rules.
scan_field = STRING ;
	Defines which packet header field is to be used in scan detection. Only meaningful in SCAN rules. Valid values are:
IP_V IP_HL IP_TOS IP_LEN IP_ID IP_OFF IP_TTL IP_P IP_SUM IP_SRC IP_DST TH_SPORT (or TCP_SPORT) TH_DPORT (or TCP_DPORT) TH_SEQ (or TCP_SEQ) TH_ACK (or TCP_ACK) TH_OFF (or TCP_OFF) TH_FLAGS (or TCP_FLAGS) TH_RFLAGS (or TCP_RFLAGS) TH_WIN (or TCP_WIN) TH_SUM (or TCP_SUM) TH_URP (or TCP_URP) UH_SPORT (or UDP_SPORT) UH_DPORT (or UDP_DPORT) UH_ULEN (or UDP_ULEN) UH_SUM (or UDP_SUM) ICMP_TYPE ICMP_CODE ICMP_CKSUM SPORT DPORT

severity = INTEGER; severity = PRIORITY;
	Defines the severity level of the rule. The severity level semantics follow standard syslog(2) conventions. Either the name or number may be used.
EMERG (or 0) ALERT (or 1) CRIT (or 2) ERR (or 3) WARNING (or 4) NOTICE (or 5) INFO (or 6) DEBUG (or 7)

tcp_options = STRING ;
	The rule will only match packets containing the TCP options defined in STRING, which should be a semicolon-delimited list of valid TCP options. Valid options are:
EOL	End of options list.
NOP	No operation.
MAXSEG
	Maximum segment size.
WINDOW (or WSCALE)
	TCP window.
SACK_PERMITTED (or SACK_OK)
	Selective ACK permitted.
SACK	Selective ACK.
ECHO	TCP echo request.
ECHOREPLY
	TCP echo reply.
TIMESTAMP (or TS)
	Timestamp.

threshold = INTEGER;
	In SCAN and THRESHOLD rules this defines the number of matches that must occur within the specified time period. See also the duration declaration. NOTE: Threshold values of zero and one are ignored; use a LOG rule instead. In COUNT rules, this defines the minimum count that will be logged.
type = STRING ;
	Set the filter type to STRING. This is used primarily for grouping of filter rules.
quiet = INTEGER;
	Not currently implemented. Sets the minimum length of time between successive matches of the filter.
xref = STRING ;
	Defines a external reference. Any well-formatted string is accepted, but only CVE/CAN numbers are currently meaningful.

	name = "Example 1a (All IP)";
	id = "EX1A";
	action = LOG;
	pcap = "ip";

	name = "Example 1b (Mail traffic not to mail server)";
	id = "EX1B";
	action = LOG;
	pcap = "(tcp[13] & 2 != 0) and (dst port 25) and (dst net 192.168.1.0 mask 255.255.255.0) and (not host 192.168.1.10)";

	id = "EX2A";
	name = "Example 2a (TCP search)";
	action = SEARCH;
	literal = "foobar";
	pcap = "tcp";

	id = "EX2B";
	name = "Example 2b (TCP hex search)";
	action = SEARCH;
	hex = "485454502f312e31";
	pcap = "tcp and dst port 80";

	id = "EX2C";
	name = "Example 2c (TCP regex search)";
	action = SEARCH;
	regex = "http[s]*://";
	pcap = "tcp and (dst port 80 or dst port 443)";

	name = "Example 3 (SYN threshold)";
	pcap = "tcp[13] == 2";
	action = THRESHOLD;
	threshold = 5;
	duration = 3;

	name = "Example 4 (Port scan)";
	id = "EX4";
	pcap = "(tcp or udp) and dst host 192.168.1.10";
	action = SCAN;
	scan_field = "TH_DPORT";
	threshold = 7;
	duration = 4;

	name = "Example 5 (TCP options)";
	id = "EX5";
	action = LOG;
	pcap = "tcp";
	tcp_options = "MAXSEG;SACK_OK;TCPOPT_TS";

Manual Reference Pages - SHOKI.FILTERS (5)

NAME

CONTENTS

SYNOPSIS

DESCRIPTION

EXAMPLES

AUTHORS

BUGS