Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

Writing Suricata rules and tuning alerts

After this lesson: I can write a Suricata rule and tune it to stop a false positive.

65 min lesson6 commandsDetection engineering lab: Suricata rules, Sigma rules and Zeek-style logs on one private Ubuntu VM

One line that watches every packet

Suricata is an open-source intrusion detection system: it reads network traffic, checks it against rules and writes an alert when one matches. A Suricata rule is one line of text.

One careless word in that line can raise hundreds of false alarms a day. You write and tune rules on a made-up office's capture, in your own lab copy only.

By the end of this lesson

Note

I can write a Suricata rule and tune it to stop a false positive.

Key words

WordWhat it meansExample
Actionwhat a rule does when it matchesalert
Sticky buffera keyword that picks which part of the traffic to searchdns.query
Contentthe text a rule looks for in that part
Anchora keyword that fixes where the text must sitendswith
Thresholda limit on how often a rule may alert
fast.logSuricata's file of alerts, one line each

The cells students fill in are left blank in this preview.

The one rule

Important

Run Suricata only on your own lab copy, or on a network whose owner has given written permission. The captures here are made up. A rule is written to protect a network, never to watch people who have not agreed to it.

A rule has a header and options

A rule starts with a header: the action, the protocol, and where the traffic goes from and to. The options follow in brackets, each ending with a semicolon.

The Run prints the tuned rule for updater's lookups, SID 1000002. The table takes it apart.

Move into the lab's folder

Command
cd ~/detect

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Read the tuned lookup rule

Command
grep "sid:1000002" rules/examples.rules

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: the parts of rule 1000002

PartIn the ruleWhat it means
Action and protocolalert dnsRaise an alert, for DNS traffic
From and toany any -> any anyAny address and port, either way
Messagemsg:"updater lookup"What the alert will say
Sticky bufferdns.querySearch only the name looked up
Content and anchorsdotprefix; content:".cdn-update.example"; endswithThe name ends in that domain
Identitysid:1000002; rev:1Its number and its version

The cells students fill in are left blank in this preview.

An alert names the rule and the flow

The first Run shows the first four alerts on the office capture. Each line has the time, the SID, the message, the protocol, and the source and destination with their ports.

The second Run keeps the alerts of the first try, rule 1000001, that did not come from the infected machine, 10.20.1.15. All three are false positives.

The first four alerts

Command
det alerts pcaps/office.pcap rules/examples.rules | head -n 4

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

The first try's false positives

Command
det alerts pcaps/office.pcap rules/examples.rules | grep "1:1000001:" | grep -v 10.20.1.15

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

A common mistake

Warning

Many people think content matches a whole name. It matches anywhere inside it, so "cdn-update" also matches cdn-updates.example and cdn-update.example.org. Use endswith to fix the end, and dotprefix so only whole labels count.

Try it: loose and tight tests

Code: python
names = ["a1b2.cdn-update.example", "cdn-update.example",
         "cdn-updates.example", "cdn-update.example.org"]

for name in names:
    loose = "cdn-update" in name
    tight = ("." + name).endswith(".cdn-update.example")
    print(name, "loose:", loose, "tight:", tight)
# Add "mycdn-update.example". Which test does it pass?

A threshold stops one machine flooding you

Updater calls home every minute, so rule 1000003 alerts 20 times for one machine. One alert says the same.

Rule 1000004 adds threshold: type limit, track by_src, count 1, seconds 3600: at most one alert per source machine an hour. type threshold alerts on every count-th match instead, and type both alerts once when the count is reached.

Read the rule with a threshold

Command
grep "sid:1000004" rules/examples.rules

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Compare the counts

Command
det count pcaps/office.pcap rules/examples.rules

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

About this lab and its source: Detection engineering lab: Suricata rules, Sigma rules and Zeek-style logs on one private Ubuntu VM

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.