--- /dev/null
+# 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.
sudo nano local.rules
-Write your rule, see [[Suricata Rules]] and save it.
+Write your rule, see :doc:`rules` and save it.
Open yaml
# 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.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
-htmlhelp_basename = 'Suricatadoc'
+htmlhelp_basename = 'suricatadoc'
# -- Options for LaTeX output ---------------------------------------------
-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
--- /dev/null
+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.
-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
--------
filemd5
-------
-Match file [[MD5]] against list of MD5 checksums.
+Match file [[**FIXME** MD5]] against list of MD5 checksums.
Syntax::
-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.
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
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:
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:
::
>= greater than or equal
<= less than or equal
-
Format
::
stream_size:<server|client|both|either>, <modifier>, <number>;
-Example of the stream-size keyword in a rule:
\ No newline at end of file
+Example of the stream-size keyword in a rule:
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.
``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:
.. 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
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
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
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
------------
-.. 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`
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.
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)
--------------
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
---------
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
---------
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
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
--------
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:......;
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
pcre
----
-For information about pcre check the [[pcre (Perl Compatible Regular
-Expressions)]] page.
+For information about pcre check the :doc:`pcre` page.
fast_pattern
------------
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
* ``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
=============
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:
-Rules
-=====
+Suricata Rules
+==============
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
meta
header-keywords
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 <http://www.emergingthreats.net/>`_, `Emerging Threats
+Pro <http://www.emergingthreatspro.com/>`_ and Sourcefire's
+`VRT <http://www.snort.org/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]]
=================
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
---------
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"
~~~~~~~~~~~
-TLS-keywords
+TLS Keywords
============
Suricata comes with several rule keywords to match on various properties of TLS/SSL handshake. Matches are string inclusion matches.
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]]