Suricata

UTMStack v12 collects Suricata IDS/IPS events through the UTMStack Forwarder, which the web interface calls the Collector. Suricata writes its EVE JSON events to the local syslog service, and rsyslog forwards them to the Collector. Nothing else is installed on the Suricata host.

Connection details

SettingValue
Card on the Integrations pageSuricata (category IDS / IPS)
Data typesuricata
Default ports on the Collector7019/UDP; 7019/TCP (also used for TLS)
Log format UTMStack readsSuricata EVE JSON, one event per line, with or without a syslog header in front. EVE stats records are discarded.
Parsing pipelinesuricata/suricata.yaml, version 1.1.1. Filters in the card's drawer opens it.
Detection rules35. Rules in the card's drawer opens them.

Before you begin

  • A Collector must be installed and online. If you do not have one, see UTMStack Forwarder. One Collector can serve all your integrations.

  • The Suricata host must reach the Collector host on the port you use. Open it on the Collector host and on any firewall in between.

  • You need the integrations.write permission to enable the integration from the web interface.

  • The Suricata host needs rsyslog installed and running.

Use TCP. EVE events, especially flow, http and tls records, are often longer than 2,048 bytes, and over UDP the Collector reads at most 2,048 bytes of each message. UTMStack v12.0.2 accepts EVE JSON lines over TCP.

Step 1: Enable the integration on a Collector

  1. 1

    Open the integration

    In UTMStack, go to Configure > Integrations and open the Suricata card.

    Suricata setup guide in UTMStack, showing How it works and the Enable this integration remotely panel with the Collector, Protocol and Port fields

    The guide selects UDP; choose TCP as recommended above. A different number typed in Port does not change the port the Collector listens on; see Use a different port below.

  2. 2

    Choose the Collector and protocol

    Under Enable this integration remotely, select the Collector and set Protocol to TCP (or UDP, or TLS). Leave Port at the default it fills in.

  3. 3

    Enable it

    Click Enable integration. The panel then shows, for example, Currently: enabled · tcp · port 7019.

To do the same on the Collector host instead, run:

sudo /opt/utmstack-forwarder/utmstack_forwarder enable-integration suricata tcp

The command prints the port the Collector really listens on, for example Integration "suricata" enabled on tcp port 7019.

To use TLS, load a certificate on the Collector first. See UTMStack Forwarder.

Use a different port

For built-in integrations, the Collector always listens on the port saved on the Collector host. That is the default port unless you change it there. A different number typed in Port, or on the enable-integration command line, is not used. To use another port:

  1. On the Collector host, change the saved port, for example:

    sudo /opt/utmstack-forwarder/utmstack_forwarder change-port suricata tcp 7119

    Use udp instead of tcp for UDP.

  2. In the Suricata card, type the same port in Port when you enable the integration. If it is already enabled, click Disable integration first, then enable it again with the new port. The panel shows the port you type there, not a value read from the Collector, so typing the same port keeps the two in step.

  3. Use the new port in the rsyslog line in step 3.

Step 2: Send Suricata EVE events to syslog

Suricata is collected as JSON (EVE). On the Suricata host, edit suricata.yaml and configure the eve-log output to write to syslog:

outputs:
  - eve-log:
      enabled: yes
      filetype: syslog
      facility: local5
      types:
        - alert
        - dns
        - http
        - tls
        - flow

Add or remove event types to suit you. alert is the one most detection rules need. Then restart Suricata:

sudo systemctl restart suricata

Step 3: Forward syslog to the Collector

Point the local5 facility, where Suricata now writes, at the Collector. Create /etc/rsyslog.d/60-utmstack-suricata.conf on the Suricata host with this line. Replace <collector-ip> with the address of the Collector host.

local5.*  @@<collector-ip>:7019

@@ sends over TCP. If you enabled the integration with UDP, use a single @ instead.

rsyslog cuts messages longer than 8 KB by default, and EVE records can be longer. To keep them whole, add this line at the very top of /etc/rsyslog.conf, before any module is loaded:

global(maxMessageSize="32k")

Then restart rsyslog:

sudo systemctl restart rsyslog

The setup guide in UTMStack fills in your UTMStack server's address in this step and shows the UDP form (@). Keep the address only if the Collector runs on the UTMStack server; otherwise use the address of the Collector host.

Step 4: Check that logs arrive

  1. 1

    Open the logs

    In the Suricata drawer, click View logs. Log Explorer opens with the suricata data type for the last 24 hours. You can also open Log Explorer, keep the data set logs and choose suricata as the data type.

  2. 2

    Check the parsed fields

    Expand an event. Parsed events have standard fields such as origin.ip, target.ip and target.port, and EVE fields under log.. The event should have no errors.

  3. 3

    Check the data source

    Within about 20 minutes, the Suricata host appears on the Data Sources page under Direct, named after the address its logs come from.

To test the whole path with an alert, use the harmless test from Suricata's quick start guide: from a machine whose traffic Suricata sees, run curl http://testmynids.org/uid/index.html. With the Emerging Threats Open rules, this raises an alert. Then look for an alert event in Log Explorer.

To list the latest events and any processing errors, switch Log Explorer to SQL mode and run:

SELECT `@timestamp`, dataSource, errors, raw
FROM logs
WHERE dataType = 'suricata'
  AND `@timestamp` > now() - INTERVAL 1 HOUR
ORDER BY `@timestamp` DESC
LIMIT 20

Troubleshooting

SymptomLikely causeWhat to do
Nothing arrivesThe Collector is offline, rsyslog sends to the wrong address, port or protocol, or a firewall blocks the port.Check that the Collector shows as online in the Collector list, that the rsyslog line matches the protocol you enabled (@@ for TCP, @ for UDP), and that the Collector host allows the port in. See Forwarder Troubleshooting.
Nothing reaches rsyslogSuricata does not write EVE to syslog.Check the eve-log section of suricata.yaml and Suricata's own log after the restart.
Events are cut off or have no EVE fieldsOver UDP, the Collector reads at most 2,048 bytes of each message; rsyslog cuts messages over its own size limit.Send over TCP (@@) and raise maxMessageSize in rsyslog.
Gaps in events when traffic is highThe local syslog service limits how many messages a program can send (rate limiting).Look for rate-limiting messages in the Suricata host's system log, and raise or turn off the limit in rsyslog or journald, following their documentation.
Suricata events appear under another data typersyslog sends to the port of a different integration.Send to the port that the Suricata integration listens on.
No stats eventsThe UTMStack pipeline discards EVE stats records on purpose.Nothing to do.

Stop collecting

In the Suricata card, select the same Collector and click Disable integration, or run on the Collector host, with the protocol you enabled (tcp, udp or tls):

sudo /opt/utmstack-forwarder/utmstack_forwarder disable-integration suricata tcp

Then delete /etc/rsyslog.d/60-utmstack-suricata.conf on the Suricata host and restart rsyslog.