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

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  
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

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

SSH major version (1 or 2)

auth_success: bool &log &optional

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

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

Copyright 2016, The Bro Project. Last updated on December 19, 2018. Created using Sphinx 1.8.2.