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

-h, --help

Show help.

-D <directory>, --data-dir <directory>

Set an alternate data directory.

Default: /var/lib/suricata

-c <filename>, --config <filename>

Path to the suricata-update config file.

Default: /etc/suricata/update.yaml

-q, --quiet

Run quietly. Only warning and error messages will be displayed.

-v, --verbose

Provide more verbose output.

--suricata-conf <path>

Path to the suricata config file.

Default: /etc/suricata/suricata.yaml

--suricata <path>

The path to the Suricata program. If not provided suricata-update will attempt to find Suricata on your path.

The Suricata program is used to determine the version of Suricata as well as providing information about the Suricata configuration.

--suricata-version <version>

Set the Suricata version to a specific version instead of checking the version of Suricata on the path.

--user-agent <string>

Set a custom user agent string for HTTP requests.

-o, --output

The directory to output the rules to.

Default: /var/lib/suricata/rules

--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.

--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.

--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.

--url=<url>

A URL to download rules from. This option can be used multiple times.

--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.

--sid-msg-map=<filename>

Output a v1 style sid-msg.map file.

--sid-msg-map-2=<filename>

Output a v2 style sid-msg.map file.

--disable-conf=<disable.conf>

Specify the configuration file for disable filters.

See Example Configuration to Disable Rules (–disable-conf)

--enable-conf=<enable.conf>

Specify the configuration file for enable rules.

See Example Configuration to Enable Rules (–enable-conf)

--modify-conf=<modify.conf>

Specify the configuration file for rule modification filters.

See Example Configuration to modify Rules (–modify-conf)

--drop-conf=<drop.conf>

Specify the configuration file for drop filters.

See Example Configuration to convert Rules to Drop (–drop-conf)

--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.

--no-ignore

Disable the –ignore option. Most useful to disable the default ignore pattern without adding others.

--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.

--dump-sample-configs

Output sample configuration files for the --disable, --enable, --modify and --threshold-in commands.

--threshold-in=<threshold.conf.in>

Specify the threshold.conf input template.

--threshold-out=<threshold.conf>

Specify the name of the processed threshold.conf to output.

-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.

--no-test

Disables the test command and proceed as if it had passed.

--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 for more information.

--no-reload

Disable Suricata rule reload.

-V, --version

Display the version of suricata-update.

--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

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 Configuration File (/etc/suricata/update.yaml)

# Configuration with disable filters.
# - Overrided by --disable-conf
# - Default: /etc/suricata/disable.conf
disable-conf: /etc/suricata/disable.conf

# Configuration with enable filters.
# - Overrided by --enable-conf
# - Default: /etc/suricata/enable.conf
enable-conf: /etc/suricata/enable.conf

# Configuration with drop filters.
# - Overrided by --drop-conf
# - Default: /etc/suricata/drop.conf
drop-conf: /etc/suricata/drop.conf

# Configuration with modify filters.
# - Overrided by --modify-conf
# - Default: /etc/suricata/modify.conf
modify-conf: /etc/suricata/modify.conf

# List of files to ignore. Overrided by the --ignore command line option.
ignore:
  - "*deleted.rules"

# Override the user-agent string.
#user-agent: "Suricata-Update"

# Provide an alternate command to the default test command.
#
# The following environment variables can be used.
# SURICATA_PATH - The path to the discovered suricata program.
# OUTPUT_DIR - The directory the rules are written to.
# OUTPUT_FILENAME - The name of the rule file. Will be empty if the rules
#                   were not merged.
#test-command: ${SURICATA_PATH} -T -S ${OUTPUT_FILENAME} -l /tmp

# Provide a command to reload the Suricata rules.
# May be overrided by the --reload-command command line option.
# See the documentation of --reload-command for the different options
# to reload Suricata rules.
#reload-command: sudo systemctl reload suricata

# Remote rule sources. Simply a list of URLs.
sources:
  # Emerging Threats Open with the Suricata version dynamically replaced.
  - https://rules.emergingthreats.net/open/suricata-%(__version__)s/emerging.rules.tar.gz
  # The SSL blacklist, which is just a standalone rule file.
  - https://sslbl.abuse.ch/blacklist/sslblacklist.rules

# A list of local rule sources. Each entry can be a rule file, a
# directory or a wild card specification.
local:
  # A directory of rules.
  - /etc/suricata/rules
  # A single rule file.
  - /etc/suricata/rules/app-layer-events.rules
  # A wildcard.
  - /etc/suricata/rules/*.rules

Example Configuration to Enable Rules (–enable-conf)

# suricata-update - enable.conf

# Example of enabling a rule by signature ID (gid is optional).
# 1:2019401
# 2019401

# Example of enabling a rule by regular expression.
# - All regular expression matches are case insensitive.
# re:heartbleed
# re:MS(0[7-9]|10)-\d+

# Examples of enabling a group of rules.
# group:emerging-icmp.rules
# group:emerging-dos
# group:emerging*

Example Configuration to Disable Rules (–disable-conf)

# suricata-update - disable.conf

# Example of disabling a rule by signature ID (gid is optional).
# 1:2019401
# 2019401

# Example of disabling a rule by regular expression.
# - All regular expression matches are case insensitive.
# re:heartbleed
# re:MS(0[7-9]|10)-\d+

# Examples of disabling a group of rules.
# group:emerging-icmp.rules
# group:emerging-dos
# group:emerging*

Example Configuration to convert Rules to Drop (–drop-conf)

# suricata-update - drop.conf
#
# Rules matching specifiers in this file will be converted to drop rules.
#
# Examples:
#
# 1:2019401
# 2019401
#
# re:heartbleed
# re:MS(0[7-9]|10)-\d+

Example Configuration to modify Rules (–modify-conf)

# suricata-update - modify.conf

# Format: <sid> "<from>" "<to>"

# Example changing the seconds for rule 2019401 to 3600.
# 2019401 "seconds \d+" "seconds 3600"
#
# 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"

# Change all trojan-activity rules to drop. Its better to setup a
# drop.conf for this, but this does show the use of back references.
# re:classtype:trojan-activity "(alert)(.*)" "drop\\2"

# For compatibility, most Oinkmaster modifysid lines should work as
# well.
# modifysid * "^drop(.*)noalert(.*)" | "alert${1}noalert${2}"