:tocdepth: 3

base/protocols/ssh/main.bro
===========================
.. bro:namespace:: SSH

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

:Namespace: SSH
:Imports: :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
:Source File: :download:`/scripts/base/protocols/ssh/main.bro`

Summary
~~~~~~~
Options
#######
=================================================================================== =============================================================
:bro:id:`SSH::compression_algorithms`: :bro:type:`set` :bro:attr:`&redef`           The set of compression algorithms.
:bro:id:`SSH::skip_processing_after_detection`: :bro:type:`bool` :bro:attr:`&redef` If true, we tell the event engine to not look at further data
                                                                                    packets after the initial SSH handshake.
=================================================================================== =============================================================

Types
#####
========================================= =
:bro:type:`SSH::Info`: :bro:type:`record` 
========================================= =

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


Detailed Interface
~~~~~~~~~~~~~~~~~~
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::skip_processing_after_detection

   :Type: :bro:type:`bool`
   :Attributes: :bro:attr:`&redef`
   :Default: ``T``

   If true, we tell the event engine to not look at further data
   packets after the initial SSH handshake. Helps with performance
   (especially with large file transfers) but precludes some
   kinds of analyses. Defaults to T.

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)

      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`

      num_failures: :bro:type:`count` :bro:attr:`&default` = ``0`` :bro:attr:`&optional`

      capabilities: :bro:type:`SSH::Capabilities` :bro:attr:`&optional`

      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.


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


