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.
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.
Suricata project (and our other utility tools) is hosted on GitHub. This means that:
- You’ll need a GitHub account – if you already have one, you’re good to go;
- Fork our repository (new PRs are pushed to master) – https://github.com/OISF/suricata;
- Clone your forked repository to your local environment, and set it up. More details can be found at: Suricata Installation – Suricata – Open Information Security Foundation;
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.
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;
- There are more details in our guide for Contributing – Suricata – Open Information Security Foundation
- And our Suricata Developers Guide – Suricata – Open Information Security Foundation
- Ticket claimed; you’ve worked on some code; now what? Testing! Compile it and:
- Run unit tests for checking the functionality of small units of code:
— will run all our unit tests
./src/suricata -u -U <pattern>
— will run all tests with “pattern” in their names
- Run Suricata-verify to test Suri functionalities in a higher level:
- clone S-V to a directory outside Suri: https://github.com/OISF/suricata-verify
- from within Suricata’s directory, you can run:
— 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 firstname.lastname@example.org
- Suricata How-Tos playlist on YouTube cover installation and setup: Help & How-To
- Check at our presented by interns Webinar – A Beginner’s Guide to Adding New Features to Suricata
- Got a segmentation fault/ core dumped? gdb is your friend, and awesome Peter Manev has long ago written a short post on how to investigate those issues further: Playing with segfaults, core dumps and such.
- You may need to investigate network traffic. Wireshark is a great open-source tool for that;
- You’ll likely need packet capture files (pcap) for writing unittests, or checking specific protocols and outcomes. There are quite a few sources for that, and Wireshark has a wiki section devoted to SampleCaptures;
- This talk has quite useful tips on how to get started contributing to open source projects in general, including how to make clearer questions; how to choose your first issues, and other common doubts topics that may pop in our minds: The OpenSource Plunge: Practical Strategies To Start Contributing