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.
271 lines
12 KiB
ReStructuredText
271 lines
12 KiB
ReStructuredText
.. role:: example-rule-emphasis
|
|
|
|
SSH Keywords
|
|
============
|
|
Suricata has several rule keywords to match on different elements of SSH
|
|
connections.
|
|
|
|
.. _ssh-hooks:
|
|
|
|
Hooks
|
|
-----
|
|
|
|
The SSH parser exposes a per-direction state machine. A rule that
|
|
hooks one of the states below is evaluated once the transaction's
|
|
progress in that direction has reached the state; for firewall rules
|
|
the verdict applies while the transaction stays at the hooked state
|
|
and stops applying once it advances past it (see :ref:`app-layer-state`).
|
|
|
|
Request (``to_server``) side:
|
|
|
|
+---------------------------+-------------------------------------------------+
|
|
| State | Meaning |
|
|
+===========================+=================================================+
|
|
| ``request_banner`` | Version exchange: the banner (version) phase; |
|
|
| | the first packets of the direction. A banner |
|
|
| | line of 256 bytes or more without an |
|
|
| | end-of-line keeps the direction here: the line |
|
|
| | is consumed greedily until the end-of-line, and |
|
|
| | the condition is observable through the |
|
|
| | ``ssh.long_banner`` event (the banner data is |
|
|
| | published when the long line first parses). |
|
|
+---------------------------+-------------------------------------------------+
|
|
| ``request_kex`` | A valid banner line was parsed; key exchange. |
|
|
| | ``ssh.proto``, ``ssh.software`` and the hassh |
|
|
| | buffers are registered at this state. A long |
|
|
| | banner can publish them while the line is |
|
|
| | still open; if the line never completes, the |
|
|
| | values are not inspected at a clean flow end |
|
|
| | (the direction stays below the registered |
|
|
| | state); a flow that ends disrupted (depth |
|
|
| | truncation or async reassembly) reads as past |
|
|
| | this state, and the values are inspected there |
|
|
+---------------------------+-------------------------------------------------+
|
|
| ``request_session`` | A ``new keys`` record was seen in this |
|
|
| | direction: the session is established for that |
|
|
| | direction; the two directions are tracked |
|
|
| | independently (a parse failure in either ends |
|
|
| | the flow's app-layer parsing, see Completion |
|
|
| | and failure). ``new keys`` is a transition |
|
|
| | rather than a phase with its own data: match |
|
|
| | the record itself with a frame rule (message |
|
|
| | code 21, see the example below). |
|
|
+---------------------------+-------------------------------------------------+
|
|
|
|
Response (``to_client``) side:
|
|
|
|
+---------------------------+-------------------------------------------------+
|
|
| State | Meaning |
|
|
+===========================+=================================================+
|
|
| ``response_banner`` | Server banner (version) phase: the same |
|
|
| | behavior as ``request_banner`` above, in the |
|
|
| | server-to-client direction. |
|
|
+---------------------------+-------------------------------------------------+
|
|
| ``response_kex`` | Server key exchange: same as |
|
|
| | ``request_kex`` — the direction's |
|
|
| | ``ssh.proto`` / ``ssh.software`` and hassh |
|
|
| | buffers are registered at this state. |
|
|
+---------------------------+-------------------------------------------------+
|
|
| ``response_session`` | A ``new keys`` record was seen in the |
|
|
| | server-to-client direction: same as |
|
|
| | ``request_session``. |
|
|
+---------------------------+-------------------------------------------------+
|
|
|
|
Overly long banner lines
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A banner line of 256 bytes or more without an end-of-line keeps the
|
|
direction in the banner state. The line is consumed greedily until
|
|
the end-of-line arrives, and the direction then advances to
|
|
``kex``. The condition is observable through the ``ssh.long_banner``
|
|
app-layer event (the banner data is published when the long line
|
|
first parses). If the line does not parse as a banner when it
|
|
completes, the direction fails and is frozen in ``banner``.
|
|
|
|
Completion and failure
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
``request_done`` / ``response_done`` is the registered completion
|
|
state. No direction ever reports it: a successful direction tops out
|
|
at ``session``, and a direction that hits an unrecoverable error —
|
|
an invalid banner or an invalid record (header or payload) — is
|
|
frozen in the state the error occurred in. It is the last progress
|
|
the direction reports, and the reason is available through
|
|
the ``ssh.invalid_banner`` / ``ssh.invalid_record`` app-layer
|
|
events and the per-direction ``error`` / ``state`` fields of the
|
|
eve ``ssh`` object (``invalid_banner`` / ``invalid_record``
|
|
and the state the failure occurred in; a failed flow is logged even when
|
|
no banner was parsed, so the error field may be its only content).
|
|
A parse failure puts the flow into an error state: nothing after
|
|
the failing packet is parsed or delivered, mid-flow or at the
|
|
flow-end flush, and the frozen state is what the progress
|
|
accessor - and thus the flow-end eve object - reports. The
|
|
``ssh.invalid_banner`` / ``ssh.invalid_record`` events are
|
|
evaluated as soon as the tx is next inspected - the failing
|
|
packet itself unless the error policy skips it - at the latest
|
|
the flow-end flush.
|
|
A keyword registered at the failed state gets no eof run (eof
|
|
requires progress above the registered state), so its flow-end
|
|
evaluation stays non-terminal; states before it were already
|
|
terminalized when the direction left them. The ``ssh.long_banner`` and
|
|
``ssh.long_kex_record`` events are non-fatal: the direction
|
|
continues (a long banner keeps it in ``banner`` until the line
|
|
completes; an oversized key-exchange record keeps it in ``kex`` until
|
|
the record has been buffered in full).
|
|
|
|
Consequences worth knowing:
|
|
|
|
* ``ssh:request_complete`` (and the firewall policy key
|
|
``request-complete``) is bound to the completion state, which no
|
|
direction reports: the hook matches nothing for well-formed
|
|
flows. A disrupted flow (depth truncation or async reassembly)
|
|
matches, because on a disrupted flow the engine reports the
|
|
completion state as the transaction progress instead of
|
|
querying the parser. Before this change it matched a flow whose
|
|
session was established. Review existing
|
|
``accept:* ssh:request_complete`` rules and ``request-complete``
|
|
firewall policies: a session-admit rule like that no longer fires.
|
|
Failures are reported through the ``ssh.invalid_banner`` /
|
|
``ssh.invalid_record`` events instead.
|
|
* Rules cannot reference ``done`` (``request_done`` /
|
|
``response_done`` do not load): it is out of both name tables.
|
|
The generic hook lists for the completion state are registered
|
|
under the built-in completion names
|
|
(``ssh:request_complete:generic`` /
|
|
``ssh:response_complete:generic``); the state-name-based lists
|
|
are not registered for the completion id (the id-to-name lookup
|
|
returns null). They run only at a disrupted flow end, where the
|
|
engine reports the completion state as the transaction progress
|
|
instead of querying the parser - so Lua hooks on ssh completion
|
|
no longer fire for well-formed flows; before this change the
|
|
accessor reported the terminal state once both directions had
|
|
sent NewKeys.
|
|
* ``app-layer-state:>request_session`` matches only directions that
|
|
were *disrupted past session (e.g. by depth truncation or async
|
|
reassembly)* — a successful request direction stops at
|
|
``request_session``, and a failed one is frozen at the state it
|
|
failed in (use the ``ssh.invalid_*`` events for that).
|
|
|
|
For firewall rules and ``app-layer-state`` users,
|
|
:doc:`../firewall/ssh-state-migration` maps the old hook names to the
|
|
new phases and describes the behaviour changes.
|
|
|
|
Frames
|
|
------
|
|
|
|
The SSH parser supports the following frames:
|
|
|
|
* ssh.record_hdr
|
|
* ssh.record_data
|
|
* ssh.record_pdu
|
|
|
|
These are header + data = pdu for SSH records, after the banner and before encryption.
|
|
The SSH record header is 6 bytes long : 4 bytes length, 1 byte passing, 1 byte message code.
|
|
|
|
Example:
|
|
|
|
.. container:: example-rule
|
|
|
|
alert ssh any any -> any any (msg:"hdr frame new keys"; :example-rule-emphasis:`frame:ssh.record.hdr; content: "|15|"; endswith;` bsize: 6; sid:2;)
|
|
|
|
This rule matches like Wireshark ``ssh.message_code == 0x15``.
|
|
|
|
ssh.proto
|
|
---------
|
|
Match on the version of the SSH protocol used. ``ssh.proto`` is a sticky buffer,
|
|
and can be used as a fast pattern. ``ssh.proto`` replaces the previous buffer
|
|
name: ``ssh_proto``. You may continue to use the previous name, but it's
|
|
recommended that existing rules be converted to use the new name.
|
|
|
|
Format::
|
|
|
|
ssh.proto;
|
|
|
|
Example:
|
|
|
|
.. container:: example-rule
|
|
|
|
alert ssh any any -> any any (msg:"match SSH protocol version"; :example-rule-emphasis:`ssh.proto;` content:"2.0"; sid:1000010;)
|
|
|
|
The example above matches on SSH connections with SSH version 2.0.
|
|
|
|
|
|
ssh.software
|
|
------------
|
|
Match on the software string from the SSH banner. ``ssh.software`` is a sticky
|
|
buffer, and can be used as fast pattern.
|
|
|
|
Format::
|
|
|
|
ssh.software;
|
|
|
|
Example:
|
|
|
|
.. container:: example-rule
|
|
|
|
alert ssh any any -> any any (msg:"match SSH software string"; :example-rule-emphasis:`ssh.software;` content:"openssh"; nocase; sid:1000020;)
|
|
|
|
The example above matches on SSH connections where the software string contains
|
|
"openssh".
|
|
|
|
|
|
ssh.hassh
|
|
---------
|
|
|
|
Match on hassh (md5 of hassh algorithms of client).
|
|
|
|
.. container:: example-rule
|
|
|
|
alert ssh any any -> any any (msg:"match hassh"; \
|
|
ssh.hassh; content:"ec7378c1a92f5a8dde7e8b7a1ddf33d1";\
|
|
sid:1000010;)
|
|
|
|
``ssh.hassh`` is a 'sticky buffer'.
|
|
|
|
``ssh.hassh`` can be used as ``fast_pattern``.
|
|
|
|
ssh.hassh.string
|
|
----------------
|
|
|
|
Match on Hassh string (hassh algorithms of client).
|
|
|
|
.. container:: example-rule
|
|
|
|
alert ssh any any -> any any (msg:"match hassh-string"; \
|
|
ssh.hassh.string; content:"none,zlib@openssh.com,zlib"; \
|
|
sid:1000030;)
|
|
|
|
``ssh.hassh.string`` is a 'sticky buffer'.
|
|
|
|
``ssh.hassh.string`` can be used as ``fast_pattern``.
|
|
|
|
ssh.hassh.server
|
|
----------------
|
|
|
|
Match on hassh (md5 of hassh algorithms of server).
|
|
|
|
.. container:: example-rule
|
|
|
|
alert ssh any any -> any any (msg:"match SSH hash-server"; \
|
|
ssh.hassh.server; content:"b12d2871a1189eff20364cf5333619ee"; \
|
|
sid:1000020;)
|
|
|
|
``ssh.hassh.server`` is a 'sticky buffer'.
|
|
|
|
``ssh.hassh.server`` can be used as ``fast_pattern``.
|
|
|
|
ssh.hassh.server.string
|
|
-----------------------
|
|
|
|
Match on hassh string (hassh algorithms of server).
|
|
|
|
.. container:: example-rule
|
|
|
|
alert ssh any any -> any any (msg:"match SSH hash-server-string"; \
|
|
ssh.hassh.server.string; content:"umac-64-etm@openssh.com,umac-128-etm@openssh.com"; \
|
|
sid:1000040;)
|
|
|
|
``ssh.hassh.server.string`` is a 'sticky buffer'.
|
|
|
|
``ssh.hassh.server.string`` can be used as ``fast_pattern``.
|