mirror of
https://github.com/zeek/zeek.git
synced 2025-10-16 13:38:19 +00:00
11c437faa3
- Log path's are generated in the scripting land
now. The default Log stream ID to path string
mapping works like this:
- Notice::LOG -> "notice"
- Notice::POLICY_LOG -> "notice_policy"
- TestModule::LOG -> "test_module"
- Logging streams updated across all of the shipped
scripts to be more user friendly. Instead of
the logging stream ID HTTP::HTTP, we now have
HTTP::LOG, etc.
- The priorities on some bro_init handlers have
been adjusted to make the process of applying
filters or disabling streams easier for users.
348 lines
9.4 KiB
ReStructuredText
348 lines
9.4 KiB
ReStructuredText
.. Automatically generated. Do not edit.
|
|
|
|
example.bro
|
|
===========
|
|
|
|
:download:`Original Source File <example.bro>`
|
|
|
|
Overview
|
|
--------
|
|
This is an example script that demonstrates how to document. Comments
|
|
of the form ``##!`` are for the script summary. The contents of
|
|
these comments are transferred directly into the auto-generated
|
|
`reStructuredText <http://docutils.sourceforge.net/rst.html>`_
|
|
(reST) document's summary section.
|
|
|
|
.. tip:: You can embed directives and roles within ``##``-stylized comments.
|
|
|
|
A script's logging information has to be documented manually as minimally
|
|
shown below. Note that references may not always be possible (e.g.
|
|
anonymous filter functions) and a script may not need to document
|
|
each of "columns", "event", "filter" depending on exactly what it's doing.
|
|
|
|
**Logging Stream ID:** :bro:enum:`Example::EXAMPLE`
|
|
:Columns: :bro:type:`Example::Info`
|
|
:Event: :bro:id:`Example::log_example`
|
|
:Filter: ``example-filter``
|
|
uses :bro:id:`Example::filter_func` to determine whether to
|
|
exclude the ``ts`` field
|
|
|
|
:Author: Jon Siwek <jsiwek@ncsa.illinois.edu>
|
|
|
|
:Imports: :doc:`policy/frameworks/software/vulnerable </scripts/policy/frameworks/software/vulnerable>`
|
|
|
|
Summary
|
|
~~~~~~~
|
|
Options
|
|
#######
|
|
============================================================================ ======================================
|
|
:bro:id:`Example::an_option`: :bro:type:`set` :bro:attr:`&redef` add documentation for "an_option" here
|
|
|
|
:bro:id:`Example::option_with_init`: :bro:type:`interval` :bro:attr:`&redef`
|
|
============================================================================ ======================================
|
|
|
|
State Variables
|
|
###############
|
|
=========================================================================== =======================================
|
|
:bro:id:`Example::a_var`: :bro:type:`bool` put some documentation for "a_var" here
|
|
|
|
:bro:id:`Example::var_with_attr`: :bro:type:`count` :bro:attr:`&persistent`
|
|
|
|
:bro:id:`Example::var_without_explicit_type`: :bro:type:`string`
|
|
=========================================================================== =======================================
|
|
|
|
Types
|
|
#####
|
|
====================================================== ==========================================================
|
|
:bro:type:`Example::SimpleEnum`: :bro:type:`enum` documentation for "SimpleEnum"
|
|
goes here.
|
|
|
|
:bro:type:`Example::SimpleRecord`: :bro:type:`record` general documentation for a type "SimpleRecord"
|
|
goes here.
|
|
|
|
:bro:type:`Example::ComplexRecord`: :bro:type:`record` general documentation for a type "ComplexRecord" goes here
|
|
|
|
:bro:type:`Example::Info`: :bro:type:`record` An example record to be used with a logging stream.
|
|
====================================================== ==========================================================
|
|
|
|
Events
|
|
######
|
|
================================================= =============================================================
|
|
:bro:id:`Example::an_event`: :bro:type:`event` Summarize "an_event" here.
|
|
|
|
:bro:id:`Example::log_example`: :bro:type:`event` This is a declaration of an example event that can be used in
|
|
logging streams and is raised once for each log entry.
|
|
|
|
:bro:id:`bro_init`: :bro:type:`event`
|
|
================================================= =============================================================
|
|
|
|
Functions
|
|
#########
|
|
=============================================== =======================================
|
|
:bro:id:`Example::a_function`: :bro:type:`func` Summarize purpose of "a_function" here.
|
|
=============================================== =======================================
|
|
|
|
Redefinitions
|
|
#############
|
|
===================================================== ========================================
|
|
:bro:type:`Log::ID`: :bro:type:`enum`
|
|
|
|
:bro:type:`Example::SimpleEnum`: :bro:type:`enum` document the "SimpleEnum" redef here
|
|
|
|
:bro:type:`Example::SimpleRecord`: :bro:type:`record` document the record extension redef here
|
|
===================================================== ========================================
|
|
|
|
Namespaces
|
|
~~~~~~~~~~
|
|
.. bro:namespace:: Example
|
|
|
|
Notices
|
|
~~~~~~~
|
|
:bro:type:`Notice::Type`
|
|
|
|
:Type: :bro:type:`enum`
|
|
|
|
.. bro:enum:: Example::Notice_One Notice::Type
|
|
|
|
any number of this type of comment
|
|
will document "Notice_One"
|
|
|
|
.. bro:enum:: Example::Notice_Two Notice::Type
|
|
|
|
any number of this type of comment
|
|
will document "Notice_Two"
|
|
|
|
.. bro:enum:: Example::Notice_Three Notice::Type
|
|
|
|
.. bro:enum:: Example::Notice_Four Notice::Type
|
|
|
|
Public Interface
|
|
----------------
|
|
Options
|
|
~~~~~~~
|
|
.. bro:id:: Example::an_option
|
|
|
|
:Type: :bro:type:`set` [:bro:type:`addr`, :bro:type:`addr`, :bro:type:`string`]
|
|
:Attributes: :bro:attr:`&redef`
|
|
:Default: ``{}``
|
|
|
|
add documentation for "an_option" here
|
|
|
|
.. bro:id:: Example::option_with_init
|
|
|
|
:Type: :bro:type:`interval`
|
|
:Attributes: :bro:attr:`&redef`
|
|
:Default: ``10.0 msecs``
|
|
|
|
State Variables
|
|
~~~~~~~~~~~~~~~
|
|
.. bro:id:: Example::a_var
|
|
|
|
:Type: :bro:type:`bool`
|
|
|
|
put some documentation for "a_var" here
|
|
|
|
.. bro:id:: Example::var_with_attr
|
|
|
|
:Type: :bro:type:`count`
|
|
:Attributes: :bro:attr:`&persistent`
|
|
|
|
.. bro:id:: Example::var_without_explicit_type
|
|
|
|
:Type: :bro:type:`string`
|
|
:Default: ``"this works"``
|
|
|
|
Types
|
|
~~~~~
|
|
.. bro:type:: Example::SimpleEnum
|
|
|
|
:Type: :bro:type:`enum`
|
|
|
|
.. bro:enum:: Example::ONE Example::SimpleEnum
|
|
|
|
and more specific info for "ONE"
|
|
can span multiple lines
|
|
|
|
.. bro:enum:: Example::TWO Example::SimpleEnum
|
|
|
|
or more info like this for "TWO"
|
|
can span multiple lines
|
|
|
|
.. bro:enum:: Example::THREE Example::SimpleEnum
|
|
|
|
documentation for "SimpleEnum"
|
|
goes here.
|
|
|
|
.. bro:type:: Example::SimpleRecord
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
field1: :bro:type:`count`
|
|
counts something
|
|
|
|
field2: :bro:type:`bool`
|
|
toggles something
|
|
|
|
general documentation for a type "SimpleRecord"
|
|
goes here.
|
|
|
|
.. bro:type:: Example::ComplexRecord
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
field1: :bro:type:`count`
|
|
counts something
|
|
|
|
field2: :bro:type:`bool`
|
|
toggles something
|
|
|
|
field3: :bro:type:`Example::SimpleRecord`
|
|
|
|
msg: :bro:type:`string` :bro:attr:`&default` = ``"blah"`` :bro:attr:`&optional`
|
|
attributes are self-documenting
|
|
|
|
general documentation for a type "ComplexRecord" goes here
|
|
|
|
.. bro:type:: Example::Info
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
ts: :bro:type:`time` :bro:attr:`&log`
|
|
|
|
uid: :bro:type:`string` :bro:attr:`&log`
|
|
|
|
status: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&optional`
|
|
|
|
An example record to be used with a logging stream.
|
|
|
|
Events
|
|
~~~~~~
|
|
.. bro:id:: Example::an_event
|
|
|
|
:Type: :bro:type:`event` (name: :bro:type:`string`)
|
|
|
|
Summarize "an_event" here.
|
|
Give more details about "an_event" here.
|
|
|
|
:param name: describe the argument here
|
|
|
|
.. bro:id:: Example::log_example
|
|
|
|
:Type: :bro:type:`event` (rec: :bro:type:`Example::Info`)
|
|
|
|
This is a declaration of an example event that can be used in
|
|
logging streams and is raised once for each log entry.
|
|
|
|
.. bro:id:: bro_init
|
|
|
|
:Type: :bro:type:`event` ()
|
|
|
|
Functions
|
|
~~~~~~~~~
|
|
.. bro:id:: Example::a_function
|
|
|
|
:Type: :bro:type:`function` (tag: :bro:type:`string`, msg: :bro:type:`string`) : :bro:type:`string`
|
|
|
|
Summarize purpose of "a_function" here.
|
|
Give more details about "a_function" here.
|
|
Separating the documentation of the params/return values with
|
|
empty comments is optional, but improves readability of script.
|
|
|
|
|
|
:param tag: function arguments can be described
|
|
like this
|
|
|
|
:param msg: another param
|
|
|
|
|
|
:returns: describe the return type here
|
|
|
|
Redefinitions
|
|
~~~~~~~~~~~~~
|
|
:bro:type:`Log::ID`
|
|
|
|
:Type: :bro:type:`enum`
|
|
|
|
.. bro:enum:: Example::LOG Log::ID
|
|
|
|
:bro:type:`Example::SimpleEnum`
|
|
|
|
:Type: :bro:type:`enum`
|
|
|
|
.. bro:enum:: Example::FOUR Example::SimpleEnum
|
|
|
|
and some documentation for "FOUR"
|
|
|
|
.. bro:enum:: Example::FIVE Example::SimpleEnum
|
|
|
|
also "FIVE" for good measure
|
|
|
|
document the "SimpleEnum" redef here
|
|
|
|
:bro:type:`Example::SimpleRecord`
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
field_ext: :bro:type:`string` :bro:attr:`&optional`
|
|
document the extending field here
|
|
(or here)
|
|
|
|
document the record extension redef here
|
|
|
|
Port Analysis
|
|
-------------
|
|
:ref:`More Information <common_port_analysis_doc>`
|
|
|
|
SSL::
|
|
|
|
[ports={
|
|
443/tcp,
|
|
562/tcp
|
|
}]
|
|
|
|
Packet Filter
|
|
-------------
|
|
:ref:`More Information <common_packet_filter_doc>`
|
|
|
|
Filters added::
|
|
|
|
[ssl] = tcp port 443,
|
|
[nntps] = tcp port 562
|
|
|
|
Private Interface
|
|
-----------------
|
|
State Variables
|
|
~~~~~~~~~~~~~~~
|
|
.. bro:id:: Example::example_ports
|
|
|
|
:Type: :bro:type:`set` [:bro:type:`port`]
|
|
:Attributes: :bro:attr:`&redef`
|
|
:Default:
|
|
|
|
::
|
|
|
|
{
|
|
443/tcp,
|
|
562/tcp
|
|
}
|
|
|
|
Types
|
|
~~~~~
|
|
.. bro:type:: Example::PrivateRecord
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
field1: :bro:type:`bool`
|
|
|
|
field2: :bro:type:`count`
|
|
|
|
Functions
|
|
~~~~~~~~~
|
|
.. bro:id:: Example::filter_func
|
|
|
|
:Type: :bro:type:`function` (rec: :bro:type:`Example::Info`) : :bro:type:`bool`
|
|
|
|
.. bro:id:: Example::function_without_proto
|
|
|
|
:Type: :bro:type:`function` (tag: :bro:type:`string`) : :bro:type:`string`
|
|
|