mirror of
https://github.com/zeek/zeek.git
synced 2025-10-03 07:08:19 +00:00
7e9d48f532
The broxygen-generated files now live in the git repo, have tests that check that they are up-to-date, and a script to re-generate them on-demand.
228 lines
9.1 KiB
ReStructuredText
228 lines
9.1 KiB
ReStructuredText
:tocdepth: 3
|
|
|
|
base/protocols/ssh/main.bro
|
|
===========================
|
|
.. bro:namespace:: GLOBAL
|
|
.. bro:namespace:: SSH
|
|
|
|
Implements base functionality for SSH analysis. Generates the ssh.log file.
|
|
|
|
:Namespaces: GLOBAL, SSH
|
|
:Imports: :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
|
|
|
|
Summary
|
|
~~~~~~~
|
|
Runtime Options
|
|
###############
|
|
==================================================================================== ====================================================================
|
|
:bro:id:`SSH::compression_algorithms`: :bro:type:`set` :bro:attr:`&redef` The set of compression algorithms.
|
|
:bro:id:`SSH::disable_analyzer_after_detection`: :bro:type:`bool` :bro:attr:`&redef` If true, after detection detach the SSH analyzer from the connection
|
|
to prevent continuing to process encrypted traffic.
|
|
==================================================================================== ====================================================================
|
|
|
|
Types
|
|
#####
|
|
========================================= =========================================================
|
|
:bro:type:`SSH::Info`: :bro:type:`record` The record type which contains the fields of the SSH log.
|
|
========================================= =========================================================
|
|
|
|
Redefinitions
|
|
#############
|
|
================================================================= ===========================================
|
|
:bro:type:`Log::ID`: :bro:type:`enum` The SSH protocol logging stream identifier.
|
|
:bro:type:`SSH::Info`: :bro:type:`record`
|
|
:bro:type:`connection`: :bro:type:`record`
|
|
:bro:id:`likely_server_ports`: :bro:type:`set` :bro:attr:`&redef`
|
|
================================================================= ===========================================
|
|
|
|
Events
|
|
######
|
|
================================================ ===================================================================
|
|
:bro:id:`SSH::log_ssh`: :bro:type:`event` Event that can be handled to access the SSH record as it is sent on
|
|
to the logging framework.
|
|
:bro:id:`ssh_auth_failed`: :bro:type:`event` This event is generated when an :abbr:`SSH (Secure Shell)`
|
|
connection was determined to have had a failed authentication.
|
|
:bro:id:`ssh_auth_result`: :bro:type:`event` This event is generated when a determination has been made about
|
|
the final authentication result of an :abbr:`SSH (Secure Shell)`
|
|
connection.
|
|
:bro:id:`ssh_server_host_key`: :bro:type:`event` Event that can be handled when the analyzer sees an SSH server host
|
|
key.
|
|
================================================ ===================================================================
|
|
|
|
|
|
Detailed Interface
|
|
~~~~~~~~~~~~~~~~~~
|
|
Runtime Options
|
|
###############
|
|
.. bro:id:: SSH::compression_algorithms
|
|
|
|
:Type: :bro:type:`set` [:bro:type:`string`]
|
|
:Attributes: :bro:attr:`&redef`
|
|
:Default:
|
|
|
|
::
|
|
|
|
{
|
|
"zlib",
|
|
"zlib@openssh.com"
|
|
}
|
|
|
|
The set of compression algorithms. We can't accurately determine
|
|
authentication success or failure when compression is enabled.
|
|
|
|
.. bro:id:: SSH::disable_analyzer_after_detection
|
|
|
|
:Type: :bro:type:`bool`
|
|
:Attributes: :bro:attr:`&redef`
|
|
:Default: ``T``
|
|
|
|
If true, after detection detach the SSH analyzer from the connection
|
|
to prevent continuing to process encrypted traffic. Helps with performance
|
|
(especially with large file transfers).
|
|
|
|
Types
|
|
#####
|
|
.. bro:type:: SSH::Info
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
ts: :bro:type:`time` :bro:attr:`&log`
|
|
Time when the SSH connection began.
|
|
|
|
uid: :bro:type:`string` :bro:attr:`&log`
|
|
Unique ID for the connection.
|
|
|
|
id: :bro:type:`conn_id` :bro:attr:`&log`
|
|
The connection's 4-tuple of endpoint addresses/ports.
|
|
|
|
version: :bro:type:`count` :bro:attr:`&log`
|
|
SSH major version (1 or 2)
|
|
|
|
auth_success: :bro:type:`bool` :bro:attr:`&log` :bro:attr:`&optional`
|
|
Authentication result (T=success, F=failure, unset=unknown)
|
|
|
|
auth_attempts: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&default` = ``0`` :bro:attr:`&optional`
|
|
The number of authentication attemps we observed. There's always
|
|
at least one, since some servers might support no authentication at all.
|
|
It's important to note that not all of these are failures, since
|
|
some servers require two-factor auth (e.g. password AND pubkey)
|
|
|
|
direction: :bro:type:`Direction` :bro:attr:`&log` :bro:attr:`&optional`
|
|
Direction of the connection. If the client was a local host
|
|
logging into an external host, this would be OUTBOUND. INBOUND
|
|
would be set for the opposite situation.
|
|
|
|
client: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
|
|
The client's version string
|
|
|
|
server: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
|
|
The server's version string
|
|
|
|
cipher_alg: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
|
|
The encryption algorithm in use
|
|
|
|
mac_alg: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
|
|
The signing (MAC) algorithm in use
|
|
|
|
compression_alg: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
|
|
The compression algorithm in use
|
|
|
|
kex_alg: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
|
|
The key exchange algorithm in use
|
|
|
|
host_key_alg: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
|
|
The server host key's algorithm
|
|
|
|
host_key: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
|
|
The server's key fingerprint
|
|
|
|
logged: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
|
|
|
|
capabilities: :bro:type:`SSH::Capabilities` :bro:attr:`&optional`
|
|
|
|
analyzer_id: :bro:type:`count` :bro:attr:`&optional`
|
|
Analzyer ID
|
|
|
|
remote_location: :bro:type:`geo_location` :bro:attr:`&log` :bro:attr:`&optional`
|
|
(present if :doc:`/scripts/policy/protocols/ssh/geo-data.bro` is loaded)
|
|
|
|
Add geographic data related to the "remote" host of the
|
|
connection.
|
|
|
|
The record type which contains the fields of the SSH log.
|
|
|
|
Events
|
|
######
|
|
.. bro:id:: SSH::log_ssh
|
|
|
|
:Type: :bro:type:`event` (rec: :bro:type:`SSH::Info`)
|
|
|
|
Event that can be handled to access the SSH record as it is sent on
|
|
to the logging framework.
|
|
|
|
.. bro:id:: ssh_auth_failed
|
|
|
|
:Type: :bro:type:`event` (c: :bro:type:`connection`)
|
|
|
|
This event is generated when an :abbr:`SSH (Secure Shell)`
|
|
connection was determined to have had a failed 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 failure, this event is *not* raised.
|
|
|
|
This event is only raised once per connection.
|
|
|
|
|
|
:c: The connection over which the :abbr:`SSH (Secure Shell)`
|
|
connection took place.
|
|
|
|
.. bro:see:: ssh_server_version ssh_client_version
|
|
ssh_auth_successful 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
|
|
|
|
.. bro:id:: ssh_auth_result
|
|
|
|
:Type: :bro:type:`event` (c: :bro:type:`connection`, result: :bro:type:`bool`, auth_attempts: :bro:type:`count`)
|
|
|
|
This event is generated when a determination has been made about
|
|
the final authentication result of an :abbr:`SSH (Secure Shell)`
|
|
connection. This determination is based on packet size analysis,
|
|
and errs on the side of caution - that is, if there's any doubt
|
|
about the result of the authentication, this event is *not* raised.
|
|
|
|
This event is only raised once per connection.
|
|
|
|
|
|
:c: The connection over which the :abbr:`SSH (Secure Shell)`
|
|
connection took place.
|
|
|
|
|
|
:result: True if the authentication was successful, false if not.
|
|
|
|
|
|
:auth_attempts: The number of authentication attempts that were
|
|
observed.
|
|
|
|
.. bro:see:: ssh_server_version ssh_client_version
|
|
ssh_auth_successful ssh_auth_failed 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
|
|
|
|
.. bro:id:: ssh_server_host_key
|
|
|
|
:Type: :bro:type:`event` (c: :bro:type:`connection`, hash: :bro:type:`string`)
|
|
|
|
Event that can be handled when the analyzer sees an SSH server host
|
|
key. This abstracts :bro:id:`ssh1_server_host_key` and
|
|
:bro:id:`ssh2_server_host_key`.
|
|
|
|
.. bro:see:: ssh_server_version ssh_client_version
|
|
ssh_auth_successful ssh_auth_failed ssh_auth_result
|
|
ssh_auth_attempted ssh_capabilities ssh2_server_host_key
|
|
ssh1_server_host_key ssh_encrypted_packet ssh2_dh_server_params
|
|
ssh2_gss_error ssh2_ecc_key
|
|
|
|
|