---

Manual Reference Pages  - SHOKI.DOCTRINE (5)

---

shoki.doctrine - format of shoki doctrine files

CONTENTS

Synopsis
Description
Examples
Authors
Bugs

doctrine {

	doctrine_id = "STRING";
	doctrine_name = "STRING";
	[doctrine_window = INTEGER;]
	[log_dname;]
	filter {
	action = ACTION;
	backfield = "STRING";
	backref = "STRING";
	id = "STRING";
	pcap = "PCAP";
	[hex = STRING ];
	[ip_options = STRING ];
	[literal = STRING ];
	[pcre = PCRE ];
	[regex = REGEX ];
	[severity = INTEGER;]
	[snaplen = INTEGER;]
	[tcp_options = STRING ];
	[terminal;]
	[threshold = INTEGER;]
	[type = STRING ];
	[quiet = INTEGER;]
	[window = FLOAT;]
	[xref = STRING ];

}; };

Doctrines allow an analyst to construct complex rules which match sequences or combinations of events rather than individual events. They are used by the ooda(8) and (indirectly) by the dlex(8) widget to build situational models from the raw event stream. See the ooda(8), ooda(7), and dlex(8) manpages for more details.

Each doctrine consists the keyword `doctrine' followed by a doctrine 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 a string by escaping it with a slash; INTEGER is an unquoted integer expression.

The following declarations are valid within a doctrine declaration:

doctrine_id = STRING ;
	Sets the unique identifier of the doctrine to STRING. Used primarily in disambiguation between doctrines (i.e., as a nonce in database lookups).
doctrine_name = STRING ;
	Sets the doctrine name to STRING. This is just the human-readable doctrine identifier.
doctrine_window = INTEGER;
	If specified, requires that all events (i.e., filter matches) in the doctrine must be matched within a total of INTEGER seconds.
log_dname;
	Specifies that the alert logged when the doctrine matches should include the name of the doctrine rather than the name of the last matching doctrine filter. By default, the name of the last matching filter is used as the text for the alert.
filter { FILTER };
	Defines a filter expression. Except where noted below, filter definitions are identical to those described in the shoki.filters(5) manpage.
backfield = STRING ; backref = STRING ;
	The backfield and backref declarations specify the conditions which events must meet before they are used as inputs into the doctrine filter. Both must be present in each doctrine filter. The backfield declaration specifies the event variable which is to be matched, and the backref declaration defines the value of that variable. For example:

	backfield = "id";
	backref = "EX1A";

would match events whose unique event ID is EX1A. The contents of events matching this back reference will be used for dynamic filter construction. See the pcap section below.

pcap = STRING ;
	Defines a template for dynamic filter construction. Variable substitution is done on STRING to create a new pcap expression. The values used for the variable substitution are taken from events matching the filter defined via the backref declaration above. Valid variables 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

terminal;
	If present in the filter declaration, the terminal directive specifies that the doctrine should match when the filter matches. Note that a doctrine may have more than one terminal filter.
window = FLOAT;

Assume a filter that matches incoming SYNs to port 25 on all machines except a known MTA (an example filter from the shoki.filters(5) manpage):

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.2 55.255.0) and (not host 192.168.1.10)";

};

A doctrine which will log an event (with the ID DOC1F1) whenever the destination host of any packets matching the filter above responds with a SYN-ACK:

doctrine {

	doctrine_id = "DOC1";
	doctrine_name = "Non-MTA Mail Server Active";
	doctrine_window = 10.0;
	filter {
	backfield = "id";
	backref = "EX1B";
	id = "DOC1F1";
	action = "LOG";
	pcap = "src host IP_DST and src port TH_DPORT and dst port TH_SPORT and tcp[13] == 10";

}; };

The same thing, but also log an event (ID DOC1F2) whenever a packet containing the literal gotcha is sent by the source of the first packet (the one matching the EX1B event, which in turn is the destination of the second packet, matching the DOC1F1 event):

doctrine {

	doctrine_id = "DOC1";
	doctrine_name = "Non-MTA Mail Server Active";
	doctrine_window = 10.0;
	filter {
	backfield = "id";
	backref = "EX1B";
	id = "DOC1F1";
	action = "LOG";
	pcap = "src host IP_DST and src port TH_DPORT and dst port TH_SPORT and tcp[13] == 10";

};

	filter {
	backfield = "id";
	backref = "DOC1F1";
	action = "SEARCH";
	literal = "gotcha";
	pcap = "src host IP_DST and src port TH_DPORT and dst port TH_SPORT";

}; };

.An Stephen P. Berry <spb@meshuggeneh.net>

More information can be found at the shoki homepage:

Check the README at the top of the source tree.