The Fast Guide to Building and Testing Suricata on Ubuntu

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.

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 checkout 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 checkout 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 limit which tests are run, the -U command line option can be used to limit the test to 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 limit tests to tests matching a name, just 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

Hit the play button in the lower left, note that there is no sound.

Your browser does not support the video tag. You can view the animation here.

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, as 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 same 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