base/protocols/ssh/main.bro

GLOBAL

SSH

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

Namespaces:GLOBAL, SSH Imports:base/utils/directions-and-hosts.bro Source File:/scripts/base/protocols/ssh/main.bro

Summary

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
connection: record
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.
ssh_server_host_key: event	Event that can be handled when the analyzer sees an SSH server host key.

Detailed Interface

Options

SSH::compression_algorithms

Type:set [string] Attributes:&redef Default:

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

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

SSH major version (1 or 2)

auth_success: bool &log &optional

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

auth_attempts: count &log &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: 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

Analzyer ID

remote_location: geo_location &log &optional

(present if 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

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.

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.

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

ssh_server_host_key

Type:event (c: connection, hash: string)

Event that can be handled when the analyzer sees an SSH server host key. This abstracts ssh1_server_host_key and ssh2_server_host_key.

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