Setting up Suricata in OPNsense

this is copied from [opnsenseETPRODocs][The OPNsense Docs]

First we need to install the required plugin, which is responsible for collecting the telemetry data and provides access to the ET Pro ruleset.

• Go to System ‣ Firmware ‣ Updates
• Press “Check for updates” in the upper right corner.
  • Open the tab “Plugins” and search for os-etpro-telemetry
  • Click on the + sign on the right to install the plugin
  • A screen containing the installation status should appear now and the plugin is ready for use.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

***GOT REQUEST TO INSTALL***
Currently running OPNsense 22.7.a_247 (amd64/OpenSSL) at Fri Apr  8 14:01:10 CDT 2022
Updating OPNsense repository catalogue...
OPNsense repository is up to date.
All repositories are up to date.
The following 1 package(s) will be affected (of 0 checked):

New packages to be INSTALLED:
	os-etpro-telemetry-devel: 1.6_1

Number of packages to be installed: 1

12 KiB to be downloaded.
[1/1] Fetching os-etpro-telemetry-devel-1.6_1.txz: .. done
Checking integrity... done (0 conflicting)
[1/1] Installing os-etpro-telemetry-devel-1.6_1...
[1/1] Extracting os-etpro-telemetry-devel-1.6_1: .......... done
Stopping configd...done
Starting configd.
Ignoring invalid metadata: /usr/local/opnsense/version/pkgs
Checking integrity... done (0 conflicting)
Nothing to do.
***DONE***

The next step is to register your token in OPNsense and enable rulesets.

• Go to Services ‣ Intrusion Detection ‣ Administration
• Click on the Download tab
  • This should present you with a list of available rules.
  • Enable all categories you would like to monitor in the “ET telemetry” section. if in doubt enable all and monitor the alerts later (select on the right and use the enable selected button on top)
  • At the bottom of the page there is a block containing settings paste the token code you received via email in et_telemetry.token
  • Press save to persist your token code
  • Press Download & Update rules to fetch the current ruleset

To download the rulesets automatically on a daily bases, you can add a schedule for this task.

Go to Services ‣ Intrusion Detection ‣ Administration Click on the “Schedule” tab A popup for the update task appears, enable it using the checkbox on top, and click “save changes” Subscription status

To validate your subscription, we recommend to add the widget to the dashboard.

Go to the dashboard Lobby ‣ Dashboard Click on “Add widget” in the top right corner, click “Telemetry status” in the list Close dialog and click “Save settings” on the right top of the dashboard Open Lobby ‣ Dashboard again to refresh the content When everything is setup properly and the plugin can reach Proofpoint, it will show something like:

../_images/ETPRO_telemetry_widget_active.png The status determines which ruleset your sensor will receive, ACTIVE or DORMANT your sensor will receive ET Pro ruleset, when DISABLED the license conditions are not met and the ET Open ruleset will be served.

All timestamps underneath the status provide you with information when data was send or received from Proofpoint.

Note

If your sensor will start sending events and heartbeats, it should switch to active after a certain amount of time. In case your sensor cant communicate to the outside world, the widget shows an error.

Note

The system log (System ‣ Log Files ‣ General) might contain more information, search for emergingthreats Tip

Always check the token code first, a common mistake is adding leading or trailing spaces to the code, which will show an error in the log (http_code starting with a 4 usually). Information sent to Proofpoint ©

When the intrusion detection system logs events, they will be (partially) sent to Proofpoint in return for using the ET Pro Telemetry edition.

This paragraph describes the attributes from the eve.json log file that are collected to improve threat detection and the sensor health data to evaluate if the data is usable.

An example of an event is detailed below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "event_type": "alert",
  "proto": "IPV6-ICMP",
  "timestamp": "2018-04-17T18:38:04.498109+0200",
  "in_iface": "em1",
  "alert": {
    "category": "Generic Protocol Command Decode",
    "severity": 3,
    "rev": 2,
    "gid": 1,
    "signature": "SURICATA zero length padN option",
    "action": "allowed",
    "signature_id": 2200094
  },
  "src_ip": "xxxx:xxxx:fec0:d65f",
  "flow_id": 982154378249516,
  "dest_ip": "ff01:fe00:1200:8900:0000:f000:0000:0016"
}

Network addresses are needed to identify hosts which pose a higher risk to your and other peoples network, but your internal addresses are kept secret.

For this reason we mask the addresses found in the log file and only send the last number(s) to identify the host. In the example above the src_ip is an internal IPv6 address, for IPv4 we only collect the last number (e.g. 0-255).

Fields collected (unmodified):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

timestamp
Timestamp of the event
flow_id
Internal identifier for this communication flow
in_iface
Interface where the event was captured
event_type
Type of event
vlan
Vlan tag
src_port
Source port number
dest_port
Destination port number
proto
Protocol
alert
Alert details, such as the signature_id, action taken and associated message.
tls
TLS details, such as certificate subject and serial.
http
HTTP detail information such as the host, but omitting sensitive details such as path and user-agent.
app_proto
Application protocol (if known)

Threats change often, to keep statistics valuable, the list of fields is subject to change

Note

The plugin comes with a small script to print eve output yourself, its called dump_data.py, when used with the -p parameter, it will output the data as it will be sent to Proofpoint. All script code can be found in the following directory /usr/local/opnsense/scripts/ids_telemetry/

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

Unique Sensor ID
Unique sensor identification, helps identifying messages from the same system, without knowing who is the operator.
OPNSense Version
Current installed software version. This will help both for troubleshooting purposes (if a bad update is pushed and Proofpoint notices that deployments running version X have an issue) as well for planning, to understand how new features and functionality would be adopted.
Suricata Version
Suricata version installed.
Suricata status
Reports if the sensor is active, when not active, no detection/telemetry can be provided.
System Time
If the system time is not correct, it will impact the timestamps of messages, so knowing what time the system thinks it has will help reconcile the actual time.
Active Ruleset Version
The active ruleset version should match what is published. If sensors do not have the active version then they either haven’t configured scheduled updates or there is another issue. This will help Proofpoint to identify if there are widespread issues with updates.
Number of rules enabled
Helps to gain a better understanding about the number of rules people use on top of the ones provided by Proofpoint.
Number of ETPro Telemetry Rules enabled
Because users can control what rules they enable, they may not want to enable all ETPro Telemetry rules, if this is the case it would help Proofpoint understand how the rules are being leveraged so they can better write / tune rules
Mode (IDS or IPS)
This is helpful to understand how the system is deployed and is useful to development purposes to determine what rules we should be focusing on based on how our customers are using them.
Suricata Log Stats
For QA purposes, some fields with general stats are collected from /var/log/suricata/stats.log (capture.kernel_packets, decoder.pkts, decoder.bytes, decoder.ipv4, decoder.ipv6, flow.tcp, flow.udp, detect.alert)