Target Audience

This quick guide is intended for those who would like to develop and/or make changes to Suricata. These instructions are not suitable for a live or production installation of Suricata.

Requirements

  • Ubuntu 24.04 (inside WSL is OK)
  • Root access via sudo.
  • Basic familiarity with the Linux command line, git and GitHub.

Install Dependencies

Before building Suricata, let's get a basic set of system dependencies installed for building and developing Suricata.

sudo apt update && sudo DEBIAN_FRONTEND=noninteractive apt -y install autoconf automake bindgen build-essential cargo cbindgen curl git jq libcap-ng-dev libhyperscan-dev libjansson-dev libmagic-dev libnet1-dev libnetfilter-queue-dev libnetfilter-queue1 libnfnetlink-dev libnfnetlink0 libnuma-dev libpcap-dev libpcre2-dev libtool libyaml-dev make python-is-python3 python3-yaml rustc software-properties-common zlib1g zlib1g-dev

Checkout Suricata and Suricata-Verify

Now it's time to check out Suricata:

  • To keep this guide brief, we are cloning from the OISF GitHub repositories. If you plan to contribute back to Suricata, you should first create your own forks of these repositories on GitHub then check out your forks.
  • This guide assumes the use of the directory ~/suridev for your Suricata development. Change as needed.
mkdir -p ~/suridev
cd ~/suridev
git clone https://github.com/OISF/suricata
git clone https://github.com/OISF/suricata-verify

Build Suricata for Development

cd ~/suridev/suricata
./autogen.sh
CFLAGS="-fsanitize=address" ./configure --enable-unittests
make -j4

Notes:

  • The -j4 option to make specifies the parallelization level. If you have 16 cores to spare, feel free to run make -j16, and so on.

Run Unit Tests

ASAN_OPTIONS=detect_leaks=0 ./src/suricata -l . -u

Notes:

  • To run a subset of tests, use the -U command-line option with a regular expression or substring, for example: -U DNS.
  • To quit immediately after a unit test fails, provide --fatal-unittests on the command line.
  • We hope to eliminate the need for ASAN_OPTIONS=detect_leaks=0 soon.

Run Verification Tests

../suricata-verify/run.py -q

Notes:

  • It can take many minutes to run all the verification tests.
  • To run only tests whose name matches your filter, add a test name (or partial name) to the command line, for example: ../suricata-verify/run.py -q dns.
  • Leave off the -q to see a line item for each test.
  • To quit immediately after a test fails, add --fail.

Demo

Alternative versions: mp4 gif

Next Steps

Break a Suricata-Verify Test

  • Modify a Suricata source file such that the output will change. For example, in rust/src/ike/logger.rs, remove init_spi from the output (hint: look for jb.set_string("init_spi").
  • Re-build Suricata: make
  • Run the IKE Suricata-Verify tests: ../suricata-verify/run.py ike

Notice how the test fails because we changed the output from what the verification test expects.

Create Your Own Suricata-Verify Test

A good way to start here is to make a copy of an existing test that is similar to what you are working on. Any test will do for the sake of example:

cd ~/suridev/suricata-verify/tests
cp -a alert-testmyids my-awesome-test

Now run your new test:

cd ~/suridev/suricata
../suricata-verify/run.py my-awesome-test