:tocdepth: 3

policy/misc/known-devices.bro
=============================
.. bro:namespace:: Known

This script provides infrastructure for logging devices for which Bro has
been able to determine the MAC address, and it logs them once per day (by
default).  The log that is output provides an easy way to determine a count
of the devices in use on a network per day.

.. note::

    This script will not generate any logs on its own, it needs to be
    supplied with information from elsewhere, such as
    :doc:`/scripts/policy/protocols/dhcp/known-devices-and-hostnames.bro`.

:Namespace: Known
:Source File: :download:`/scripts/policy/misc/known-devices.bro`

Summary
~~~~~~~
State Variables
###############
===================================================================================================================================== ===================================
:bro:id:`Known::known_devices`: :bro:type:`set` :bro:attr:`&create_expire` = ``1.0 day`` :bro:attr:`&synchronized` :bro:attr:`&redef` The set of all known MAC addresses.
===================================================================================================================================== ===================================

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

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

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


Detailed Interface
~~~~~~~~~~~~~~~~~~
State Variables
###############
.. bro:id:: Known::known_devices

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

   The set of all known MAC addresses. It can accessed from other
   scripts to add, and check for, addresses seen in use.
   
   We maintain each entry for 24 hours by default so that the existence
   of individual addresses is logged each day.

Types
#####
.. bro:type:: Known::DevicesInfo

   :Type: :bro:type:`record`

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

      mac: :bro:type:`string` :bro:attr:`&log`
         The MAC address that was detected.

      dhcp_host_name: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         (present if :doc:`/scripts/policy/protocols/dhcp/known-devices-and-hostnames.bro` is loaded)

         The value of the DHCP host name option, if seen.

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

Events
######
.. bro:id:: Known::log_known_devices

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

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


