:tocdepth: 3

policy/protocols/conn/known-services.bro
========================================
.. bro:namespace:: Known

This script logs and tracks services.  In the case of this script, a service
is defined as an IP address and port which has responded to and fully 
completed a TCP handshake with another host.  If a protocol is detected
during the session, the protocol will also be logged.

:Namespace: Known
:Imports: :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
:Source File: :download:`/scripts/policy/protocols/conn/known-services.bro`

Summary
~~~~~~~
Options
#######
====================================================================== ======================================================
:bro:id:`Known::service_tracking`: :bro:type:`Host` :bro:attr:`&redef` The hosts whose services should be tracked and logged.
====================================================================== ======================================================

State Variables
###############
=================================================================================================================== ====================================================================
:bro:id:`Known::known_services`: :bro:type:`set` :bro:attr:`&create_expire` = ``1.0 day`` :bro:attr:`&synchronized` Tracks the set of daily-detected services for preventing the logging
                                                                                                                    of duplicates, but can also be inspected by other scripts for
                                                                                                                    different purposes.
=================================================================================================================== ====================================================================

Types
#####
=================================================== ======================================================================
:bro:type:`Known::ServicesInfo`: :bro:type:`record` The record type which contains the column fields of the known-services
                                                    log.
=================================================== ======================================================================

Redefinitions
#############
========================================== =============================================
:bro:type:`Log::ID`: :bro:type:`enum`      The known-services logging stream identifier.
:bro:type:`connection`: :bro:type:`record` 
========================================== =============================================

Events
######
====================================================== =======================================================================
:bro:id:`Known::log_known_services`: :bro:type:`event` Event that can be handled to access the :bro:type:`Known::ServicesInfo`
                                                       record as it is sent on to the logging framework.
====================================================== =======================================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Options
#######
.. bro:id:: Known::service_tracking

   :Type: :bro:type:`Host`
   :Attributes: :bro:attr:`&redef`
   :Default: ``ALL_HOSTS``

   The hosts whose services should be tracked and logged.
   See :bro:type:`Host` for possible choices.

State Variables
###############
.. bro:id:: Known::known_services

   :Type: :bro:type:`set` [:bro:type:`addr`, :bro:type:`port`]
   :Attributes: :bro:attr:`&create_expire` = ``1.0 day`` :bro:attr:`&synchronized`
   :Default: ``{}``

   Tracks the set of daily-detected services for preventing the logging
   of duplicates, but can also be inspected by other scripts for
   different purposes.

Types
#####
.. bro:type:: Known::ServicesInfo

   :Type: :bro:type:`record`

      ts: :bro:type:`time` :bro:attr:`&log`
         The time at which the service was detected.

      host: :bro:type:`addr` :bro:attr:`&log`
         The host address on which the service is running.

      port_num: :bro:type:`port` :bro:attr:`&log`
         The port number on which the service is running.

      port_proto: :bro:type:`transport_proto` :bro:attr:`&log`
         The transport-layer protocol which the service uses.

      service: :bro:type:`set` [:bro:type:`string`] :bro:attr:`&log`
         A set of protocols that match the service's connection payloads.

   The record type which contains the column fields of the known-services
   log.

Events
######
.. bro:id:: Known::log_known_services

   :Type: :bro:type:`event` (rec: :bro:type:`Known::ServicesInfo`)

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


