From: Jason Ish Date: Sun, 3 Dec 2017 17:12:18 +0000 (-0600) Subject: doc: re-org into commands X-Git-Tag: 1.0.0a1~19 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=571cfcafb3b3d183de9b9c50082ab81acad09d73;p=thirdparty%2Fsuricata-update.git doc: re-org into commands --- diff --git a/doc/add-source.rst b/doc/add-source.rst new file mode 100644 index 0000000..383dc88 --- /dev/null +++ b/doc/add-source.rst @@ -0,0 +1,30 @@ +################################ +add-source - Add a source by URL +################################ + +Synopsis +======== + +:: + + suricata-update add-source [--name name] [--url ] + +Description +=========== + +The ``add-source`` adds a source to the set of enabled sources by +URL. It is useful to add a source that is not provided in the index. + +Options +======= + +.. option:: --name + + The name of the source. If not provided on the command line the + user will be prompted. + +.. option:: --url + + The URL of the source. If not provided on the command line the user + will be prompted. + diff --git a/doc/index.rst b/doc/index.rst index 656b37b..7ffbf74 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,343 +3,8 @@ suricata-update - A Suricata Rule Update Tool ############################################# .. toctree:: + :maxdepth: 2 quickstart - -Synopsis -======== - -``suricata-update`` [OPTIONS] - -Description -=========== - -``suricata-update`` aims to be a simple to use rule download and -management tool for Suricata. - -Options -======= - -.. option:: -h, --help - - Show help. - -.. option:: -v, --verbose - - Be more verbose. - -.. option:: -c , --config - - Path to the suricata-update config file. - - Default: */etc/suricata/update.yaml* - -.. option:: -o, --output - - The directory to output the rules to. - - Default: */var/lib/suricata/rules* - -.. option:: --suricata= - - The path to the Suricata program used to determine which version of - the ET pro rules to download if not explicitly set in a ``--url`` - argument. - -.. option:: --suricata-version - - Set the Suricata version to a specific version instead of checking - the version of Suricata on the path. - -.. option:: --force - - Force remote rule files to be downloaded if they otherwise wouldn't - be due to just recently downloaded, or the remote checksum matching - the cached copy. - -.. option:: --merged= - - Write a single file containing all rules. This can be used in - addition to ``--output`` or instead of ``--output``. - -.. option:: --no-merge - - Do not merge the rules into a single rule file. - - *Warning: No attempt is made to resolve conflicts if 2 input rule files have the same name.* - -.. option:: --yaml-fragment= - - Output a fragment of YAML containing the *rule-files* section will - all downloaded rule files listed for inclusion in your - *suricata.yaml*. - -.. option:: --url= - - A URL to download rules from. This option can be used multiple - times. - -.. option:: --local= - - A path to a filename or directory of local rule files to include. - - If the path is a directory all files ending in *.rules* will be - loaded. - - Wildcards are accepted but to avoid shell expansion the argument - must be quoted, for example:: - - --local '/etc/suricata/custom-*.rules' - - This option can be specified multiple times. - -.. option:: --sid-msg-map= - - Output a v1 style sid-msg.map file. - -.. option:: --sid-msg-map-2= - - Output a v2 style sid-msg.map file. - -.. option:: --disable-conf= - - Specify the configuration file for disable filters. - - See :ref:`example-disable-conf` - -.. option:: --enable-conf= - - Specify the configuration file for enable rules. - - See :ref:`example-enable-conf` - -.. option:: --modify-conf= - - Specify the configuration file for rule modification filters. - - See :ref:`example-modify-conf` - -.. option:: --drop-conf= - - Specify the configuration file for drop filters. - - See :ref:`example-drop-conf` - -.. option:: --ignore= - - Filenames to ignore. This is a pattern that will be matched against - the basename of a rule files. - - This argument may be specified multiple times. - - Default: *\*deleted.rules* - - Example:: - - --ignore dnp3-events.rules --ignore deleted.rules --ignore "modbus*" - - .. note:: - - If specified the default value of *\*deleted.rules* will no longer - be used, so add it as an extra ignore if needed. - -.. option:: --no-ignore - - Disable the --ignore option. Most useful to disable the default - ignore pattern without adding others. - -.. option:: --etopen - - Download the ET/Open ruleset. - - This is the default action of no ``--url`` options are provided or - no sources are configured. - - Use this option to enable the ET/Open ruleset in addition to any - URLs provided on the command line or sources provided in the - configuration. - -.. option:: -q, --quiet - - Run quietly. Only warning and error message will be displayed. - -.. option:: --dump-sample-configs - - Output sample configuration files for the ``--disable``, - ``--enable``, ``--modify`` and ``--threshold-in`` commands. - -.. option:: --threshold-in= - - Specify the threshold.conf input template. - -.. option:: --threshold-out= - - Specify the name of the processed threshold.conf to output. - -.. option:: -T , --test-command - - Specifies a custom test command to test the rules before reloading - Suricata. This overrides the default command and can also be - specified in the configuration file under ``test-command``. - -.. option:: --no-test - - Disables the test command and proceed as if it had passed. - -.. option:: --reload-command= - - A command to run after the rules have been updated; will not run if - no change to the output files was made. For example:: - - --reload-command=sudo kill -USR2 $(cat /var/run/suricata.pid) - - will tell Suricata to reload its rules. - -.. option:: --no-reload - - Disable Suricata rule reload. - -.. option:: -V, --version - - Display the version of **suricata-update**. - -Rule Matching -============= - -Matching rules for disabling, enabling, converting to drop or -modification can be done with the following: - -- signature ID -- regular expression -- rule group -- filename - -Signature ID Matching ---------------------- - -A signature ID can be matched by just its signature ID, for example:: - - 1034 - -The generator ID can also be used for compatibility with other tools:: - - 1:1034 - -Regular Expression Matching ---------------------------- - -Regular expression matching will match a regular expression over the -complete rule. Example:: - - re:heartbleed - re:MS(0[7-9]|10)-\d+ - -Group Matching --------------- - -The group matcher matches against the group the rule was loaded -from. Basically this is the filename without the leading path or file -extension. Example:: - - group:emerging-icmp.rules - group:emerging-dos - -Wild card matching similar to wildcards used in a Unix shell can also -be used:: - - group:*deleted* - -Filename Matching ------------------ - -The filename matcher matches against the filename the rule was loaded -from taking into consideration the full path. Shell wildcard patterns -are allowed:: - - filename:rules/*deleted* - filename:*/emerging-dos.rules - -Modifying Rules ---------------- - -Rule modification can be done with regular expression search and -replace. The basic format for a rule modification specifier is:: - - - -where is one of the rule matchers from above, is the -text to be replaced and is the replacement text. - -Example converting all alert rules to drop:: - - re:. ^alert drop - -Example converting all drop rules with noalert back to alert:: - - re:. "^drop(.*)noalert(.*)" "alert\\1noalert\\2" - -Sub Commands -============ - -add-sources - Add a new source by URL - -add-source - Add a new source by URL ------------------------------------- - -Description -~~~~~~~~~~~ - -The ``add-source`` adds a source to the set of enabled sources by -URL. It is useful to add a source that is not provided in the index. - -Options -~~~~~~~ - -.. option:: --name - - The name of the source. If not provided on the command line the - user will be prompted. - -.. option:: --url - - The URL of the source. If not provided on the command line the user - will be prompted. - -Example Configuration Files -=========================== - -.. _example_update_yaml: - -Example Configuration File (/etc/suricata/update.yaml) ------------------------------------------------------- - -.. literalinclude:: ../suricata/update/configs/update.yaml - -.. _example-enable-conf: - -Example Configuration to Enable Rules (--enable-conf) ------------------------------------------------------ - -.. literalinclude:: ../suricata/update/configs/enable.conf - -.. _example-disable-conf: - -Example Configuration to Enable Disable (--disable-conf) --------------------------------------------------------- - -.. literalinclude:: ../suricata/update/configs/disable.conf - -.. _example-drop-conf: - -Example Configuration to convert Rules to Drop (--drop-conf) ------------------------------------------------------------- - -.. literalinclude:: ../suricata/update/configs/drop.conf - -.. _example-modify-conf: - -Example Configuration to modify Rules (--modify-conf) ------------------------------------------------------ - -.. literalinclude:: ../suricata/update/configs/modify.conf + update + add-source diff --git a/doc/quickstart.rst b/doc/quickstart.rst index 0295aab..8035974 100644 --- a/doc/quickstart.rst +++ b/doc/quickstart.rst @@ -1,5 +1,5 @@ -Suricata-Update Quick Start -########################### +Quick Start +########### Install Suricata Update ======================= diff --git a/doc/update.rst b/doc/update.rst new file mode 100644 index 0000000..59ba099 --- /dev/null +++ b/doc/update.rst @@ -0,0 +1,313 @@ +######################## +suricata-update - Update +######################## + +Synopsis +======== + +``suricata-update`` [OPTIONS] + +Description +=========== + +``suricata-update`` aims to be a simple to use rule download and +management tool for Suricata. + +Options +======= + +.. option:: -h, --help + + Show help. + +.. option:: -v, --verbose + + Be more verbose. + +.. option:: -c , --config + + Path to the suricata-update config file. + + Default: */etc/suricata/update.yaml* + +.. option:: -o, --output + + The directory to output the rules to. + + Default: */var/lib/suricata/rules* + +.. option:: --suricata= + + The path to the Suricata program used to determine which version of + the ET pro rules to download if not explicitly set in a ``--url`` + argument. + +.. option:: --suricata-version + + Set the Suricata version to a specific version instead of checking + the version of Suricata on the path. + +.. option:: --force + + Force remote rule files to be downloaded if they otherwise wouldn't + be due to just recently downloaded, or the remote checksum matching + the cached copy. + +.. option:: --merged= + + Write a single file containing all rules. This can be used in + addition to ``--output`` or instead of ``--output``. + +.. option:: --no-merge + + Do not merge the rules into a single rule file. + + *Warning: No attempt is made to resolve conflicts if 2 input rule files have the same name.* + +.. option:: --yaml-fragment= + + Output a fragment of YAML containing the *rule-files* section will + all downloaded rule files listed for inclusion in your + *suricata.yaml*. + +.. option:: --url= + + A URL to download rules from. This option can be used multiple + times. + +.. option:: --local= + + A path to a filename or directory of local rule files to include. + + If the path is a directory all files ending in *.rules* will be + loaded. + + Wildcards are accepted but to avoid shell expansion the argument + must be quoted, for example:: + + --local '/etc/suricata/custom-*.rules' + + This option can be specified multiple times. + +.. option:: --sid-msg-map= + + Output a v1 style sid-msg.map file. + +.. option:: --sid-msg-map-2= + + Output a v2 style sid-msg.map file. + +.. option:: --disable-conf= + + Specify the configuration file for disable filters. + + See :ref:`example-disable-conf` + +.. option:: --enable-conf= + + Specify the configuration file for enable rules. + + See :ref:`example-enable-conf` + +.. option:: --modify-conf= + + Specify the configuration file for rule modification filters. + + See :ref:`example-modify-conf` + +.. option:: --drop-conf= + + Specify the configuration file for drop filters. + + See :ref:`example-drop-conf` + +.. option:: --ignore= + + Filenames to ignore. This is a pattern that will be matched against + the basename of a rule files. + + This argument may be specified multiple times. + + Default: *\*deleted.rules* + + Example:: + + --ignore dnp3-events.rules --ignore deleted.rules --ignore "modbus*" + + .. note:: + + If specified the default value of *\*deleted.rules* will no longer + be used, so add it as an extra ignore if needed. + +.. option:: --no-ignore + + Disable the --ignore option. Most useful to disable the default + ignore pattern without adding others. + +.. option:: --etopen + + Download the ET/Open ruleset. + + This is the default action of no ``--url`` options are provided or + no sources are configured. + + Use this option to enable the ET/Open ruleset in addition to any + URLs provided on the command line or sources provided in the + configuration. + +.. option:: -q, --quiet + + Run quietly. Only warning and error message will be displayed. + +.. option:: --dump-sample-configs + + Output sample configuration files for the ``--disable``, + ``--enable``, ``--modify`` and ``--threshold-in`` commands. + +.. option:: --threshold-in= + + Specify the threshold.conf input template. + +.. option:: --threshold-out= + + Specify the name of the processed threshold.conf to output. + +.. option:: -T , --test-command + + Specifies a custom test command to test the rules before reloading + Suricata. This overrides the default command and can also be + specified in the configuration file under ``test-command``. + +.. option:: --no-test + + Disables the test command and proceed as if it had passed. + +.. option:: --reload-command= + + A command to run after the rules have been updated; will not run if + no change to the output files was made. For example:: + + --reload-command=sudo kill -USR2 $(cat /var/run/suricata.pid) + + will tell Suricata to reload its rules. + +.. option:: --no-reload + + Disable Suricata rule reload. + +.. option:: -V, --version + + Display the version of **suricata-update**. + +Rule Matching +============= + +Matching rules for disabling, enabling, converting to drop or +modification can be done with the following: + +- signature ID +- regular expression +- rule group +- filename + +Signature ID Matching +--------------------- + +A signature ID can be matched by just its signature ID, for example:: + + 1034 + +The generator ID can also be used for compatibility with other tools:: + + 1:1034 + +Regular Expression Matching +--------------------------- + +Regular expression matching will match a regular expression over the +complete rule. Example:: + + re:heartbleed + re:MS(0[7-9]|10)-\d+ + +Group Matching +-------------- + +The group matcher matches against the group the rule was loaded +from. Basically this is the filename without the leading path or file +extension. Example:: + + group:emerging-icmp.rules + group:emerging-dos + +Wild card matching similar to wildcards used in a Unix shell can also +be used:: + + group:*deleted* + +Filename Matching +----------------- + +The filename matcher matches against the filename the rule was loaded +from taking into consideration the full path. Shell wildcard patterns +are allowed:: + + filename:rules/*deleted* + filename:*/emerging-dos.rules + +Modifying Rules +--------------- + +Rule modification can be done with regular expression search and +replace. The basic format for a rule modification specifier is:: + + + +where is one of the rule matchers from above, is the +text to be replaced and is the replacement text. + +Example converting all alert rules to drop:: + + re:. ^alert drop + +Example converting all drop rules with noalert back to alert:: + + re:. "^drop(.*)noalert(.*)" "alert\\1noalert\\2" + +Example Configuration Files +=========================== + +.. _example_update_yaml: + +Example Configuration File (/etc/suricata/update.yaml) +------------------------------------------------------ + +.. literalinclude:: ../suricata/update/configs/update.yaml + +.. _example-enable-conf: + +Example Configuration to Enable Rules (--enable-conf) +----------------------------------------------------- + +.. literalinclude:: ../suricata/update/configs/enable.conf + +.. _example-disable-conf: + +Example Configuration to Enable Disable (--disable-conf) +-------------------------------------------------------- + +.. literalinclude:: ../suricata/update/configs/disable.conf + +.. _example-drop-conf: + +Example Configuration to convert Rules to Drop (--drop-conf) +------------------------------------------------------------ + +.. literalinclude:: ../suricata/update/configs/drop.conf + +.. _example-modify-conf: + +Example Configuration to modify Rules (--modify-conf) +----------------------------------------------------- + +.. literalinclude:: ../suricata/update/configs/modify.conf