Get Started with Suricata CLI Debugging

Tutorials, Tips & Tricks
,
1

Let’s review how to debug Suricata rules from the command line.

If you want to troubleshoot your rules or the Suricata engine itself, then CLI debugging is an invaluable skill to have! The following Suricata bug inspired the material below, Bug #6415: http.header, http.header.raw and http.request_header buffers not populated when malformed header value exists - Suricata - Open Information Security Foundation.

No fancy setup here, just a quick guide that is hopefully accessible for all.

Steps for Linux Users

Whenever Suricata runs from the CLI, it returns files. Let’s setup a directory for our PCAP and custom.rules to reside.

  1. Create a directory for our PCAP and custom.rules.
alice@vm:~/workspace/input$ ls
custom.rules  qlik_bypass.pcap

The custom.rules file should contain…
alert http any any -> any any (msg:"Test Usage of Unbuffered Content"; flow:established,to_server; content:"X-Qlik-User"; fast_pattern; classtype:web-application-attack; sid:13; rev:1;)

qlik_bypass.pcap can be downloaded … here (750 Bytes)

  1. For this blog, we will use Suricata (Stable) version 7.0.2. Download it here: Suricata 7.0.2 released! - Suricata

  2. Extract Suricata to a path e.g.

alice@vm:~/ids/suricata-7.0.2$ pwd
/home/alice/ids/suricata-7.0.2

  1. Configure Suricata
    alice@vm:~/ids/suricata-7.0.2$ ./configure --enable-debug

  2. Install Suricata
    alice@vm:~/ids/suricata-7.0.2$ make

Congrats! Now, you can run Suricata from CLI like this,

alice@vm:~/ids/suricata-7.0.2$ /home/alice/ids/suricata-7.0.2/src/suricata -V
This is Suricata version 7.0.2 RELEASE
  1. Update suricata.yaml so that its default-rule-path and rule-files look like …
default-rule-path: /home/alice/workspace/input

rule-files:
  - custom.rules
  1. Run Suricata
alice@vm:~/workspace$ /home/alice/ids/suricata-7.0.2/src/suricata -c /home/alice/ids/suricata-7.0.2/suricata.yaml -k none -r /home/alice/workspace/input/qlik_bypass.pcap -vvvv 2>&1 | tee run.txt

More on command line options used, :

  • -c, allows us to use our config file
  • -k none, forces Suricata disable all checksum checks. It is useful to turn this off as some PCAPs used are generated with data integrity issues.
  • -r …pcap, this is the path to our pcap
  • -vvvv, returns the Suricata debug lines
  • 2>&1, redirect stderr to stdout
  • | tee output.txt, reads the stdin and stdout, and puts them into an output.txt
  1. Review output files. Here are important files to consider…

  • fast.log - log of alerts consisting of a single line, 12.1. Suricata.yaml — Suricata 7.0.2 documentation. Use this to determine if your rule fired or not.

  • run.txt - log of Suricata engine work. Use this to walk through how Suricata parsed traffic. Reviewing run.txt allowed me to see where Suricata error’ed against the PCAP and how this effected the eve.json being populated.

  • eve.json - log of suricata events and alerts, 17.1.1. Eve JSON Output — Suricata 7.0.2 documentation. Use this to determine how Suricata translated its work to the eve.json format.

Summary

The steps above described how to configure and install Suricata such that it will analyze a rule file and PCAP. After Suricata runs, it returns output files which can be used for troubleshooting analysis.

If you’d like to follow along and analyze these files further, please watch this thread so that you may get updates for Part 2.

Otherwise, you are now prepared to debug Suricata from the CLI!

3 Likes