zeek/doc/scripts/base/bif/plugins/Zeek_SSH.events.bif.zeek.rst
Patrick Kelley 8fd444092b initial
2025-05-07 15:35:15 -04:00

528 lines
23 KiB
ReStructuredText

:tocdepth: 3
base/bif/plugins/Zeek_SSH.events.bif.zeek
=========================================
.. zeek:namespace:: GLOBAL
:Namespace: GLOBAL
Summary
~~~~~~~
Events
######
========================================================= ==================================================================
:zeek:id:`ssh1_server_host_key`: :zeek:type:`event` During the :abbr:`SSH (Secure Shell)` key exchange, the server
supplies its public host key.
:zeek:id:`ssh2_dh_gex_init`: :zeek:type:`event` Generated if the connection uses a Diffie-Hellman Group Exchange
key exchange method.
:zeek:id:`ssh2_dh_server_params`: :zeek:type:`event` Generated if the connection uses a Diffie-Hellman Group Exchange
key exchange method.
:zeek:id:`ssh2_ecc_init`: :zeek:type:`event` The :abbr:`ECDH (Elliptic Curve Diffie-Hellman)` and
:abbr:`ECMQV (Elliptic Curve Menezes-Qu-Vanstone)` key exchange
algorithms use two ephemeral key pairs to generate a shared
secret.
:zeek:id:`ssh2_ecc_key`: :zeek:type:`event` The :abbr:`ECDH (Elliptic Curve Diffie-Hellman)` and
:abbr:`ECMQV (Elliptic Curve Menezes-Qu-Vanstone)` key exchange
algorithms use two ephemeral key pairs to generate a shared
secret.
:zeek:id:`ssh2_gss_error`: :zeek:type:`event` In the event of a GSS-API error on the server, the server MAY send
send an error message with some additional details.
:zeek:id:`ssh2_gss_init`: :zeek:type:`event` In the event of a GSS-API key exchange, this event is raised on
SSH_MSG_KEXGSS_INIT message.
:zeek:id:`ssh2_rsa_secret`: :zeek:type:`event` In the event of a GSS-API key exchange, this event is raised on
SSH_MSG_KEXRSA_PUBKEY message.
:zeek:id:`ssh2_server_host_key`: :zeek:type:`event` During the :abbr:`SSH (Secure Shell)` key exchange, the server
supplies its public host key.
:zeek:id:`ssh_auth_attempted`: :zeek:type:`event` This event is generated when an :abbr:`SSH (Secure Shell)`
connection was determined to have had an authentication attempt.
:zeek:id:`ssh_auth_successful`: :zeek:type:`event` This event is generated when an :abbr:`SSH (Secure Shell)`
connection was determined to have had a successful
authentication.
:zeek:id:`ssh_capabilities`: :zeek:type:`event` During the initial :abbr:`SSH (Secure Shell)` key exchange, each
endpoint lists the algorithms that it supports, in order of
preference.
:zeek:id:`ssh_client_version`: :zeek:type:`event` An :abbr:`SSH (Secure Shell)` Protocol Version Exchange message
from the client.
:zeek:id:`ssh_encrypted_packet`: :zeek:type:`event` This event is generated when an :abbr:`SSH (Secure Shell)`
encrypted packet is seen.
:zeek:id:`ssh_server_host_key`: :zeek:type:`event` During the :abbr:`SSH (Secure Shell)` key exchange, the server
supplies its public host key.
:zeek:id:`ssh_server_pre_banner_data`: :zeek:type:`event` SSH servers can send textual data to the client before sending
a banner.
:zeek:id:`ssh_server_version`: :zeek:type:`event` An :abbr:`SSH (Secure Shell)` Protocol Version Exchange message
from the server.
========================================================= ==================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Events
######
.. zeek:id:: ssh1_server_host_key
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 163 163
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, modulus: :zeek:type:`string`, exponent: :zeek:type:`string`)
During the :abbr:`SSH (Secure Shell)` key exchange, the server
supplies its public host key. This event is generated when the
appropriate key exchange message is seen for SSH1.
:param c: The connection over which the :abbr:`SSH (Secure Shell)`
connection took place.
:param p: The exponent for the server's public host key (note this parameter
is truly the exponent even though named *p* and the *exponent* parameter
will eventually replace it).
:param e: The prime modulus for the server's public host key (note this parameter
is truly the modulus even though named *e* and the *modulus* parameter
will eventually replace it).
:param modulus: The prime modulus of the server's public host key.
:param exponent: The exponent of the server's public host key.
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh2_dh_gex_init
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 321 321
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, is_orig: :zeek:type:`bool`)
Generated if the connection uses a Diffie-Hellman Group Exchange
key exchange method. This event contains the direction of the key
exchange setup, which is indicated by the the SSH_MSG_KEX_DH_GEX_INIT
message as defined in :rfc:`4419#section-3`.
:param c: The connection.
:param is_orig: Did this message come from the originator?
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh2_dh_server_params
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 237 237
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, p: :zeek:type:`string`, q: :zeek:type:`string`)
Generated if the connection uses a Diffie-Hellman Group Exchange
key exchange method. This event contains the server DH parameters,
which are sent in the SSH_MSG_KEY_DH_GEX_GROUP message as defined in
:rfc:`4419#section-3`.
:param c: The connection.
:param p: The DH prime modulus.
:param q: The DH generator.
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh2_ecc_init
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 303 303
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, is_orig: :zeek:type:`bool`)
The :abbr:`ECDH (Elliptic Curve Diffie-Hellman)` and
:abbr:`ECMQV (Elliptic Curve Menezes-Qu-Vanstone)` key exchange
algorithms use two ephemeral key pairs to generate a shared
secret. This event is generated when either the SSH_MSG_KEX_ECDH_INIT
or SSH_MSG_ECMQV_INIT message is observed. By definition, these need
to originate from the client and not from the server.
For more information, see:
:rfc:`5656#section-4`.
:param c: The connection.
:param is_orig: Did this message come from the originator?
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh2_ecc_key
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 281 281
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, is_orig: :zeek:type:`bool`, q: :zeek:type:`string`)
The :abbr:`ECDH (Elliptic Curve Diffie-Hellman)` and
:abbr:`ECMQV (Elliptic Curve Menezes-Qu-Vanstone)` key exchange
algorithms use two ephemeral key pairs to generate a shared
secret. This event is generated when either the client's or
server's ephemeral public key is seen. For more information, see:
:rfc:`5656#section-4`.
:param c: The connection.
:param is_orig: Did this message come from the originator?
:param q: The ephemeral public key
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh2_gss_error
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 259 259
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, major_status: :zeek:type:`count`, minor_status: :zeek:type:`count`, err_msg: :zeek:type:`string`)
In the event of a GSS-API error on the server, the server MAY send
send an error message with some additional details. This event is
generated when such an error message is seen. For more information,
see :rfc:`4462#section-2.1`.
:param c: The connection.
:param major_status: GSS-API major status code.
:param minor_status: GSS-API minor status code.
:param err_msg: Detailed human-readable error message
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh2_gss_init
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 338 338
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, is_orig: :zeek:type:`bool`)
In the event of a GSS-API key exchange, this event is raised on
SSH_MSG_KEXGSS_INIT message.
For more information see :rfc:`4462#section-2.1`.
:param c: The connection.
:param is_orig: Did this message come from the originator?
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh2_rsa_secret
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 356 356
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, is_orig: :zeek:type:`bool`)
In the event of a GSS-API key exchange, this event is raised on
SSH_MSG_KEXRSA_PUBKEY message. This message is sent first by the server,
after which the server will respond with a SSH_MSG_KEXRSA_SECRET message.
For more information see :rfc:`4432#section-4`.
:param c: The connection.
:param is_orig: Did this message come from the originator?
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh2_server_host_key
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 135 135
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, key: :zeek:type:`string`)
During the :abbr:`SSH (Secure Shell)` key exchange, the server
supplies its public host key. This event is generated when the
appropriate key exchange message is seen for SSH2.
:param c: The connection over which the :abbr:`SSH (Secure Shell)`
connection took place.
:param key: The server's public host key. Note that this is the public key
itself, and not just the fingerprint or hash.
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_attempted ssh_capabilities
ssh2_server_host_key ssh1_server_host_key ssh_server_host_key
ssh_encrypted_packet ssh2_dh_server_params ssh2_gss_error
ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init ssh2_gss_init
ssh2_rsa_secret
.. zeek:id:: ssh_auth_attempted
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 92 92
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, authenticated: :zeek:type:`bool`)
This event is generated when an :abbr:`SSH (Secure Shell)`
connection was determined to have had an authentication attempt.
This determination is based on packet size analysis, and errs
on the side of caution - that is, if there's any doubt about
whether or not an authentication attempt occurred, this event is
*not* raised.
At this point in the protocol, all we can determine is whether
or not the user is authenticated. We don't know if the particular
attempt succeeded or failed, since some servers require multiple
authentications (e.g. require both a password AND a pubkey), and
could return an authentication failed message which is marked
as a partial success.
This event will often be raised multiple times per connection.
In almost all connections, it will be raised once unless
:param c: The connection over which the :abbr:`SSH (Secure Shell)`
connection took place.
:param authenticated: This is true if the analyzer detected a
successful connection from the authentication attempt.
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh_auth_successful
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 60 60
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, auth_method_none: :zeek:type:`bool`)
This event is generated when an :abbr:`SSH (Secure Shell)`
connection was determined to have had a successful
authentication. This determination is based on packet size
analysis, and errs on the side of caution - that is, if there's any
doubt about the authentication success, this event is *not* raised.
:param c: The connection over which the :abbr:`SSH (Secure Shell)`
connection took place.
:param auth_method_none: This is true if the analyzer detected a
successful connection before any authentication challenge. The
:abbr:`SSH (Secure Shell)` protocol provides a mechanism for
unauthenticated access, which some servers support.
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh_capabilities
:source-code: base/protocols/ssh/main.zeek 287 310
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, cookie: :zeek:type:`string`, capabilities: :zeek:type:`SSH::Capabilities`)
During the initial :abbr:`SSH (Secure Shell)` key exchange, each
endpoint lists the algorithms that it supports, in order of
preference. This event is generated for each endpoint, when the
SSH_MSG_KEXINIT message is seen. See :rfc:`4253#section-7.1` for
details.
:param c: The connection over which the :abbr:`SSH (Secure Shell)`
connection took place.
:param cookie: The SSH_MSG_KEXINIT cookie - a random value generated by
the sender.
:param capabilities: The list of algorithms and languages that the sender
advertises support for, in order of preference.
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh_client_version
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 37 37
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, version: :zeek:type:`string`)
An :abbr:`SSH (Secure Shell)` Protocol Version Exchange message
from the client. This contains an identification string that's used
for version identification. See :rfc:`4253#section-4.2` for
details.
:param c: The connection over which the message was sent.
:param version: The identification string
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh_encrypted_packet
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 217 217
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, orig: :zeek:type:`bool`, len: :zeek:type:`count`)
This event is generated when an :abbr:`SSH (Secure Shell)`
encrypted packet is seen. This event is not handled by default, but
is provided for heuristic analysis scripts. Note that you have to set
:zeek:id:`SSH::disable_analyzer_after_detection` to false to use this
event. This carries a performance penalty.
:param c: The connection over which the :abbr:`SSH (Secure Shell)`
connection took place.
:param orig: Whether the packet was sent by the originator of the TCP
connection.
:param len: The length of the :abbr:`SSH (Secure Shell)` payload, in
bytes. Note that this ignores reassembly, as this is unknown.
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh_server_host_key
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 193 193
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, hash: :zeek:type:`string`)
During the :abbr:`SSH (Secure Shell)` key exchange, the server
supplies its public host key. This event is generated when the
appropriate key exchange message is seen for SSH1 or SSH2 and provides
a fingerprint of the server's host key.
:param c: The connection over which the :abbr:`SSH (Secure Shell)`
connection took place.
:param hash: an MD5 hash fingerprint associated with the server's host key.
For SSH2, this is the hash of the "server public host key" string as
seen on the wire in the Diffie-Hellman key exchange reply message
(the string itself, excluding the 4-byte length associated with it),
which is also the *key* parameter of :zeek:see:`ssh2_server_host_key`
For SSH1, this is the hash of the combined multiprecision integer
strings representing the RSA1 key's prime modulus and public exponent
(concatenated in that order) as seen on the wire,
which are also the parameters of :zeek:see:`ssh1_server_host_key`.
In either case, the hash is the same "fingerprint" string as presented
by other traditional tools, ``ssh``, ``ssh-keygen``, etc, and is the
hexadecimal representation of all 16 MD5 hash bytes delimited by colons.
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret
.. zeek:id:: ssh_server_pre_banner_data
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 372 372
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, data: :zeek:type:`string`)
SSH servers can send textual data to the client before sending
a banner. The primary use case of this are error messages of TCP
wrappers.
As this event happens before the SSH banner is exchanged, it is
possible that it contains data from different protocols; e.g. if
an SSH client connects to a non-SSH-server.
:param c: The connection.
:param data: The pre-banner data.
.. zeek:see:: ssh_server_version
.. zeek:id:: ssh_server_version
:source-code: base/bif/plugins/Zeek_SSH.events.bif.zeek 19 19
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, version: :zeek:type:`string`)
An :abbr:`SSH (Secure Shell)` Protocol Version Exchange message
from the server. This contains an identification string that's used
for version identification. See :rfc:`4253#section-4.2` for
details.
:param c: The connection over which the message was sent.
:param version: The identification string
.. zeek:see:: ssh_server_version ssh_client_version ssh_auth_failed
ssh_auth_result ssh_auth_successful ssh_auth_attempted
ssh_capabilities ssh2_server_host_key ssh1_server_host_key
ssh_server_host_key ssh_encrypted_packet ssh2_dh_server_params
ssh2_gss_error ssh2_ecc_key ssh2_ecc_init ssh2_dh_gex_init
ssh2_gss_init ssh2_rsa_secret ssh_server_pre_banner_data