mirror of https://github.com/OISF/suricata
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
136 lines
4.7 KiB
ReStructuredText
136 lines
4.7 KiB
ReStructuredText
.. _devguide-exception-policies:
|
|
|
|
Exception Policies
|
|
##################
|
|
|
|
This section offers an overview on the Suricata Exception Policies from a
|
|
development perspective, for those interested in extending them. For more on
|
|
usage, configuration etc, see the chapter `Exception Policies
|
|
<https://docs.suricata.io/en/latest/configuration/exception-policies.html>`_.
|
|
|
|
Exception Policies allow control on how the engine will behave when it reaches
|
|
exception scenarios where it could lose visibility into traffic being processed,
|
|
for instance.
|
|
|
|
Briefly, they give the ability to fail close or open, for a set of known
|
|
conditions, currently related to (This may be expanded by future work):
|
|
|
|
- hitting memory capacity limits;
|
|
- encountering application layer protocol errors;
|
|
- picking a TCP session midstream.
|
|
|
|
When failing close or open, the chosen policies may affect:
|
|
|
|
- individual packets, or
|
|
- the whole flow.
|
|
|
|
In the Suricata documentation, it is common to refer to anything in this scope
|
|
as Exception Policies, but more strictly, what the engine proactively does when
|
|
it reaches any of those conditions is an Exception Policy.
|
|
|
|
Extending
|
|
*********
|
|
|
|
The policy scope should be decided based on what is the setting about, as well
|
|
as on its possible impacts. Allowing for a midstream pickup policy to affect
|
|
individual packets of a flow, for instance, would only lead to the policy being
|
|
effectively applied to every single packet, and thus this isn't allowed.
|
|
|
|
Besides those aspects, there are differences in impacts when the engine is
|
|
running in `IDS` or `IPS` mode.
|
|
|
|
There are two main ways to extend Suricata adding new Exception Policies:
|
|
|
|
- add a new *policy*, that is, a new possible behavior;
|
|
- add a new *exception policy*, that is, covering another exception scenario.
|
|
|
|
The next sections will cover what are the steps and files to take into account
|
|
when extending Suricata Exception Policies.
|
|
|
|
Adding a New Policy
|
|
*******************
|
|
|
|
This section indicates the main steps and entry points for changes when adding
|
|
a new policy.
|
|
|
|
Currently Suricata supports the following exception policies:
|
|
|
|
.. literalinclude:: ../../../../../src/util-exception-policy-types.h
|
|
:caption: src/util-exception-policy-types.h
|
|
:language: c
|
|
:start-after: // exception policy docs tag start: exception policy types
|
|
:end-before: // exception policy docs tag end: exception policy types
|
|
|
|
If a new policy is needed, once it is clear what the new policy type and
|
|
nomenclature, will be, the following give an overview of where to go to add
|
|
the patch.
|
|
|
|
For the behavior type and logic:
|
|
|
|
- src/util-exception-policy-types.h
|
|
- src/util-exception-policy.c
|
|
|
|
To indicate whether the new policy is valid for each scenario
|
|
|
|
- src/app-layer.c
|
|
- src/decode.c
|
|
- src/stream-tcp.c
|
|
|
|
Don't forget to document:
|
|
|
|
- suricata.yaml.in
|
|
- doc/userguide/configuration/suricata-yaml.rst
|
|
- doc/userguide/configuration/exception-policies.rst
|
|
|
|
Ensure the new policy is valid in the JSON logs, by adding it to:
|
|
|
|
- etc/schema.json
|
|
|
|
For an example PR on adding a new policy, see:
|
|
https://github.com/OISF/suricata/pull/14225/files
|
|
|
|
Adding a New Exception Policy
|
|
*****************************
|
|
|
|
When the goal is to expand the exception scenarios that the exception policies
|
|
cover, the files to modify will depend on what the exception is.
|
|
|
|
Consider:
|
|
|
|
- What is the exception;
|
|
- When to get the Exception Policy setting;
|
|
- At what moment should the policy be applied.
|
|
|
|
Once you know how it should work, the related function calls are::
|
|
|
|
- ExceptionPolicyParse
|
|
- ExceptionPolicyApply
|
|
|
|
It will also be necessary to update:
|
|
|
|
- suricata.yaml.in - to add the new setting options;
|
|
- src/decode.h - ``PacketDropReason`` to add the corresponding drop reason.
|
|
|
|
Documentation updates:
|
|
|
|
- Exception Policy section: add new scenario to tables, add explanations;
|
|
- This DevGuide section, in case new files or exception conditions should be
|
|
listed;
|
|
- Corresponding suricata-yaml section.
|
|
|
|
For an example PR on adding a new exception policy, see:
|
|
https://github.com/OISF/suricata/pull/7791, especially commit
|
|
`aa5bb2c329aff5 <https://github.com/OISF/suricata/pull/7791/commits/aa5bb2c329aff59b7811b43258ffd4d95fe7364f>`_.
|
|
|
|
Testing
|
|
*******
|
|
|
|
For any significant fixes new features, tests are required. For Exception
|
|
Policies, please add Suricata-Verify tests. To learn more about testing Suricata
|
|
refer to:
|
|
|
|
- :ref:`Suricata Testing: Suricata Verify<testing-suricata-verify>`
|
|
- Suricata-verify: https://github.com/OISF/suricata-verify/blob/master/README.md
|
|
- Suricata Testing 101 - Building Robust Security Tools (SuriCon 2024 talk
|
|
by Haleema Khan and Modupe Falodun): https://youtu.be/9gOGkrSIcXQ?si=gANUv8Im5dw8qBk3
|