6147347a01
The server states were completion milestones: server_hello landed when the server hello record was fully parsed and server_cert_done when the certificate message was done, so the states named moments at which the phase data was complete instead of the phase being processed. The flight-completion state (server_hello_done) named a moment at which no data is published and no decision can act. The states now denote the record phase being processed: server_hello is entered when the server hello message begins (its header is read once, the message may span several records) and server_cert when the certificate message begins, so the state names the message being parsed and a message that fails to decode leaves the track in the state that names it. The record that completes a hello hands the track over to the certificate phase before a single certificate byte arrives. The enter/leave is the shared handshake phase mechanism, so the client track follows: client_hello is entered at the start of the client hello as well, and the completing client hello is decided at client_cert. The flight-done state is removed and renumbers the tail (server_data, server_finished), leaving both tracks with the same five-phase shape and an absorbing finished state. Hello and certificate decode failures suppress the phase advance of their own message only: the decoders keep their pre-existing return contract (the message bytes are consumed and the error events are raised as before) and set a per-connp suppression flag that is reset at the start of the next handshake message and checked at the phase advance. A decode failure is not an app-layer parse error: the flow is neither dropped nor blinded, and the next message that decodes cleanly still advances. An undecodable certificate in a chain is skipped, not fatal: one decoder event is raised for the bad certificate and the remaining certificates are still decoded - the rest of the chain is kept and the certificate data is filled from the first fully decodable certificate. The certificate phase is suppressed for such a message (the phase data is incomplete). The incomplete-data condition is sticky per connp: it is set while the certificate message is being decoded, cleared by a fully decoded certificate message only, and consulted by the handshake-done heuristic that would otherwise establish the data phase from the certificate data - a later handshake message does not complete the data, so the tracks do not cross the cert phase on partial data. The certificate field extraction is commit-on-success: the fields are extracted into stashes and published to the connp only when the whole certificate yields every field, so a certificate that fails a late extraction leaves no partial data behind and the next certificate can fill the fields. An extraction failure raises its decoder event once per message: the message no longer aborts at the first failing certificate, and the event is not repeated for the later failing entries. The tls.cert_chain_len match is gated on the chain being final (the per-connp flag set by a fully decoded certificate message), so it does not match while the track sits in server_cert with a chain that is still arriving. TOCLIENT keyword registrations and the tc log threshold follow the renamed constants (values 1/2 unchanged; the threshold is triggered by the same writes as before, so the log fires on the same packets). The ja3s lua registration moves to server_data: lua keeps a numeric hook, so it must follow the renamed state the old hook value pointed at (server hello done was 3, server data is 3). The ja3s content is final once the ServerHello parses, which is why the C keywords (ja3s.string, ja3s.hash) stay registered at server_hello. Two string-based generic buffer lookups and the user guide follow the renamed states. Ticket: #9047. |
3 weeks ago | |
|---|---|---|
| .clusterfuzzlite | ||
| .github | 3 weeks ago | |
| benches | ||
| doc | 4 weeks ago | |
| ebpf | ||
| etc | 4 weeks ago | |
| examples | ||
| git-templates | ||
| lua | ||
| plugins | ||
| python | ||
| qa | 4 weeks ago | |
| rules | ||
| rust | 3 weeks ago | |
| scripts | 4 weeks ago | |
| src | 3 weeks ago | |
| suricata-update | ||
| .clang-format | ||
| .gitignore | ||
| .readthedocs.yaml | ||
| COPYING | ||
| ChangeLog | ||
| LICENSE | ||
| Makefile.am | ||
| README.md | ||
| SECURITY.md | ||
| acsite.m4 | ||
| autogen.sh | ||
| bundle.txt | ||
| config.rpath | ||
| configure.ac | 3 weeks ago | |
| doxygen.cfg | ||
| libsuricata-config.in | ||
| shell.nix | ||
| suricata.yaml.in | ||
| threshold.config | ||
README.md
Suricata
Introduction
Suricata is a network IDS, IPS and NSM engine developed by the OISF and the Suricata community.
Resources
Contributing
We're happily taking patches and other contributions. Please see our Contribution Process for how to get started.
Suricata is a complex piece of software dealing with mostly untrusted input. Mishandling this input will have serious consequences:
- in IPS mode a crash may knock a network offline
- in passive mode a compromise of the IDS may lead to loss of critical and confidential data
- missed detection may lead to undetected compromise of the network
In other words, we think the stakes are pretty high, especially since in many common cases the IDS/IPS will be directly reachable by an attacker.
For this reason, we have developed a QA process that is quite extensive. A consequence is that contributing to Suricata can be a somewhat lengthy process.
On a high level, the steps are:
- GitHub-CI based checks. This runs automatically when a pull request is made.
- Review by devs from the team and community
- QA runs from private QA setups. These are private due to the nature of the test traffic.
Overview of Suricata's QA steps
OISF team members are able to submit builds to our private QA setup. It will run a series of build tests and a regression suite to confirm no existing features break.
The final QA runs takes a few hours minimally, and generally runs overnight. It currently runs:
- extensive build tests on different OS', compilers, optimization levels, configure features
- static code analysis using cppcheck, scan-build
- runtime code analysis using valgrind, AddressSanitizer, LeakSanitizer
- regression tests for past bugs
- output validation of logging
- unix socket testing
- pcap based fuzz testing using ASAN and LSAN
- traffic replay based IDS and IPS tests
Next to these tests, based on the type of code change further tests can be run manually:
- traffic replay testing (multi-gigabit)
- large pcap collection processing (multi-terabytes)
- fuzz testing (might take multiple days or even weeks)
- pcap based performance testing
- live performance testing
- various other manual tests based on evaluation of the proposed changes
It's important to realize that almost all of the tests above are used as acceptance tests. If something fails, it's up to you to address this in your code.
One step of the QA is currently run post-merge. We submit builds to the Coverity Scan program. Due to limitations of this (free) service, we can submit once a day max. Of course it can happen that after the merge the community will find issues. For both cases we request you to help address the issues as they may come up.
FAQ
Q: Will you accept my PR?
A: That depends on a number of things, including the code quality. With new features it also depends on whether the team and/or the community think the feature is useful, how much it affects other code and features, the risk of performance regressions, etc.
Q: When will my PR be merged?
A: It depends, if it's a major feature or considered a high risk change, it will probably go into the next major version.
Q: Why was my PR closed?
A: As documented in the Suricata GitHub workflow, we expect a new pull request for every change.
Normally, the team (or community) will give feedback on a pull request after which it is expected to be replaced by an improved PR. So look at the comments. If you disagree with the comments we can still discuss them in the closed PR.
If the PR was closed without comments it's likely due to QA failure. If the GitHub-CI checks failed, the PR should be fixed right away. No need for a discussion about it, unless you believe the QA failure is incorrect.
Q: The compiler/code analyser/tool is wrong, what now?
A: To assist in the automation of the QA, we're not accepting warnings or errors to stay. In some cases this could mean that we add a suppression if the tool supports that (e.g. valgrind, DrMemory). Some warnings can be disabled. In some exceptional cases the only 'solution' is to refactor the code to work around a static code checker limitation false positive. While frustrating, we prefer this over leaving warnings in the output. Warnings tend to get ignored and then increase risk of hiding other warnings.
Q: I think your QA test is wrong
A: If you really think it is, we can discuss how to improve it. But don't come to this conclusion too quickly, more often it's the code that turns out to be wrong.
Q: Do you require signing of a contributor license agreement?
A: Yes, we do this to keep the ownership of Suricata in one hand: the Open Information Security Foundation. See http://suricata.io/about/open-source/ and http://suricata.io/about/contribution-agreement/