mirror of https://github.com/OISF/suricata
devguide: add chapter about exception policies
Adds a chapter indicating what are the main steps when adding exception
policies, how is it possible to extend them, as well as main aspects and
files to consider when doing so.
Task #5612
(cherry picked from commit 48b15ac152)
pull/14800/head
Juliana Fajardini
4 months ago
committed by
Victor Julien
parent
ddadef5c9b
commit
c8e2301922
@ -0,0 +1,135 @@
|
||||
.. _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
|
||||
Loading…
Reference in New Issue