Getting Started Contributing to Suricata

Posted on | by kmisata

Getting started contributing to Suricata

Written by: Juliana Fajardini, OISF Developer

Last month, we wrote about our participation in Outreachy and its importance. Now, I want to cover a more practical side of Outreachy contributions, not only for those who have applied and have OISF as one of their communities of choice, but also to anyone interested in making their first contributions to our tools and open source, really.

Disclaimer(s): this post is focused mainly on aspects for those contributing to Suricata with code, because so far our internship projects have had this perspective. This post is heavily influenced by what I have learned during my internship, and in the past months, as a junior developer at OISF.

Ed has the hacking skills

The main topics I’ll try to cover are:

  • Setting up your Suricata coding environment;
  • Understanding our contribution flow and guidelines;
  • Tips, our mindset, resources.

Setup steps

Suricata project (and our other utility tools) is hosted on GitHub. This means that:

There are some useful configuration flags one should use before compiling the code, for developers or advanced users. When you follow the installation instructions, replace the ./configure line with the buffed:

CFLAGS="-O0 -ggdb -fno-omit-frame-pointer" ./configure --disable-shared --enable-debug --enable-unittests

This enables unit tests and debugging.

Contributing

All set! What’s next? You must find an issue/ ticket to work on. Our issues (bugs, tasks, documentation requests) are kept on our Redmine project: Open Information Security Foundation. You’ll need to register a user in order to interact with us there.

  • There are labels for one to filter “good first issues” or “beginner” tickets;
  • Before assigning a ticket to yourself, you’ll need to claim it (ask in the issue itself). For the first time, we also have to grant you developer privileges before;
./src/suricata -u 

— will run all our unit tests

./src/suricata -u -U <pattern> 

— will run all tests with “pattern” in their names

python ../your-suricata-verify-dir/run.py  

— will run all S-V tests

python ../your-suricata-verify-dir/run.py <pattern>  

— will run all tests with “pattern” in their name

  • Tests pass, uhu! /o/ commit locally; run clang for code formatting checks; and push to your GitHub repo; wait and see if there are any CI failures you know how to fix; then you can open a pull request :]

/* Before you commit, do check our Commit Criteria. Reading this post on How to Write a Git Commit Message helped a lot in understanding why all that is useful. */

  • Your PR got feedback? New work goes in a new branch. Submit new changes to a new PR. Mention the new PR in the previous one, and close it. When a PR gets merged, close the ticket, with a link to the merged PR.

Ok, all that may sound overwhelming. Even this post got longer than intended. D: But consider it this way: you’re entering a new professional space, and it’s important to understand how things work, if we want to have a good journey, right? So bear with us, and relax – you don’t need to know all of that by heart, just bookmark what you consider important, and, by repetition, the things that make sense to you will stick. In a few months or less you’ll realize you don’t even think before doing any of these things: they’ll be part of your routine 🙂

Wrapping up thoughts

  • There will be lots of PR reviews. It happens to all of us 🙂
  • Check out our forum, we have a nice community there: forum.suricata.io
  • Feeling vintage? We have IRC channels: #suricata @ libera chat
  • Checking our GitHub – commits, PRs, reviews, other folks’ code – is a great learning source
  • Mindset! We are all learning. Mentors and seniors are just folks who have been doing this for longer, but we all had to get started somewhere 🙂
    • There are no dumb questions. If you’ve looked for an answer and couldn’t find it, or if you don’t even understand the problem well enough to formulate a question to help you find an answer, that’s ok. When you reach out for help and ask what you fear could be a beginner’s question, you allow others to better understand your needs, and you open the door to learning more. As a bonus, if you ask it in a forum or public chat, others may also benefit from that interaction.
    • We all make mistakes.
      • Code mistakes. The tests, GitHub Continuous Integration checks, and PR reviews are there to reduce the chances that something could break the code, and ensure the quality of our tool. 
      • Other mistakes. So long as no one intentionally offends someone else, we understand we’re all in the process of learning and getting better. Making mistakes is how one learns, so we should be ok with them. No hiding, no shaming 🙂 
  • Communicate early, and often;
    • This applies to sharing code, too! Small commits and PRs are much easier to review and work incrementally on;
  • Break bigger complex tasks into small(er) steps.

It’s also good to know that…

  • Very Busy/ Absent times: we have our yearly conference (SuriCon) happening around October, usually. While this shall not affect our dedication to Outreachy applicants during the contribution phase, we may not be as available for much else. Christmas and Gregorian Calendar’s new year are also moments where our team is less available;
  • If you are an Outreachy applicant, you are welcome to participate in our forum group for Outreachy-ers: https://forum.suricata.io/g/Outreachy
  • We do have a code of conduct: https://oisf.net/about-us/. If you feel someone has violated that, please do not hesitate to contact us at info@oisf.net

Resources