Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

detect: add ldap operation keywords - v4 #12447

Closed
wants to merge 4 commits into from
Closed

detect: add ldap operation keywords - v4 #12447

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c69b38f
rustfmt: rust/src/ldap/types.rs
AkakiAlice Jan 20, 2025
0c584e8
detect: add ldap.request.operation
AkakiAlice Jan 20, 2025
2a39cfb
detect: add ldap.responses.operation
AkakiAlice Jan 20, 2025
575ec24
detect: add ldap.responses.count
AkakiAlice Jan 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/userguide/rules/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,4 @@ Suricata Rules
multi-buffer-matching
tag
vlan-keywords
ldap-keywords
165 changes: 165 additions & 0 deletions doc/userguide/rules/ldap-keywords.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
LDAP Keywords
=============

.. role:: example-rule-action
.. role:: example-rule-header
.. role:: example-rule-options
.. role:: example-rule-emphasis

LDAP Request and Response operations
------------------------------------

.. table:: **Operation values for ldap.request.operation and ldap.responses.operation keywords**

==== ================================================
Code Operation
==== ================================================
0 bind_request
1 bind_response
2 unbind_request
3 search_request
4 search_result_entry
5 search_result_done
6 modify_request
7 modify_response
8 add_request
9 add_response
10 del_request
11 del_response
12 mod_dn_request
13 mod_dn_response
14 compare_request
15 compare_response
16 abandon_request
19 search_result_reference
23 extended_request
24 extended_response
25 intermediate_response
==== ================================================

The keywords ldap.request.operation and ldap.responses.operation
accept both the operation code and the operation name as arguments.

ldap.request.operation
----------------------

Suricata has a ``ldap.request.operation`` keyword that can be used in signatures to identify
and filter network packets based on Lightweight Directory Access Protocol request operations.

Syntax::

ldap.request.operation: operation;

ldap.request.operation uses :ref:`unsigned 8-bit integer <rules-integer-keywords>`.

This keyword maps to the eve field ``ldap.request.operation``
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lukashino what do you think about this ? cf your work on #11951

Especially, is the log field written the correct way ?
Here this is a simple case, but what about the 2 others with arrays : ldap.responses[].operation and len(ldap.responses[])

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also should we update schema.json to document the revert mapping ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think @jasonish had some more thoughts about this.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need to document my thoughts more throuroughly somewhere, but I think its just a simplified version of what @lukashino had previous proposed. Looking at LDAP and the schema we see:

        "ldap": {
            "type": "object",
            "optional": true,
            "properties": {
                "request": {
                    "type": "object",
                    "properties": { 
                        "operation": {
                            "type": "string"
                        },
                        "message_id": { 
                            "type": "integer"
                        },

We could extend it out like:

        "ldap": {
            "type": "object",
            "optional": true,
            "properties": {
                "request": {
                    "type": "object",
                    "properties": { 
                        "operation": {
                            "type": "string"
                            "suricata": {
                              // A keyword that is a one to one mapping to this buffer.
                              "keyword": "ldap.operation",
                              // Related keywords that may also cover this field, if any.
                              "related_keywords": ["aaa", "bbb"]
                            }
                        },
                        "message_id": { 
                            "type": "integer"
                        },

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More here: #11951 (comment)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, I understand that the PR is good as is, and we wait for a decision on what needs to be updated in the schema.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think Victor was just poking me here so I'd write down some thoughts I had on the matter.


Examples
^^^^^^^^

Example of a signatures that would alert if the packet has an LDAP bind request operation:

.. container:: example-rule

alert tcp any any -> any any (msg:"Test LDAP bind request"; :example-rule-emphasis:`ldap.request.operation:0;` sid:1;)

.. container:: example-rule

alert tcp any any -> any any (msg:"Test LDAP bind request"; :example-rule-emphasis:`ldap.request.operation:bind_request;` sid:1;)

ldap.responses.operation
------------------------

Suricata has a ``ldap.responses.operation`` keyword that can be used in signatures to identify
and filter network packets based on Lightweight Directory Access Protocol response operations.

Syntax::

ldap.responses.operation: operation[,index];

ldap.responses.operation uses :ref:`unsigned 8-bit integer <rules-integer-keywords>`.

This keyword maps to the eve field ``ldap.responses[].operation``

An LDAP request operation can receive multiple responses. By default, the ldap.responses.operation
keyword matches all indices, but it is possible to specify a particular index for matching
and also use flags such as ``all`` and ``any``.

.. table:: **Index values for ldap.responses.operation keyword**

========= ================================================
Value Description
========= ================================================
[default] Match with any index
all Match only if all indexes match
any Match with any index
0>= Match specific index
0< Match specific index with back to front indexing
========= ================================================

Examples
^^^^^^^^

Example of a signatures that would alert if the packet has an LDAP bind response operation:

.. container:: example-rule

alert tcp any any -> any any (msg:"Test LDAP bind response"; :example-rule-emphasis:`ldap.responses.operation:1;` sid:1;)

.. container:: example-rule

alert tcp any any -> any any (msg:"Test LDAP bind response"; :example-rule-emphasis:`ldap.responses.operation:bind_response;` sid:1;)

Example of a signature that would alert if the packet has an LDAP search_result_done response operation at index 1:

.. container:: example-rule

alert tcp any any -> any any (msg:"Test LDAP search response"; :example-rule-emphasis:`ldap.responses.operation:search_result_done,1;` sid:1;)

Example of a signature that would alert if all the responses are of type search_result_entry:

.. container:: example-rule

alert tcp any any -> any any (msg:"Test LDAP search response"; :example-rule-emphasis:`ldap.responses.operation:search_result_entry,all;` sid:1;)

The keyword ldap.responses.operation supports back to front indexing with negative numbers,
this means that -1 will represent the last index, -2 the second to last index, and so on.
This is an example of a signature that would alert if a search_result_entry response is found at the last index:

.. container:: example-rule

alert tcp any any -> any any (msg:"Test LDAP search response"; :example-rule-emphasis:`ldap.responses.operation:search_result_entry,-1;` sid:1;)

ldap.responses.count
--------------------

Matches based on the number of responses.

Syntax::

ldap.responses.count: [op]number;

It can be matched exactly, or compared using the ``op`` setting::

ldap.responses.count:3 # exactly 3 responses
ldap.responses.count:<3 # less than 3 responses
ldap.responses.count:>=2 # more or equal to 2 responses

ldap.responses.count uses :ref:`unsigned 32-bit integer <rules-integer-keywords>`.

This keyword maps to the eve field ``len(ldap.responses[])``

Examples
^^^^^^^^

Example of a signature that would alert if a packet has 0 LDAP responses:

.. container:: example-rule

alert ip any any -> any any (msg:"Packet has 0 LDAP responses"; :example-rule-emphasis:`ldap.responses.count:0;` sid:1;)

Example of a signature that would alert if a packet has more than 2 LDAP responses:

.. container:: example-rule

alert ip any any -> any any (msg:"Packet has more than 2 LDAP responses"; :example-rule-emphasis:`ldap.responses.count:>2;` sid:1;)
Loading
Loading