diff options
Diffstat (limited to 'doc/update.rst')
| -rw-r--r-- | doc/update.rst | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/doc/update.rst b/doc/update.rst new file mode 100644 index 0000000..c3db62e --- /dev/null +++ b/doc/update.rst @@ -0,0 +1,324 @@ +######################## +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 +======= + +.. include:: ./common-options.rst + +.. option:: -o, --output + + The directory to output the rules to. + + Default: */var/lib/suricata/rules* + +.. 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:: --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=<filename.yaml> + + Output a fragment of YAML containing the *rule-files* section will + all downloaded rule files listed for inclusion in your + *suricata.yaml*. + +.. option:: --url=<url> + + A URL to download rules from. This option can be used multiple + times. + +.. option:: --local=<filename or directory> + + 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=<filename> + + Output a v1 style sid-msg.map file. + +.. option:: --sid-msg-map-2=<filename> + + Output a v2 style sid-msg.map file. + +.. option:: --disable-conf=<disable.conf> + + Specify the configuration file for disable filters. + + See :ref:`example-disable-conf` + +.. option:: --enable-conf=<enable.conf> + + Specify the configuration file for enable rules. + + See :ref:`example-enable-conf` + +.. option:: --modify-conf=<modify.conf> + + Specify the configuration file for rule modification filters. + + See :ref:`example-modify-conf` + +.. option:: --drop-conf=<drop.conf> + + Specify the configuration file for drop filters. + + See :ref:`example-drop-conf` + +.. option:: --ignore=<pattern> + + 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:: --dump-sample-configs + + Output sample configuration files for the ``--disable``, + ``--enable``, ``--modify`` and ``--threshold-in`` commands. + +.. option:: --threshold-in=<threshold.conf.in> + + Specify the threshold.conf input template. + +.. option:: --threshold-out=<threshold.conf> + + Specify the name of the processed threshold.conf to output. + +.. option:: -T <command>, --test-command <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=<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 $(pidof suricata)' + + will tell Suricata to reload its rules. + + Furthermore the reload can be triggered using the Unix socket of Suricata. + + Blocking reload (with Suricata waiting for the reload to finish):: + + --reload-command='sudo suricatasc -c reload-rules' + + Non blocking reload (without restarting Suricata):: + + --reload-command='sudo suricatasc -c ruleset-reload-nonblocking' + + See the Suricata documentation on `Rule Reloads + <https://suricata.readthedocs.io/en/latest/rule-management/rule-reload.html>`_ + for more information. + +.. option:: --no-reload + + Disable Suricata rule reload. + +.. option:: -V, --version + + Display the version of **suricata-update**. + +.. option:: --offline + + Run offline using most recent cached rules. + +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 + +Metadata Matching +----------------- + +Rules can be enabled or disabled based on the metadata fields +contained in the rule, for example:: + + metadata: deployment perimeter + +Will match rules that have a metadata field of "deployment" with the +value of "perimeter" (case insensitive). This will match on a rule +with the provided metadata:: + + metadata:affected_product Any, attack_target Any, deployment Perimeter + +.. note:: Metadata matching can only be used to enable, disable or + convert rules to drop. It is not available for rule + modification. + +Modifying Rules +--------------- + +Rule modification can be done with regular expression search and +replace. The basic format for a rule modification specifier is:: + + <match> <from> <to> + +where <match> is one of the rule matchers from above, <from> is the +text to be replaced and <to> 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" + +Order of application of configuration files +=========================================== +1. disable.conf +2. enable.conf +3. drop.conf +4. modify.conf + +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 Disable Rules (--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 |