Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-07 17:18:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Remove broxygen Sphinx integration

Browse source 
The broxygen-generated files now live in the git repo, have tests
that check that they are up-to-date, and a script to re-generate
them on-demand.
This commit is contained in:
Jon Siwek 2018-12-17 16:25:41 -06:00
parent 9e5e9d04b7
commit 7e9d48f532
549 changed files with 89909 additions and 100 deletions
Download patch file Download diff file Expand all files Collapse all files

176
doc/scripts/policy/protocols/conn/known-hosts.bro.rst Normal file
View file

@ -0,0 +1,176 @@
: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/frameworks/cluster </scripts/base/frameworks/cluster/index>`, :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
Summary
~~~~~~~
Runtime Options
###############
============================================================================ =======================================================
:bro:id:`Known::host_store_timeout`: :bro:type:`interval` :bro:attr:`&redef` The timeout interval to use for operations against
:bro:see:`Known::host_store`.
:bro:id:`Known::host_tracking`: :bro:type:`Host` :bro:attr:`&redef` The hosts whose existence should be logged and tracked.
============================================================================ =======================================================
Redefinable Options
###################
=========================================================================== ===================================================================
:bro:id:`Known::host_store_expiry`: :bro:type:`interval` :bro:attr:`&redef` The expiry interval of new entries in :bro:see:`Known::host_store`.
:bro:id:`Known::host_store_name`: :bro:type:`string` :bro:attr:`&redef` The Broker topic name to use for :bro:see:`Known::host_store`.
:bro:id:`Known::use_host_store`: :bro:type:`bool` :bro:attr:`&redef` Toggles between different implementations of this script.
=========================================================================== ===================================================================
State Variables
###############
=================================================================================================== =================================================================
:bro:id:`Known::host_store`: :bro:type:`Cluster::StoreInfo` Holds the set of all known hosts.
:bro:id:`Known::hosts`: :bro:type:`set` :bro:attr:`&create_expire` = ``1.0 day`` :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
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: Known::host_store_timeout
:Type: :bro:type:`interval`
:Attributes: :bro:attr:`&redef`
:Default: ``15.0 secs``
The timeout interval to use for operations against
:bro:see:`Known::host_store`.
.. 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.
Redefinable Options
###################
.. bro:id:: Known::host_store_expiry
:Type: :bro:type:`interval`
:Attributes: :bro:attr:`&redef`
:Default: ``1.0 day``
The expiry interval of new entries in :bro:see:`Known::host_store`.
This also changes the interval at which hosts get logged.
.. bro:id:: Known::host_store_name
:Type: :bro:type:`string`
:Attributes: :bro:attr:`&redef`
:Default: ``"bro/known/hosts"``
The Broker topic name to use for :bro:see:`Known::host_store`.
.. bro:id:: Known::use_host_store
:Type: :bro:type:`bool`
:Attributes: :bro:attr:`&redef`
:Default: ``T``
Toggles between different implementations of this script.
When true, use a Broker data store, else use a regular Bro set
with keys uniformly distributed over proxy nodes in cluster
operation.
State Variables
###############
.. bro:id:: Known::host_store
:Type: :bro:type:`Cluster::StoreInfo`
:Default:
::
{
name=<uninitialized>
store=<uninitialized>
master_node=""
master=F
backend=Broker::MEMORY
options=[sqlite=[path=""], rocksdb=[path=""]]
clone_resync_interval=10.0 secs
clone_stale_interval=5.0 mins
clone_mutation_buffer_interval=2.0 mins
}
Holds the set of all known hosts. Keys in the store are addresses
and their associated value will always be the "true" boolean.
.. bro:id:: Known::hosts
:Type: :bro:type:`set` [:bro:type:`addr`]
:Attributes: :bro:attr:`&create_expire` = ``1.0 day`` :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.
In cluster operation, this set is distributed uniformly across
proxy nodes.
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.

199
doc/scripts/policy/protocols/conn/known-services.bro.rst Normal file
View file

@ -0,0 +1,199 @@
: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/frameworks/cluster </scripts/base/frameworks/cluster/index>`, :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
Summary
~~~~~~~
Runtime Options
###############
=============================================================================== ======================================================
:bro:id:`Known::service_store_timeout`: :bro:type:`interval` :bro:attr:`&redef` The timeout interval to use for operations against
:bro:see:`Known::service_store`.
:bro:id:`Known::service_tracking`: :bro:type:`Host` :bro:attr:`&redef` The hosts whose services should be tracked and logged.
=============================================================================== ======================================================
Redefinable Options
###################
============================================================================== ======================================================================
:bro:id:`Known::service_store_expiry`: :bro:type:`interval` :bro:attr:`&redef` The expiry interval of new entries in :bro:see:`Known::service_store`.
:bro:id:`Known::service_store_name`: :bro:type:`string` :bro:attr:`&redef` The Broker topic name to use for :bro:see:`Known::service_store`.
:bro:id:`Known::use_service_store`: :bro:type:`bool` :bro:attr:`&redef` Toggles between different implementations of this script.
============================================================================== ======================================================================
State Variables
###############
=================================================================================== ====================================================================
:bro:id:`Known::service_store`: :bro:type:`Cluster::StoreInfo` Holds the set of all known services.
:bro:id:`Known::services`: :bro:type:`set` :bro:attr:`&create_expire` = ``1.0 day`` 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::AddrPortPair`: :bro:type:`record`
: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
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: Known::service_store_timeout
:Type: :bro:type:`interval`
:Attributes: :bro:attr:`&redef`
:Default: ``15.0 secs``
The timeout interval to use for operations against
:bro:see:`Known::service_store`.
.. 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.
Redefinable Options
###################
.. bro:id:: Known::service_store_expiry
:Type: :bro:type:`interval`
:Attributes: :bro:attr:`&redef`
:Default: ``1.0 day``
The expiry interval of new entries in :bro:see:`Known::service_store`.
This also changes the interval at which services get logged.
.. bro:id:: Known::service_store_name
:Type: :bro:type:`string`
:Attributes: :bro:attr:`&redef`
:Default: ``"bro/known/services"``
The Broker topic name to use for :bro:see:`Known::service_store`.
.. bro:id:: Known::use_service_store
:Type: :bro:type:`bool`
:Attributes: :bro:attr:`&redef`
:Default: ``T``
Toggles between different implementations of this script.
When true, use a Broker data store, else use a regular Bro set
with keys uniformly distributed over proxy nodes in cluster
operation.
State Variables
###############
.. bro:id:: Known::service_store
:Type: :bro:type:`Cluster::StoreInfo`
:Default:
::
{
name=<uninitialized>
store=<uninitialized>
master_node=""
master=F
backend=Broker::MEMORY
options=[sqlite=[path=""], rocksdb=[path=""]]
clone_resync_interval=10.0 secs
clone_stale_interval=5.0 mins
clone_mutation_buffer_interval=2.0 mins
}
Holds the set of all known services. Keys in the store are
:bro:type:`Known::AddrPortPair` and their associated value is
always the boolean value of "true".
.. bro:id:: Known::services
:Type: :bro:type:`set` [:bro:type:`addr`, :bro:type:`port`]
:Attributes: :bro:attr:`&create_expire` = ``1.0 day``
: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.
In cluster operation, this set is uniformly distributed across
proxy nodes.
This set is automatically populated and shouldn't be directly modified.
Types
#####
.. bro:type:: Known::AddrPortPair
:Type: :bro:type:`record`
host: :bro:type:`addr`
p: :bro:type:`port`
.. 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.

23
doc/scripts/policy/protocols/conn/mac-logging.bro.rst Normal file
View file

@ -0,0 +1,23 @@
:tocdepth: 3
policy/protocols/conn/mac-logging.bro
=====================================
.. bro:namespace:: Conn
This script adds link-layer address (MAC) information to the connection logs
:Namespace: Conn
:Imports: :doc:`base/protocols/conn </scripts/base/protocols/conn/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================== =
:bro:type:`Conn::Info`: :bro:type:`record`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

23
doc/scripts/policy/protocols/conn/vlan-logging.bro.rst Normal file
View file

@ -0,0 +1,23 @@
:tocdepth: 3
policy/protocols/conn/vlan-logging.bro
======================================
.. bro:namespace:: Conn
This script adds VLAN information to the connection log.
:Namespace: Conn
:Imports: :doc:`base/protocols/conn </scripts/base/protocols/conn/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================== =
:bro:type:`Conn::Info`: :bro:type:`record`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

27
doc/scripts/policy/protocols/conn/weirds.bro.rst Normal file
View file

@ -0,0 +1,27 @@
:tocdepth: 3
policy/protocols/conn/weirds.bro
================================
.. bro:namespace:: Conn
This script handles core generated connection related "weird" events to
push weird information about connections into the weird framework.
For live operational deployments, this can frequently cause load issues
due to large numbers of these events and quite possibly shouldn't be
loaded.
:Namespace: Conn
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

354
doc/scripts/policy/protocols/dhcp/deprecated_events.bro.rst Normal file
View file

@ -0,0 +1,354 @@
:tocdepth: 3
policy/protocols/dhcp/deprecated_events.bro
===========================================
Bro 2.6 removed certain DHCP events, but scripts in the Bro
ecosystem are still relying on those events. As a transition, this
script will handle the new event, and generate the old events,
which are marked as deprecated. Note: This script should be
removed in the next Bro version after 2.6.
:Imports: :doc:`base/protocols/dhcp </scripts/base/protocols/dhcp/index>`
Summary
~~~~~~~
Types
#####
=============================================== ====================================================
:bro:type:`dhcp_msg`: :bro:type:`record` A DHCP message.
:bro:type:`dhcp_router_list`: :bro:type:`table` A list of router addresses offered by a DHCP server.
=============================================== ====================================================
Events
######
================================================================== ===================================================================================
:bro:id:`dhcp_ack`: :bro:type:`event` :bro:attr:`&deprecated` Generated for DHCP messages of type *DHCPACK* (Server to client with configuration
parameters, including committed network address).
:bro:id:`dhcp_decline`: :bro:type:`event` :bro:attr:`&deprecated` Generated for DHCP messages of type *DHCPDECLINE* (Client to server indicating
network address is already in use).
:bro:id:`dhcp_discover`: :bro:type:`event` :bro:attr:`&deprecated` Generated for DHCP messages of type *DHCPDISCOVER* (client broadcast to locate
available servers).
:bro:id:`dhcp_inform`: :bro:type:`event` :bro:attr:`&deprecated` Generated for DHCP messages of type *DHCPINFORM* (Client to server, asking only for
local configuration parameters; client already has externally configured network
address).
:bro:id:`dhcp_nak`: :bro:type:`event` :bro:attr:`&deprecated` Generated for DHCP messages of type *DHCPNAK* (Server to client indicating client's
notion of network address is incorrect (e.g., client has moved to new subnet) or
client's lease has expired).
:bro:id:`dhcp_offer`: :bro:type:`event` :bro:attr:`&deprecated` Generated for DHCP messages of type *DHCPOFFER* (server to client in response
to DHCPDISCOVER with offer of configuration parameters).
:bro:id:`dhcp_release`: :bro:type:`event` :bro:attr:`&deprecated` Generated for DHCP messages of type *DHCPRELEASE* (Client to server relinquishing
network address and cancelling remaining lease).
:bro:id:`dhcp_request`: :bro:type:`event` :bro:attr:`&deprecated` Generated for DHCP messages of type *DHCPREQUEST* (Client message to servers either
(a) requesting offered parameters from one server and implicitly declining offers
from all others, (b) confirming correctness of previously allocated address after,
e.g., system reboot, or (c) extending the lease on a particular network address.)
================================================================== ===================================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Types
#####
.. bro:type:: dhcp_msg
:Type: :bro:type:`record`
op: :bro:type:`count`
Message OP code. 1 = BOOTREQUEST, 2 = BOOTREPLY
m_type: :bro:type:`count`
The type of DHCP message.
xid: :bro:type:`count`
Transaction ID of a DHCP session.
h_addr: :bro:type:`string`
Hardware address of the client.
ciaddr: :bro:type:`addr`
Original IP address of the client.
yiaddr: :bro:type:`addr`
IP address assigned to the client.
A DHCP message.
.. note:: This type is included to support the deprecated events dhcp_ack,
dhcp_decline, dhcp_discover, dhcp_inform, dhcp_nak, dhcp_offer,
dhcp_release and dhcp_request and is thus similarly deprecated
itself. Use :bro:see:`dhcp_message` instead.
.. bro:see:: dhcp_message dhcp_ack dhcp_decline dhcp_discover
dhcp_inform dhcp_nak dhcp_offer dhcp_release dhcp_request
.. bro:type:: dhcp_router_list
:Type: :bro:type:`table` [:bro:type:`count`] of :bro:type:`addr`
A list of router addresses offered by a DHCP server.
.. note:: This type is included to support the deprecated events dhcp_ack
and dhcp_offer and is thus similarly deprecated
itself. Use :bro:see:`dhcp_message` instead.
.. bro:see:: dhcp_message dhcp_ack dhcp_offer
Events
######
.. bro:id:: dhcp_ack
:Type: :bro:type:`event` (c: :bro:type:`connection`, msg: :bro:type:`dhcp_msg`, mask: :bro:type:`addr`, router: :bro:type:`dhcp_router_list`, lease: :bro:type:`interval`, serv_addr: :bro:type:`addr`, host_name: :bro:type:`string`)
:Attributes: :bro:attr:`&deprecated`
Generated for DHCP messages of type *DHCPACK* (Server to client with configuration
parameters, including committed network address).
:c: The connection record describing the underlying UDP flow.
:msg: The parsed type-independent part of the DHCP message.
:mask: The subnet mask specified by the message.
:router: The list of routers specified by the message.
:lease: The least interval specified by the message.
:serv_addr: The server address specified by the message.
:host_name: Optional host name value. May differ from the host name requested
from the client.
.. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request
dhcp_decline dhcp_nak dhcp_release dhcp_inform
.. note:: This event has been deprecated, and will be removed in the next version.
Use dhcp_message instead.
.. bro:id:: dhcp_decline
:Type: :bro:type:`event` (c: :bro:type:`connection`, msg: :bro:type:`dhcp_msg`, host_name: :bro:type:`string`)
:Attributes: :bro:attr:`&deprecated`
Generated for DHCP messages of type *DHCPDECLINE* (Client to server indicating
network address is already in use).
:c: The connection record describing the underlying UDP flow.
:msg: The parsed type-independent part of the DHCP message.
:host_name: Optional host name value.
.. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request
dhcp_ack dhcp_nak dhcp_release dhcp_inform
.. note:: This event has been deprecated, and will be removed in the next version.
Use dhcp_message instead.
.. note:: Bro does not support broadcast packets (as used by the DHCP
protocol). It treats broadcast addresses just like any other and
associates packets into transport-level flows in the same way as usual.
.. bro:id:: dhcp_discover
:Type: :bro:type:`event` (c: :bro:type:`connection`, msg: :bro:type:`dhcp_msg`, req_addr: :bro:type:`addr`, host_name: :bro:type:`string`)
:Attributes: :bro:attr:`&deprecated`
Generated for DHCP messages of type *DHCPDISCOVER* (client broadcast to locate
available servers).
:c: The connection record describing the underlying UDP flow.
:msg: The parsed type-independent part of the DHCP message.
:req_addr: The specific address requested by the client.
:host_name: The value of the host name option, if specified by the client.
.. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request
dhcp_decline dhcp_ack dhcp_nak dhcp_release dhcp_inform
.. note:: This event has been deprecated, and will be removed in the next version.
Use dhcp_message instead.
.. note:: Bro does not support broadcast packets (as used by the DHCP
protocol). It treats broadcast addresses just like any other and
associates packets into transport-level flows in the same way as usual.
.. bro:id:: dhcp_inform
:Type: :bro:type:`event` (c: :bro:type:`connection`, msg: :bro:type:`dhcp_msg`, host_name: :bro:type:`string`)
:Attributes: :bro:attr:`&deprecated`
Generated for DHCP messages of type *DHCPINFORM* (Client to server, asking only for
local configuration parameters; client already has externally configured network
address).
:c: The connection record describing the underlying UDP flow.
:msg: The parsed type-independent part of the DHCP message.
:host_name: The value of the host name option, if specified by the client.
.. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request
dhcp_decline dhcp_ack dhcp_nak dhcp_release
.. note:: This event has been deprecated, and will be removed in the next version.
Use dhcp_message instead.
.. note:: Bro does not support broadcast packets (as used by the DHCP
protocol). It treats broadcast addresses just like any other and
associates packets into transport-level flows in the same way as usual.
.. bro:id:: dhcp_nak
:Type: :bro:type:`event` (c: :bro:type:`connection`, msg: :bro:type:`dhcp_msg`, host_name: :bro:type:`string`)
:Attributes: :bro:attr:`&deprecated`
Generated for DHCP messages of type *DHCPNAK* (Server to client indicating client's
notion of network address is incorrect (e.g., client has moved to new subnet) or
client's lease has expired).
:c: The connection record describing the underlying UDP flow.
:msg: The parsed type-independent part of the DHCP message.
:host_name: Optional host name value.
.. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request
dhcp_decline dhcp_ack dhcp_release dhcp_inform
.. note:: This event has been deprecated, and will be removed in the next version.
Use dhcp_message instead.
.. note:: Bro does not support broadcast packets (as used by the DHCP
protocol). It treats broadcast addresses just like any other and
associates packets into transport-level flows in the same way as usual.
.. bro:id:: dhcp_offer
:Type: :bro:type:`event` (c: :bro:type:`connection`, msg: :bro:type:`dhcp_msg`, mask: :bro:type:`addr`, router: :bro:type:`dhcp_router_list`, lease: :bro:type:`interval`, serv_addr: :bro:type:`addr`, host_name: :bro:type:`string`)
:Attributes: :bro:attr:`&deprecated`
Generated for DHCP messages of type *DHCPOFFER* (server to client in response
to DHCPDISCOVER with offer of configuration parameters).
:c: The connection record describing the underlying UDP flow.
:msg: The parsed type-independent part of the DHCP message.
:mask: The subnet mask specified by the message.
:router: The list of routers specified by the message.
:lease: The least interval specified by the message.
:serv_addr: The server address specified by the message.
:host_name: Optional host name value. May differ from the host name requested
from the client.
.. bro:see:: dhcp_message dhcp_discover dhcp_request dhcp_decline
dhcp_ack dhcp_nak dhcp_release dhcp_inform
.. note:: This event has been deprecated, and will be removed in the next version.
Use dhcp_message instead.
.. note:: Bro does not support broadcast packets (as used by the DHCP
protocol). It treats broadcast addresses just like any other and
associates packets into transport-level flows in the same way as usual.
.. bro:id:: dhcp_release
:Type: :bro:type:`event` (c: :bro:type:`connection`, msg: :bro:type:`dhcp_msg`, host_name: :bro:type:`string`)
:Attributes: :bro:attr:`&deprecated`
Generated for DHCP messages of type *DHCPRELEASE* (Client to server relinquishing
network address and cancelling remaining lease).
:c: The connection record describing the underlying UDP flow.
:msg: The parsed type-independent part of the DHCP message.
:host_name: The value of the host name option, if specified by the client.
.. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_request
dhcp_decline dhcp_ack dhcp_nak dhcp_inform
.. note:: This event has been deprecated, and will be removed in the next version.
Use dhcp_message instead.
.. bro:id:: dhcp_request
:Type: :bro:type:`event` (c: :bro:type:`connection`, msg: :bro:type:`dhcp_msg`, req_addr: :bro:type:`addr`, serv_addr: :bro:type:`addr`, host_name: :bro:type:`string`)
:Attributes: :bro:attr:`&deprecated`
Generated for DHCP messages of type *DHCPREQUEST* (Client message to servers either
(a) requesting offered parameters from one server and implicitly declining offers
from all others, (b) confirming correctness of previously allocated address after,
e.g., system reboot, or (c) extending the lease on a particular network address.)
:c: The connection record describing the underlying UDP flow.
:msg: The parsed type-independent part of the DHCP message.
:req_addr: The client address specified by the message.
:serv_addr: The server address specified by the message.
:host_name: The value of the host name option, if specified by the client.
.. bro:see:: dhcp_message dhcp_discover dhcp_offer dhcp_decline
dhcp_ack dhcp_nak dhcp_release dhcp_inform
.. note:: This event has been deprecated, and will be removed in the next version.
Use dhcp_message instead.
.. note:: Bro does not support broadcast packets (as used by the DHCP
protocol). It treats broadcast addresses just like any other and
associates packets into transport-level flows in the same way as usual.

26
doc/scripts/policy/protocols/dhcp/msg-orig.bro.rst Normal file
View file

@ -0,0 +1,26 @@
:tocdepth: 3
policy/protocols/dhcp/msg-orig.bro
==================================
.. bro:namespace:: DHCP
Add a field that logs the order of hosts sending messages
using the same DHCP transaction ID. This information is
occasionally needed on some networks to fully explain the
DHCP sequence.
:Namespace: DHCP
:Imports: :doc:`base/protocols/dhcp </scripts/base/protocols/dhcp/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================== =
:bro:type:`DHCP::Info`: :bro:type:`record`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

24
doc/scripts/policy/protocols/dhcp/software.bro.rst Normal file
View file

@ -0,0 +1,24 @@
:tocdepth: 3
policy/protocols/dhcp/software.bro
==================================
.. bro:namespace:: DHCP
Software identification and extraction for DHCP traffic.
:Namespace: DHCP
:Imports: :doc:`base/frameworks/software </scripts/base/frameworks/software/index>`, :doc:`base/protocols/dhcp </scripts/base/protocols/dhcp/index>`
Summary
~~~~~~~
Redefinitions
#############
============================================ =
:bro:type:`DHCP::Info`: :bro:type:`record`
:bro:type:`Software::Type`: :bro:type:`enum`
============================================ =
Detailed Interface
~~~~~~~~~~~~~~~~~~

22
doc/scripts/policy/protocols/dhcp/sub-opts.bro.rst Normal file
View file

@ -0,0 +1,22 @@
:tocdepth: 3
policy/protocols/dhcp/sub-opts.bro
==================================
.. bro:namespace:: DHCP
:Namespace: DHCP
:Imports: :doc:`base/protocols/dhcp </scripts/base/protocols/dhcp/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================== =
:bro:type:`DHCP::Info`: :bro:type:`record`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

28
doc/scripts/policy/protocols/dns/auth-addl.bro.rst Normal file
View file

@ -0,0 +1,28 @@
:tocdepth: 3
policy/protocols/dns/auth-addl.bro
==================================
.. bro:namespace:: DNS
This script adds authoritative and additional responses for the current
query to the DNS log. It can cause severe overhead due to the need
for all authoritative and additional responses to have events generated.
This script is not recommended for use on heavily loaded links.
:Namespace: DNS
:Imports: :doc:`base/protocols/dns/main.bro </scripts/base/protocols/dns/main.bro>`
Summary
~~~~~~~
Redefinitions
#############
================================================================ =
:bro:type:`DNS::Info`: :bro:type:`record`
:bro:id:`dns_skip_all_addl`: :bro:type:`bool` :bro:attr:`&redef`
:bro:id:`dns_skip_all_auth`: :bro:type:`bool` :bro:attr:`&redef`
================================================================ =
Detailed Interface
~~~~~~~~~~~~~~~~~~

26
doc/scripts/policy/protocols/dns/detect-external-names.bro.rst Normal file
View file

@ -0,0 +1,26 @@
:tocdepth: 3
policy/protocols/dns/detect-external-names.bro
==============================================
.. bro:namespace:: DNS
This script detects names which are not within zones considered to be
local but resolving to addresses considered local.
The :bro:id:`Site::local_zones` variable **must** be set appropriately for
this detection.
:Namespace: DNS
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/utils/site.bro </scripts/base/utils/site.bro>`
Summary
~~~~~~~
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

53
doc/scripts/policy/protocols/ftp/detect-bruteforcing.bro.rst Normal file
View file

@ -0,0 +1,53 @@
:tocdepth: 3
policy/protocols/ftp/detect-bruteforcing.bro
============================================
.. bro:namespace:: FTP
FTP brute-forcing detector, triggering when too many rejected usernames or
failed passwords have occurred from a single address.
:Namespace: FTP
:Imports: :doc:`base/frameworks/sumstats </scripts/base/frameworks/sumstats/index>`, :doc:`base/protocols/ftp </scripts/base/protocols/ftp/index>`, :doc:`base/utils/time.bro </scripts/base/utils/time.bro>`
Summary
~~~~~~~
Redefinable Options
###################
======================================================================================= ==================================================================
:bro:id:`FTP::bruteforce_measurement_interval`: :bro:type:`interval` :bro:attr:`&redef` The time period in which the threshold needs to be crossed before
being reset.
:bro:id:`FTP::bruteforce_threshold`: :bro:type:`double` :bro:attr:`&redef` How many rejected usernames or passwords are required before being
considered to be bruteforcing.
======================================================================================= ==================================================================
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Redefinable Options
###################
.. bro:id:: FTP::bruteforce_measurement_interval
:Type: :bro:type:`interval`
:Attributes: :bro:attr:`&redef`
:Default: ``15.0 mins``
The time period in which the threshold needs to be crossed before
being reset.
.. bro:id:: FTP::bruteforce_threshold
:Type: :bro:type:`double`
:Attributes: :bro:attr:`&redef`
:Default: ``20.0``
How many rejected usernames or passwords are required before being
considered to be bruteforcing.

23
doc/scripts/policy/protocols/ftp/detect.bro.rst Normal file
View file

@ -0,0 +1,23 @@
:tocdepth: 3
policy/protocols/ftp/detect.bro
===============================
.. bro:namespace:: FTP
Detect various potentially bad FTP activities.
:Namespace: FTP
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ftp </scripts/base/protocols/ftp/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

23
doc/scripts/policy/protocols/ftp/software.bro.rst Normal file
View file

@ -0,0 +1,23 @@
:tocdepth: 3
policy/protocols/ftp/software.bro
=================================
.. bro:namespace:: FTP
Software detection with the FTP protocol.
:Namespace: FTP
:Imports: :doc:`base/frameworks/software </scripts/base/frameworks/software/index>`
Summary
~~~~~~~
Redefinitions
#############
============================================ =
:bro:type:`Software::Type`: :bro:type:`enum`
============================================ =
Detailed Interface
~~~~~~~~~~~~~~~~~~

98
doc/scripts/policy/protocols/http/detect-sqli.bro.rst Normal file
View file

@ -0,0 +1,98 @@
:tocdepth: 3
policy/protocols/http/detect-sqli.bro
=====================================
.. bro:namespace:: HTTP
SQL injection attack detection in HTTP.
:Namespace: HTTP
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/frameworks/sumstats </scripts/base/frameworks/sumstats/index>`, :doc:`base/protocols/http </scripts/base/protocols/http/index>`
Summary
~~~~~~~
Redefinable Options
###################
=============================================================================== ================================================================
:bro:id:`HTTP::collect_SQLi_samples`: :bro:type:`count` :bro:attr:`&redef` Collecting samples will add extra data to notice emails
by collecting some sample SQL injection url paths.
:bro:id:`HTTP::match_sql_injection_uri`: :bro:type:`pattern` :bro:attr:`&redef` Regular expression is used to match URI based SQL injections.
:bro:id:`HTTP::sqli_requests_interval`: :bro:type:`interval` :bro:attr:`&redef` Interval at which to watch for the
:bro:id:`HTTP::sqli_requests_threshold` variable to be crossed.
:bro:id:`HTTP::sqli_requests_threshold`: :bro:type:`double` :bro:attr:`&redef` Defines the threshold that determines if an SQL injection attack
is ongoing based on the number of requests that appear to be SQL
injection attacks.
=============================================================================== ================================================================
Redefinitions
#############
========================================== =
:bro:type:`HTTP::Tags`: :bro:type:`enum`
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Hooks
#####
============================================= =======================================================================
:bro:id:`HTTP::sqli_policy`: :bro:type:`hook` A hook that can be used to prevent specific requests from being counted
as an injection attempt.
============================================= =======================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Redefinable Options
###################
.. bro:id:: HTTP::collect_SQLi_samples
:Type: :bro:type:`count`
:Attributes: :bro:attr:`&redef`
:Default: ``5``
Collecting samples will add extra data to notice emails
by collecting some sample SQL injection url paths. Disable
sample collection by setting this value to 0.
.. bro:id:: HTTP::match_sql_injection_uri
:Type: :bro:type:`pattern`
:Attributes: :bro:attr:`&redef`
:Default:
::
/^?((^?((^?((^?((^?((^?([\?&][^[:blank:]\x00-\x37\|]+?=[\-[:alnum:]%]+([[:blank:]\x00-\x37]|\/\*.*?\*\/)*['"]?([[:blank:]\x00-\x37]|\/\*.*?\*\/|\)?;)+.*?([hH][aA][vV][iI][nN][gG]|[uU][nN][iI][oO][nN]|[eE][xX][eE][cC]|[sS][eE][lL][eE][cC][tT]|[dD][eE][lL][eE][tT][eE]|[dD][rR][oO][pP]|[dD][eE][cC][lL][aA][rR][eE]|[cC][rR][eE][aA][tT][eE]|[iI][nN][sS][eE][rR][tT])([[:blank:]\x00-\x37]|\/\*.*?\*\/)+)$?)|(^?([\?&][^[:blank:]\x00-\x37\|]+?=[\-0-9%]+([[:blank:]\x00-\x37]|\/\*.*?\*\/)*['"]?([[:blank:]\x00-\x37]|\/\*.*?\*\/|\)?;)+([xX]?[oO][rR]|[nN]?[aA][nN][dD])([[:blank:]\x00-\x37]|\/\*.*?\*\/)+['"]?(([^a-zA-Z&]+)?=|[eE][xX][iI][sS][tT][sS]))$?))$?)|(^?([\?&][^[:blank:]\x00-\x37]+?=[\-0-9%]*([[:blank:]\x00-\x37]|\/\*.*?\*\/)*['"]([[:blank:]\x00-\x37]|\/\*.*?\*\/)*(-|=|\+|\|\|)([[:blank:]\x00-\x37]|\/\*.*?\*\/)*([0-9]|\(?[cC][oO][nN][vV][eE][rR][tT]|[cC][aA][sS][tT]))$?))$?)|(^?([\?&][^[:blank:]\x00-\x37\|]+?=([[:blank:]\x00-\x37]|\/\*.*?\*\/)*['"]([[:blank:]\x00-\x37]|\/\*.*?\*\/|;)*([xX]?[oO][rR]|[nN]?[aA][nN][dD]|[hH][aA][vV][iI][nN][gG]|[uU][nN][iI][oO][nN]|[eE][xX][eE][cC]|[sS][eE][lL][eE][cC][tT]|[dD][eE][lL][eE][tT][eE]|[dD][rR][oO][pP]|[dD][eE][cC][lL][aA][rR][eE]|[cC][rR][eE][aA][tT][eE]|[rR][eE][gG][eE][xX][pP]|[iI][nN][sS][eE][rR][tT])([[:blank:]\x00-\x37]|\/\*.*?\*\/|[\[(])+[a-zA-Z&]{2,})$?))$?)|(^?([\?&][^[:blank:]\x00-\x37]+?=[^\.]*?([cC][hH][aA][rR]|[aA][sS][cC][iI][iI]|[sS][uU][bB][sS][tT][rR][iI][nN][gG]|[tT][rR][uU][nN][cC][aA][tT][eE]|[vV][eE][rR][sS][iI][oO][nN]|[lL][eE][nN][gG][tT][hH])\()$?))$?)|(^?(\/\*![[:digit:]]{5}.*?\*\/)$?))$?/
Regular expression is used to match URI based SQL injections.
.. bro:id:: HTTP::sqli_requests_interval
:Type: :bro:type:`interval`
:Attributes: :bro:attr:`&redef`
:Default: ``5.0 mins``
Interval at which to watch for the
:bro:id:`HTTP::sqli_requests_threshold` variable to be crossed.
At the end of each interval the counter is reset.
.. bro:id:: HTTP::sqli_requests_threshold
:Type: :bro:type:`double`
:Attributes: :bro:attr:`&redef`
:Default: ``50.0``
Defines the threshold that determines if an SQL injection attack
is ongoing based on the number of requests that appear to be SQL
injection attacks.
Hooks
#####
.. bro:id:: HTTP::sqli_policy
:Type: :bro:type:`hook` (c: :bro:type:`connection`, method: :bro:type:`string`, unescaped_URI: :bro:type:`string`) : :bro:type:`bool`
A hook that can be used to prevent specific requests from being counted
as an injection attempt. Use a 'break' statement to exit the hook
early and ignore the request.

25
doc/scripts/policy/protocols/http/detect-webapps.bro.rst Normal file
View file

@ -0,0 +1,25 @@
:tocdepth: 3
policy/protocols/http/detect-webapps.bro
========================================
.. bro:namespace:: HTTP
Detect and log web applications through the software framework.
:Namespace: HTTP
:Imports: :doc:`base/frameworks/signatures </scripts/base/frameworks/signatures/index>`, :doc:`base/frameworks/software </scripts/base/frameworks/software/index>`, :doc:`base/protocols/http </scripts/base/protocols/http/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================================================= =
:bro:id:`Signatures::ignored_ids`: :bro:type:`pattern` :bro:attr:`&redef`
:bro:type:`Software::Info`: :bro:type:`record`
:bro:type:`Software::Type`: :bro:type:`enum`
========================================================================= =
Detailed Interface
~~~~~~~~~~~~~~~~~~

50
doc/scripts/policy/protocols/http/header-names.bro.rst Normal file
View file

@ -0,0 +1,50 @@
:tocdepth: 3
policy/protocols/http/header-names.bro
======================================
.. bro:namespace:: HTTP
Extract and include the header names used for each request in the HTTP
logging stream. The headers in the logging stream will be stored in the
same order which they were seen on the wire.
:Namespace: HTTP
:Imports: :doc:`base/protocols/http/main.bro </scripts/base/protocols/http/main.bro>`
Summary
~~~~~~~
Runtime Options
###############
============================================================================ =====================================================================
:bro:id:`HTTP::log_client_header_names`: :bro:type:`bool` :bro:attr:`&redef` A boolean value to determine if client header names are to be logged.
:bro:id:`HTTP::log_server_header_names`: :bro:type:`bool` :bro:attr:`&redef` A boolean value to determine if server header names are to be logged.
============================================================================ =====================================================================
Redefinitions
#############
========================================== =
:bro:type:`HTTP::Info`: :bro:type:`record`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: HTTP::log_client_header_names
:Type: :bro:type:`bool`
:Attributes: :bro:attr:`&redef`
:Default: ``T``
A boolean value to determine if client header names are to be logged.
.. bro:id:: HTTP::log_server_header_names
:Type: :bro:type:`bool`
:Attributes: :bro:attr:`&redef`
:Default: ``F``
A boolean value to determine if server header names are to be logged.

25
doc/scripts/policy/protocols/http/software-browser-plugins.bro.rst Normal file
View file

@ -0,0 +1,25 @@
:tocdepth: 3
policy/protocols/http/software-browser-plugins.bro
==================================================
.. bro:namespace:: HTTP
Detect browser plugins as they leak through requests to Omniture
advertising servers.
:Namespace: HTTP
:Imports: :doc:`base/frameworks/software </scripts/base/frameworks/software/index>`, :doc:`base/protocols/http </scripts/base/protocols/http/index>`
Summary
~~~~~~~
Redefinitions
#############
============================================ =
:bro:type:`HTTP::Info`: :bro:type:`record`
:bro:type:`Software::Type`: :bro:type:`enum`
============================================ =
Detailed Interface
~~~~~~~~~~~~~~~~~~

43
doc/scripts/policy/protocols/http/software.bro.rst Normal file
View file

@ -0,0 +1,43 @@
:tocdepth: 3
policy/protocols/http/software.bro
==================================
.. bro:namespace:: HTTP
Software identification and extraction for HTTP traffic.
:Namespace: HTTP
:Imports: :doc:`base/frameworks/software </scripts/base/frameworks/software/index>`
Summary
~~~~~~~
Runtime Options
###############
=========================================================================== ===============================================================
:bro:id:`HTTP::ignored_user_agents`: :bro:type:`pattern` :bro:attr:`&redef` The pattern of HTTP User-Agents which you would like to ignore.
=========================================================================== ===============================================================
Redefinitions
#############
============================================ =
:bro:type:`Software::Type`: :bro:type:`enum`
============================================ =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: HTTP::ignored_user_agents
:Type: :bro:type:`pattern`
:Attributes: :bro:attr:`&redef`
:Default:
::
/^?(NO_DEFAULT)$?/
The pattern of HTTP User-Agents which you would like to ignore.

23
doc/scripts/policy/protocols/http/var-extraction-cookies.bro.rst Normal file
View file

@ -0,0 +1,23 @@
:tocdepth: 3
policy/protocols/http/var-extraction-cookies.bro
================================================
.. bro:namespace:: HTTP
Extracts and logs variable names from cookies sent by clients.
:Namespace: HTTP
:Imports: :doc:`base/protocols/http/main.bro </scripts/base/protocols/http/main.bro>`, :doc:`base/protocols/http/utils.bro </scripts/base/protocols/http/utils.bro>`
Summary
~~~~~~~
Redefinitions
#############
========================================== =
:bro:type:`HTTP::Info`: :bro:type:`record`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

24
doc/scripts/policy/protocols/http/var-extraction-uri.bro.rst Normal file
View file

@ -0,0 +1,24 @@
:tocdepth: 3
policy/protocols/http/var-extraction-uri.bro
============================================
.. bro:namespace:: HTTP
Extracts and logs variables from the requested URI in the default HTTP
logging stream.
:Namespace: HTTP
:Imports: :doc:`base/protocols/http </scripts/base/protocols/http/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================== =
:bro:type:`HTTP::Info`: :bro:type:`record`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

23
doc/scripts/policy/protocols/krb/ticket-logging.bro.rst Normal file
View file

@ -0,0 +1,23 @@
:tocdepth: 3
policy/protocols/krb/ticket-logging.bro
=======================================
.. bro:namespace:: KRB
Add Kerberos ticket hashes to the krb.log
:Namespace: KRB
:Imports: :doc:`base/protocols/krb </scripts/base/protocols/krb/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================= =
:bro:type:`KRB::Info`: :bro:type:`record`
========================================= =
Detailed Interface
~~~~~~~~~~~~~~~~~~

91
doc/scripts/policy/protocols/modbus/known-masters-slaves.bro.rst Normal file
View file

@ -0,0 +1,91 @@
:tocdepth: 3
policy/protocols/modbus/known-masters-slaves.bro
================================================
.. bro:namespace:: Known
Script for tracking known Modbus masters and slaves.
.. todo:: This script needs a lot of work. What might be more interesting
is to track master/slave relationships based on commands sent and
successful (non-exception) responses.
:Namespace: Known
:Imports: :doc:`base/protocols/modbus </scripts/base/protocols/modbus/index>`
Summary
~~~~~~~
State Variables
###############
========================================================================================================== ===============================
:bro:id:`Known::modbus_nodes`: :bro:type:`set` :bro:attr:`&create_expire` = ``1.0 day`` :bro:attr:`&redef` The Modbus nodes being tracked.
========================================================================================================== ===============================
Types
#####
===================================================== =
:bro:type:`Known::ModbusDeviceType`: :bro:type:`enum`
:bro:type:`Known::ModbusInfo`: :bro:type:`record`
===================================================== =
Redefinitions
#############
===================================== =
:bro:type:`Log::ID`: :bro:type:`enum`
===================================== =
Events
######
==================================================== =====================================================================
:bro:id:`Known::log_known_modbus`: :bro:type:`event` Event that can be handled to access the loggable record as it is sent
on to the logging framework.
==================================================== =====================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
State Variables
###############
.. bro:id:: Known::modbus_nodes
:Type: :bro:type:`set` [:bro:type:`addr`, :bro:type:`Known::ModbusDeviceType`]
:Attributes: :bro:attr:`&create_expire` = ``1.0 day`` :bro:attr:`&redef`
:Default: ``{}``
The Modbus nodes being tracked.
Types
#####
.. bro:type:: Known::ModbusDeviceType
:Type: :bro:type:`enum`
.. bro:enum:: Known::MODBUS_MASTER Known::ModbusDeviceType
.. bro:enum:: Known::MODBUS_SLAVE Known::ModbusDeviceType
.. bro:type:: Known::ModbusInfo
:Type: :bro:type:`record`
ts: :bro:type:`time` :bro:attr:`&log`
The time the device was discovered.
host: :bro:type:`addr` :bro:attr:`&log`
The IP address of the host.
device_type: :bro:type:`Known::ModbusDeviceType` :bro:attr:`&log`
The type of device being tracked.
Events
######
.. bro:id:: Known::log_known_modbus
:Type: :bro:type:`event` (rec: :bro:type:`Known::ModbusInfo`)
Event that can be handled to access the loggable record as it is sent
on to the logging framework.

126
doc/scripts/policy/protocols/modbus/track-memmap.bro.rst Normal file
View file

@ -0,0 +1,126 @@
:tocdepth: 3
policy/protocols/modbus/track-memmap.bro
========================================
.. bro:namespace:: Modbus
This script tracks the memory map of holding (read/write) registers and logs
changes as they are discovered.
.. todo:: Not all register read and write functions are supported yet.
:Namespace: Modbus
:Imports: :doc:`base/protocols/modbus </scripts/base/protocols/modbus/index>`, :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
Summary
~~~~~~~
Runtime Options
###############
=================================================================== ==================================================
:bro:id:`Modbus::track_memmap`: :bro:type:`Host` :bro:attr:`&redef` The hosts that should have memory mapping enabled.
=================================================================== ==================================================
State Variables
###############
===================================================== =======================================================
:bro:id:`Modbus::device_registers`: :bro:type:`table` The memory map of slaves is tracked with this variable.
===================================================== =======================================================
Types
#####
===================================================== =====================================================================
:bro:type:`Modbus::MemmapInfo`: :bro:type:`record`
:bro:type:`Modbus::RegisterValue`: :bro:type:`record`
:bro:type:`Modbus::Registers`: :bro:type:`table` Indexed on the device register value and yielding the register value.
===================================================== =====================================================================
Redefinitions
#############
============================================ =
:bro:type:`Log::ID`: :bro:type:`enum`
:bro:type:`Modbus::Info`: :bro:type:`record`
============================================ =
Events
######
===================================================== =====================================================================
:bro:id:`Modbus::changed_register`: :bro:type:`event` This event is generated every time a register is seen to be different
than it was previously seen to be.
===================================================== =====================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: Modbus::track_memmap
:Type: :bro:type:`Host`
:Attributes: :bro:attr:`&redef`
:Default: ``ALL_HOSTS``
The hosts that should have memory mapping enabled.
State Variables
###############
.. bro:id:: Modbus::device_registers
:Type: :bro:type:`table` [:bro:type:`addr`] of :bro:type:`Modbus::Registers`
:Default: ``{}``
The memory map of slaves is tracked with this variable.
Types
#####
.. bro:type:: Modbus::MemmapInfo
:Type: :bro:type:`record`
ts: :bro:type:`time` :bro:attr:`&log`
Timestamp for the detected register change.
uid: :bro:type:`string` :bro:attr:`&log`
Unique ID for the connection.
id: :bro:type:`conn_id` :bro:attr:`&log`
Connection ID.
register: :bro:type:`count` :bro:attr:`&log`
The device memory offset.
old_val: :bro:type:`count` :bro:attr:`&log`
The old value stored in the register.
new_val: :bro:type:`count` :bro:attr:`&log`
The new value stored in the register.
delta: :bro:type:`interval` :bro:attr:`&log`
The time delta between when the *old_val* and *new_val* were
seen.
.. bro:type:: Modbus::RegisterValue
:Type: :bro:type:`record`
last_set: :bro:type:`time`
value: :bro:type:`count`
.. bro:type:: Modbus::Registers
:Type: :bro:type:`table` [:bro:type:`count`] of :bro:type:`Modbus::RegisterValue`
Indexed on the device register value and yielding the register value.
Events
######
.. bro:id:: Modbus::changed_register
:Type: :bro:type:`event` (c: :bro:type:`connection`, register: :bro:type:`count`, old_val: :bro:type:`count`, new_val: :bro:type:`count`, delta: :bro:type:`interval`)
This event is generated every time a register is seen to be different
than it was previously seen to be.

23
doc/scripts/policy/protocols/mysql/software.bro.rst Normal file
View file

@ -0,0 +1,23 @@
:tocdepth: 3
policy/protocols/mysql/software.bro
===================================
.. bro:namespace:: MySQL
Software identification and extraction for MySQL traffic.
:Namespace: MySQL
:Imports: :doc:`base/frameworks/software </scripts/base/frameworks/software/index>`
Summary
~~~~~~~
Redefinitions
#############
============================================ =
:bro:type:`Software::Type`: :bro:type:`enum`
============================================ =
Detailed Interface
~~~~~~~~~~~~~~~~~~

24
doc/scripts/policy/protocols/rdp/indicate_ssl.bro.rst Normal file
View file

@ -0,0 +1,24 @@
:tocdepth: 3
policy/protocols/rdp/indicate_ssl.bro
=====================================
.. bro:namespace:: RDP
If an RDP session is "upgraded" to SSL, this will be indicated
with this script in a new field added to the RDP log.
:Namespace: RDP
:Imports: :doc:`base/protocols/rdp </scripts/base/protocols/rdp/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================= =
:bro:type:`RDP::Info`: :bro:type:`record`
========================================= =
Detailed Interface
~~~~~~~~~~~~~~~~~~

14
doc/scripts/policy/protocols/smb/__load__.bro.rst Normal file
View file

@ -0,0 +1,14 @@
:tocdepth: 3
policy/protocols/smb/__load__.bro
=================================
:Imports: :doc:`base/protocols/smb </scripts/base/protocols/smb/index>`
Summary
~~~~~~~
Detailed Interface
~~~~~~~~~~~~~~~~~~

14
doc/scripts/policy/protocols/smb/index.rst Normal file
View file

@ -0,0 +1,14 @@
:orphan:
Package: policy/protocols/smb
=============================
:doc:`/scripts/policy/protocols/smb/log-cmds.bro`
Load this script to generate an SMB command log, smb_cmd.log.
This is primarily useful for debugging.
:doc:`/scripts/policy/protocols/smb/__load__.bro`

46
doc/scripts/policy/protocols/smb/log-cmds.bro.rst Normal file
View file

@ -0,0 +1,46 @@
:tocdepth: 3
policy/protocols/smb/log-cmds.bro
=================================
.. bro:namespace:: SMB
Load this script to generate an SMB command log, smb_cmd.log.
This is primarily useful for debugging.
:Namespace: SMB
:Imports: :doc:`base/protocols/smb </scripts/base/protocols/smb/index>`
Summary
~~~~~~~
Runtime Options
###############
=========================================================================== ====================================================
:bro:id:`SMB::ignored_command_statuses`: :bro:type:`set` :bro:attr:`&redef` The server response statuses which are *not* logged.
=========================================================================== ====================================================
Redefinitions
#############
===================================== =
:bro:type:`Log::ID`: :bro:type:`enum`
===================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: SMB::ignored_command_statuses
:Type: :bro:type:`set` [:bro:type:`string`]
:Attributes: :bro:attr:`&redef`
:Default:
::
{
"MORE_PROCESSING_REQUIRED"
}
The server response statuses which are *not* logged.

42
doc/scripts/policy/protocols/smtp/blocklists.bro.rst Normal file
View file

@ -0,0 +1,42 @@
:tocdepth: 3
policy/protocols/smtp/blocklists.bro
====================================
.. bro:namespace:: SMTP
Watch for various SPAM blocklist URLs in SMTP error messages.
:Namespace: SMTP
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/smtp </scripts/base/protocols/smtp/index>`
Summary
~~~~~~~
Runtime Options
###############
================================================================================ =
:bro:id:`SMTP::blocklist_error_messages`: :bro:type:`pattern` :bro:attr:`&redef`
================================================================================ =
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: SMTP::blocklist_error_messages
:Type: :bro:type:`pattern`
:Attributes: :bro:attr:`&redef`
:Default:
::
/^?((^?((^?((^?((^?((^?((^?((^?((^?((^?((^?((^?((^?((^?((^?(spamhaus\.org\/)$?)|(^?(sophos\.com\/security\/)$?))$?)|(^?(spamcop\.net\/bl)$?))$?)|(^?(cbl\.abuseat\.org\/)$?))$?)|(^?(sorbs\.net\/)$?))$?)|(^?(bsn\.borderware\.com\/)$?))$?)|(^?(mail-abuse\.com\/)$?))$?)|(^?(b\.barracudacentral\.com\/)$?))$?)|(^?(psbl\.surriel\.com\/)$?))$?)|(^?(antispam\.imp\.ch\/)$?))$?)|(^?(dyndns\.com\/.*spam)$?))$?)|(^?(rbl\.knology\.net\/)$?))$?)|(^?(intercept\.datapacket\.net\/)$?))$?)|(^?(uceprotect\.net\/)$?))$?)|(^?(hostkarma\.junkemailfilter\.com\/)$?))$?/

49
doc/scripts/policy/protocols/smtp/detect-suspicious-orig.bro.rst Normal file
View file

@ -0,0 +1,49 @@
:tocdepth: 3
policy/protocols/smtp/detect-suspicious-orig.bro
================================================
.. bro:namespace:: SMTP
:Namespace: SMTP
:Imports: :doc:`base/frameworks/notice/main.bro </scripts/base/frameworks/notice/main.bro>`, :doc:`base/protocols/smtp/main.bro </scripts/base/protocols/smtp/main.bro>`
Summary
~~~~~~~
Runtime Options
###############
==================================================================================== ===================================================================
:bro:id:`SMTP::suspicious_origination_countries`: :bro:type:`set` :bro:attr:`&redef` Places where it's suspicious for mail to originate from represented
as all-capital, two character country codes (e.g., US).
:bro:id:`SMTP::suspicious_origination_networks`: :bro:type:`set` :bro:attr:`&redef`
==================================================================================== ===================================================================
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: SMTP::suspicious_origination_countries
:Type: :bro:type:`set` [:bro:type:`string`]
:Attributes: :bro:attr:`&redef`
:Default: ``{}``
Places where it's suspicious for mail to originate from represented
as all-capital, two character country codes (e.g., US). It requires
Bro to be built with GeoIP support.
.. bro:id:: SMTP::suspicious_origination_networks
:Type: :bro:type:`set` [:bro:type:`subnet`]
:Attributes: :bro:attr:`&redef`
:Default: ``{}``

43
doc/scripts/policy/protocols/smtp/entities-excerpt.bro.rst Normal file
View file

@ -0,0 +1,43 @@
:tocdepth: 3
policy/protocols/smtp/entities-excerpt.bro
==========================================
.. bro:namespace:: SMTP
This script is for optionally adding a body excerpt to the SMTP
entities log.
:Namespace: SMTP
:Imports: :doc:`base/protocols/smtp/entities.bro </scripts/base/protocols/smtp/entities.bro>`
Summary
~~~~~~~
Runtime Options
###############
================================================================================ ===================================================================
:bro:id:`SMTP::default_entity_excerpt_len`: :bro:type:`count` :bro:attr:`&redef` This is the default value for how much of the entity body should be
included for all MIME entities.
================================================================================ ===================================================================
Redefinitions
#############
============================================ =
:bro:type:`SMTP::Entity`: :bro:type:`record`
============================================ =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: SMTP::default_entity_excerpt_len
:Type: :bro:type:`count`
:Attributes: :bro:attr:`&redef`
:Default: ``0``
This is the default value for how much of the entity body should be
included for all MIME entities. The lesser of this value and
:bro:see:`default_file_bof_buffer_size` will be used.

71
doc/scripts/policy/protocols/smtp/software.bro.rst Normal file
View file

@ -0,0 +1,71 @@
:tocdepth: 3
policy/protocols/smtp/software.bro
==================================
.. bro:namespace:: SMTP
This script feeds software detected through email into the software
framework. Mail clients and webmail interfaces are the only thing
currently detected.
TODO:
* Find some heuristic to determine if email was sent through
a MS Exchange webmail interface as opposed to a desktop client.
:Namespace: SMTP
:Imports: :doc:`base/frameworks/software/main.bro </scripts/base/frameworks/software/main.bro>`, :doc:`base/protocols/smtp/main.bro </scripts/base/protocols/smtp/main.bro>`
Summary
~~~~~~~
Runtime Options
###############
==================================================================================== ===================================================================
:bro:id:`SMTP::detect_clients_in_messages_from`: :bro:type:`Host` :bro:attr:`&redef` Assuming that local mail servers are more trustworthy with the
headers they insert into message envelopes, this default makes Bro
not attempt to detect software in inbound message bodies.
:bro:id:`SMTP::webmail_user_agents`: :bro:type:`pattern` :bro:attr:`&redef` A regular expression to match USER-AGENT-like headers to find if a
message was sent with a webmail interface.
==================================================================================== ===================================================================
Redefinitions
#############
============================================ =
:bro:type:`SMTP::Info`: :bro:type:`record`
:bro:type:`Software::Type`: :bro:type:`enum`
============================================ =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: SMTP::detect_clients_in_messages_from
:Type: :bro:type:`Host`
:Attributes: :bro:attr:`&redef`
:Default: ``LOCAL_HOSTS``
Assuming that local mail servers are more trustworthy with the
headers they insert into message envelopes, this default makes Bro
not attempt to detect software in inbound message bodies. If mail
coming in from external addresses gives incorrect data in
the Received headers, it could populate your SOFTWARE logging stream
with incorrect data. If you would like to detect mail clients for
incoming messages (network traffic originating from a non-local
address), set this variable to EXTERNAL_HOSTS or ALL_HOSTS.
.. bro:id:: SMTP::webmail_user_agents
:Type: :bro:type:`pattern`
:Attributes: :bro:attr:`&redef`
:Default:
::
/^?((^?((^?((^?((^?((^?(^iPlanet Messenger)$?)|(^?(^Sun Java\(tm\) System Messenger Express)$?))$?)|(^?(\(IMP\))$?))$?)|(^?(^SquirrelMail)$?))$?)|(^?(^NeoMail)$?))$?)|(^?(ZimbraWebClient)$?))$?/
A regular expression to match USER-AGENT-like headers to find if a
message was sent with a webmail interface.

66
doc/scripts/policy/protocols/ssh/detect-bruteforcing.bro.rst Normal file
View file

@ -0,0 +1,66 @@
:tocdepth: 3
policy/protocols/ssh/detect-bruteforcing.bro
============================================
.. bro:namespace:: SSH
Detect hosts which are doing password guessing attacks and/or password
bruteforcing over SSH.
:Namespace: SSH
:Imports: :doc:`base/frameworks/intel </scripts/base/frameworks/intel/index>`, :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/frameworks/sumstats </scripts/base/frameworks/sumstats/index>`, :doc:`base/protocols/ssh </scripts/base/protocols/ssh/index>`
Summary
~~~~~~~
Redefinable Options
###################
============================================================================ =====================================================================
:bro:id:`SSH::guessing_timeout`: :bro:type:`interval` :bro:attr:`&redef` The amount of time to remember presumed non-successful logins to
build a model of a password guesser.
:bro:id:`SSH::ignore_guessers`: :bro:type:`table` :bro:attr:`&redef` This value can be used to exclude hosts or entire networks from being
tracked as potential "guessers".
:bro:id:`SSH::password_guesses_limit`: :bro:type:`double` :bro:attr:`&redef` The number of failed SSH connections before a host is designated as
guessing passwords.
============================================================================ =====================================================================
Redefinitions
#############
========================================== =
:bro:type:`Intel::Where`: :bro:type:`enum`
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Redefinable Options
###################
.. bro:id:: SSH::guessing_timeout
:Type: :bro:type:`interval`
:Attributes: :bro:attr:`&redef`
:Default: ``30.0 mins``
The amount of time to remember presumed non-successful logins to
build a model of a password guesser.
.. bro:id:: SSH::ignore_guessers
:Type: :bro:type:`table` [:bro:type:`subnet`] of :bro:type:`subnet`
:Attributes: :bro:attr:`&redef`
:Default: ``{}``
This value can be used to exclude hosts or entire networks from being
tracked as potential "guessers". The index represents
client subnets and the yield value represents server subnets.
.. bro:id:: SSH::password_guesses_limit
:Type: :bro:type:`double`
:Attributes: :bro:attr:`&redef`
:Default: ``30.0``
The number of failed SSH connections before a host is designated as
guessing passwords.

48
doc/scripts/policy/protocols/ssh/geo-data.bro.rst Normal file
View file

@ -0,0 +1,48 @@
:tocdepth: 3
policy/protocols/ssh/geo-data.bro
=================================
.. bro:namespace:: SSH
Geodata based detections for SSH analysis.
:Namespace: SSH
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssh </scripts/base/protocols/ssh/index>`
Summary
~~~~~~~
Runtime Options
###############
==================================================================== ==================================================================
:bro:id:`SSH::watched_countries`: :bro:type:`set` :bro:attr:`&redef` The set of countries for which you'd like to generate notices upon
successful login.
==================================================================== ==================================================================
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
:bro:type:`SSH::Info`: :bro:type:`record`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: SSH::watched_countries
:Type: :bro:type:`set` [:bro:type:`string`]
:Attributes: :bro:attr:`&redef`
:Default:
::
{
"RO"
}
The set of countries for which you'd like to generate notices upon
successful login.

47
doc/scripts/policy/protocols/ssh/interesting-hostnames.bro.rst Normal file
View file

@ -0,0 +1,47 @@
:tocdepth: 3
policy/protocols/ssh/interesting-hostnames.bro
==============================================
.. bro:namespace:: SSH
This script will generate a notice if an apparent SSH login originates
or heads to a host with a reverse hostname that looks suspicious. By
default, the regular expression to match "interesting" hostnames includes
names that are typically used for infrastructure hosts like nameservers,
mail servers, web servers and ftp servers.
:Namespace: SSH
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`
Summary
~~~~~~~
Runtime Options
###############
============================================================================ ===============================================================
:bro:id:`SSH::interesting_hostnames`: :bro:type:`pattern` :bro:attr:`&redef` Strange/bad host names to see successful SSH logins from or to.
============================================================================ ===============================================================
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: SSH::interesting_hostnames
:Type: :bro:type:`pattern`
:Attributes: :bro:attr:`&redef`
:Default:
::
/^?((^?((^?((^?((^?((^?((^?(^d?ns[0-9]*\.)$?)|(^?(^smtp[0-9]*\.)$?))$?)|(^?(^mail[0-9]*\.)$?))$?)|(^?(^pop[0-9]*\.)$?))$?)|(^?(^imap[0-9]*\.)$?))$?)|(^?(^www[0-9]*\.)$?))$?)|(^?(^ftp[0-9]*\.)$?))$?/
Strange/bad host names to see successful SSH logins from or to.

24
doc/scripts/policy/protocols/ssh/software.bro.rst Normal file
View file

@ -0,0 +1,24 @@
:tocdepth: 3
policy/protocols/ssh/software.bro
=================================
.. bro:namespace:: SSH
Extracts SSH client and server information from SSH
connections and forwards it to the software framework.
:Namespace: SSH
:Imports: :doc:`base/frameworks/software </scripts/base/frameworks/software/index>`
Summary
~~~~~~~
Redefinitions
#############
============================================ =
:bro:type:`Software::Type`: :bro:type:`enum`
============================================ =
Detailed Interface
~~~~~~~~~~~~~~~~~~

57
doc/scripts/policy/protocols/ssl/expiring-certs.bro.rst Normal file
View file

@ -0,0 +1,57 @@
:tocdepth: 3
policy/protocols/ssl/expiring-certs.bro
=======================================
.. bro:namespace:: SSL
Generate notices when X.509 certificates over SSL/TLS are expired or
going to expire soon based on the date and time values stored within the
certificate.
:Namespace: SSL
:Imports: :doc:`base/files/x509 </scripts/base/files/x509/index>`, :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`, :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
Summary
~~~~~~~
Runtime Options
###############
==================================================================================== =====================================================================
:bro:id:`SSL::notify_certs_expiration`: :bro:type:`Host` :bro:attr:`&redef` The category of hosts you would like to be notified about which have
certificates that are going to be expiring soon.
:bro:id:`SSL::notify_when_cert_expiring_in`: :bro:type:`interval` :bro:attr:`&redef` The time before a certificate is going to expire that you would like
to start receiving :bro:enum:`SSL::Certificate_Expires_Soon` notices.
==================================================================================== =====================================================================
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: SSL::notify_certs_expiration
:Type: :bro:type:`Host`
:Attributes: :bro:attr:`&redef`
:Default: ``LOCAL_HOSTS``
The category of hosts you would like to be notified about which have
certificates that are going to be expiring soon. By default, these
notices will be suppressed by the notice framework for 1 day after
a particular certificate has had a notice generated.
Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS
.. bro:id:: SSL::notify_when_cert_expiring_in
:Type: :bro:type:`interval`
:Attributes: :bro:attr:`&redef`
:Default: ``30.0 days``
The time before a certificate is going to expire that you would like
to start receiving :bro:enum:`SSL::Certificate_Expires_Soon` notices.

45
doc/scripts/policy/protocols/ssl/extract-certs-pem.bro.rst Normal file
View file

@ -0,0 +1,45 @@
:tocdepth: 3
policy/protocols/ssl/extract-certs-pem.bro
==========================================
.. bro:namespace:: SSL
This script is used to extract host certificates seen on the wire to disk
after being converted to PEM files. The certificates will be stored in
a single file, one for local certificates and one for remote certificates.
.. note::
- It doesn't work well on a cluster because each worker will write its
own certificate files and no duplicate checking is done across the
cluster so each node would log each certificate.
:Namespace: SSL
:Imports: :doc:`base/files/x509 </scripts/base/files/x509/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`, :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
Summary
~~~~~~~
Runtime Options
###############
===================================================================== =========================================================
:bro:id:`SSL::extract_certs_pem`: :bro:type:`Host` :bro:attr:`&redef` Control if host certificates offered by the defined hosts
will be written to the PEM certificates file.
===================================================================== =========================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: SSL::extract_certs_pem
:Type: :bro:type:`Host`
:Attributes: :bro:attr:`&redef`
:Default: ``LOCAL_HOSTS``
Control if host certificates offered by the defined hosts
will be written to the PEM certificates file.
Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS.

25
doc/scripts/policy/protocols/ssl/heartbleed.bro.rst Normal file
View file

@ -0,0 +1,25 @@
:tocdepth: 3
policy/protocols/ssl/heartbleed.bro
===================================
.. bro:namespace:: Heartbleed
Detect the TLS heartbleed attack. See http://heartbleed.com for more.
:Namespace: Heartbleed
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Redefinitions
#############
==================================================================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
:bro:type:`SSL::Info`: :bro:type:`record`
:bro:id:`SSL::disable_analyzer_after_detection`: :bro:type:`bool` :bro:attr:`&redef`
==================================================================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

195
doc/scripts/policy/protocols/ssl/known-certs.bro.rst Normal file
View file

@ -0,0 +1,195 @@
:tocdepth: 3
policy/protocols/ssl/known-certs.bro
====================================
.. bro:namespace:: Known
Log information about certificates while attempting to avoid duplicate
logging.
:Namespace: Known
:Imports: :doc:`base/files/x509 </scripts/base/files/x509/index>`, :doc:`base/frameworks/cluster </scripts/base/frameworks/cluster/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`, :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
Summary
~~~~~~~
Runtime Options
###############
============================================================================ ===================================================================
:bro:id:`Known::cert_store_expiry`: :bro:type:`interval` :bro:attr:`&redef` The expiry interval of new entries in :bro:see:`Known::cert_store`.
:bro:id:`Known::cert_store_timeout`: :bro:type:`interval` :bro:attr:`&redef` The timeout interval to use for operations against
:bro:see:`Known::cert_store`.
:bro:id:`Known::cert_tracking`: :bro:type:`Host` :bro:attr:`&redef` The certificates whose existence should be logged and tracked.
============================================================================ ===================================================================
Redefinable Options
###################
======================================================================= ==============================================================
:bro:id:`Known::cert_store_name`: :bro:type:`string` :bro:attr:`&redef` The Broker topic name to use for :bro:see:`Known::cert_store`.
:bro:id:`Known::use_cert_store`: :bro:type:`bool` :bro:attr:`&redef` Toggles between different implementations of this script.
======================================================================= ==============================================================
State Variables
###############
=================================================================================================== ====================================================================
:bro:id:`Known::cert_store`: :bro:type:`Cluster::StoreInfo` Holds the set of all known certificates.
:bro:id:`Known::certs`: :bro:type:`set` :bro:attr:`&create_expire` = ``1.0 day`` :bro:attr:`&redef` The set of all known certificates to store for preventing duplicate
logging.
=================================================================================================== ====================================================================
Types
#####
======================================================= =
:bro:type:`Known::AddrCertHashPair`: :bro:type:`record`
:bro:type:`Known::CertsInfo`: :bro:type:`record`
======================================================= =
Redefinitions
#############
===================================== =
:bro:type:`Log::ID`: :bro:type:`enum`
===================================== =
Events
######
=================================================== =====================================================================
:bro:id:`Known::log_known_certs`: :bro:type:`event` Event that can be handled to access the loggable record as it is sent
on to the logging framework.
=================================================== =====================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: Known::cert_store_expiry
:Type: :bro:type:`interval`
:Attributes: :bro:attr:`&redef`
:Default: ``1.0 day``
The expiry interval of new entries in :bro:see:`Known::cert_store`.
This also changes the interval at which certs get logged.
.. bro:id:: Known::cert_store_timeout
:Type: :bro:type:`interval`
:Attributes: :bro:attr:`&redef`
:Default: ``15.0 secs``
The timeout interval to use for operations against
:bro:see:`Known::cert_store`.
.. bro:id:: Known::cert_tracking
:Type: :bro:type:`Host`
:Attributes: :bro:attr:`&redef`
:Default: ``ALL_HOSTS``
The certificates whose existence should be logged and tracked.
Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS.
Redefinable Options
###################
.. bro:id:: Known::cert_store_name
:Type: :bro:type:`string`
:Attributes: :bro:attr:`&redef`
:Default: ``"bro/known/certs"``
The Broker topic name to use for :bro:see:`Known::cert_store`.
.. bro:id:: Known::use_cert_store
:Type: :bro:type:`bool`
:Attributes: :bro:attr:`&redef`
:Default: ``T``
Toggles between different implementations of this script.
When true, use a Broker data store, else use a regular Bro set
with keys uniformly distributed over proxy nodes in cluster
operation.
State Variables
###############
.. bro:id:: Known::cert_store
:Type: :bro:type:`Cluster::StoreInfo`
:Default:
::
{
name=<uninitialized>
store=<uninitialized>
master_node=""
master=F
backend=Broker::MEMORY
options=[sqlite=[path=""], rocksdb=[path=""]]
clone_resync_interval=10.0 secs
clone_stale_interval=5.0 mins
clone_mutation_buffer_interval=2.0 mins
}
Holds the set of all known certificates. Keys in the store are of
type :bro:type:`Known::AddrCertHashPair` and their associated value is
always the boolean value of "true".
.. bro:id:: Known::certs
:Type: :bro:type:`set` [:bro:type:`addr`, :bro:type:`string`]
:Attributes: :bro:attr:`&create_expire` = ``1.0 day`` :bro:attr:`&redef`
:Default: ``{}``
The set of all known certificates to store for preventing duplicate
logging. It can also be used from other scripts to
inspect if a certificate has been seen in use. The string value
in the set is for storing the DER formatted certificate' SHA1 hash.
In cluster operation, this set is uniformly distributed across
proxy nodes.
Types
#####
.. bro:type:: Known::AddrCertHashPair
:Type: :bro:type:`record`
host: :bro:type:`addr`
hash: :bro:type:`string`
.. bro:type:: Known::CertsInfo
:Type: :bro:type:`record`
ts: :bro:type:`time` :bro:attr:`&log`
The timestamp when the certificate was detected.
host: :bro:type:`addr` :bro:attr:`&log`
The address that offered the certificate.
port_num: :bro:type:`port` :bro:attr:`&log` :bro:attr:`&optional`
If the certificate was handed out by a server, this is the
port that the server was listening on.
subject: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
Certificate subject.
issuer_subject: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
Certificate issuer subject.
serial: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
Serial number for the certificate.
Events
######
.. bro:id:: Known::log_known_certs
:Type: :bro:type:`event` (rec: :bro:type:`Known::CertsInfo`)
Event that can be handled to access the loggable record as it is sent
on to the logging framework.

25
doc/scripts/policy/protocols/ssl/log-hostcerts-only.bro.rst Normal file
View file

@ -0,0 +1,25 @@
:tocdepth: 3
policy/protocols/ssl/log-hostcerts-only.bro
===========================================
.. bro:namespace:: X509
When this script is loaded, only the host certificates (client and server)
will be logged to x509.log. Logging of all other certificates will be suppressed.
:Namespace: X509
:Imports: :doc:`base/files/x509 </scripts/base/files/x509/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================================== =
:bro:type:`X509::Info`: :bro:type:`record`
:bro:type:`fa_file`: :bro:type:`record` :bro:attr:`&redef`
========================================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

60
doc/scripts/policy/protocols/ssl/notary.bro.rst Normal file
View file

@ -0,0 +1,60 @@
:tocdepth: 3
policy/protocols/ssl/notary.bro
===============================
.. bro:namespace:: CertNotary
:Namespace: CertNotary
:Imports: :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Runtime Options
###############
=================================================================== ===========================
:bro:id:`CertNotary::domain`: :bro:type:`string` :bro:attr:`&redef` The notary domain to query.
=================================================================== ===========================
Types
#####
==================================================== ============================================
:bro:type:`CertNotary::Response`: :bro:type:`record` A response from the ICSI certificate notary.
==================================================== ============================================
Redefinitions
#############
========================================= =
:bro:type:`SSL::Info`: :bro:type:`record`
========================================= =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: CertNotary::domain
:Type: :bro:type:`string`
:Attributes: :bro:attr:`&redef`
:Default: ``"notary.icsi.berkeley.edu"``
The notary domain to query.
Types
#####
.. bro:type:: CertNotary::Response
:Type: :bro:type:`record`
first_seen: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&optional`
last_seen: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&optional`
times_seen: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&optional`
valid: :bro:type:`bool` :bro:attr:`&log` :bro:attr:`&optional`
A response from the ICSI certificate notary.

99
doc/scripts/policy/protocols/ssl/validate-certs.bro.rst Normal file
View file

@ -0,0 +1,99 @@
:tocdepth: 3
policy/protocols/ssl/validate-certs.bro
=======================================
.. bro:namespace:: SSL
Perform full certificate chain validation for SSL certificates.
:Namespace: SSL
:Imports: :doc:`base/frameworks/cluster </scripts/base/frameworks/cluster/index>`, :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
State Variables
###############
===================================================================================================================== ==================================================================
:bro:id:`SSL::recently_validated_certs`: :bro:type:`table` :bro:attr:`&read_expire` = ``5.0 mins`` :bro:attr:`&redef` Result values for recently validated chains along with the
validation status are kept in this table to avoid constant
validation every time the same certificate chain is seen.
:bro:id:`SSL::ssl_cache_intermediate_ca`: :bro:type:`bool` :bro:attr:`&redef` Use intermediate CA certificate caching when trying to validate
certificates.
:bro:id:`SSL::ssl_store_valid_chain`: :bro:type:`bool` :bro:attr:`&redef` Store the valid chain in c$ssl$valid_chain if validation succeeds.
===================================================================================================================== ==================================================================
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
:bro:type:`SSL::Info`: :bro:type:`record`
========================================== =
Events
######
================================================== ===============================================================
:bro:id:`SSL::intermediate_add`: :bro:type:`event` Event from a manager to workers when encountering a new, valid
intermediate.
:bro:id:`SSL::new_intermediate`: :bro:type:`event` Event from workers to the manager when a new intermediate chain
is to be added.
================================================== ===============================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
State Variables
###############
.. bro:id:: SSL::recently_validated_certs
:Type: :bro:type:`table` [:bro:type:`string`] of :bro:type:`X509::Result`
:Attributes: :bro:attr:`&read_expire` = ``5.0 mins`` :bro:attr:`&redef`
:Default: ``{}``
Result values for recently validated chains along with the
validation status are kept in this table to avoid constant
validation every time the same certificate chain is seen.
.. bro:id:: SSL::ssl_cache_intermediate_ca
:Type: :bro:type:`bool`
:Attributes: :bro:attr:`&redef`
:Default: ``T``
Use intermediate CA certificate caching when trying to validate
certificates. When this is enabled, Bro keeps track of all valid
intermediate CA certificates that it has seen in the past. When
encountering a host certificate that cannot be validated because
of missing intermediate CA certificate, the cached list is used
to try to validate the cert. This is similar to how Firefox is
doing certificate validation.
Disabling this will usually greatly increase the number of validation warnings
that you encounter. Only disable if you want to find misconfigured servers.
.. bro:id:: SSL::ssl_store_valid_chain
:Type: :bro:type:`bool`
:Attributes: :bro:attr:`&redef`
:Default: ``T``
Store the valid chain in c$ssl$valid_chain if validation succeeds.
This has a potentially high memory impact, depending on the local environment
and is thus disabled by default.
Events
######
.. bro:id:: SSL::intermediate_add
:Type: :bro:type:`event` (key: :bro:type:`string`, value: :bro:type:`vector` of :bro:type:`opaque` of x509)
Event from a manager to workers when encountering a new, valid
intermediate.
.. bro:id:: SSL::new_intermediate
:Type: :bro:type:`event` (key: :bro:type:`string`, value: :bro:type:`vector` of :bro:type:`opaque` of x509)
Event from workers to the manager when a new intermediate chain
is to be added.

24
doc/scripts/policy/protocols/ssl/validate-ocsp.bro.rst Normal file
View file

@ -0,0 +1,24 @@
:tocdepth: 3
policy/protocols/ssl/validate-ocsp.bro
======================================
.. bro:namespace:: SSL
Perform validation of stapled OCSP responses.
:Namespace: SSL
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
:bro:type:`SSL::Info`: :bro:type:`record`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~

90
doc/scripts/policy/protocols/ssl/validate-sct.bro.rst Normal file
View file

@ -0,0 +1,90 @@
:tocdepth: 3
policy/protocols/ssl/validate-sct.bro
=====================================
.. bro:namespace:: SSL
Perform validation of Signed Certificate Timestamps, as used
for Certificate Transparency. See RFC6962 for more details.
:Namespace: SSL
:Imports: :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`, :doc:`policy/protocols/ssl/validate-certs.bro </scripts/policy/protocols/ssl/validate-certs.bro>`
Summary
~~~~~~~
Types
#####
============================================ ================================================================
:bro:type:`SSL::SctInfo`: :bro:type:`record` This record is used to store information about the SCTs that are
encountered in a SSL connection.
:bro:type:`SSL::SctSource`: :bro:type:`enum` List of the different sources for Signed Certificate Timestamp
============================================ ================================================================
Redefinitions
#############
========================================================================= =
:bro:type:`SSL::Info`: :bro:type:`record`
:bro:id:`SSL::ssl_store_valid_chain`: :bro:type:`bool` :bro:attr:`&redef`
========================================================================= =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Types
#####
.. bro:type:: SSL::SctInfo
:Type: :bro:type:`record`
version: :bro:type:`count`
The version of the encountered SCT (should always be 0 for v1).
logid: :bro:type:`string`
The ID of the log issuing this SCT.
timestamp: :bro:type:`count`
The timestamp at which this SCT was issued measured since the
epoch (January 1, 1970, 00:00), ignoring leap seconds, in
milliseconds. Not converted to a Bro timestamp because we need
the exact value for validation.
sig_alg: :bro:type:`count`
The signature algorithm used for this sct.
hash_alg: :bro:type:`count`
The hash algorithm used for this sct.
signature: :bro:type:`string`
The signature of this SCT.
source: :bro:type:`SSL::SctSource`
Source of this SCT.
valid: :bro:type:`bool` :bro:attr:`&optional`
Validation result of this SCT.
This record is used to store information about the SCTs that are
encountered in a SSL connection.
.. bro:type:: SSL::SctSource
:Type: :bro:type:`enum`
.. bro:enum:: SSL::SCT_X509_EXT SSL::SctSource
Signed Certificate Timestamp was encountered in the extension of
an X.509 certificate.
.. bro:enum:: SSL::SCT_TLS_EXT SSL::SctSource
Signed Certificate Timestamp was encountered in an TLS session
extension.
.. bro:enum:: SSL::SCT_OCSP_EXT SSL::SctSource
Signed Certificate Timestamp was encountered in the extension of
an stapled OCSP reply.
List of the different sources for Signed Certificate Timestamp

94
doc/scripts/policy/protocols/ssl/weak-keys.bro.rst Normal file
View file

@ -0,0 +1,94 @@
:tocdepth: 3
policy/protocols/ssl/weak-keys.bro
==================================
.. bro:namespace:: SSL
Generate notices when SSL/TLS connections use certificates, DH parameters,
or cipher suites that are deemed to be insecure.
:Namespace: SSL
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`, :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
Summary
~~~~~~~
Runtime Options
###############
======================================================================================== ==============================================================================
:bro:id:`SSL::notify_dh_length_shorter_cert_length`: :bro:type:`bool` :bro:attr:`&redef` Warn if the DH key length is smaller than the certificate key length.
:bro:id:`SSL::notify_minimal_key_length`: :bro:type:`count` :bro:attr:`&redef` The minimal key length in bits that is considered to be safe.
:bro:id:`SSL::notify_weak_keys`: :bro:type:`Host` :bro:attr:`&redef` The category of hosts you would like to be notified about which are using weak
keys/ciphers/protocol_versions.
:bro:id:`SSL::tls_minimum_version`: :bro:type:`count` :bro:attr:`&redef` Warn if a server negotiates a SSL session with a protocol version smaller than
the specified version.
:bro:id:`SSL::unsafe_ciphers_regex`: :bro:type:`pattern` :bro:attr:`&redef` Warn if a server negotiates an unsafe cipher suite.
======================================================================================== ==============================================================================
Redefinitions
#############
========================================== =
:bro:type:`Notice::Type`: :bro:type:`enum`
========================================== =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. bro:id:: SSL::notify_dh_length_shorter_cert_length
:Type: :bro:type:`bool`
:Attributes: :bro:attr:`&redef`
:Default: ``T``
Warn if the DH key length is smaller than the certificate key length. This is
potentially unsafe because it gives a wrong impression of safety due to the
certificate key length. However, it is very common and cannot be avoided in some
settings (e.g. with old jave clients).
.. bro:id:: SSL::notify_minimal_key_length
:Type: :bro:type:`count`
:Attributes: :bro:attr:`&redef`
:Default: ``2048``
The minimal key length in bits that is considered to be safe. Any shorter
(non-EC) key lengths will trigger a notice.
.. bro:id:: SSL::notify_weak_keys
:Type: :bro:type:`Host`
:Attributes: :bro:attr:`&redef`
:Default: ``LOCAL_HOSTS``
The category of hosts you would like to be notified about which are using weak
keys/ciphers/protocol_versions. By default, these notices will be suppressed
by the notice framework for 1 day after a particular host has had a notice
generated. Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS
.. bro:id:: SSL::tls_minimum_version
:Type: :bro:type:`count`
:Attributes: :bro:attr:`&redef`
:Default: ``769``
Warn if a server negotiates a SSL session with a protocol version smaller than
the specified version. By default, the minimal version is TLSv10 because SSLv2
and v3 have serious security issued.
See https://tools.ietf.org/html/draft-thomson-sslv3-diediedie-00
To disable, set to SSLv20
.. bro:id:: SSL::unsafe_ciphers_regex
:Type: :bro:type:`pattern`
:Attributes: :bro:attr:`&redef`
:Default:
::
/^?((_EXPORT_)|(_RC4_))$?/
Warn if a server negotiates an unsafe cipher suite. By default, we only warn when
encountering old export cipher suites, or RC4 (see RFC7465).