From: jason taylor Date: Fri, 5 Jan 2024 22:06:47 +0000 (+0000) Subject: doc: update http.user_agent keyword X-Git-Tag: suricata-8.0.0-beta1~1545 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8307168ae7124a73d46bcb298e6f14fa90b4087a;p=thirdparty%2Fsuricata.git doc: update http.user_agent keyword Ticket: 3025 Signed-off-by: jason taylor --- diff --git a/doc/userguide/rules/http-keywords.rst b/doc/userguide/rules/http-keywords.rst index 733ef7f6f1..58ba1f6ec3 100644 --- a/doc/userguide/rules/http-keywords.rst +++ b/doc/userguide/rules/http-keywords.rst @@ -396,59 +396,50 @@ Example HTTP Request:: http.user_agent --------------- -The ``http.user_agent`` sticky buffer 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. - -Normalization: leading spaces **are not** part of this buffer. So -"User-Agent: \r\n" will result in an empty ``http.user_agent`` buffer. +The ``http.user_agent`` keyword is used to match on the User-Agent field that +can be present in HTTP request headers. -Example of the User-Agent header in a HTTP request: +It is possible to use any of the :doc:`payload-keywords` with the +``http.user_agent`` keyword. +Example HTTP Request:: -Example of the purpose of ``http.user_agent``: + GET /index.html HTTP/1.1 + User-Agent: Mozilla/5.0 + Cookie: PHPSESSION=123 + Host: suricata.io +.. container:: example-rule -Notes -~~~~~ + alert http $HOME_NET any -> $EXTERNAL_NET any (msg:"HTTP User-Agent Example"; \ + flow:established,to_server; :example-rule-options:`http.user_agent; \ + content:"Mozilla/5.0";` bsize:11; classtype:bad-unknown; sid:90; rev:1;) -- The ``http.user_agent`` buffer will NOT include the header name, - colon, or leading whitespace. i.e. it will not include - "User-Agent: ". +.. note:: The ``http.user_agent`` buffer does not include the header name (User-Agent), + colon, leading whitespace, or ending CRLF. -- The ``http.user_agent`` buffer does not include a CRLF (0x0D - 0x0A) at the end. If you want to match the end of the buffer, use a - relative ``isdataat`` or a PCRE (although PCRE will be worse on - performance). +.. note:: Using the ``http.user_agent`` generally provides better performance + than using :ref:`http.header`. -- If a request contains multiple "User-Agent" headers, the values will +.. note:: If a request contains multiple "User-Agent" headers, the values will be concatenated in the ``http.user_agent`` buffer, in the order seen from top to bottom, with a comma and space (", ") between each of them. - Example request:: - - GET /test.html HTTP/1.1 - User-Agent: SuriTester/0.8 - User-Agent: GGGG - - ``http.user_agent`` buffer contents:: - - SuriTester/0.8, GGGG +Example Duplicate User-Agent Header Request:: -- Corresponding PCRE modifier: ``V`` + GET /index.html HTTP/1.1 + User-Agent: Mozilla/5.0 + User-Agent: Chrome/2.0 + Cookie: PHPSESSION=123 + Host: suricata.io -- Using the ``http.user_agent`` buffer is more efficient when it - comes to performance than using the ``http.header`` buffer (~10% - better). +.. container:: example-rule -- `https://blog.inliniac.net/2012/07/09/suricata-http\_user\_agent-vs-http\_header/ `_ + alert http $HOME_NET any -> $EXTERNAL_NET any (msg:"HTTP User-Agent Example"; \ + flow:established,to_server; :example-rule-options:`http.user_agent; \ + content:"Mozilla/5.0, Chrome/2.0";` bsize:23; classtype:bad-unknown; sid:90; \ + rev:1;) .. _http.accept: