]> git.ipfire.org Git - thirdparty/suricata.git/commitdiff
doc: finish off the rules section
authorJason Ish <ish@unx.ca>
Fri, 4 Dec 2015 16:26:53 +0000 (10:26 -0600)
committerVictor Julien <victor@inliniac.net>
Wed, 28 Sep 2016 11:11:10 +0000 (13:11 +0200)
34 files changed:
doc/sphinx/README.md [new file with mode: 0644]
doc/sphinx/adding-your-own-rules.rst
doc/sphinx/conf.py
doc/sphinx/dnp3-keywords.rst
doc/sphinx/dns-keywords.rst [new file with mode: 0644]
doc/sphinx/dns-keywords/dns_query.png [new file with mode: 0644]
doc/sphinx/file-keywords.rst
doc/sphinx/flow-keywords.rst
doc/sphinx/http-keywords.rst
doc/sphinx/index.rst
doc/sphinx/meta.rst
doc/sphinx/meta/classification.png [new file with mode: 0644]
doc/sphinx/meta/classtype.png [new file with mode: 0644]
doc/sphinx/meta/gid.png [new file with mode: 0644]
doc/sphinx/meta/msg.png [new file with mode: 0644]
doc/sphinx/meta/reference.png [new file with mode: 0644]
doc/sphinx/meta/rev.png [new file with mode: 0644]
doc/sphinx/meta/sid.png [new file with mode: 0644]
doc/sphinx/payload-keywords.rst
doc/sphinx/pcre.rst
doc/sphinx/rule-lua-scripting.rst
doc/sphinx/rules.rst
doc/sphinx/rules/Dest_port.png [new file with mode: 0644]
doc/sphinx/rules/Direction.png [new file with mode: 0644]
doc/sphinx/rules/Source-port.png [new file with mode: 0644]
doc/sphinx/rules/Source.png [new file with mode: 0644]
doc/sphinx/rules/TCP-session.png [new file with mode: 0644]
doc/sphinx/rules/action.png [new file with mode: 0644]
doc/sphinx/rules/destination.png [new file with mode: 0644]
doc/sphinx/rules/intro_sig.png [new file with mode: 0644]
doc/sphinx/rules/protocol.png [new file with mode: 0644]
doc/sphinx/thresholding.rst
doc/sphinx/tls-keywords.rst
doc/sphinx/what-is-suricata.rst

diff --git a/doc/sphinx/README.md b/doc/sphinx/README.md
new file mode 100644 (file)
index 0000000..fe06acd
--- /dev/null
@@ -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.
index 303566fadc31caac81e60b9893d58bce89ec4b4f..cbf99b6d80fc77688545da05eebd96ed7920903b 100644 (file)
@@ -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
 
index a5af0169ea2cb20b42dd07933208345d7b3d6d92..6cd7f0cf4d96b6b30418ed0c5b4bdc128699f797 100644 (file)
@@ -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 ---------------------------------------------
 
index 3e2748fd5d7d15a91b131b4d17caafb2b385966b..7fe34f75de572f012c322f09ec3fe47a4cd3568f 100644 (file)
@@ -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 (file)
index 0000000..a437553
--- /dev/null
@@ -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 (file)
index 0000000..35d16ca
Binary files /dev/null and b/doc/sphinx/dns-keywords/dns_query.png differ
index f35e3fee0ad479609a3ff80e2bb4ee8019926e8c..4f13cceb3cfa8ce4c6f455426717dc8528bd4b3e 100644 (file)
@@ -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::
 
index f314f5978f1c0712cbc44d7414559da298d74d82..06658eebcc4cab8edc17033217281e6cd0384957 100644 (file)
@@ -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:<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:
index 63a52d56b58736b252e061b170361f4968cb7624..623a301a8a7ff7165afa1f035cd176543537631a 100644 (file)
@@ -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
 ------------
index af8d429c5ba4ce134ef9c75584afdbc3dbab8e97..40581d2bce35ba87ecc16938d6c9c56679f4f920 100644 (file)
@@ -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`
index 6b5fbf5a71c04120cea653d25170cb4f25eb8abd..4fb169f467f9cc785f2064e0c32e248b0fcb3805 100644 (file)
@@ -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 (file)
index 0000000..456b1ee
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 (file)
index 0000000..3d89194
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 (file)
index 0000000..051eecb
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 (file)
index 0000000..8d1e1be
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 (file)
index 0000000..8ed3057
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 (file)
index 0000000..d6f039f
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 (file)
index 0000000..7952641
Binary files /dev/null and b/doc/sphinx/meta/sid.png differ
index c6889cddd8942c1b99b328af13ad96374fb03523..7af5fc21c9b4a6770829a8d8544eba35870b863d 100644 (file)
@@ -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
 ------------
index 74f8024d91a3e90b426d501f7b2019f227cc6718..eeeb314caf2c8df6c9f7cd6a667ed15cb68b80ae 100644 (file)
@@ -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
 
index 9eff413a3c07a314954bacc2813092c6390d61dc..c142eeca5083d6e44f39a401c4aa3fa22c0b0bcd 100644 (file)
@@ -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:
 
index c3e706696b638477ce3df62904461ebd7ae6a9f4..76279c032a698fe4247ffb13d33262b34ea38671 100644 (file)
@@ -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 <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]]
diff --git a/doc/sphinx/rules/Dest_port.png b/doc/sphinx/rules/Dest_port.png
new file mode 100644 (file)
index 0000000..43e0414
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 (file)
index 0000000..bdd2378
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 (file)
index 0000000..c046c49
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 (file)
index 0000000..d0d1baa
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 (file)
index 0000000..87d0eea
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 (file)
index 0000000..4d67d15
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 (file)
index 0000000..3fc44db
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 (file)
index 0000000..b726fc5
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 (file)
index 0000000..2e0ef37
Binary files /dev/null and b/doc/sphinx/rules/protocol.png differ
index a92d3fb57dca3f858ae1c2c964c3cb3d3e78c2ad..2782087db9aee9f9ed2ba3303f941a47a4810636 100644 (file)
@@ -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"
 ~~~~~~~~~~~
index 57a5a805847e421f3a7fa5383d2ed81e146d95c5..5e891a68f64c2369e4013224fcc8a1c916126c6e 100644 (file)
@@ -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.
index 6ae7ba1fd818bbcfb3f75aea0a7ef61e6ace8792..920f081a7d016c52c24fb73ebe8d935b5c0c458f 100644 (file)
@@ -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]]