diff --git a/doc/sphinx/http-keywords.rst b/doc/sphinx/http-keywords.rst index e4363c79ce..63a52d56b5 100644 --- a/doc/sphinx/http-keywords.rst +++ b/doc/sphinx/http-keywords.rst @@ -11,7 +11,6 @@ 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 diff --git a/doc/sphinx/payload-keywords.rst b/doc/sphinx/payload-keywords.rst index f9c34b1eeb..c6889cddd8 100644 --- a/doc/sphinx/payload-keywords.rst +++ b/doc/sphinx/payload-keywords.rst @@ -4,6 +4,7 @@ Payload Keywords .. toctree:: :maxdepth: 2 + pcre fast-pattern Payload keywords inspect the content of the payload of a packet or diff --git a/doc/sphinx/pcre.rst b/doc/sphinx/pcre.rst new file mode 100644 index 0000000000..74f8024d91 --- /dev/null +++ b/doc/sphinx/pcre.rst @@ -0,0 +1,139 @@ +pcre (Perl Compatible Regular Expressions) +========================================== + +The keyword pcre matches specific on regular expressions. More +information about regular expressions can be found here +http://en.wikipedia.org/wiki/Regular_expression. + +The complexity of pcre comes with a high price though: it has a +negative influence on performance. So, to mitigate Suricata from +having to check pcre often, pcre is mostly combined with 'content'. In +that case, the content has to match first, before pcre will be +checked. + +Format of pcre:: + + “//opts”; + +Example of pcre:: + + pcre:”/[0-9]{6}/”; + +In this example there will be a match if the payload contains six +numbers following. + +Example of pcre in a signature: + +.. image:: pcre/pcre.png + +There are a few qualities of pcre which can be modified: + +* By default pcre is case-sensitive. +* The . (dot) is a part of regex. It matches on every byte except for + newline characters. +* By default the payload will be inspected as one line. + +These qualities can be modified with the following characters:: + + i pcre is case insensitive + s pcre does check newline characters + m can make one line (of the payload) count as two lines + +These options are perl compatible modifiers. To use these modifiers, +you should add them to pcre, behind regex. Like this:: + + pcre: “//i”; + +*Pcre compatible modifiers* + +There are a few pcre compatible modifiers which can change the +qualities of pcre as well. These are: + +* ``A``: A pattern has to match at the beginning of a buffer. (In pcre + ^ is similar to A.) +* ``E``: Ignores newline characters at the end of the buffer/payload. +* ``G``: Inverts the greediness. + +Suricata's modifiers +~~~~~~~~~~~~~~~~~~~~ + +Suricata has its own specific pcre modifiers. These are: + +* ``R``: Match relative to the last pattern match. It is similar to distance:0; +* ``U``: Makes pcre match on the normalized uri. It matches on the + uri_buffer just like uricontent and content combined with http_uri.U + can be combined with /R. Note that R is relative to the previous + match so both matches have to be in the HTTP-uri buffer. Read more + about [[HTTP-uri normalization]]. + +.. image:: pcre/pcre3.png + +.. image:: pcre/pcre4.png + +.. image:: pcre/pcre5.png + +.. image:: pcre/pcre6.png + +* ``I``: Makes pcre match on the HTTP-raw-uri. It matches on the same + buffer as http_raw_uri. I can be combined with /R. Note that R is + relative to the previous match so both matches have to be in the + HTTP-raw-uri buffer. Read more about [[HTTP-uri normalization]]. + +.. image:: pcre/pcre7.png + +.. image:: pcre/pcre8.png + +* ``P``: Makes pcre match on the HTTP- request-body. So, it matches on + the same buffer as http_client_body. P can be combined with /R. Note + that R is relative to the previous match so both matches have to be + in the HTTP-request body. + +* ``Q``: Makes pcre match on the HTTP- response-body. So, it matches + on the same buffer as http_server_body. Q can be combined with + /R. Note that R is relative to the previous match so both matches + have to be in the HTTP-response body. + +* ``H``: Makes pcre match on the HTTP-header. H can be combined with + /R. Note that R is relative to the previous match so both matches have + to be in the HTTP-header body. + +* ``D``: Makes pcre match on the unnormalized header. So, it matches + on the same buffer as http_raw_header. D can be combined with + /R. Note that R is relative to the previous match so both matches + have to be in the HTTP-raw-header. + +* ``M``: Makes pcre match on the request-method. So, it matches on the + same buffer as http_method. M can be combined with /R. Note that R + is relative to the previous match so both matches have to be in the + HTTP-method buffer. + +* ``C``: Makes pcre match on the HTTP-cookie. So, it matches on the + same buffer as http_cookie. C can be combined with /R. Note that R + is relative to the previous match so both matches have to be in the + HTTP-cookie buffer. + +* ``S``: Makes pcre match on the HTTP-stat-code. So, it matches on the + same buffer as http_stat_code. S can be combined with /R. Note that + R is relative to the previous match so both matches have to be in + the HTTP-stat-code buffer. + +* ``Y``: Makes pcre match on the HTTP-stat-msg. So, it matches on the + same buffer as http_stat_msg. Y can be combined with /R. Note that + R is relative to the previous match so both matches have to be in + the HTTP-stat-msg buffer. + +* ``B``: You can encounter B in signatures but this is just for + compatibility. So, Suricata does not use B but supports it so it + does not cause errors. + +* ``O``: Overrides the configures pcre match limit. + +* ``V``: Makes pcre match on the HTTP-User-Agent. So, it matches on + the same buffer as http_user_agent. V can be combined with /R. Note + that R is relative to the previous match so both matches have to be + in the HTTP-User-Agent buffer. + +* ``W``: Makes pcre match on the HTTP-Host. So, it matches on the same + buffer as http_host. W can be combined with /R. Note that R is + relative to the previous match so both matches have to be in the + HTTP-Host buffer. diff --git a/doc/sphinx/pcre/pcre.png b/doc/sphinx/pcre/pcre.png new file mode 100644 index 0000000000..83c3185671 Binary files /dev/null and b/doc/sphinx/pcre/pcre.png differ diff --git a/doc/sphinx/pcre/pcre3.png b/doc/sphinx/pcre/pcre3.png new file mode 100644 index 0000000000..3a55404fc9 Binary files /dev/null and b/doc/sphinx/pcre/pcre3.png differ diff --git a/doc/sphinx/pcre/pcre4.png b/doc/sphinx/pcre/pcre4.png new file mode 100644 index 0000000000..0b60132fac Binary files /dev/null and b/doc/sphinx/pcre/pcre4.png differ diff --git a/doc/sphinx/pcre/pcre5.png b/doc/sphinx/pcre/pcre5.png new file mode 100644 index 0000000000..7884e91b53 Binary files /dev/null and b/doc/sphinx/pcre/pcre5.png differ diff --git a/doc/sphinx/pcre/pcre6.png b/doc/sphinx/pcre/pcre6.png new file mode 100644 index 0000000000..ca73a902e9 Binary files /dev/null and b/doc/sphinx/pcre/pcre6.png differ