Project

General

Profile

Do not edit. This page has been migrated. See Converting_Wiki_Documentation_to_Sphinx.
h1. HTTP keywords

There are additional content modifiers that can provide protocol-specific capabilities at the application layer (if you are unfamiliar with content modifiers, please visit the page Payload keywords). These keywords make sure the signature checks only specific parts of the network traffic. For instance, to check specifically on the request URI, cookies, or the HTTP request or response body, etc.

Use http_method to match on the HTTP request method, http_uri or http_raw_uri to match on the request URI, http_stat_code to match on the response status code and http_stat_msg to match on the response status message.

It is important to understand the structure of HTTP requests and responses. A simple example of a HTTP request and response follows:

HTTP request

GET /index.html HTTP/1.0\r\n

GET is a request method. Examples of methods are: GET, POST, PUT, HEAD, etc. The URI path is /index.html and the HTTP version is HTTP/1.0. Several HTTP versions have been used over the years; of the versions 0.9, 1.0 and 1.1, 1.0 and 1.1 are the most commonly used today.

HTTP response

HTTP/1.0 200 OK\r\n
<html>
<title> some page </title>
</HTML>

In this example, HTTP/1.0 is the HTTP version, 200 the response status code and OK the response status message.

Another more detailed example:

Request:

Response:

Request:

Although cookies are sent in an HTTP header, you can not match on them with the http_header keyword. Cookies are matched with their own keyword, namely http_cookie.

Each part of the table belongs to a so-called buffer. The HTTP method belongs to the method buffer, HTTP headers to the header buffer etc. A buffer is a specific portion of the request or response that Suricata extracts in memory for inspection.

All previous described keywords can be used in combination with a buffer in a signature. The keywords distance and within are relative modifiers, so they may only be used within the same buffer. You can not relate content matches against different buffers with relative modifiers.

http_method

With the http_method content modifier, it is possible to match specifically and only on the HTTP method buffer. The keyword can be used in combination with all previously mentioned content modifiers such as: depth, distance, offset, nocase and within.

Methods are: GET, POST, PUT, HEAD, DELETE, TRACE, OPTIONS, CONNECT and PATCH.

Example of a method in a HTTP request:

Example of the purpose of method:

http_uri and http_raw_uri

With the http_uri and the http_raw_uri content modifiers, it is possible to match specifically and only on the request URI buffer. The keyword can be used in combination with all previously mentioned content modifiers like depth, distance, offset, nocase and within.

To learn more about the difference between http_uri and http_raw_uri, please read the information about HTTP-uri normalization.

Example of the URI in a HTTP request:

Example of the purpose of http_uri:

Example of the purpose of http_raw_uri:

uricontent

The uricontent keyword has the exact same effect as the http_uri content modifier. uricontent is a deprecated (although still supported) way to match specifically and only on the request URI buffer.

Example of uricontent:

The difference between http_uri and uricontent is the syntax:

When authoring new rules, it is recommended that the http_uri content modifier be used rather than the deprecated uricontent keyword.

http_header and http_raw_header

With the http_header content modifier, it is possible to match specifically and only on the HTTP header buffer. This contains all of the extracted headers in a single buffer, except for those indicated in the documentation that are not able to match by this buffer and have their own content modifier (e.g. http_cookie). The modifier can be used in combination with all previously mentioned content modifiers, like depth, distance, offset, nocase and within.

Note: the header buffer is normalized. Any trailing whitespace and tab characters are removed. See: http://lists.openinfosecfoundation.org/pipermail/oisf-users/2011-October/000935.html. Match on the http_raw_header buffer if you require the raw (non-normalized) headers.

Example of a header in a HTTP request:

Example of the purpose of http_header:

http_cookie

With the http_cookie content modifier, it is possible to match specifically and only on the cookie buffer. The keyword can be used in combination with all previously mentioned content modifiers like depth, distance, offset, nocase and within.

Note that cookies are passed in HTTP headers, but are extracted to a dedicated buffer and matched using their own specific content modifier.

Example of a cookie in a HTTP request:

Example of the purpose of http_cookie:

http_user_agent

The http_user_agent content modifier is part of the HTTP request header. It makes it possible to match specifically on the value of the User-Agent header. It is normalized in the sense that it does not include the "User-Agent: " header name and separator, nor does it contain the trailing carriage return and line feed (CRLF). The keyword can be used in combination with all previously mentioned content modifiers like depth, distance, offset, nocase and within. Note that the pcre keyword can also inspect this buffer when using the /V modifier.

An analysis into the performance of http_user_agent vs. http_header is found at: http://blog.inliniac.net/2012/07/09/suricata-http_user_agent-vs-http_header/

Normalization: leading spaces are not part of this buffer. So "User-Agent: \r\n" will result in an empty http_user_agent buffer.

Example of the User-Agent header in a HTTP request:

Example of the purpose of http_user_agent:

http_client_body

With the http_client_body content modifier, it is possible to match specifically and only on the HTTP request body. The keyword can be used in combination with all previously mentioned content modifiers like distance, offset, nocase, within, etc.

Example of http_client_body in a HTTP request:

Example of the purpose of http_client_body:

Note: how much of the request/client body is inspected is controlled in the suricata.yaml, in the "libhtp" section, via the request-body-limit setting.

http_stat_code

With the http_stat_code content modifier, it is possible to match specifically and only on the HTTP status code buffer. The keyword can be used in combination with all previously mentioned content modifiers like distance, offset, nocase, within, etc.

Example of http_stat_code in a HTTP response:

Example of the purpose of http_stat_code:

http_stat_msg

With the http_stat_msg content modifier, it is possible to match specifically and only on the HTTP status message buffer. The keyword can be used in combination with all previously mentioned content modifiers like depth, distance, offset, nocase and within.

Example of http_stat_msg in a HTTP response:

Example of the purpose of http_stat_msg:

http_server_body

With the http_server_body content modifier, it is possible to match specifically and only on the HTTP response body. The keyword can be used in combination with all previously mentioned content modifiers like distance, offset, nocase, within, etc. If the response body is gzip encoded, it is first uncompressed for inspection.

Note: how much of the response/server body is inspected is controlled in your suricata.yaml, in the "libhtp" section, via the response-body-limit setting.

file_data

With file_data, the HTTP response body is inspected, just like with http_server_body. The file_data keyword works a bit differently from the normal content modifiers; when used in a rule, all content matches following it in the rule are affected (modified) by it.

Example:

alert http any any -> any any (file_data; content:"abc"; content:"xyz";)

The file_data keyword affects all following content matches, until the pkt_data keyword is encountered or it reaches the end of the rule. This makes it a useful shortcut for applying many content matches to the HTTP response body, eliminating the need to modify each content match individually. If the response body is gzip encoded, it is first uncompressed for inspection.

Note: how much of the response/server body is inspected is controlled in your suricata.yaml, in the "libhtp" section via the response-body-limit setting.

NOTE: In 2.0.x, file_data is only supported for HTTP server bodies (specified as flow direction to_client). Starting with 2.1-dev and above, file_data is handled more intelligently per-protocol, supported with to_server for SMTP and to_client for HTTP.

urilen

The urilen keyword is used to match on the length of the request URI. It is possible to use the < and > operators, which indicate respectively smaller than and larger than.

The format of urilen is:

urilen:3;

Other possibilities are:


urilen:1;
urilen:>1;
urilen:<10;
urilen:10<>20;    (bigger than 10, smaller than 20)

Example:

Example of urilen in a signature:

You can specify whether the inspected URI buffer is either the normalized or the raw buffer by appending norm or raw:


urilen:<5,raw;

pcre

For information about the pcre keyword, check the pcre (Perl Compatible Regular Expressions) page.

fast_pattern

For information about the fast_pattern keyword, check the fast_pattern page.

method2.png (18.2 KB) Anne-Fleur Koolstra, 04/23/2011 07:17 AM

method1.png (23.8 KB) Anne-Fleur Koolstra, 04/23/2011 07:18 AM

uri1.png (4.9 KB) Anne-Fleur Koolstra, 04/23/2011 07:19 AM

header.png (16 KB) Anne-Fleur Koolstra, 04/23/2011 07:28 AM

header1.png (37.3 KB) Anne-Fleur Koolstra, 04/23/2011 07:29 AM

cookie.png (39.5 KB) Anne-Fleur Koolstra, 04/23/2011 07:29 AM

cookie1.png (47.2 KB) Anne-Fleur Koolstra, 04/23/2011 07:29 AM

client_body.png (17.7 KB) Anne-Fleur Koolstra, 04/23/2011 07:30 AM

client_body1.png (38.3 KB) Anne-Fleur Koolstra, 04/23/2011 07:30 AM

stat_code.png (2.24 KB) Anne-Fleur Koolstra, 04/23/2011 07:30 AM

stat-code1.png (24.7 KB) Anne-Fleur Koolstra, 04/23/2011 07:31 AM

stat_msg.png (1.96 KB) Anne-Fleur Koolstra, 04/23/2011 07:31 AM

stat_msg_1.png (24.5 KB) Anne-Fleur Koolstra, 04/23/2011 07:31 AM

fast_pattern.png (11.5 KB) Anne-Fleur Koolstra, 04/23/2011 07:31 AM

urilen.png (25.8 KB) Anne-Fleur Koolstra, 04/23/2011 07:32 AM

urilen1.png (48.5 KB) Anne-Fleur Koolstra, 04/23/2011 07:33 AM

Legenda_rules.png (13.2 KB) Anne-Fleur Koolstra, 04/23/2011 07:43 AM

method.png (15.3 KB) Anne-Fleur Koolstra, 04/27/2011 05:39 AM

uri.png (22.6 KB) Anne-Fleur Koolstra, 09/20/2011 09:56 AM

user_agent.png (29.4 KB) Anne-Fleur Koolstra, 01/31/2013 09:19 AM

user_agent_match.png (264 KB) Anne-Fleur Koolstra, 02/01/2013 10:16 AM

request.png (68.8 KB) Anne-Fleur Koolstra, 02/05/2013 10:41 AM

request2.png (48.5 KB) Anne-Fleur Koolstra, 02/05/2013 10:41 AM

file_data.png (11.6 KB) Anne-Fleur Koolstra, 02/05/2013 11:01 AM

response1.png (78.5 KB) Anne-Fleur Koolstra, 02/07/2013 08:13 AM

http_server_body.png (8.97 KB) Anne-Fleur Koolstra, 02/07/2013 08:58 AM

uricontent.png (52 KB) Anne-Fleur Koolstra, 04/11/2013 10:36 AM

uricontent1.png (6.12 KB) Anne-Fleur Koolstra, 04/11/2013 11:06 AM

http_uri.png (53.6 KB) Anne-Fleur Koolstra, 04/11/2013 11:16 AM