Suricata/Suricata-yaml-configuration-file

You are here:

Suricata

suricata.yaml

Description

This section describes Suricata's configuration file: suricata.yaml. The syntax is based on YAML (YAML Ain't Markup Language), a human friendly syntax inspired from XML.

By default, the configuration file is located in /etc/suricata/suricata.yaml.

Configuration file syntax

The syntax is the following:

• Each line beginning with a dash (#) is a comment
• Each parameter is composed of a key and one or more values
• Each key begins a line without space and finishes with a colon (e.g. "action_order:")
• Value(s):
  • If a key has only one value, this latest is defined immediately after the colon, on the same line as the key and is preceded by a space (e.g. "default-log-dir: /var/log/suricata")
  • If the key has more than one value, each value begins on a new line with one or more spaces, indent, a space and a value (e.g. " - pass")

Here is an example for the parameter action-order:

action-order:
  - pass
  - drop
  - reject
  - alert

List of parameters

action-order

Set the order of alerts based on actions. The default order is pass, drop, reject, alert

default-log-dir

The default logging directory. Any log or output file will be placed here if its not specified with a full path name. This can be overridden with the -l command line parameter.

outputs

Configure the type of alert (and other) logging you would like.

Each output has two mandatory values [enabled (yes|no) and filename] and one optional value [limit (in MB)].

• fast: a line based alerts log similar to Snort's fast.log
• unified-log: log output for use with Barnyard
• unified2-alert: alert output for use with Barnyard2
• http-log: a line based log of HTTP requests (no alerts)
• alert-debug: a full alerts log containing much information for signature writers or for investigating suspected false positives.
• alert-prelude: alert output to prelude (http://www.prelude-technologies.com/) only available if Suricata has been compiled with --enable-prelude

defrag

Defines the eventual packet fragmentation

Expects following values:

• max-frags: Default value is 65535
• prealloc: Default value is yes
• timeout: Default value is 60

threshold-file

Specifies the path to the threshold configuration file (e.g. /etc/suricata/threshold.config)

detect-engine

The detection engine builds internal groups of signatures. The engine allows to specify the profile to use for them, to manage memory on an efficient way keeping a good performance.

• profile: Memory management. Can take on of these values: low | medium | high | custom
• custom-values

threading

On some cpu's/architectures it is beneficial to tie individual threads to specific CPU's/CPU cores. In this case all threads are tied to CPU0, and each extra CPU/core has one "detect" thread.

On Intel Core2 and Nehalem CPU's enabling this will degrade performance.

By default Suricata creates one "detect" thread per available CPU/CPU core.

"detect_thread_ratio" allows controlling this behaviour. A ratio setting of 2 will create 2 detect threads for each CPU/CPU core. So for a dual core CPU this will result in 4 detect threads. If values below 1 are used, less threads are created. So on a dual core CPU a setting of 0.5 results in 1 detect thread being created. Regardless of the setting at a minimum 1 detect thread will always be created.

• set_cpu_affinity: yes | no
• detect_thread_ratio: float number

cuda

Select the cuda device to use. The "device_id" identifies the device to be used if one has multiple devices on the system. To find out device_id associated with the card(s) on the system run "suricata --list-cuda-cards".

mpm-algo

Select the multi pattern algorithm you want to run for scan/search the in the engine. The supported algorithms are b2g, b3g and wumanber.

There is also a CUDA pattern matcher (only available if Suricata was compiled with --enable-cuda: b2g_cuda. Make sure to update your max-pending-packets setting above as well if you use b2g_cuda.

pattern-matcher

Scan (scan_algo) and search (search_algo) algorithms to use, hash size (hash_size) and bloom filter size (bf_size) for:

• b2g
• b3g
• wumanber

flow

By default, the reserved memory (memcap) for flows is 32MB. This is the limit for flow allocation inside the engine. You can change this value to allow more memory usage for flows.

The hash_size determines the size of the hash used to identify flows inside the engine, and by default the value is 65536.

At the startup, the engine can preallocate a number of flows, to get a better performance. The number of flows preallocated is 10000 by default.

emergency_recovery is the percentage of flows that the engine needs to prune before unsetting the emergency state. The emergency state is activated when the memcap limit is reached, allowing to create new flows, but prunning them with the emergency timeouts (they are defined below).

If the memcap is reached, the engine will try to prune prune_flows with the default timeouts. If it doens't find a flow to prune, it will set the emergency bit and it will try again with more agressive timeouts.

If that doesn't work, then it will try to kill the last time seen flows not in use.

• memcap: Default value is 33554432
• hash_size: Default value is 65536
• prealloc: Default value is 10000
• emergency_recovery: Default value is 30
• prune_flows: Default value is 5

flow-timeouts

Specify the timeouts that the active flows will wait to transit from the current state to another, on each protocol.

The value of "new" determine the seconds to wait after a hanshake or stream startup before the engine frees the data of that flow.

The value of "established" is the amount of seconds that the engine will wait to free the flow if it spends that amount without receiving new packets or closing the connection.

"closed" is the amount of time to wait after a flow is closed (usually zero).

There's an emergency mode that will become active under attack circumstances, making the engine to check flow status faster. This configuration variables use the prefix "emergency_" (emergency_new, emergency_established, emergency_closed) and work similar as the normal ones.

Some timeouts doesn't apply to all the protocols, like "closed", for udp and icmp.

stream

Stream engine settings

• memcap: TCP session memcap. Default: 33554432
• checksum_validation: To validate the checksum of received packet. If csum validation is specified as "yes", then packet with invalid csum will not be processed by the engine stream/app layer. Default: yes.
• max_sessions: Nb of concurrent sessions. Default: 262144
• prealloc_sessions: Nb of sessions prealloc'd. Default: 32768
• midstream: Don't allow midstream session pickups. Default: false.
• async_oneside: Don't enable async stream handling. Default: false.
• reassembly
  • memcap: TCP reassembly memcap. Default 67108864
  • depth: Default 1048576

Logging

This logging doesn't concern the output files generated about alerts but debug and status information.

Note that debug level logging will only be emitted if Suricata was compiled with the --enable-debug configure option.

• default-log-level
  • This value is overriden by the SC_LOG_LEVEL env var.
  • Default value: info

• default-log-format
  • Optional parameter, should default to something reasonable if not provided.
  • You can leave this out to get the default. This value is overriden by the SC_LOG_FORMAT env var.
  • Example: "[%i] %t - (%f:%l) <%d> (%n) -- "

• default-output-filter
  • A regex to filter output. Can be overridden in an output section.
  • Defaults to empty (no filter).
  • This value is overriden by the SC_LOG_OP_FILTER env var.

• outputs: Define your logging outputs. If none are defined, or they are all disabled you will get the default - console output.

Param	Possible values	console	file	syslog
enabled	yes, no	x	x	x
filename	/var/log/suricata.log		x
facility	local5			x
format	"[%i] <%d> -- "	x	x	x

pfring

• interface
  • Default interface we will listen on.
  • Default: eth0

• cluster-id
  • Default clusterid.
  • PF_RING will load balance packets based on flow.
  • All threads/processes that will participate need to have the same clusterid.
  • Default: 99

• cluster-type
  • Default PF_RING cluster type. PF_RING can load balance per flow or per hash.
  • This is only supported in versions of PF_RING > 4.1.1.
  • Default: cluster_round_robin

ipfw

For FreeBSD ipfw(8) divert(4) support.

Make sure you have ipfw_load="YES" and ipdivert_load="YES" in /etc/loader.conf or kldload'ing the appropriate kernel modules.

Additionally, you need to have an ipfw rule for the engine to see the packets from ipfw.

For Example:

ipfw add 100 divert 8000 ip from any to any

The 8000 above should be the same number you passed on the command line, i.e. -d 8000.

Reinject packets at the specified ipfw rule number. This config option is the ipfw rule number AT WHICH rule processing continues in the ipfw processing system after the engine has finished inspecting the packet for acceptance. If no rule number is specified, accepted packets are reinjected at the divert rule which they entered and IPFW rule processing continues. No check is done to verify this will rule makes sense so care must be taken to avoid loops in ipfw.

The following example tells the engine to reinject packets back into the ipfw firewall AT rule number 5500:

ipfw-reinjection-rule-number: 5500

default-rule-path

Set the default rule path here to search for the files.

If not set, it will look at the current working dir.

Default value: /etc/suricata/rules/

rule-files

List of signature files to use. For more information about rules and know how to set up rules, please refer to this section.

The default list is as follows. It contains a mix of rules from Snort (VRT) and Threat.

• attack-responses.rules
• backdoor.rules
• bad-traffic.rules
• chat.rules
• ddos.rules
• deleted.rules
• dns.rules
• dos.rules
• experimental.rules
• exploit.rules
• finger.rules
• ftp.rules
• icmp-info.rules
• icmp.rules
• imap.rules
• info.rules
• local.rules
• misc.rules
• multimedia.rules
• mysql.rules
• netbios.rules
• nntp.rules
• oracle.rules
• other-ids.rules
• p2p.rules
• policy.rules
• pop2.rules
• pop3.rules
• porn.rules
• rpc.rules
• rservices.rules
• scada.rules
• scan.rules
• shellcode.rules
• smtp.rules
• snmp.rules
• specific-threats.rules
• spyware-put.rules
• sql.rules
• telnet.rules
• tftp.rules
• virus.rules
• voip.rules
• web-activex.rules
• web-attacks.rules
• web-cgi.rules
• web-client.rules
• web-coldfusion.rules
• web-frontpage.rules
• web-iis.rules
• web-misc.rules
• web-php.rules
• x11.rules
• emerging-attack_response.rules
• emerging-dos.rules
• emerging-exploit.rules
• emerging-game.rules
• emerging-inappropriate.rules
• emerging-malware.rules
• emerging-p2p.rules
• emerging-policy.rules
• emerging-scan.rules
• emerging-virus.rules
• emerging-voip.rules
• emerging-web.rules
• emerging-web_client.rules
• emerging-web_server.rules
• emerging-web_specific_apps.rules
• emerging-user_agents.rules
• emerging-current_events.rules

classification-file

Path to classification file. For more information, please refer to this section.

Default value: /etc/suricata/classification.config

vars

Holds IP addresses and ports used by the engine.

• address-groups: Definition of IP addresses. May be of the following form: "[a.b.c.d/x]" or "[a.b.c.d/x,e.f.g.h/y,::1]" or "any" or a reference to an already defined variable (e.g. "$HOME_NET") or an exclusion (e.g. "!$HOME_NET").
  • HOME_NET: Defines the home net IP range Suricata will apply to.
  • EXTERNAL_NET
  • HTTP_SERVERS
  • SMTP_SERVERS
  • SQL_SERVERS
  • DNS_SERVERS
  • TELNET_SERVERS
  • AIM_SERVERS

• port-groups: Definition of the ports to use. Can be of the form of an included port (e.g. "80" or 80) or an excluded port (e.g. "!80")
  • HTTP_PORTS
  • SHELLCODE_PORTS
  • ORACLE_PORTS
  • SSH_PORTS

host-os-policy

Host specific policies for defragmentation and TCP stream reassembly. The host OS lookup is done using a radix tree, just like a routing table so the most specific entry matches.

Values can be of the form of single IP addresses (e.g. 192.168.1.100) or an IP range (e.g. 10.0.0.0/8) or ports, separated by a colon (e.g. "8762:2352:6241").

The default configuration applies for a windows policy.

• windows: List of Windows hosts. Default value: [0.0.0.0/0]
• bsd: List of BSD hosts. Default value: []
• bsd_right: Default value: []
• old_linux: List of old Linux hosts. Default value: []
• linux: List of Linux hosts. Default value: [10.0.0.0/8, 192.168.1.100, "8762:2352:6241:7245:E000:0000:0000:0000"]
• old_solaris: List of old Solaris hosts. Default value: []
• solaris: List of Solaris hosts. Default value: ["::1"]
• hpux10: List of HP UX 10.x hosts. Default value: []
• hpux11: List of HP UX 11.x hosts. Default value: []
• irix: List of IRIX hosts. Default value: []
• macos: List of MacOS hosts. Default value: []
• vista: List of Windows Vista hosts. Default value: []
• windows2k3: List of Windows 2003 hosts. Default value: []

libhtp

Configure Libhtp.

Currently Available Personalities:

• Minimal
• Generic
• IDS
• IIS_4_0
• IIS_5_0
• IIS_5_1
• IIS_6_0
• IIS_7_0
• IIS_7_5
• Apache
• Apache_2_2

• default-config: Used when no server-config matches
  • personality: List of personalities used by default. Default value: IDS.
• server-config: List of server configurations to use if address matches
  • address: List of IP addresses or networks for this block
  • personality: List of personalities used by this block

profiling

Rule profiling settings. Only effective if Suricata has been built with the --enable-profiling configure flag.

• rules
  • enabled: Profiling can be disabled here, but it will still have a performance impact if compiled in. Possible values: yes|no. Default value: yes.
  • sort: Sort options: ticks, avgticks, checks, matches. Default value: avgticks.
  • limit: Limit the number of items printed at exit. Default value: 100