:tocdepth: 3

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

Base SSH analysis script.  The heuristic to blindly determine success or
failure for SSH connections is implemented here.  At this time, it only
uses the size of the data being returned from the server to make the
heuristic determination about success of the connection.
Requires that :bro:id:`use_conn_size_analyzer` is set to T!  The heuristic
is not attempted if the connection size analyzer isn't enabled.

:Namespace: SSH
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/conn </scripts/base/protocols/conn/index>`, :doc:`base/utils/conn-ids.bro </scripts/base/utils/conn-ids.bro>`, :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`, :doc:`base/utils/site.bro </scripts/base/utils/site.bro>`, :doc:`base/utils/thresholds.bro </scripts/base/utils/thresholds.bro>`
:Source File: :download:`/scripts/base/protocols/ssh/main.bro`

Summary
~~~~~~~
Options
#######
=================================================================================== =============================================================
:bro:id:`SSH::authentication_data_size`: :bro:type:`count` :bro:attr:`&redef`       The size in bytes of data sent by the server at which the SSH
                                                                                    connection is presumed to be successful.
: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:`connection`: :bro:type:`record`                        
:bro:id:`likely_server_ports`: :bro:type:`set` :bro:attr:`&redef` 
================================================================= ===========================================

Events
######
============================================================ ==============================================================
:bro:id:`SSH::heuristic_failed_login`: :bro:type:`event`     Event that is generated when the heuristic thinks that a login
                                                             failed.
:bro:id:`SSH::heuristic_successful_login`: :bro:type:`event` Event that is generated when the heuristic thinks that a login
                                                             was successful.
:bro:id:`SSH::log_ssh`: :bro:type:`event`                    Event that can be handled to access the :bro:type:`SSH::Info`
                                                             record as it is sent on to the logging framework.
============================================================ ==============================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Options
#######
.. bro:id:: SSH::authentication_data_size

   :Type: :bro:type:`count`
   :Attributes: :bro:attr:`&redef`
   :Default: ``4000``

   The size in bytes of data sent by the server at which the SSH
   connection is presumed to be successful.

.. bro:id:: SSH::skip_processing_after_detection

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

   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.

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.

      status: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&default` = ``"undetermined"`` :bro:attr:`&optional`
         Indicates if the login was heuristically guessed to be
         "success", "failure", or "undetermined".

      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`
         Software string from the client.

      server: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         Software string from the server.

      done: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         Indicate if the SSH session is done being watched.

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

   :Type: :bro:type:`event` (c: :bro:type:`connection`)

   Event that is generated when the heuristic thinks that a login
   failed.

.. bro:id:: SSH::heuristic_successful_login

   :Type: :bro:type:`event` (c: :bro:type:`connection`)

   Event that is generated when the heuristic thinks that a login
   was successful.

.. bro:id:: SSH::log_ssh

   :Type: :bro:type:`event` (rec: :bro:type:`SSH::Info`)

   Event that can be handled to access the :bro:type:`SSH::Info`
   record as it is sent on to the logging framework.


