NAME

yaf application labeling

DESCRIPTION

yaf can examine packet payloads and determine the application protocol in use within a flow, and export a 16-bit application label with each flow if yaf is built with application labeler support (using the --enable-applabel option to ./configure when yaf is built).

The exported application label uses the common port number for the protocol. For example, HTTP Traffic, independent of what port the traffic is detected on, will be labeled with a value of 80, the default HTTP port. Labels and rules are taken from a configuration file read by yaf at startup time. This rule file can be given on the command line with the --applabel-rules option or will try to be read from the default location of /usr/local/etc/yafApplabelRules.conf. If yaf was installed in a nonstandard location, it may be necessary to set the LTDL_LIBRARY_PATH environment variable to the location of the application label plugins. By default, yaf installs the application labeling plugins in /usr/local/lib/yaf.

Application labeling requires payload capture to be enabled with the --max-payload option. A minimum payload capture length of 384 bytes is recommended for best results.

Application labeling is presently experimental, and not guaranteed to be 100% accurate. However, application labels are supported in yafscii and SiLK via rwflowpack, flowcap, and rwipfix2silk.

CONFIG FILE FORMAT

The yafApplabelRules.conf file is the main source of information by which yaf determines application labels, and is required for application labeling support. By default, this file is located in /usr/local/etc/yafApplabelRules.conf.

The file is a list of label statements. A label statement begins with the keyword 'label', and has the following form:

label <N> <label-rule>

where <N> is the application label to apply (an unsigned 16-bit decimal integer in the range 0 to 65535), and <label-rule> specifies how to recognize the given application protocol. There are three types of label rules supported: regex, plugin, and signature.

A '#' symbol starts a comment in the rule file, and the rest of the line is a comment.

Rule Types

Regular Expression Rules

Regular Expression rules have the following form:

label <N> regex <expression>

The regular expression is compared against the available payload of the flow, and is a PCRE regular expression (see PCRE documentation for details). The expression is undelimited, and continues until the end of the line. <N> should be the well-known port of the protocol you are trying to detect with the <expression>. The regular expression is stored along with the application label <N> and will be compared first against the forward payload with source or destination port matching <N>. For example, if a flow has a destination port of 80, it will first be matched against the regular expression associated with application label 80. If a match does not occur, it starts at the beginning of the configuration file and proceeds down the list until it either finds a match or all options have been tried. If no match has occurred, it will repeat the previous steps with the reverse payload. For this reason, <N> should be the well-known port of the protocol. If the expression matches, the label <N> is applied to the flow.

Plugin Rules

Plugin rules are used to label application payload using a dynamically loaded library, written in C, and have the following form:

label <N> plugin <library> <function name> <arg-list>

where <library> is the name of the dynamically loadable library that exists somewhere within the LD_LIBRARY_PATH, the LTDL_LIBRARY_PATH, or a system library path, without the library extension name (usually .so); <function> is the name of the function to call within the library; and the optional <arg-list> is a space-separated list of arguments that will be passed as the argc and argv parameters to that function. See the source code to the plugins included with yaf for details on the specific protocol implementations. Similar to regular expression rules, <N> should be the well-known port of the application you are trying to detect because the plugin is first executed on flows which have a source or destination port matching <N>. The label <N> is applied to a flow if the flow passes all the requirements specified in the plugin.

Signature Rules

Signatures are the newest addition to the application labeling feature in yaf. Regular expression rules that only search for some expression, regardless of port, have the following form:

label <N> signature <expression>

The <expression> is compared against the available payload of the flow. All signature regular expressions are compared before port-based matching begins. The <expression> should be a PCRE Regular expression. The expression is undelimited, and continues until the end of the line. If the expression matches, the label <N> is applied to the flow, and port-based matching will not execute. For example, if you want to label flows that have the phrase "foo bar" with application label 9876, you would add the following to the yafApplabelRules.conf file:

label 9876 signature foo bar

MISCELLANEOUS

Regardless of rule type, each rule should have a unique application label. Note that once a match is found, application labeling will not continue to find a "better" match. Therefore, the order of the rules in the configuration file can make a difference. More common protocols should be listed at the beginning of the configuration file to increase efficiency. Regular expressions specifically crafted for reverse payloads are not recommended; unless there is no chance that they will match another protocol in the list. This issue may be addressed in a later release. Be aware that poorly crafted regular expressions can be detrimental to the efficiency of the software.

Since signature rule labels are usually not a well-known port, they will be compared against the payload in the same order as they appear in the configuration file.

If yaf is seeing traffic behind a web proxy, it may incorrectly label https (443) traffic as http (80) due to the HTTP Connect method that occurs before the Certificate exchange. To accurately label https traffic, uncomment the following line in the yafApplabelRules.conf file:

label <N> plugin proxyplugin proxyplugin_LTX_ycProxyScanScan

and set <N> to the port on which the proxy is listening for connections. This will not label https flows as <N>. It will set the application label to 443 and will allow the DPI plugin to capture and export X.509 Certificates.

LABELS

*NETBIOS is not included in the configuration file. It is contained in the DNS decoder due to its similarites with the DNS Protocol.

**RTCP is not included in the configuration file. It is contained in the RTP decoder due to similarities in the protocols.

AUTHORS

CERT Network Situational Awareness Group Engineering Team, http://www.cert.org/netsa