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::LOG`
`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.

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.

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.