:tocdepth: 3

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

This script logs hosts that Bro determines have performed complete TCP 
handshakes and logs the address once per day (by default).  The log that 
is output provides an easy way to determine a count of the IP addresses in
use on a network per day.

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

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

State Variables
###############
=================================================================================================================================== =================================================================
:bro:id:`Known::known_hosts`: :bro:type:`set` :bro:attr:`&create_expire` = ``1.0 day`` :bro:attr:`&synchronized` :bro:attr:`&redef` The set of all known addresses to store for preventing duplicate 
                                                                                                                                    logging of addresses.
=================================================================================================================================== =================================================================

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

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

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


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

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

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

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

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

   The set of all known addresses to store for preventing duplicate 
   logging of addresses.  It can also be used from other scripts to 
   inspect if an address has been seen in use.
   Maintain the list of known hosts for 24 hours so that the existence
   of each individual address is logged each day.

Types
#####
.. bro:type:: Known::HostsInfo

   :Type: :bro:type:`record`

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

      host: :bro:type:`addr` :bro:attr:`&log`
         The address that was detected originating or responding to a
         TCP connection.

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

Events
######
.. bro:id:: Known::log_known_hosts

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

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


