base/protocols/ssh/main.zeek

GLOBAL
SSH

Implements base functionality for SSH analysis. Generates the ssh.log file.

Namespaces

GLOBAL, SSH

Imports

base/protocols/conn/removal-hooks.zeek, base/utils/directions-and-hosts.zeek

Summary

Runtime Options

SSH::compression_algorithms: set &redef

The set of compression algorithms.

SSH::disable_analyzer_after_detection: bool &redef

If true, after detection detach the SSH analyzer from the connection to prevent continuing to process encrypted traffic.

Types

SSH::Info: record

The record type which contains the fields of the SSH log.

Redefinitions

Log::ID: enum

The SSH protocol logging stream identifier.

SSH::Info: record

New Fields

SSH::Info

logged: bool &default = F &optional

capabilities: SSH::Capabilities &optional

analyzer_id: count &optional

Analyzer ID

connection: record

New Fields

connection

ssh: SSH::Info &optional

likely_server_ports: set &redef

Events

SSH::log_ssh: event

Event that can be handled to access the SSH record as it is sent on to the logging framework.

ssh_auth_failed: event

This event is generated when an SSH connection was determined to have had a failed authentication.

ssh_auth_result: event

This event is generated when a determination has been made about the final authentication result of an SSH connection.

Hooks

SSH::finalize_ssh: Conn::RemovalHook

SSH finalization hook.

SSH::log_policy: Log::PolicyHook

A default logging policy hook for the stream.

Detailed Interface

Runtime Options

SSH::compression_algorithms
Type

set [string]

Attributes

&redef

Default
{
   "zlib@openssh.com",
   "zlib"
}

The set of compression algorithms. We can’t accurately determine authentication success or failure when compression is enabled.

SSH::disable_analyzer_after_detection
Type

bool

Attributes

&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

SSH::Info
Type

record

ts: time &log

Time when the SSH connection began.

uid: string &log

Unique ID for the connection.

id: conn_id &log

The connection’s 4-tuple of endpoint addresses/ports.

version: count &log &optional

SSH major version (1, 2, or unset). The version can be unset if the client and server version strings are unset, malformed or incompatible so no common version can be extracted. If no version can be extracted even though both client and server versions are set a weird will be generated.

auth_success: bool &log &optional

Authentication result (T=success, F=failure, unset=unknown)

auth_attempts: count &log &default = 0 &optional

The number of authentication attempts 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: Direction &log &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: string &log &optional

The client’s version string

server: string &log &optional

The server’s version string

cipher_alg: string &log &optional

The encryption algorithm in use

mac_alg: string &log &optional

The signing (MAC) algorithm in use

compression_alg: string &log &optional

The compression algorithm in use

kex_alg: string &log &optional

The key exchange algorithm in use

host_key_alg: string &log &optional

The server host key’s algorithm

host_key: string &log &optional

The server’s key fingerprint

logged: bool &default = F &optional

capabilities: SSH::Capabilities &optional

analyzer_id: count &optional

Analyzer ID

remote_location: geo_location &log &optional

(present if policy/protocols/ssh/geo-data.zeek 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

SSH::log_ssh
Type

event (rec: SSH::Info)

Event that can be handled to access the SSH record as it is sent on to the logging framework.

ssh_auth_failed
Type

event (c: connection)

This event is generated when an SSH 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.

Parameters

c – The connection over which the SSH connection took place.

See also: 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

ssh_auth_result
Type

event (c: connection, result: bool, auth_attempts: count)

This event is generated when a determination has been made about the final authentication result of an SSH 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.

Parameters
  • c – The connection over which the SSH connection took place.

  • result – True if the authentication was successful, false if not.

  • auth_attempts – The number of authentication attempts that were observed.

See also: 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

Hooks

SSH::finalize_ssh
Type

Conn::RemovalHook

SSH finalization hook. Remaining SSH info may get logged when it’s called.

SSH::log_policy
Type

Log::PolicyHook

A default logging policy hook for the stream.