From 4b306fed14b3dee05ba9b7bf9282cf6aa0f064bf Mon Sep 17 00:00:00 2001 From: Jason Ish Date: Mon, 4 Jan 2016 11:38:06 -0600 Subject: [PATCH] doc: fixup references --- doc/sphinx/configuration/suricata-yaml.rst | 10 +++++++ .../file-extraction/file-extraction.rst | 5 +++- doc/sphinx/file-extraction/md5.rst | 2 ++ .../public-sha1-md5-data-sets.rst | 3 --- doc/sphinx/performance/packet-profiling.rst | 4 +-- doc/sphinx/performance/runmodes.rst | 8 +++--- doc/sphinx/rules/file-keywords.rst | 5 ++-- doc/sphinx/rules/flow-keywords.rst | 13 +++++----- doc/sphinx/rules/http-keywords.rst | 19 ++++++++------ doc/sphinx/rules/http-uri-normalization.rst | 10 +++++++ doc/sphinx/rules/intro.rst | 26 +++++++++---------- doc/sphinx/rules/normalized-buffers.rst | 3 +++ doc/sphinx/rules/payload-keywords.rst | 2 +- doc/sphinx/rules/pcre.rst | 4 +-- doc/sphinx/rules/thresholding.rst | 4 +-- doc/sphinx/setting-up-ipsinline-for-linux.rst | 2 +- 16 files changed, 75 insertions(+), 45 deletions(-) create mode 100644 doc/sphinx/rules/http-uri-normalization.rst diff --git a/doc/sphinx/configuration/suricata-yaml.rst b/doc/sphinx/configuration/suricata-yaml.rst index 8f78cff227..7dd34ca81c 100644 --- a/doc/sphinx/configuration/suricata-yaml.rst +++ b/doc/sphinx/configuration/suricata-yaml.rst @@ -8,6 +8,8 @@ Suricata. This document will explain each option. At the top of the YAML-file you will find % YAML 1.1. Suricata reads the file and identifies the file as YAML. +.. _suricata-yaml-max-pending-packets: + Max-pending-packets ------------------- @@ -64,6 +66,8 @@ It is possible to set the user and group to run Suricata as: group: suri +.. _suricata-yaml-action-order: + Action-order ------------ @@ -952,6 +956,8 @@ seconds. Flow and Stream handling ------------------------ +.. _suricata-yaml-flow-settings: + Flow Settings ~~~~~~~~~~~~~ @@ -1213,6 +1219,8 @@ Limit for the maximum number of asn1 frames to decode (default 256): asn1_max_frames: 256 +.. _suricata-yaml-configure-libhtp: + Configure HTTP (libhtp) ~~~~~~~~~~~~~~~~~~~~~~~ @@ -1692,6 +1700,8 @@ You can set the direction of the classification configuration. classification-file: /etc/suricata/classification.config +.. _suricata-yaml-rule-vars: + Rule-vars ~~~~~~~~~ diff --git a/doc/sphinx/file-extraction/file-extraction.rst b/doc/sphinx/file-extraction/file-extraction.rst index 853cb12ce3..2cd9e710f7 100644 --- a/doc/sphinx/file-extraction/file-extraction.rst +++ b/doc/sphinx/file-extraction/file-extraction.rst @@ -82,7 +82,10 @@ Please make sure you choose the appropriate interface name (eth0,eth1,eth5...) Output ~~~~~~ -For file extraction two separate output modules were created: "file-log" and "file-store". They need to be enabled in the [[suricata.yaml]]. For "file-store", the "files" drop dir must be configured. +For file extraction two separate output modules were created: +"file-log" and "file-store". They need to be enabled in the +:doc:`../configuration/suricata-yaml`. For "file-store", the "files" +drop dir must be configured. :: diff --git a/doc/sphinx/file-extraction/md5.rst b/doc/sphinx/file-extraction/md5.rst index 1e38313738..419a3970b0 100644 --- a/doc/sphinx/file-extraction/md5.rst +++ b/doc/sphinx/file-extraction/md5.rst @@ -1,3 +1,5 @@ +.. _md5: + Storing MD5s checksums ====================== diff --git a/doc/sphinx/file-extraction/public-sha1-md5-data-sets.rst b/doc/sphinx/file-extraction/public-sha1-md5-data-sets.rst index 373a52ecc4..f5e7d09b3e 100644 --- a/doc/sphinx/file-extraction/public-sha1-md5-data-sets.rst +++ b/doc/sphinx/file-extraction/public-sha1-md5-data-sets.rst @@ -1,7 +1,4 @@ Public SHA1 MD5 data sets ========================= - - - National Software Reference Library - http://www.nsrl.nist.gov/Downloads.htm diff --git a/doc/sphinx/performance/packet-profiling.rst b/doc/sphinx/performance/packet-profiling.rst index f93deb6c04..910f8be425 100644 --- a/doc/sphinx/performance/packet-profiling.rst +++ b/doc/sphinx/performance/packet-profiling.rst @@ -27,8 +27,8 @@ sure you enter the following during the configuring stage: ./configure --enable-profiling Find a folder in which you have pcaps. If you do not have pcaps yet, -you can get these with Wireshark. See [[Sniffing Packets with -Wireshark]]. +you can get these with Wireshark. See `Sniffing Packets with Wireshark +`_. Go to the directory of your pcaps. For example: diff --git a/doc/sphinx/performance/runmodes.rst b/doc/sphinx/performance/runmodes.rst index 0927501e12..8f05f8de9f 100644 --- a/doc/sphinx/performance/runmodes.rst +++ b/doc/sphinx/performance/runmodes.rst @@ -10,10 +10,10 @@ another one the output-module. A packet can be processed by more than one thread. The packet will be passed on to the next thread through a queue. Packets will be processed by one thread at a time, but there can be multiple packets being processed at a time by the engine. (see -[[**FIXME** suricata.yaml#max-pending-packets]]) A thread can have one or more -thread-modules. If they have more modules, they can only be active on -a a time. The way threads, modules and queues are arranged together -is called the Runmode. +:ref:`suricata-yaml-max-pending-packets`) A thread can have one or +more thread-modules. If they have more modules, they can only be +active on a a time. The way threads, modules and queues are arranged +together is called the Runmode. Different runmodes ~~~~~~~~~~~~~~~~~~ diff --git a/doc/sphinx/rules/file-keywords.rst b/doc/sphinx/rules/file-keywords.rst index 4f13cceb3c..44c5b667a9 100644 --- a/doc/sphinx/rules/file-keywords.rst +++ b/doc/sphinx/rules/file-keywords.rst @@ -2,7 +2,8 @@ File Keywords ============= Suricata comes with several rule keywords to match on various file -properties. They depend on properly configured [[**FIXME** File Extraction]]. +properties. They depend on properly configured +:doc:`../file-extraction/file-extraction`. filename -------- @@ -73,7 +74,7 @@ the rule and the scope will be per file. filemd5 ------- -Match file [[**FIXME** MD5]] against list of MD5 checksums. +Match file :ref:`MD5 ` against list of MD5 checksums. Syntax:: diff --git a/doc/sphinx/rules/flow-keywords.rst b/doc/sphinx/rules/flow-keywords.rst index 06658eebcc..ba057fd99a 100644 --- a/doc/sphinx/rules/flow-keywords.rst +++ b/doc/sphinx/rules/flow-keywords.rst @@ -9,12 +9,13 @@ 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 -[[**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. +:ref:`suricata-yaml-flow-settings`. 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: diff --git a/doc/sphinx/rules/http-keywords.rst b/doc/sphinx/rules/http-keywords.rst index 53aa36c111..9584014a2f 100644 --- a/doc/sphinx/rules/http-keywords.rst +++ b/doc/sphinx/rules/http-keywords.rst @@ -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 [[**FIXME** -HTTP-uri normalization]]. +``http_raw_uri``, please read the information about +:doc:`http-uri-normalization`. Example of the URI in a HTTP request: @@ -236,8 +236,9 @@ 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 [[**FIXME** suricata.yaml#Configure-Libhtp]], in the "libhtp" section, -via the ``request-body-limit`` setting. +in the :ref:`libhtp configuration section +` via the ``request-body-limit`` +setting. http_stat_code -------------- @@ -283,8 +284,9 @@ 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 [[**FIXME** suricata.yaml#Configure-Libhtp]], in the "libhtp" section, -via the ``response-body-limit`` setting. +in your :ref:`libhtp configuration section +` via the ``response-body-limit`` +setting. http_host and http_raw_host --------------------------- @@ -322,8 +324,9 @@ 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 [[**FIXME** suricata.yaml#Configure-Libhtp]], in the "libhtp" section -via the ``response-body-limit`` setting. +in your :ref:`libhtp configuration section +` via the ``response-body-limit`` +setting. **NOTE:** In 2.0.x, ``file_data`` is only supported for HTTP server bodies (specified as flow direction **to_client**). Starting with diff --git a/doc/sphinx/rules/http-uri-normalization.rst b/doc/sphinx/rules/http-uri-normalization.rst new file mode 100644 index 0000000000..20d9b14bc6 --- /dev/null +++ b/doc/sphinx/rules/http-uri-normalization.rst @@ -0,0 +1,10 @@ +HTTP-uri normalization +====================== + +The uri has two appearances in Suricata: the raw_uri and the +normalized uri. The space for example can be indicated with the +heximal notation %20. To convert this notation in a space, means +normalizing it. It is possible though to match specific on the +characters %20 in a uri. This means matching on the raw_uri. The +raw_uri and the normalized uri are separate buffers. So, the raw_uri +inspects the raw_uri buffer and can not inspect the normalized buffer. diff --git a/doc/sphinx/rules/intro.rst b/doc/sphinx/rules/intro.rst index e834c31e59..726c9171a2 100644 --- a/doc/sphinx/rules/intro.rst +++ b/doc/sphinx/rules/intro.rst @@ -5,11 +5,11 @@ Rules 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. +Threats `_, `Emerging Threats Pro +`_ and Sourcefire's `VRT +`_. A way to install rules is described in +:doc:`../oinkmaster`. This Suricata Rules document explains all about +signatures; how to read-, adjust-and create them. A rule/signature consists of the following: @@ -22,8 +22,8 @@ Example of a signature: Action ------ -For more information read 'Action Order' in the -[[**FIXME** suricata.yaml#Action-order]] wiki. +For more information read 'Action Order' see +:ref:`suricata-yaml-action-order`. Example: @@ -54,11 +54,11 @@ 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 [ ]. +information see :ref:`suricata-yaml-rule-vars`. 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:: @@ -180,4 +180,4 @@ following headlines: * :doc:`http-keywords` * :doc:`dns-keywords` * :doc:`flow-keywords` -* **FIXME** [[IPReputationRules|IP Reputation keyword]] +* :doc:`../reputation/ipreputation/ip-reputation-rules` diff --git a/doc/sphinx/rules/normalized-buffers.rst b/doc/sphinx/rules/normalized-buffers.rst index 111bb97163..a3a282a95f 100644 --- a/doc/sphinx/rules/normalized-buffers.rst +++ b/doc/sphinx/rules/normalized-buffers.rst @@ -1,6 +1,9 @@ Normalized Buffers ================== +.. toctree:: + + http-uri-normalization A packet consists of raw data. HTTP and reassembly make a copy of those kinds of packets data. They erase anomalous content, combine diff --git a/doc/sphinx/rules/payload-keywords.rst b/doc/sphinx/rules/payload-keywords.rst index 7af5fc21c9..b5f400ac45 100644 --- a/doc/sphinx/rules/payload-keywords.rst +++ b/doc/sphinx/rules/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 [[**FIXME** Normalized Buffers]] like HTTP uri or a content match in +work for :doc:`normalized-buffers` like HTTP uri or a content match in the reassembled stream. The checksums will be recalculated by Suricata and changed after the diff --git a/doc/sphinx/rules/pcre.rst b/doc/sphinx/rules/pcre.rst index a0df46fc3b..9af5484214 100644 --- a/doc/sphinx/rules/pcre.rst +++ b/doc/sphinx/rules/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 [[**FIXME** HTTP-uri normalization]]. + about :doc:`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 [[**FIXME** HTTP-uri normalization]]. + HTTP-raw-uri buffer. Read more about :doc:`http-uri-normalization`. ** FIXME - image is missing on wiki: .. image:: pcre/pcre7.png diff --git a/doc/sphinx/rules/thresholding.rst b/doc/sphinx/rules/thresholding.rst index 2782087db9..196f20a340 100644 --- a/doc/sphinx/rules/thresholding.rst +++ b/doc/sphinx/rules/thresholding.rst @@ -2,11 +2,11 @@ Rule Thresholding ================= Thresholding can be configured per rule and also globally, see -[[**FIXME** Global-Thresholds]]. +:doc:`../configuration/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 -[[**FIXME** Global-Thresholds#Global-thresholds-vs-rule-thresholds]]. +:ref:`global-thresholds-vs-rule-thresholds` threshold --------- diff --git a/doc/sphinx/setting-up-ipsinline-for-linux.rst b/doc/sphinx/setting-up-ipsinline-for-linux.rst index 0a4b956c87..470f2a1748 100644 --- a/doc/sphinx/setting-up-ipsinline-for-linux.rst +++ b/doc/sphinx/setting-up-ipsinline-for-linux.rst @@ -4,7 +4,7 @@ Setting up IPS/inline for Linux In this guide will be explained how to work with Suricata in layer3 inline mode and how to set iptables for that purpose. First start with compiling Suricata with NFQ support. For instructions see [[**FIXME** Ubuntu Installation]]. -For more information about NFQ and iptables, see [[**FIXME** suricata.yaml#NFQ]]. +For more information about NFQ and iptables, see :ref:`suricata-yaml-nfq`. To check if you have NFQ enabled in your Suricata, enter the following command: