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.

--merged=<filename>

Write a single file containing all rules. This can be used in addition to --output or instead of --output.

--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 Enable Disable (–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 $(cat /var/run/suricata.pid)

will tell Suricata to reload its rules.

--no-reload

Disable Suricata rule reload.

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

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

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.
#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 Enable Disable (–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"

# 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}"