From: Jason Ish Date: Fri, 4 Dec 2015 16:26:53 +0000 (-0600) Subject: doc: finish off the rules section X-Git-Tag: suricata-3.2beta1~253 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b1bc0038aeecce4184e6c1ad7e51dfee43d1698d;p=thirdparty%2Fsuricata.git doc: finish off the rules section --- diff --git a/doc/sphinx/README.md b/doc/sphinx/README.md new file mode 100644 index 0000000000..fe06acda5e --- /dev/null +++ b/doc/sphinx/README.md @@ -0,0 +1,20 @@ +# Suricata User Guide + +This directory contains the Suricata Guide. The +[Sphinx Document Generate](http://sphinx-doc.org) is used to build the +documentation. For a primer os reStructuredText see the +[reStructuredText Primer](http://sphinx-doc.org/rest.html). + +## Development Server + +To help with writing documentation there is a development web server +with live reload. To get run the live server you will first need npm +installed then run the following: + + npm install + gulp serve + +Then point your browser at http://localhost:8000/_build/html/index.html + +Any edits to .rst files should trigger a "make html" and cause your +browser to refresh. diff --git a/doc/sphinx/adding-your-own-rules.rst b/doc/sphinx/adding-your-own-rules.rst index 303566fadc..cbf99b6d80 100644 --- a/doc/sphinx/adding-your-own-rules.rst +++ b/doc/sphinx/adding-your-own-rules.rst @@ -11,7 +11,7 @@ your console: sudo nano local.rules -Write your rule, see [[Suricata Rules]] and save it. +Write your rule, see :doc:`rules` and save it. Open yaml diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index a5af0169ea..6cd7f0cf4d 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -55,9 +55,9 @@ author = u'OISF' # built documents. # # The short X.Y version. -version = '2.1dev' +version = '3.0dev' # The full version, including alpha/beta/rc tags. -release = '3.0dev' +release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -201,7 +201,7 @@ html_static_path = ['_static'] #html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'Suricatadoc' +htmlhelp_basename = 'suricatadoc' # -- Options for LaTeX output --------------------------------------------- diff --git a/doc/sphinx/dnp3-keywords.rst b/doc/sphinx/dnp3-keywords.rst index 3e2748fd5d..7fe34f75de 100644 --- a/doc/sphinx/dnp3-keywords.rst +++ b/doc/sphinx/dnp3-keywords.rst @@ -1,5 +1,7 @@ -DNP3 keyword (Currently in development, not available yet) -========================================================== +DNP3 Keywords +============= + +**NOTE: DNP3 is currently in development and is not yet available.** The DNP3 keywords can be used to match on fields in decoded DNP3 messages. The keywords are based on Snort's DNP3 keywords and aim to diff --git a/doc/sphinx/dns-keywords.rst b/doc/sphinx/dns-keywords.rst new file mode 100644 index 0000000000..a437553c81 --- /dev/null +++ b/doc/sphinx/dns-keywords.rst @@ -0,0 +1,25 @@ +DNS Keywords +============ + +(from v2.0) + +There are some more content modifiers (If you are unfamiliar with +content modifiers, please visit the page :doc:`payload-keywords` These +ones make sure the signature checks a specific part of the +network-traffic. + + +dns_query +--------- + +With **dns_query** the DNS response body is inspected. The dns_query +keyword works a bit different from the normal content modifiers. When +used in a rule all contents following it are affected by it. Example: + + alert dns any any -> any any (msg:"Test dns_query option"; + dns_query; content:"google"; nocase; sid:1;) + +.. image:: dns-keywords/dns_query.png + +The dns_query keyword affects all following contents, until pkt_data +is used or it reaches the end of the rule. diff --git a/doc/sphinx/dns-keywords/dns_query.png b/doc/sphinx/dns-keywords/dns_query.png new file mode 100644 index 0000000000..35d16ca23e Binary files /dev/null and b/doc/sphinx/dns-keywords/dns_query.png differ diff --git a/doc/sphinx/file-keywords.rst b/doc/sphinx/file-keywords.rst index f35e3fee0a..4f13cceb3c 100644 --- a/doc/sphinx/file-keywords.rst +++ b/doc/sphinx/file-keywords.rst @@ -1,8 +1,8 @@ -File-keywords +File Keywords ============= Suricata comes with several rule keywords to match on various file -properties. They depend on properly configured [[File Extraction]]. +properties. They depend on properly configured [[**FIXME** File Extraction]]. filename -------- @@ -73,7 +73,7 @@ the rule and the scope will be per file. filemd5 ------- -Match file [[MD5]] against list of MD5 checksums. +Match file [[**FIXME** MD5]] against list of MD5 checksums. Syntax:: diff --git a/doc/sphinx/flow-keywords.rst b/doc/sphinx/flow-keywords.rst index f314f5978f..06658eebcc 100644 --- a/doc/sphinx/flow-keywords.rst +++ b/doc/sphinx/flow-keywords.rst @@ -1,17 +1,23 @@ -Flow-keywords +Flow Keywords ============= Flowbits ~~~~~~~~ -Flowbits consists of two parts. The first part describes the action it is going to perform, the second part is the name of the flowbit. +Flowbits consists of two parts. The first part describes the action it +is going to perform, the second part is the name of the flowbit. -There are multiple packets that belong to one flow. Suricata keeps those flows in memory. For more information see [[suricata.yaml#Flow]]. -Flowbits can make sure an alert will be generated when for example two different packets match. An alert will only be generated when both packets match. So, when the second packet matches, Suricata has to know if the first packet was a match too. Flowbits marks the flow if a packet matches so Suricata 'knows' it should generate an alert when the second packet matches as well. +There are multiple packets that belong to one flow. Suricata keeps +those flows in memory. For more information see +[[**FIXME** suricata.yaml#Flow]]. Flowbits can make sure an alert will be +generated when for example two different packets match. An alert will +only be generated when both packets match. So, when the second packet +matches, Suricata has to know if the first packet was a match +too. Flowbits marks the flow if a packet matches so Suricata 'knows' +it should generate an alert when the second packet matches as well. Flowbits have different actions. These are: - :: flowbits: set, name Will set the condition/'name', if present, in the flow. @@ -24,26 +30,37 @@ Flowbits have different actions. These are: when it matches and the condition is not set in the flow. flowbits: noalert Does not generate an alert for this rule. - Example: .. image:: flow-keywords/Flowbit_3.png +When you take a look at the first rule you will notice it would +generate an alert if it would match, if it were not for the 'flowbits: +noalert' at the end of that rule. The purpose of this rule is to check +for a match on 'userlogin' and mark that in the flow. So, there is no +need for generating an alert. The second rule has no effect without +the first rule. If the first rule matches, the flowbits sets that +specific condition to be present in the flow. Now with the second rule +there can be checked whether or not the previous packet fulfills the +first condition. If at that point the second rule matches, an alert +will be generated. - -When you take a look at the first rule you will notice it would generate an alert if it would match, if it were not for the 'flowbits: noalert' at the end of that rule. The purpose of this rule is to check for a match on 'userlogin' and mark that in the flow. So, there is no need for generating an alert. -The second rule has no effect without the first rule. If the first rule matches, the flowbits sets that specific condition to be present in the flow. Now with the second rule there can be checked whether or not the previous packet fulfills the first condition. If at that point the second rule matches, an alert will be generated. - -It is possible to use flowbits several times in a rule and combine the different functions. +It is possible to use flowbits several times in a rule and combine the +different functions. Flow ~~~~ -The flow keyword can be used to match on direction of the flow, so to/from client or to/from server. The to_client is equal to from_server, same goes for from_client and to_server - there's no difference, both names are supported due to historical reasons. It can also match if the flow is established or not. The flow keyword can also be use to say the signature has to match on stream only (only_stream) or on packet only (no_stream). +The flow keyword can be used to match on direction of the flow, so +to/from client or to/from server. The to_client is equal to +from_server, same goes for from_client and to_server - there's no +difference, both names are supported due to historical reasons. It can +also match if the flow is established or not. The flow keyword can +also be use to say the signature has to match on stream only +(only_stream) or on packet only (no_stream). So with the flow keyword you can match on: - :: to_client established only_stream @@ -51,20 +68,24 @@ So with the flow keyword you can match on: to_server from_server -**NOTE:** *from_server* and *to_client* are the same, and so are *to_server* and _from_client_. This comes from the original Snort language and we support it for compatibility reasons. - -These options from the different columns can be combined. You can use up to three options. For example: +**NOTE:** *from_server* and *to_client* are the same, and so are + *to_server* and _from_client_. This comes from the original Snort + language and we support it for compatibility reasons. +These options from the different columns can be combined. You can use +up to three options. For example: :: flow:to_client, established; flow:from_client, established, only_stream; - -There are different ways in which can be checked whether the connection is established or not. With tcp-traffic a connection starts with the three-way-handshake. In the flow is a part in which the state is set. There will be checked in which state the connection is. -In other cases there will be just checked if traffic comes from two sides. - +There are different ways in which can be checked whether the +connection is established or not. With tcp-traffic a connection starts +with the three-way-handshake. In the flow is a part in which the state +is set. There will be checked in which state the connection is. In +other cases there will be just checked if traffic comes from two +sides. Example: @@ -75,15 +96,14 @@ Example: Flowint ~~~~~~~ -For information, read the information on the [[flowint]] page. - +For information, read the information on the :doc:`flowint` page. stream_size ~~~~~~~~~~~ -The stream size option matches on traffic according to the registered amount of bytes by the sequence numbers. -There are several modifiers to this keyword: - +The stream size option matches on traffic according to the registered +amount of bytes by the sequence numbers. There are several modifiers +to this keyword: :: @@ -94,11 +114,10 @@ There are several modifiers to this keyword: >= greater than or equal <= less than or equal - Format :: stream_size:, , ; -Example of the stream-size keyword in a rule: \ No newline at end of file +Example of the stream-size keyword in a rule: diff --git a/doc/sphinx/http-keywords.rst b/doc/sphinx/http-keywords.rst index 63a52d56b5..623a301a8a 100644 --- a/doc/sphinx/http-keywords.rst +++ b/doc/sphinx/http-keywords.rst @@ -5,9 +5,9 @@ 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 +unfamiliar with content modifiers, please visit the page +:doc:`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. @@ -108,8 +108,8 @@ 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]]. +``http_raw_uri``, please read the information about [[**FIXME** +HTTP-uri normalization]]. Example of the URI in a HTTP request: @@ -236,7 +236,7 @@ Example of the purpose of ``http_client_body``: .. image:: http-keywords/client_body1.png Note: how much of the request/client body is inspected is controlled -in the [[suricata.yaml#Configure-Libhtp]], in the "libhtp" section, +in the [[**FIXME** suricata.yaml#Configure-Libhtp]], in the "libhtp" section, via the ``request-body-limit`` setting. http_stat_code @@ -283,7 +283,7 @@ 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#Configure-Libhtp]], in the "libhtp" section, +in your [[**FIXME** suricata.yaml#Configure-Libhtp]], in the "libhtp" section, via the ``response-body-limit`` setting. file_data @@ -309,7 +309,7 @@ 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#Configure-Libhtp]], in the "libhtp" section +in your [[**FIXME** suricata.yaml#Configure-Libhtp]], in the "libhtp" section via the ``response-body-limit`` setting. **NOTE:** In 2.0.x, ``file_data`` is only supported for HTTP server @@ -352,8 +352,7 @@ normalized or the raw buffer by appending ``norm`` or ``raw``:: pcre ---- -For information about the ``pcre`` keyword, check the [[pcre (Perl -Compatible Regular Expressions)]] page. +For information about the ``pcre`` keyword, check the :doc:`pcre` page. fast_pattern ------------ diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index af8d429c5b..40581d2bce 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -1,20 +1,9 @@ -.. Suricata documentation master file, created by - sphinx-quickstart on Fri Nov 6 10:12:25 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Suricata User Guide =================== .. toctree:: - :maxdepth: 2 + :numbered: + :titlesonly: what-is-suricata rules - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/doc/sphinx/meta.rst b/doc/sphinx/meta.rst index 6b5fbf5a71..4fb169f467 100644 --- a/doc/sphinx/meta.rst +++ b/doc/sphinx/meta.rst @@ -12,20 +12,27 @@ possible alert. The first part shows the filename of the signature. It is a convention that part is written in uppercase characters. -The format of msg is:: +The format of msg is: - msg: “...”; +:: -Example:: + + msg: “..........”; + +Example: + +:: msg:"ATTACK-RESPONSES 403 Forbidden"; msg:"ET EXPLOIT SMB-DS DCERPC PnP bind attempt"; -*It is a convention that msg is always the first keyword of a signature.* +:: + + It is a convention that msg is always the first keyword of a signature. Another example of msg in a signature: - alert tcp $HOME_NET any -> $EXTERNAL_NET any (**msg:"ET TROJAN Likely Bot Nick in IRC (USA +..)";** flow:established,to_server; content:"NICK "; depth:5; content:"USA"; within:10; reference:url,doc.emergingthreats.net/2008124; classtype:trojan-activity; sid:2008124; rev:5;) +.. image:: meta/msg.png In this example the red, bold-faced part is the msg. @@ -35,31 +42,38 @@ Sid (signature id) The keyword sid gives every signature its own id. This id is stated with a number. -The format of sid is:: +The format of sid is: + +:: sid:123; Example of sid in a signature: - alert tcp $HOME_NET any -> $EXTERNAL_NET any (msg:"ET TROJAN Likely Bot Nick in IRC (USA +..)"; flow:established,to_server; content:"NICK "; depth:5; content:"USA"; within:10; reference:url,doc.emergingthreats.net/2008124; classtype:trojan-activity; **sid:2008124;** rev:5;) +.. image:: meta/sid.png + +In this example the red, bold-faced part is the sid. Rev (Revision) -------------- The sid keyword is almost every time accompanied by rev. Rev represents the version of the signature. If a signature is modified, -the number of rev will be incremented by the signature writers. +the number of rev will be incremented by the signature writers. The +format of rev is: -The format of rev is:: +:: - rev:123; + rev:123; -*It is a convention that sid comes before rev, and both are the last of -all keywords.* +*It is a convention that sid comes before rev, and both are the last +of all keywords.* Example of rev in a signature: - alert tcp $HOME_NET any -> $EXTERNAL_NET any (msg:"ET TROJAN Likely Bot Nick in IRC (USA +..)"; flow:established,to_server; content:"NICK "; depth:5; content:"USA"; within:10; reference:url,doc.emergingthreats.net/2008124; classtype:trojan-activity; sid:2008124; **rev:5;**) +.. image:: meta/rev.png + +In this example the red, bold-faced part is the rev. Gid (group id) -------------- @@ -70,10 +84,12 @@ possible to modify this. It is not usual that it will be changed, and changing it has no technical implications. You can only notice it in the alert. - 10/01/2014-05:14:43.926704 [**] [**1**:2016903:5] ET USER_AGENTS Suspicious User-Agent (DownloadMR) [**] [Classification: A Network Trojan was detected] [Priority: 1] {TCP} 192.168.81.10:1032 -> 95.211.39.161:80 +Example of gid in a signature: + +.. image:: meta/gid.png -This is an example from the fast.log. In the part [1:2008124:2], 1 is -the gid (2008124 is the the sid and 2 the rev). +This is an example from the fast.log. +In the part [1:2008124:2], 1 is the gid (2008124 is the the sid and 2 the rev). Classtype --------- @@ -92,21 +108,16 @@ Example classtype:: config classification: web-application-attack,Web Application Attack,1 config classification: not-suspicious,Not Suspicious Traffic,3 -============== =================================== ====================== -Signature classification.config Alert -============== =================================== ====================== -web-attack web-attack, Web Application Attack, Web Application Attack - priority:1 -not-suspicious not-suspicious, Not Suspiscious Not Suspicious Traffic - Traffic, priority:3 -============== =================================== ====================== +.. image:: meta/classification.png -In the above table you see how classtype appears in signatures, the +In this example you see how classtype appears in signatures, the classification.config and the alert. Another example of classtype in a signature: - alert tcp $HOME_NET any -> $EXTERNAL_NET any (msg:"ET TROJAN Likely Bot Nick in IRC (USA +..)" flow:established,to_server; content:"NICK "; depth:5; content:"USA"; within:10; reference:url,doc.emergingthreats.net/2008124; **classtype:trojan-activity;** sid:2008124; rev:5;) +.. image:: meta/classtype.png + +In this example the red, bold-faced part is the classtype. Reference --------- @@ -115,7 +126,9 @@ The reference keywords direct to places where information about the signature and about the problem the signature tries to address, can be found. The reference keyword can appear multiple times in a signature. This keyword is meant for signature-writers and analysts who -investigate why a signature has matched. It has the following format:: +investigate why a signature has matched. It has the following format: + +:: reference: url, www.info.nl @@ -124,27 +137,30 @@ actual reference (notice here you can not use http before the url). There are different types of references: -========= =============================================== -system URL Prefix -========= =============================================== -bugtraq ``http://www.securityfocus.com/bid`` -cve ``http://cve.mitre.org/cgi-bin/cvename.cgi?name=`` -nessus ``http://cgi.nessus.org/plugins/dump.php3?id=`` -arachnids ``http://www.whitehats.com/info/IDS`` -mcafee ``http://vil.nai.com/vil/dispVirus.asp?virus_k=`` -url ``http://`` -========= =============================================== +type: + +:: + + system URL Prefix + bugtraq http://www.securityfocus.com/bid + cve http://cve.mitre.org/cgi-bin/cvename.cgi?name= + nessus http://cgi.nessus.org/plugins/dump.php3?id= + arachnids (No longer available but you might still encounter this in signatures.) + http://www.whitehats.com/info/IDS + mcafee http://vil.nai.com/vil/dispVirus.asp?virus_k= + url http:// -*Note that ararchnids is no longer available but may still be -encountered in signatures.* +For example bugtraq will be replaced by the full url: -For example bugtraq will be replaced by the full url:: +:: reference: bugtraq, 123; http://www.securityfocus.com/bid Example of reference in a signature: - alert tcp $HOME_NET any -> $EXTERNAL_NET any (msg:"ET TROJAN Likely Bot Nick in IRC (USA +..)" flow:established,to_server; content:"NICK "; depth:5; content:"USA"; within:10; **reference:url,doc.emergingthreats.net/2008124;** classtype:trojan-activity; sid:2008124; rev:5;) +.. image:: meta/reference.png + +In this example the red, bold-faced part is the action. Priority -------- @@ -154,15 +170,18 @@ range from 1 till 255. The numbers 1 to 4 are most often used. Signatures with a higher priority will be examined first. The highest priority is 1. Normally signatures have already a priority through class type. This can be overruled with the keyword priority. The -format of priority is:: +format of priority is: + +:: priority:1; Metadata -------- -Suricata ignores the words behind meta data. -Suricata supports this keyword because it is part of the signature language. -The format is:: +Suricata ignores the words behind meta data. Suricata supports this +keyword because it is part of the signature language. The format is: + +:: - metadata:...; + metadata:......; diff --git a/doc/sphinx/meta/classification.png b/doc/sphinx/meta/classification.png new file mode 100644 index 0000000000..456b1ee30a Binary files /dev/null and b/doc/sphinx/meta/classification.png differ diff --git a/doc/sphinx/meta/classtype.png b/doc/sphinx/meta/classtype.png new file mode 100644 index 0000000000..3d891943d2 Binary files /dev/null and b/doc/sphinx/meta/classtype.png differ diff --git a/doc/sphinx/meta/gid.png b/doc/sphinx/meta/gid.png new file mode 100644 index 0000000000..051eecbf5d Binary files /dev/null and b/doc/sphinx/meta/gid.png differ diff --git a/doc/sphinx/meta/msg.png b/doc/sphinx/meta/msg.png new file mode 100644 index 0000000000..8d1e1beeb9 Binary files /dev/null and b/doc/sphinx/meta/msg.png differ diff --git a/doc/sphinx/meta/reference.png b/doc/sphinx/meta/reference.png new file mode 100644 index 0000000000..8ed3057ef8 Binary files /dev/null and b/doc/sphinx/meta/reference.png differ diff --git a/doc/sphinx/meta/rev.png b/doc/sphinx/meta/rev.png new file mode 100644 index 0000000000..d6f039fbdb Binary files /dev/null and b/doc/sphinx/meta/rev.png differ diff --git a/doc/sphinx/meta/sid.png b/doc/sphinx/meta/sid.png new file mode 100644 index 0000000000..7952641d64 Binary files /dev/null and b/doc/sphinx/meta/sid.png differ diff --git a/doc/sphinx/payload-keywords.rst b/doc/sphinx/payload-keywords.rst index c6889cddd8..7af5fc21c9 100644 --- a/doc/sphinx/payload-keywords.rst +++ b/doc/sphinx/payload-keywords.rst @@ -285,7 +285,7 @@ another ('def'), see example: The replace modifier has to contain as many characters as the content it replaces. It can only be used with individual packets. It will not -work for [[Normalized Buffers]] like HTTP uri or a content match in +work for [[**FIXME** Normalized Buffers]] like HTTP uri or a content match in the reassembled stream. The checksums will be recalculated by Suricata and changed after the @@ -294,8 +294,7 @@ replace keyword is being used. pcre ---- -For information about pcre check the [[pcre (Perl Compatible Regular -Expressions)]] page. +For information about pcre check the :doc:`pcre` page. fast_pattern ------------ diff --git a/doc/sphinx/pcre.rst b/doc/sphinx/pcre.rst index 74f8024d91..eeeb314caf 100644 --- a/doc/sphinx/pcre.rst +++ b/doc/sphinx/pcre.rst @@ -64,7 +64,7 @@ Suricata has its own specific pcre modifiers. These are: 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]]. + about [[**FIXME** HTTP-uri normalization]]. .. image:: pcre/pcre3.png @@ -77,7 +77,7 @@ Suricata has its own specific pcre modifiers. These are: * ``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]]. + HTTP-raw-uri buffer. Read more about [[**FIXME** HTTP-uri normalization]]. .. image:: pcre/pcre7.png diff --git a/doc/sphinx/rule-lua-scripting.rst b/doc/sphinx/rule-lua-scripting.rst index 9eff413a3c..c142eeca50 100644 --- a/doc/sphinx/rule-lua-scripting.rst +++ b/doc/sphinx/rule-lua-scripting.rst @@ -2,7 +2,7 @@ Lua Scripting ============= In order to enable Lua scripting, please reference this page before -continuing [[Installation from GIT with luajit]]. +continuing [[**FIXME** Installation from GIT with luajit]]. Syntax: diff --git a/doc/sphinx/rules.rst b/doc/sphinx/rules.rst index c3e706696b..76279c032a 100644 --- a/doc/sphinx/rules.rst +++ b/doc/sphinx/rules.rst @@ -1,9 +1,9 @@ -Rules -===== +Suricata Rules +============== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 meta header-keywords @@ -16,8 +16,191 @@ Rules rule-lua-scripting adding-your-own-rules live-rule-swap + dns-keywords tls-keywords normalized-buffers rule-profiling modbus-keyword dnp3-keywords + +Introduction +~~~~~~~~~~~~ + +Signatures play a very important role in Suricata. In most occasions +people are using existing rulesets. The most used are `Emerging +Threats `_, `Emerging Threats +Pro `_ and Sourcefire's +`VRT `_. A way to install rules is described +in [[**FIXME** Rule Management with Oinkmaster]]. This Suricata Rules document +explains all about signatures; how to read-, adjust-and create them. + +A rule/signature consists of the following: + + The action, header and rule-options. + +Example of a signature: + +.. image:: rules/intro_sig.png + +Action +~~~~~~ + +For more information read 'Action Order' in the +[[**FIXME** suricata.yaml#Action-order]] wiki. + +Example: + +.. image:: rules/action.png + +In this example the red, bold-faced part is the action. + +Protocol +~~~~~~~~ + +This keyword in a signature tells Suricata which protocol it +concerns. You can choose between four settings. tcp (for +tcp-traffic), udp, icmp and ip. ip stands for 'all' or 'any'. +Suricata adds a few protocols : http, ftp, tls (this includes ssl), +smb and dns (from v2.0). These are the so-called application layer +protocols or layer 7 protocols. If you have a signature with for +instance a http-protocol, Suricata makes sure the signature can only +match if it concerns http-traffic. + +Example: + +.. image:: rules/protocol.png + +In this example the red, bold-faced part is the protocol. + +Source and destination +~~~~~~~~~~~~~~~~~~~~~~ + +In source you can assign IP-addresses; IPv4 and IPv6 combined as well +as separated. You can also set variables such as HOME_NET. (For more +information see 'Rule-vars' at [[**FIXME** Suricata.yaml#Rule-vars]] in the user +guide.) In the Yaml-file you can set IP-addresses for variables such +as EXTERNAL_NET and HOME_NET. These settings will be used when you use +these variables in a rule. In source and destination you can make use +of signs like ! And [ ]. + +For example:: + + ! 1.1.1.1 (Every IP address but 1.1.1.1) + ![1.1.1.1, 1.1.1.2] (Every IP address but 1.1.1.1 and 1.1.1.2) + $HOME_NET (Your setting of HOME_NET in yaml) + [$EXTERNAL_NET, !$HOME_NET] (EXTERNAL_NET and not HOME_NET) + [10.0.0.0/24, !10.0.0.5] (10.0.0.0/24 except for 10.0.0.5) + […..,[....]] + […. ,![.....]] + + +Pay attention to the following: + +If your settings in Yaml are:: + + HOME_NET: any + EXTERNAL_NET: ! $HOME_NET + +You can not write a signature using EXTERNAL_NET because it stands for +'not any'. This is a invalid setting. + +Example of source and destination in a signature: + +.. image:: rules/Source.png + +The red, bold-faced part is the source. + +.. image:: rules/destination.png + +The red, bold-faced part is the destination. + +Ports (source-and destination-port) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Traffic comes in and goes out through ports. Different ports have +different port-numbers. The HTTP-port for example is 80 while 443 is +the port for HTTPS and MSN makes use of port 1863. Commonly the Source +port will be set as 'any'. This will be influenced by the +protocol. The source port is designated at random by the operating +system. Sometimes it is possible to filter/screen on the source In +setting ports you can make use of special signs as well, like +described above at 'source'. Signs like:: + + ! exception/negation + : range + [] signs to make clear which parts belong together + , separation + +Example:: + + [80, 81, 82] (port 80, 81 and 82) + [80: 82] (Range from 80 till 82) + [1024: ] (From 1024 till the highest port-number) + !80 (Every port but 80) + [80:100,!99] (Range from 80 till 100 but 99 excluded) + [1:80,![2,4]] + [….[.....]] + +Example of ports in a signature: + +.. image:: rules/Source-port.png + + +.. image:: rules/Dest_port.png + +In this example, the red, bold-faced part is the port. + +Direction +~~~~~~~~~ + +The direction tells in which way the signature has to match. Nearly +every signature has an arrow to the right. This means that only +packets with the same direction can match. + +:: + + source -> destination + source <> destination (both directions) + +Example:: + + alert tcp 1.2.3.4 1024 - > 5.6.7.8 80 + +Example 1 tcp-session + +.. image:: rules/TCP-session.png + +In this example there will only be a match if the signature has the +same order/direction as the payload. + +Example of direction in a signature: + +.. image:: rules/Direction.png + +In this example the red, bold-faced part is the direction. + +Rule options +------------ + +Keywords have a set format:: + + name: settings; + +Sometimes it is just the name of the setting followed by ; . Like nocase; + +There are specific settings for: + +* meta-information. +* headers +* payloads +* flows + +For more information about these settings, you can click on the +following headlines: + +* :doc:`meta` +* :doc:`payload-keywords` +* :doc:`http-keywords` +* :doc:`dns-keywords` +* :doc:`flow-keywords` +* **FIXME** [[IPReputationRules|IP Reputation keyword]] diff --git a/doc/sphinx/rules/Dest_port.png b/doc/sphinx/rules/Dest_port.png new file mode 100644 index 0000000000..43e04147b8 Binary files /dev/null and b/doc/sphinx/rules/Dest_port.png differ diff --git a/doc/sphinx/rules/Direction.png b/doc/sphinx/rules/Direction.png new file mode 100644 index 0000000000..bdd2378e9f Binary files /dev/null and b/doc/sphinx/rules/Direction.png differ diff --git a/doc/sphinx/rules/Source-port.png b/doc/sphinx/rules/Source-port.png new file mode 100644 index 0000000000..c046c49a53 Binary files /dev/null and b/doc/sphinx/rules/Source-port.png differ diff --git a/doc/sphinx/rules/Source.png b/doc/sphinx/rules/Source.png new file mode 100644 index 0000000000..d0d1baaa38 Binary files /dev/null and b/doc/sphinx/rules/Source.png differ diff --git a/doc/sphinx/rules/TCP-session.png b/doc/sphinx/rules/TCP-session.png new file mode 100644 index 0000000000..87d0eea07e Binary files /dev/null and b/doc/sphinx/rules/TCP-session.png differ diff --git a/doc/sphinx/rules/action.png b/doc/sphinx/rules/action.png new file mode 100644 index 0000000000..4d67d152b0 Binary files /dev/null and b/doc/sphinx/rules/action.png differ diff --git a/doc/sphinx/rules/destination.png b/doc/sphinx/rules/destination.png new file mode 100644 index 0000000000..3fc44dbc67 Binary files /dev/null and b/doc/sphinx/rules/destination.png differ diff --git a/doc/sphinx/rules/intro_sig.png b/doc/sphinx/rules/intro_sig.png new file mode 100644 index 0000000000..b726fc5dcb Binary files /dev/null and b/doc/sphinx/rules/intro_sig.png differ diff --git a/doc/sphinx/rules/protocol.png b/doc/sphinx/rules/protocol.png new file mode 100644 index 0000000000..2e0ef370a9 Binary files /dev/null and b/doc/sphinx/rules/protocol.png differ diff --git a/doc/sphinx/thresholding.rst b/doc/sphinx/thresholding.rst index a92d3fb57d..2782087db9 100644 --- a/doc/sphinx/thresholding.rst +++ b/doc/sphinx/thresholding.rst @@ -2,11 +2,11 @@ Rule Thresholding ================= Thresholding can be configured per rule and also globally, see -[[Global-Thresholds]]. +[[**FIXME** Global-Thresholds]]. *Note: mixing rule and global thresholds is not supported in 1.3 and before. See bug #425.* For the state of the support in 1.4 see -[[Global-Thresholds#Global-thresholds-vs-rule-thresholds]]. +[[**FIXME** Global-Thresholds#Global-thresholds-vs-rule-thresholds]]. threshold --------- @@ -61,7 +61,7 @@ If a signature sets a flowbit, flowint, etc. those actions are still performed for each of the matches. *Rule actions drop (IPS mode) and reject are applied to each packet - (not only the one that meets the limit condition).* + (not only the one that meets the limit condition).* type "both" ~~~~~~~~~~~ diff --git a/doc/sphinx/tls-keywords.rst b/doc/sphinx/tls-keywords.rst index 57a5a80584..5e891a68f6 100644 --- a/doc/sphinx/tls-keywords.rst +++ b/doc/sphinx/tls-keywords.rst @@ -1,4 +1,4 @@ -TLS-keywords +TLS Keywords ============ Suricata comes with several rule keywords to match on various properties of TLS/SSL handshake. Matches are string inclusion matches. diff --git a/doc/sphinx/what-is-suricata.rst b/doc/sphinx/what-is-suricata.rst index 6ae7ba1fd8..920f081a7d 100644 --- a/doc/sphinx/what-is-suricata.rst +++ b/doc/sphinx/what-is-suricata.rst @@ -65,4 +65,4 @@ very advanced processing of HTTP streams for Suricata. The HTP library is required by the engine, but may also be used independently in a range of applications and tools. -[[Major Features|Next]] +[[**FIXME** Major Features|Next]]