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
| Word | What it means | Example |
|---|---|---|
| Action | what a rule does when it matches | alert |
| Sticky buffer | a keyword that picks which part of the traffic to search | dns.query |
| Content | the text a rule looks for in that part | |
| Anchor | a keyword that fixes where the text must sit | endswith |
| Threshold | a limit on how often a rule may alert | |
| fast.log | Suricata'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
cd ~/detectShown here, not run. Press Start lab to type it into your own lab’s terminal.
Read the tuned lookup rule
grep "sid:1000002" rules/examples.rulesShown here, not run. Press Start lab to type it into your own lab’s terminal.
Worked example: the parts of rule 1000002
| Part | In the rule | What it means |
|---|---|---|
| Action and protocol | alert dns | Raise an alert, for DNS traffic |
| From and to | any any -> any any | Any address and port, either way |
| Message | msg:"updater lookup" | What the alert will say |
| Sticky buffer | dns.query | Search only the name looked up |
| Content and anchors | dotprefix; content:".cdn-update.example"; endswith | The name ends in that domain |
| Identity | sid:1000002; rev:1 | Its 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
det alerts pcaps/office.pcap rules/examples.rules | head -n 4Shown here, not run. Press Start lab to type it into your own lab’s terminal.
The first try's false positives
det alerts pcaps/office.pcap rules/examples.rules | grep "1:1000001:" | grep -v 10.20.1.15Shown 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
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
grep "sid:1000004" rules/examples.rulesShown here, not run. Press Start lab to type it into your own lab’s terminal.
Compare the counts
det count pcaps/office.pcap rules/examples.rulesShown here, not run. Press Start lab to type it into your own lab’s terminal.