mirror of
https://github.com/zeek/zeek.git
synced 2025-10-14 20:48:21 +00:00
Integrate new Broxygen functionality into Sphinx.
Add a "broxygen" domain Sphinx extension w/ directives to allow on-the-fly documentation to be generated w/ Bro and included in files. This means all autogenerated reST docs are now done by Bro. The odd CMake/Python glue scipts which used to generate some portions are now gone. Bro and the Sphinx extension handle checking for outdated docs themselves. Parallel builds of `make doc` target should now work (mostly because I don't think there's any tasks that can be done in parallel anymore). Overall, this seems to simplify things and make the Broxygen-generated portions of the documentation visible/traceable from the main Sphinx source tree. The one odd thing still is that per-script documentation is rsync'd in to a shadow copy of the Sphinx source tree within the build dir. This is less elegant than using the new broxygen extension to make per-script docs, but rsync is faster and simpler. Simpler as in less code because it seems like, in the best case, I'd need to write a custom Sphinx Builder to be able to get that to even work.
This commit is contained in:
Jon Siwek
parent
4f6d01000a
commit
9967aea52c
47 changed files with 578 additions and 1173 deletions
|
|
@ -1,226 +0,0 @@
|
|||
# find out what BROPATH to use when executing bro
|
||||
execute_process(COMMAND ${CMAKE_BINARY_DIR}/bro-path-dev
|
||||
OUTPUT_VARIABLE BROPATH
|
||||
RESULT_VARIABLE retval
|
||||
OUTPUT_STRIP_TRAILING_WHITESPACE)
|
||||
if (NOT ${retval} EQUAL 0)
|
||||
message(FATAL_ERROR "Problem setting BROPATH")
|
||||
endif ()
|
||||
|
||||
# This macro is used to add a new makefile target for reST policy script
|
||||
# documentation that can be generated using Bro itself to parse policy scripts.
|
||||
# It's called like:
|
||||
#
|
||||
# rest_target(srcDir broInput [group])
|
||||
#
|
||||
# srcDir: the directory which contains broInput
|
||||
# broInput: the file name of a bro policy script, any path prefix of this
|
||||
# argument will be used to derive what path under scripts/ the generated
|
||||
# documentation will be placed.
|
||||
# group: optional name of group that the script documentation will belong to.
|
||||
# If this is not given, the group is automatically set to any path portion
|
||||
# of the broInput argument.
|
||||
#
|
||||
# In addition to adding the makefile target, several CMake variables are set:
|
||||
#
|
||||
# MASTER_POLICY_INDEX_TEXT: a running list of policy scripts docs that have
|
||||
# been generated so far, formatted such that it can be appended to a file
|
||||
# that ends in a Sphinx toctree directive
|
||||
# ALL_REST_OUTPUTS: a running list (the CMake list type) of all reST docs
|
||||
# that are to be generated
|
||||
# MASTER_GROUP_LIST: a running list (the CMake list type) of all script groups
|
||||
# MASTER_PKG_LIST: a running list (the CMake list type) of all script groups
|
||||
# that were defived from the path portion of the broInput argument
|
||||
# ${group}_files: a running list of files belonging to a given group, from
|
||||
# which summary text can be extracted at build time
|
||||
# ${group}_doc_names: a running list of reST style document names that can be
|
||||
# given to a :doc: role, shared indices with ${group}_files
|
||||
|
||||
macro(REST_TARGET srcDir broInput)
|
||||
set(absSrcPath ${srcDir}/${broInput})
|
||||
get_filename_component(basename ${broInput} NAME)
|
||||
string(REPLACE .bro "" basename ${basename})
|
||||
get_filename_component(extension ${broInput} EXT)
|
||||
get_filename_component(relDstDir ${broInput} PATH)
|
||||
|
||||
set(sumTextSrc ${absSrcPath})
|
||||
set(ogSourceFile ${absSrcPath})
|
||||
|
||||
if (NOT relDstDir)
|
||||
set(docName "${basename}")
|
||||
set(dstDir "${RST_OUTPUT_DIR}")
|
||||
else ()
|
||||
set(docName "${relDstDir}/${basename}")
|
||||
set(dstDir "${RST_OUTPUT_DIR}/${relDstDir}")
|
||||
endif ()
|
||||
|
||||
set(restFile "${docName}.rst")
|
||||
string(REPLACE "/" "^" restFile ${restFile})
|
||||
set(restOutput "${dstDir}/${basename}.rst")
|
||||
|
||||
set(MASTER_POLICY_INDEX_TEXT
|
||||
"${MASTER_POLICY_INDEX_TEXT}\n ${docName} <${docName}>")
|
||||
list(APPEND ALL_REST_OUTPUTS ${restOutput})
|
||||
|
||||
if (NOT "${ARGN}" STREQUAL "")
|
||||
set(group ${ARGN})
|
||||
elseif (relDstDir)
|
||||
set(group ${relDstDir}/index)
|
||||
# add package index to master package list if not already in it
|
||||
# and if a __load__.bro exists in the original script directory
|
||||
list(FIND MASTER_PKG_LIST ${relDstDir} _found)
|
||||
if (_found EQUAL -1)
|
||||
if (EXISTS ${CMAKE_SOURCE_DIR}/scripts/${relDstDir}/__load__.bro)
|
||||
list(APPEND MASTER_PKG_LIST ${relDstDir})
|
||||
endif ()
|
||||
endif ()
|
||||
else ()
|
||||
set(group "")
|
||||
endif ()
|
||||
|
||||
if (NOT "${group}" STREQUAL "")
|
||||
# add group to master group list if not already in it
|
||||
list(FIND MASTER_GROUP_LIST ${group} _found)
|
||||
if (_found EQUAL -1)
|
||||
list(APPEND MASTER_GROUP_LIST ${group})
|
||||
if (MASTER_GROUP_LIST_TEXT)
|
||||
set(MASTER_GROUP_LIST_TEXT "${MASTER_GROUP_LIST_TEXT}\n${group}")
|
||||
else ()
|
||||
set(MASTER_GROUP_LIST_TEXT "${group}")
|
||||
endif ()
|
||||
endif ()
|
||||
|
||||
list(APPEND ${group}_files ${sumTextSrc})
|
||||
list(APPEND ${group}_doc_names ${docName})
|
||||
endif ()
|
||||
|
||||
add_custom_command(OUTPUT ${restOutput}
|
||||
# delete any leftover state from previous bro runs
|
||||
COMMAND "${CMAKE_COMMAND}"
|
||||
ARGS -E remove_directory .state
|
||||
# generate the reST documentation using bro
|
||||
COMMAND BROPATH=${BROPATH}:${srcDir} BROMAGIC=${CMAKE_SOURCE_DIR}/magic/database ${CMAKE_BINARY_DIR}/src/bro
|
||||
ARGS -b -Z ${broInput} || (rm -rf .state *.log *.rst && exit 1)
|
||||
# move generated doc into a new directory tree that
|
||||
# defines the final structure of documents
|
||||
COMMAND "${CMAKE_COMMAND}"
|
||||
ARGS -E make_directory ${dstDir}
|
||||
COMMAND "${CMAKE_COMMAND}"
|
||||
ARGS -E copy ${restFile} ${restOutput}
|
||||
# copy the bro or bif script, too
|
||||
COMMAND "${CMAKE_COMMAND}"
|
||||
ARGS -E copy ${ogSourceFile} ${dstDir}
|
||||
# clean up the build directory
|
||||
COMMAND rm
|
||||
ARGS -rf .state *.log *.rst
|
||||
DEPENDS bro
|
||||
DEPENDS ${absSrcPath}
|
||||
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
|
||||
COMMENT "[Bro] Generating reST docs for ${broInput}"
|
||||
)
|
||||
|
||||
endmacro(REST_TARGET)
|
||||
|
||||
# Schedule Bro scripts for which to generate documentation.
|
||||
include(DocSourcesList.cmake)
|
||||
|
||||
# Macro for generating reST docs that are independent of any particular Bro
|
||||
# script.
|
||||
macro(INDEPENDENT_REST_TARGET reST_file)
|
||||
add_custom_command(OUTPUT ${reST_file}
|
||||
# delete any leftover state from previous bro runs
|
||||
COMMAND "${CMAKE_COMMAND}"
|
||||
ARGS -E remove_directory .state
|
||||
# generate the reST documentation using bro
|
||||
COMMAND BROPATH=${BROPATH}:${srcDir} BROMAGIC=${CMAKE_SOURCE_DIR}/magic/database ${CMAKE_BINARY_DIR}/src/bro
|
||||
ARGS -b -Z base/init-bare.bro || (rm -rf .state *.log *.rst && exit 1)
|
||||
# move generated doc into a new directory tree that
|
||||
# defines the final structure of documents
|
||||
COMMAND "${CMAKE_COMMAND}"
|
||||
ARGS -E make_directory ${dstDir}
|
||||
COMMAND "${CMAKE_COMMAND}"
|
||||
ARGS -E copy ${reST_file} ${dstDir}
|
||||
# clean up the build directory
|
||||
COMMAND rm
|
||||
ARGS -rf .state *.log *.rst
|
||||
DEPENDS bro
|
||||
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
|
||||
COMMENT "[Bro] Generating reST docs for ${reST_file}"
|
||||
)
|
||||
list(APPEND ALL_REST_OUTPUTS ${reST_file})
|
||||
endmacro(INDEPENDENT_REST_TARGET)
|
||||
|
||||
independent_rest_target(proto-analyzers.rst)
|
||||
independent_rest_target(file-analyzers.rst)
|
||||
|
||||
# create temporary list of all docs to include in the master policy/index file
|
||||
file(WRITE ${MASTER_POLICY_INDEX} "${MASTER_POLICY_INDEX_TEXT}")
|
||||
|
||||
# create the temporary list of all packages to include in the master
|
||||
# policy/packages.rst file
|
||||
set(MASTER_PKG_INDEX_TEXT "")
|
||||
foreach (pkg ${MASTER_PKG_LIST})
|
||||
set(MASTER_PKG_INDEX_TEXT
|
||||
"${MASTER_PKG_INDEX_TEXT}\n:doc:`${pkg} <${pkg}/index>`\n")
|
||||
if (EXISTS ${CMAKE_SOURCE_DIR}/scripts/${pkg}/README)
|
||||
file(STRINGS ${CMAKE_SOURCE_DIR}/scripts/${pkg}/README pkgreadme)
|
||||
foreach (line ${pkgreadme})
|
||||
set(MASTER_PKG_INDEX_TEXT "${MASTER_PKG_INDEX_TEXT}\n ${line}")
|
||||
endforeach ()
|
||||
set(MASTER_PKG_INDEX_TEXT "${MASTER_PKG_INDEX_TEXT}\n")
|
||||
endif ()
|
||||
endforeach ()
|
||||
file(WRITE ${MASTER_PACKAGE_INDEX} "${MASTER_PKG_INDEX_TEXT}")
|
||||
|
||||
# create temporary file containing list of all groups
|
||||
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/group_list
|
||||
"${MASTER_GROUP_LIST_TEXT}")
|
||||
|
||||
# create temporary files containing list of each source file in a given group
|
||||
foreach (group ${MASTER_GROUP_LIST})
|
||||
if (EXISTS ${CMAKE_CURRENT_BINARY_DIR}/${group}_files)
|
||||
file(REMOVE ${CMAKE_CURRENT_BINARY_DIR}/${group}_files)
|
||||
endif ()
|
||||
if (EXISTS ${CMAKE_CURRENT_BINARY_DIR}/${group}_doc_names)
|
||||
file(REMOVE ${CMAKE_CURRENT_BINARY_DIR}/${group}_doc_names)
|
||||
endif ()
|
||||
foreach (src ${${group}_files})
|
||||
file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/${group}_files "${src}\n")
|
||||
endforeach ()
|
||||
foreach (dname ${${group}_doc_names})
|
||||
file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/${group}_doc_names "${dname}\n")
|
||||
endforeach ()
|
||||
endforeach ()
|
||||
|
||||
# remove previously generated docs no longer scheduled for generation
|
||||
if (EXISTS ${RST_OUTPUT_DIR})
|
||||
file(GLOB_RECURSE EXISTING_REST_DOCS "${RST_OUTPUT_DIR}/*.rst")
|
||||
foreach (_doc ${EXISTING_REST_DOCS})
|
||||
list(FIND ALL_REST_OUTPUTS ${_doc} _found)
|
||||
if (_found EQUAL -1)
|
||||
file(REMOVE ${_doc})
|
||||
message(STATUS "Broxygen: remove stale reST doc: ${_doc}")
|
||||
string(REPLACE .rst .bro _brofile ${_doc})
|
||||
if (EXISTS ${_brofile})
|
||||
file(REMOVE ${_brofile})
|
||||
message(STATUS "Broxygen: remove stale bro source: ${_brofile}")
|
||||
endif ()
|
||||
endif ()
|
||||
endforeach ()
|
||||
endif ()
|
||||
|
||||
# The "restdoc" target uses Bro to parse policy scripts in order to
|
||||
# generate reST documentation from them.
|
||||
add_custom_target(restdoc
|
||||
# create symlink to the reST output directory for convenience
|
||||
COMMAND "${CMAKE_COMMAND}" -E create_symlink
|
||||
${RST_OUTPUT_DIR}
|
||||
${CMAKE_BINARY_DIR}/reST
|
||||
DEPENDS ${ALL_REST_OUTPUTS})
|
||||
|
||||
# The "restclean" target removes all generated reST documentation from the
|
||||
# build directory.
|
||||
add_custom_target(restclean
|
||||
COMMAND "${CMAKE_COMMAND}" -E remove_directory
|
||||
${RST_OUTPUT_DIR}
|
||||
VERBATIM)
|
||||
|
|
@ -1,282 +0,0 @@
|
|||
# DO NOT EDIT
|
||||
# This file is auto-generated from the genDocSourcesList.sh script.
|
||||
#
|
||||
# This is a list of Bro script sources for which to generate reST documentation.
|
||||
# It will be included inline in the CMakeLists.txt found in the same directory
|
||||
# in order to create Makefile targets that define how to generate reST from
|
||||
# a given Bro script.
|
||||
#
|
||||
# Note: any path prefix of the script (2nd argument of rest_target macro)
|
||||
# will be used to derive what path under scripts/ the generated documentation
|
||||
# will be placed.
|
||||
|
||||
set(psd ${PROJECT_SOURCE_DIR}/scripts)
|
||||
|
||||
rest_target(${CMAKE_CURRENT_SOURCE_DIR} example.bro internal)
|
||||
rest_target(${psd} base/init-default.bro internal)
|
||||
rest_target(${psd} base/init-bare.bro internal)
|
||||
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/analyzer.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/bloom-filter.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/bro.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/broxygen.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/cardinality-counter.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/const.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/event.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/file_analysis.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/input.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/logging.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_ARP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_AYIYA.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_BackDoor.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_BitTorrent.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_ConnSize.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_DCE_RPC.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_DHCP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_DNP3.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_DNS.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_FTP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_FTP.functions.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_File.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_FileExtract.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_FileExtract.functions.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_FileHash.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_Finger.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_GTPv1.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_Gnutella.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_HTTP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_HTTP.functions.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_ICMP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_IRC.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_Ident.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_InterConn.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_Login.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_Login.functions.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_MIME.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_Modbus.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_NCP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_NTP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_NetBIOS.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_NetBIOS.functions.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_NetFlow.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_PIA.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_POP3.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_RPC.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_SMB.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_SMTP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_SMTP.functions.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_SOCKS.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_SSH.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_SSL.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_SSL.functions.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_SteppingStone.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_Syslog.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_TCP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_TCP.functions.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_Teredo.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_UDP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_Unified2.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_Unified2.types.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/plugins/Bro_ZIP.events.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/reporter.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/strings.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/top-k.bif.bro)
|
||||
rest_target(${CMAKE_BINARY_DIR}/scripts base/bif/types.bif.bro)
|
||||
rest_target(${psd} base/files/extract/main.bro)
|
||||
rest_target(${psd} base/files/hash/main.bro)
|
||||
rest_target(${psd} base/files/unified2/main.bro)
|
||||
rest_target(${psd} base/frameworks/analyzer/main.bro)
|
||||
rest_target(${psd} base/frameworks/cluster/main.bro)
|
||||
rest_target(${psd} base/frameworks/cluster/nodes/manager.bro)
|
||||
rest_target(${psd} base/frameworks/cluster/nodes/proxy.bro)
|
||||
rest_target(${psd} base/frameworks/cluster/nodes/worker.bro)
|
||||
rest_target(${psd} base/frameworks/cluster/setup-connections.bro)
|
||||
rest_target(${psd} base/frameworks/communication/main.bro)
|
||||
rest_target(${psd} base/frameworks/control/main.bro)
|
||||
rest_target(${psd} base/frameworks/dpd/main.bro)
|
||||
rest_target(${psd} base/frameworks/files/main.bro)
|
||||
rest_target(${psd} base/frameworks/input/main.bro)
|
||||
rest_target(${psd} base/frameworks/input/readers/ascii.bro)
|
||||
rest_target(${psd} base/frameworks/input/readers/benchmark.bro)
|
||||
rest_target(${psd} base/frameworks/input/readers/binary.bro)
|
||||
rest_target(${psd} base/frameworks/input/readers/raw.bro)
|
||||
rest_target(${psd} base/frameworks/input/readers/sqlite.bro)
|
||||
rest_target(${psd} base/frameworks/intel/cluster.bro)
|
||||
rest_target(${psd} base/frameworks/intel/input.bro)
|
||||
rest_target(${psd} base/frameworks/intel/main.bro)
|
||||
rest_target(${psd} base/frameworks/logging/main.bro)
|
||||
rest_target(${psd} base/frameworks/logging/postprocessors/scp.bro)
|
||||
rest_target(${psd} base/frameworks/logging/postprocessors/sftp.bro)
|
||||
rest_target(${psd} base/frameworks/logging/writers/ascii.bro)
|
||||
rest_target(${psd} base/frameworks/logging/writers/dataseries.bro)
|
||||
rest_target(${psd} base/frameworks/logging/writers/elasticsearch.bro)
|
||||
rest_target(${psd} base/frameworks/logging/writers/none.bro)
|
||||
rest_target(${psd} base/frameworks/logging/writers/sqlite.bro)
|
||||
rest_target(${psd} base/frameworks/notice/actions/add-geodata.bro)
|
||||
rest_target(${psd} base/frameworks/notice/actions/drop.bro)
|
||||
rest_target(${psd} base/frameworks/notice/actions/email_admin.bro)
|
||||
rest_target(${psd} base/frameworks/notice/actions/page.bro)
|
||||
rest_target(${psd} base/frameworks/notice/actions/pp-alarms.bro)
|
||||
rest_target(${psd} base/frameworks/notice/cluster.bro)
|
||||
rest_target(${psd} base/frameworks/notice/extend-email/hostnames.bro)
|
||||
rest_target(${psd} base/frameworks/notice/main.bro)
|
||||
rest_target(${psd} base/frameworks/notice/non-cluster.bro)
|
||||
rest_target(${psd} base/frameworks/notice/weird.bro)
|
||||
rest_target(${psd} base/frameworks/packet-filter/cluster.bro)
|
||||
rest_target(${psd} base/frameworks/packet-filter/main.bro)
|
||||
rest_target(${psd} base/frameworks/packet-filter/netstats.bro)
|
||||
rest_target(${psd} base/frameworks/packet-filter/utils.bro)
|
||||
rest_target(${psd} base/frameworks/reporter/main.bro)
|
||||
rest_target(${psd} base/frameworks/signatures/main.bro)
|
||||
rest_target(${psd} base/frameworks/software/main.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/cluster.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/main.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/non-cluster.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/average.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/hll_unique.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/last.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/max.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/min.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/sample.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/std-dev.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/sum.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/topk.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/unique.bro)
|
||||
rest_target(${psd} base/frameworks/sumstats/plugins/variance.bro)
|
||||
rest_target(${psd} base/frameworks/tunnels/main.bro)
|
||||
rest_target(${psd} base/misc/find-checksum-offloading.bro)
|
||||
rest_target(${psd} base/protocols/conn/contents.bro)
|
||||
rest_target(${psd} base/protocols/conn/inactivity.bro)
|
||||
rest_target(${psd} base/protocols/conn/main.bro)
|
||||
rest_target(${psd} base/protocols/conn/polling.bro)
|
||||
rest_target(${psd} base/protocols/dhcp/consts.bro)
|
||||
rest_target(${psd} base/protocols/dhcp/main.bro)
|
||||
rest_target(${psd} base/protocols/dhcp/utils.bro)
|
||||
rest_target(${psd} base/protocols/dnp3/consts.bro)
|
||||
rest_target(${psd} base/protocols/dnp3/main.bro)
|
||||
rest_target(${psd} base/protocols/dns/consts.bro)
|
||||
rest_target(${psd} base/protocols/dns/main.bro)
|
||||
rest_target(${psd} base/protocols/ftp/files.bro)
|
||||
rest_target(${psd} base/protocols/ftp/gridftp.bro)
|
||||
rest_target(${psd} base/protocols/ftp/info.bro)
|
||||
rest_target(${psd} base/protocols/ftp/main.bro)
|
||||
rest_target(${psd} base/protocols/ftp/utils-commands.bro)
|
||||
rest_target(${psd} base/protocols/ftp/utils.bro)
|
||||
rest_target(${psd} base/protocols/http/entities.bro)
|
||||
rest_target(${psd} base/protocols/http/files.bro)
|
||||
rest_target(${psd} base/protocols/http/main.bro)
|
||||
rest_target(${psd} base/protocols/http/utils.bro)
|
||||
rest_target(${psd} base/protocols/irc/dcc-send.bro)
|
||||
rest_target(${psd} base/protocols/irc/files.bro)
|
||||
rest_target(${psd} base/protocols/irc/main.bro)
|
||||
rest_target(${psd} base/protocols/modbus/consts.bro)
|
||||
rest_target(${psd} base/protocols/modbus/main.bro)
|
||||
rest_target(${psd} base/protocols/smtp/entities.bro)
|
||||
rest_target(${psd} base/protocols/smtp/files.bro)
|
||||
rest_target(${psd} base/protocols/smtp/main.bro)
|
||||
rest_target(${psd} base/protocols/socks/consts.bro)
|
||||
rest_target(${psd} base/protocols/socks/main.bro)
|
||||
rest_target(${psd} base/protocols/ssh/main.bro)
|
||||
rest_target(${psd} base/protocols/ssl/consts.bro)
|
||||
rest_target(${psd} base/protocols/ssl/main.bro)
|
||||
rest_target(${psd} base/protocols/ssl/mozilla-ca-list.bro)
|
||||
rest_target(${psd} base/protocols/syslog/consts.bro)
|
||||
rest_target(${psd} base/protocols/syslog/main.bro)
|
||||
rest_target(${psd} base/utils/active-http.bro)
|
||||
rest_target(${psd} base/utils/addrs.bro)
|
||||
rest_target(${psd} base/utils/conn-ids.bro)
|
||||
rest_target(${psd} base/utils/dir.bro)
|
||||
rest_target(${psd} base/utils/directions-and-hosts.bro)
|
||||
rest_target(${psd} base/utils/exec.bro)
|
||||
rest_target(${psd} base/utils/files.bro)
|
||||
rest_target(${psd} base/utils/numbers.bro)
|
||||
rest_target(${psd} base/utils/paths.bro)
|
||||
rest_target(${psd} base/utils/patterns.bro)
|
||||
rest_target(${psd} base/utils/queue.bro)
|
||||
rest_target(${psd} base/utils/site.bro)
|
||||
rest_target(${psd} base/utils/strings.bro)
|
||||
rest_target(${psd} base/utils/thresholds.bro)
|
||||
rest_target(${psd} base/utils/time.bro)
|
||||
rest_target(${psd} base/utils/urls.bro)
|
||||
rest_target(${psd} policy/frameworks/communication/listen.bro)
|
||||
rest_target(${psd} policy/frameworks/control/controllee.bro)
|
||||
rest_target(${psd} policy/frameworks/control/controller.bro)
|
||||
rest_target(${psd} policy/frameworks/dpd/detect-protocols.bro)
|
||||
rest_target(${psd} policy/frameworks/dpd/packet-segment-logging.bro)
|
||||
rest_target(${psd} policy/frameworks/files/detect-MHR.bro)
|
||||
rest_target(${psd} policy/frameworks/files/hash-all-files.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/do_notice.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/seen/conn-established.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/seen/dns.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/seen/file-hashes.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/seen/file-names.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/seen/http-headers.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/seen/http-url.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/seen/smtp-url-extraction.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/seen/smtp.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/seen/ssl.bro)
|
||||
rest_target(${psd} policy/frameworks/intel/seen/where-locations.bro)
|
||||
rest_target(${psd} policy/frameworks/packet-filter/shunt.bro)
|
||||
rest_target(${psd} policy/frameworks/software/version-changes.bro)
|
||||
rest_target(${psd} policy/frameworks/software/vulnerable.bro)
|
||||
rest_target(${psd} policy/integration/barnyard2/main.bro)
|
||||
rest_target(${psd} policy/integration/barnyard2/types.bro)
|
||||
rest_target(${psd} policy/integration/collective-intel/main.bro)
|
||||
rest_target(${psd} policy/misc/app-stats/main.bro)
|
||||
rest_target(${psd} policy/misc/app-stats/plugins/facebook.bro)
|
||||
rest_target(${psd} policy/misc/app-stats/plugins/gmail.bro)
|
||||
rest_target(${psd} policy/misc/app-stats/plugins/google.bro)
|
||||
rest_target(${psd} policy/misc/app-stats/plugins/netflix.bro)
|
||||
rest_target(${psd} policy/misc/app-stats/plugins/pandora.bro)
|
||||
rest_target(${psd} policy/misc/app-stats/plugins/youtube.bro)
|
||||
rest_target(${psd} policy/misc/capture-loss.bro)
|
||||
rest_target(${psd} policy/misc/detect-traceroute/main.bro)
|
||||
rest_target(${psd} policy/misc/known-devices.bro)
|
||||
rest_target(${psd} policy/misc/load-balancing.bro)
|
||||
rest_target(${psd} policy/misc/loaded-scripts.bro)
|
||||
rest_target(${psd} policy/misc/profiling.bro)
|
||||
rest_target(${psd} policy/misc/scan.bro)
|
||||
rest_target(${psd} policy/misc/stats.bro)
|
||||
rest_target(${psd} policy/misc/trim-trace-file.bro)
|
||||
rest_target(${psd} policy/protocols/conn/known-hosts.bro)
|
||||
rest_target(${psd} policy/protocols/conn/known-services.bro)
|
||||
rest_target(${psd} policy/protocols/conn/weirds.bro)
|
||||
rest_target(${psd} policy/protocols/dhcp/known-devices-and-hostnames.bro)
|
||||
rest_target(${psd} policy/protocols/dns/auth-addl.bro)
|
||||
rest_target(${psd} policy/protocols/dns/detect-external-names.bro)
|
||||
rest_target(${psd} policy/protocols/ftp/detect-bruteforcing.bro)
|
||||
rest_target(${psd} policy/protocols/ftp/detect.bro)
|
||||
rest_target(${psd} policy/protocols/ftp/software.bro)
|
||||
rest_target(${psd} policy/protocols/http/detect-sqli.bro)
|
||||
rest_target(${psd} policy/protocols/http/detect-webapps.bro)
|
||||
rest_target(${psd} policy/protocols/http/header-names.bro)
|
||||
rest_target(${psd} policy/protocols/http/software-browser-plugins.bro)
|
||||
rest_target(${psd} policy/protocols/http/software.bro)
|
||||
rest_target(${psd} policy/protocols/http/var-extraction-cookies.bro)
|
||||
rest_target(${psd} policy/protocols/http/var-extraction-uri.bro)
|
||||
rest_target(${psd} policy/protocols/modbus/known-masters-slaves.bro)
|
||||
rest_target(${psd} policy/protocols/modbus/track-memmap.bro)
|
||||
rest_target(${psd} policy/protocols/smtp/blocklists.bro)
|
||||
rest_target(${psd} policy/protocols/smtp/detect-suspicious-orig.bro)
|
||||
rest_target(${psd} policy/protocols/smtp/entities-excerpt.bro)
|
||||
rest_target(${psd} policy/protocols/smtp/software.bro)
|
||||
rest_target(${psd} policy/protocols/ssh/detect-bruteforcing.bro)
|
||||
rest_target(${psd} policy/protocols/ssh/geo-data.bro)
|
||||
rest_target(${psd} policy/protocols/ssh/interesting-hostnames.bro)
|
||||
rest_target(${psd} policy/protocols/ssh/software.bro)
|
||||
rest_target(${psd} policy/protocols/ssl/cert-hash.bro)
|
||||
rest_target(${psd} policy/protocols/ssl/expiring-certs.bro)
|
||||
rest_target(${psd} policy/protocols/ssl/extract-certs-pem.bro)
|
||||
rest_target(${psd} policy/protocols/ssl/known-certs.bro)
|
||||
rest_target(${psd} policy/protocols/ssl/notary.bro)
|
||||
rest_target(${psd} policy/protocols/ssl/validate-certs.bro)
|
||||
rest_target(${psd} policy/tuning/defaults/extracted_file_limits.bro)
|
||||
rest_target(${psd} policy/tuning/defaults/packet-fragments.bro)
|
||||
rest_target(${psd} policy/tuning/defaults/warnings.bro)
|
||||
rest_target(${psd} policy/tuning/logs-to-elasticsearch.bro)
|
||||
rest_target(${psd} policy/tuning/track-all-assets.bro)
|
||||
rest_target(${psd} site/local-manager.bro)
|
||||
rest_target(${psd} site/local-proxy.bro)
|
||||
rest_target(${psd} site/local-worker.bro)
|
||||
rest_target(${psd} site/local.bro)
|
||||
rest_target(${psd} test-all-policy.bro)
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
This directory contains scripts and templates that can be used to automate
|
||||
the generation of Bro script documentation. Several build targets are defined
|
||||
by CMake and available in the top-level Makefile:
|
||||
|
||||
``restdoc``
|
||||
|
||||
This target uses Bro to parse policy scripts in order to generate
|
||||
reStructuredText (reST) documentation from them. The list of scripts
|
||||
for which to generate reST documentation is defined in the
|
||||
``CMakeLists.txt`` file in this directory. Script documentation is
|
||||
rebuild automatically if the policy script from which it is derived
|
||||
or the Bro binary becomes out of date
|
||||
|
||||
The resulting output from this target can be found in the CMake
|
||||
``build/`` directory inside ``reST`` (a symlink to
|
||||
``doc/scripts/rest_output``).
|
||||
|
||||
``restclean``
|
||||
|
||||
This target removes any reST documentation that has been generated so far.
|
||||
|
||||
The ``genDocSourcesList.sh`` script can be run to automatically generate
|
||||
``DocSourcesList.cmake``, which is the file CMake uses to define the list
|
||||
of documentation targets. This script should be run after adding new
|
||||
Bro script source files, and the changes commited to git.
|
||||
|
||||
If a script shouldn't have documentation generated for it, there's also a
|
||||
blacklist manifest that can be maintained in the ``genDocSourcesList.sh``
|
||||
script.
|
||||
|
||||
The blacklist can also be used if you want to define a certain grouping for
|
||||
the script's generated docs to belong to (as opposed to the automatic grouping
|
||||
the happens for script packages/directories). To do that, add the
|
||||
script's name to the blacklist, then append a ``rest_target()`` to the
|
||||
``statictext`` variable where the first argument is the source directory
|
||||
containing the policy script to document, the second argument is the file
|
||||
name of the policy script, and the third argument is the path/name of a
|
||||
pre-created reST document in the ``../`` source directory to which the
|
||||
``make doc`` process can append script documentation references. This
|
||||
pre-created reST document should also then be linked to from the TOC tree
|
||||
in ``../index.rst``.
|
||||
|
||||
See ``example.bro`` for an example of how to document a Bro script such that
|
||||
``make doc`` will be able to produce reST/HTML documentation for it.
|
||||
|
|
@ -1,985 +0,0 @@
|
|||
Types and Attributes
|
||||
====================
|
||||
|
||||
Types
|
||||
-----
|
||||
|
||||
Every value in a Bro script has a type (see below for a list of all built-in
|
||||
types). Although Bro variables have static types (meaning that their type
|
||||
is fixed), their type is inferred from the value to which they are
|
||||
initially assigned when the variable is declared without an explicit type
|
||||
name.
|
||||
|
||||
Automatic conversions happen when a binary operator has operands of
|
||||
different types. Automatic conversions are limited to converting between
|
||||
numeric types. The numeric types are ``int``, ``count``, and ``double``
|
||||
(``bool`` is not a numeric type).
|
||||
When an automatic conversion occurs, values are promoted to the "highest"
|
||||
type in the expression. In general, this promotion follows a simple
|
||||
hierarchy: ``double`` is highest, ``int`` comes next, and ``count`` is
|
||||
lowest.
|
||||
|
||||
The Bro scripting language supports the following built-in types.
|
||||
|
||||
.. bro:type:: void
|
||||
|
||||
An internal Bro type representing the absence of a return type for a
|
||||
function.
|
||||
|
||||
.. bro:type:: bool
|
||||
|
||||
Reflects a value with one of two meanings: true or false. The two
|
||||
``bool`` constants are ``T`` and ``F``.
|
||||
|
||||
The ``bool`` type supports the following operators: equality/inequality
|
||||
(``==``, ``!=``), logical and/or (``&&``, ``||``), logical
|
||||
negation (``!``), and absolute value (where ``|T|`` is 1, and ``|F|`` is 0).
|
||||
|
||||
.. bro:type:: int
|
||||
|
||||
A numeric type representing a 64-bit signed integer. An ``int`` constant
|
||||
is a string of digits preceded by a ``+`` or ``-`` sign, e.g.
|
||||
``-42`` or ``+5`` (the "+" sign is optional but see note about type
|
||||
inferencing below). An ``int`` constant can also be written in
|
||||
hexadecimal notation (in which case "0x" must be between the sign and
|
||||
the hex digits), e.g. ``-0xFF`` or ``+0xabc123``.
|
||||
|
||||
The ``int`` type supports the following operators: arithmetic
|
||||
operators (``+``, ``-``, ``*``, ``/``, ``%``), comparison operators
|
||||
(``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``), assignment operators
|
||||
(``=``, ``+=``, ``-=``), pre-increment (``++``), pre-decrement
|
||||
(``--``), and absolute value (e.g., ``|-3|`` is 3).
|
||||
|
||||
When using type inferencing use care so that the
|
||||
intended type is inferred, e.g. ``local size_difference = 0`` will
|
||||
infer :bro:type:`count`, while ``local size_difference = +0``
|
||||
will infer :bro:type:`int`.
|
||||
|
||||
.. bro:type:: count
|
||||
|
||||
A numeric type representing a 64-bit unsigned integer. A ``count``
|
||||
constant is a string of digits, e.g. ``1234`` or ``0``. A ``count``
|
||||
can also be written in hexadecimal notation (in which case "0x" must
|
||||
precede the hex digits), e.g. ``0xff`` or ``0xABC123``.
|
||||
|
||||
The ``count`` type supports the same operators as the :bro:type:`int`
|
||||
type. A unary plus or minus applied to a ``count`` results in an ``int``.
|
||||
|
||||
.. bro:type:: counter
|
||||
|
||||
An alias to :bro:type:`count`.
|
||||
|
||||
.. bro:type:: double
|
||||
|
||||
A numeric type representing a double-precision floating-point
|
||||
number. Floating-point constants are written as a string of digits
|
||||
with an optional decimal point, optional scale-factor in scientific
|
||||
notation, and optional ``+`` or ``-`` sign. Examples are ``-1234``,
|
||||
``-1234e0``, ``3.14159``, and ``.003E-23``.
|
||||
|
||||
The ``double`` type supports the following operators: arithmetic
|
||||
operators (``+``, ``-``, ``*``, ``/``), comparison operators
|
||||
(``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``), assignment operators
|
||||
(``=``, ``+=``, ``-=``), and absolute value (e.g., ``|-3.14|`` is 3.14).
|
||||
|
||||
When using type inferencing use care so that the
|
||||
intended type is inferred, e.g. ``local size_difference = 5`` will
|
||||
infer :bro:type:`count`, while ``local size_difference = 5.0``
|
||||
will infer :bro:type:`double`.
|
||||
|
||||
.. bro:type:: time
|
||||
|
||||
A temporal type representing an absolute time. There is currently
|
||||
no way to specify a ``time`` constant, but one can use the
|
||||
:bro:id:`double_to_time`, :bro:id:`current_time`, or :bro:id:`network_time`
|
||||
built-in functions to assign a value to a ``time``-typed variable.
|
||||
|
||||
Time values support the comparison operators (``==``, ``!=``, ``<``,
|
||||
``<=``, ``>``, ``>=``). A ``time`` value can be subtracted from
|
||||
another ``time`` value to produce an ``interval`` value. An ``interval``
|
||||
value can be added to, or subtracted from, a ``time`` value to produce a
|
||||
``time`` value. The absolute value of a ``time`` value is a ``double``
|
||||
with the same numeric value.
|
||||
|
||||
.. bro:type:: interval
|
||||
|
||||
A temporal type representing a relative time. An ``interval``
|
||||
constant can be written as a numeric constant followed by a time
|
||||
unit where the time unit is one of ``usec``, ``msec``, ``sec``, ``min``,
|
||||
``hr``, or ``day`` which respectively represent microseconds, milliseconds,
|
||||
seconds, minutes, hours, and days. Whitespace between the numeric
|
||||
constant and time unit is optional. Appending the letter "s" to the
|
||||
time unit in order to pluralize it is also optional (to no semantic
|
||||
effect). Examples of ``interval`` constants are ``3.5 min`` and
|
||||
``3.5mins``. An ``interval`` can also be negated, for example
|
||||
``-12 hr`` represents "twelve hours in the past".
|
||||
|
||||
Intervals support addition and subtraction. Intervals also support
|
||||
division (in which case the result is a ``double`` value), the
|
||||
comparison operators (``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``),
|
||||
and the assignment operators (``=``, ``+=``, ``-=``). Also, an
|
||||
``interval`` can be multiplied or divided by an arithmetic type
|
||||
(``count``, ``int``, or ``double``) to produce an ``interval`` value.
|
||||
The absolute value of an ``interval`` is a ``double`` value equal to the
|
||||
number of seconds in the ``interval`` (e.g., ``|-1 min|`` is 60).
|
||||
|
||||
.. bro:type:: string
|
||||
|
||||
A type used to hold character-string values which represent text.
|
||||
String constants are created by enclosing text in double quotes (")
|
||||
and the backslash character (\\) introduces escape sequences (all of
|
||||
the C-style escape sequences are supported).
|
||||
|
||||
Strings support concatenation (``+``), and assignment (``=``, ``+=``).
|
||||
Strings also support the comparison operators (``==``, ``!=``, ``<``,
|
||||
``<=``, ``>``, ``>=``). Substring searching can be performed using
|
||||
the "in" or "!in" operators (e.g., "bar" in "foobar" yields true).
|
||||
The number of characters in a string can be found by enclosing the
|
||||
string within pipe characters (e.g., ``|"abc"|`` is 3).
|
||||
|
||||
Note that Bro represents strings internally as a count and vector of
|
||||
bytes rather than a NUL-terminated byte string (although string
|
||||
constants are also automatically NUL-terminated). This is because
|
||||
network traffic can easily introduce NULs into strings either by
|
||||
nature of an application, inadvertently, or maliciously. And while
|
||||
NULs are allowed in Bro strings, when present in strings passed as
|
||||
arguments to many functions, a run-time error can occur as their
|
||||
presence likely indicates a sort of problem. In that case, the
|
||||
string will also only be represented to the user as the literal
|
||||
"<string-with-NUL>" string.
|
||||
|
||||
.. bro:type:: pattern
|
||||
|
||||
A type representing regular-expression patterns which can be used
|
||||
for fast text-searching operations. Pattern constants are created
|
||||
by enclosing text within forward slashes (/) and is the same syntax
|
||||
as the patterns supported by the `flex lexical analyzer
|
||||
<http://flex.sourceforge.net/manual/Patterns.html>`_. The speed of
|
||||
regular expression matching does not depend on the complexity or
|
||||
size of the patterns. Patterns support two types of matching, exact
|
||||
and embedded.
|
||||
|
||||
In exact matching the ``==`` equality relational operator is used
|
||||
with one :bro:type:`pattern` operand and one :bro:type:`string`
|
||||
operand (order of operands does not matter) to check whether the full
|
||||
string exactly matches the pattern. In exact matching, the ``^``
|
||||
beginning-of-line and ``$`` end-of-line anchors are redundant since
|
||||
the pattern is implicitly anchored to the beginning and end of the
|
||||
line to facilitate an exact match. For example::
|
||||
|
||||
/foo|bar/ == "foo"
|
||||
|
||||
yields true, while::
|
||||
|
||||
/foo|bar/ == "foobar"
|
||||
|
||||
yields false. The ``!=`` operator would yield the negation of ``==``.
|
||||
|
||||
In embedded matching the ``in`` operator is used with one
|
||||
:bro:type:`pattern` operand (which must be on the left-hand side) and
|
||||
one :bro:type:`string` operand, but tests whether the pattern
|
||||
appears anywhere within the given string. For example::
|
||||
|
||||
/foo|bar/ in "foobar"
|
||||
|
||||
yields true, while::
|
||||
|
||||
/^oob/ in "foobar"
|
||||
|
||||
is false since "oob" does not appear at the start of "foobar". The
|
||||
``!in`` operator would yield the negation of ``in``.
|
||||
|
||||
.. bro:type:: enum
|
||||
|
||||
A type allowing the specification of a set of related values that
|
||||
have no further structure. An example declaration:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
type color: enum { Red, White, Blue, };
|
||||
|
||||
The last comma after ``Blue`` is optional.
|
||||
|
||||
The only operations allowed on enumerations are equality comparisons
|
||||
(``==``, ``!=``) and assignment (``=``).
|
||||
Enumerations do not have associated values or ordering.
|
||||
|
||||
.. bro:type:: port
|
||||
|
||||
A type representing transport-level port numbers. Besides TCP and
|
||||
UDP ports, there is a concept of an ICMP "port" where the source
|
||||
port is the ICMP message type and the destination port the ICMP
|
||||
message code. A ``port`` constant is written as an unsigned integer
|
||||
followed by one of ``/tcp``, ``/udp``, ``/icmp``, or ``/unknown``.
|
||||
|
||||
Ports support the comparison operators (``==``, ``!=``, ``<``, ``<=``,
|
||||
``>``, ``>=``). When comparing order across transport-level protocols,
|
||||
``unknown`` < ``tcp`` < ``udp`` < ``icmp``, for example ``65535/tcp``
|
||||
is smaller than ``0/udp``.
|
||||
|
||||
Note that you can obtain the transport-level protocol type of a ``port``
|
||||
with the :bro:id:`get_port_transport_proto` built-in function, and
|
||||
the numeric value of a ``port`` with the :bro:id:`port_to_count`
|
||||
built-in function.
|
||||
|
||||
.. bro:type:: addr
|
||||
|
||||
A type representing an IP address.
|
||||
|
||||
IPv4 address constants are written in "dotted quad" format,
|
||||
``A1.A2.A3.A4``, where Ai all lie between 0 and 255.
|
||||
|
||||
IPv6 address constants are written as colon-separated hexadecimal form
|
||||
as described by :rfc:`2373` (including the mixed notation with embedded
|
||||
IPv4 addresses as dotted-quads in the lower 32 bits), but additionally
|
||||
encased in square brackets. Some examples: ``[2001:db8::1]``,
|
||||
``[::ffff:192.168.1.100]``, or
|
||||
``[aaaa:bbbb:cccc:dddd:eeee:ffff:1111:2222]``.
|
||||
|
||||
Note that IPv4-mapped IPv6 addresses (i.e., addresses with the first 80
|
||||
bits zero, the next 16 bits one, and the remaining 32 bits are the IPv4
|
||||
address) are treated internally as IPv4 addresses (for example,
|
||||
``[::ffff:192.168.1.100]`` is equal to ``192.168.1.100``).
|
||||
|
||||
Hostname constants can also be used, but since a hostname can
|
||||
correspond to multiple IP addresses, the type of such a variable is a
|
||||
:bro:type:`set` of :bro:type:`addr` elements. For example:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
local a = www.google.com;
|
||||
|
||||
Addresses can be compared for equality (``==``, ``!=``),
|
||||
and also for ordering (``<``, ``<=``, ``>``, ``>=``). The absolute value
|
||||
of an address gives the size in bits (32 for IPv4, and 128 for IPv6).
|
||||
Addresses can also be masked with ``/`` to produce a :bro:type:`subnet`:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
local a: addr = 192.168.1.100;
|
||||
local s: subnet = 192.168.0.0/16;
|
||||
if ( a/16 == s )
|
||||
print "true";
|
||||
|
||||
And checked for inclusion within a :bro:type:`subnet` using ``in``
|
||||
or ``!in``:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
local a: addr = 192.168.1.100;
|
||||
local s: subnet = 192.168.0.0/16;
|
||||
if ( a in s )
|
||||
print "true";
|
||||
|
||||
Note that you can check if a given ``addr`` is IPv4 or IPv6 using
|
||||
the :bro:id:`is_v4_addr` and :bro:id:`is_v6_addr` built-in functions.
|
||||
|
||||
.. bro:type:: subnet
|
||||
|
||||
A type representing a block of IP addresses in CIDR notation. A
|
||||
``subnet`` constant is written as an :bro:type:`addr` followed by a
|
||||
slash (/) and then the network prefix size specified as a decimal
|
||||
number. For example, ``192.168.0.0/16`` or ``[fe80::]/64``.
|
||||
|
||||
Subnets can be compared for equality (``==``, ``!=``). An
|
||||
:bro:type:`addr` can be checked for inclusion in a subnet using
|
||||
the "in" or "!in" operators.
|
||||
|
||||
.. bro:type:: any
|
||||
|
||||
Used to bypass strong typing. For example, a function can take an
|
||||
argument of type ``any`` when it may be of different types.
|
||||
|
||||
.. bro:type:: table
|
||||
|
||||
An associate array that maps from one set of values to another. The
|
||||
values being mapped are termed the *index* or *indices* and the
|
||||
result of the mapping is called the *yield*. Indexing into tables
|
||||
is very efficient, and internally it is just a single hash table
|
||||
lookup.
|
||||
|
||||
The table declaration syntax is::
|
||||
|
||||
table [ type^+ ] of type
|
||||
|
||||
where *type^+* is one or more types, separated by commas. For example:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global a: table[count] of string;
|
||||
|
||||
declares a table indexed by :bro:type:`count` values and yielding
|
||||
:bro:type:`string` values. The yield type can also be more complex:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global a: table[count] of table[addr, port] of string;
|
||||
|
||||
which declares a table indexed by :bro:type:`count` and yielding
|
||||
another :bro:type:`table` which is indexed by an :bro:type:`addr`
|
||||
and :bro:type:`port` to yield a :bro:type:`string`.
|
||||
|
||||
Initialization of tables occurs by enclosing a set of initializers within
|
||||
braces, for example:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global t: table[count] of string = {
|
||||
[11] = "eleven",
|
||||
[5] = "five",
|
||||
};
|
||||
|
||||
A table constructor (equivalent to above example) can also be used
|
||||
to create a table:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global t2: table[count] of string = table(
|
||||
[11] = "eleven",
|
||||
[5] = "five"
|
||||
);
|
||||
|
||||
Table constructors can also be explicitly named by a type, which is
|
||||
useful for when a more complex index type could otherwise be
|
||||
ambiguous:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
type MyRec: record {
|
||||
a: count &optional;
|
||||
b: count;
|
||||
};
|
||||
|
||||
type MyTable: table[MyRec] of string;
|
||||
|
||||
global t3 = MyTable([[$b=5]] = "b5", [[$b=7]] = "b7");
|
||||
|
||||
Accessing table elements is provided by enclosing index values within
|
||||
square brackets (``[]``), for example:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
print t[11];
|
||||
|
||||
And membership can be tested with ``in`` or ``!in``:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
if ( 13 in t )
|
||||
...
|
||||
|
||||
Iterate over tables with a ``for`` loop:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
local t: table[count] of string;
|
||||
for ( n in t )
|
||||
...
|
||||
|
||||
local services: table[addr, port] of string;
|
||||
for ( [a, p] in services )
|
||||
...
|
||||
|
||||
Add or overwrite individual table elements by assignment:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
t[13] = "thirteen";
|
||||
|
||||
Remove individual table elements with ``delete``:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
delete t[13];
|
||||
|
||||
Nothing happens if the element with index value ``13`` isn't present in
|
||||
the table.
|
||||
|
||||
The number of elements in a table can be obtained by placing the table
|
||||
identifier between vertical pipe characters:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
|t|
|
||||
|
||||
.. bro:type:: set
|
||||
|
||||
A set is like a :bro:type:`table`, but it is a collection of indices
|
||||
that do not map to any yield value. They are declared with the
|
||||
syntax::
|
||||
|
||||
set [ type^+ ]
|
||||
|
||||
where *type^+* is one or more types separated by commas.
|
||||
|
||||
Sets are initialized by listing elements enclosed by curly braces:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global s: set[port] = { 21/tcp, 23/tcp, 80/tcp, 443/tcp };
|
||||
global s2: set[port, string] = { [21/tcp, "ftp"], [23/tcp, "telnet"] };
|
||||
|
||||
The types are explicitly shown in the example above, but they could
|
||||
have been left to type inference.
|
||||
|
||||
A set constructor (equivalent to above example) can also be used to
|
||||
create a set:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global s3: set[port] = set(21/tcp, 23/tcp, 80/tcp, 443/tcp);
|
||||
|
||||
Set constructors can also be explicitly named by a type, which is
|
||||
useful for when a more complex index type could otherwise be
|
||||
ambiguous:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
type MyRec: record {
|
||||
a: count &optional;
|
||||
b: count;
|
||||
};
|
||||
|
||||
type MySet: set[MyRec];
|
||||
|
||||
global s4 = MySet([$b=1], [$b=2]);
|
||||
|
||||
Set membership is tested with ``in`` or ``!in``:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
if ( 21/tcp in s )
|
||||
...
|
||||
|
||||
if ( 21/tcp !in s )
|
||||
...
|
||||
|
||||
Iterate over a set with a ``for`` loop:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
local s: set[port];
|
||||
for ( p in s )
|
||||
...
|
||||
|
||||
Elements are added with ``add``:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
add s[22/tcp];
|
||||
|
||||
Nothing happens if the element with value ``22/tcp`` was already present in
|
||||
the set.
|
||||
|
||||
And removed with ``delete``:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
delete s[21/tcp];
|
||||
|
||||
Nothing happens if the element with value ``21/tcp`` isn't present in
|
||||
the set.
|
||||
|
||||
The number of elements in a set can be obtained by placing the set
|
||||
identifier between vertical pipe characters:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
|s|
|
||||
|
||||
.. bro:type:: vector
|
||||
|
||||
A vector is like a :bro:type:`table`, except it's always indexed by a
|
||||
:bro:type:`count` (and vector indexing is always zero-based). A vector
|
||||
is declared like:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global v: vector of string;
|
||||
|
||||
And can be initialized with the vector constructor:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global v: vector of string = vector("one", "two", "three");
|
||||
|
||||
Vector constructors can also be explicitly named by a type, which
|
||||
is useful for when a more complex yield type could otherwise be
|
||||
ambiguous.
|
||||
|
||||
.. code:: bro
|
||||
|
||||
type MyRec: record {
|
||||
a: count &optional;
|
||||
b: count;
|
||||
};
|
||||
|
||||
type MyVec: vector of MyRec;
|
||||
|
||||
global v2 = MyVec([$b=1], [$b=2], [$b=3]);
|
||||
|
||||
Accessing vector elements is provided by enclosing index values within
|
||||
square brackets (``[]``), for example:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
print v[2];
|
||||
|
||||
Iterate over a vector with a ``for`` loop:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
local v: vector of string;
|
||||
for ( n in v )
|
||||
...
|
||||
|
||||
An element can be added to a vector by assigning the value (a value
|
||||
that already exists at that index will be overwritten):
|
||||
|
||||
.. code:: bro
|
||||
|
||||
v[3] = "four";
|
||||
|
||||
The number of elements in a vector can be obtained by placing the vector
|
||||
identifier between vertical pipe characters:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
|v|
|
||||
|
||||
Vectors of integral types (``int`` or ``count``) support the pre-increment
|
||||
(``++``) and pre-decrement operators (``--``), which will increment or
|
||||
decrement each element in the vector.
|
||||
|
||||
Vectors of arithmetic types (``int``, ``count``, or ``double``) can be
|
||||
operands of the arithmetic operators (``+``, ``-``, ``*``, ``/``, ``%``),
|
||||
but both operands must have the same number of elements (and the modulus
|
||||
operator ``%`` cannot be used if either operand is a ``vector of double``).
|
||||
The resulting vector contains the result of the operation applied to each
|
||||
of the elements in the operand vectors.
|
||||
|
||||
Vectors of bool can be operands of the logical "and" (``&&``) and logical
|
||||
"or" (``||``) operators (both operands must have same number of elements).
|
||||
The resulting vector of bool is the logical "and" (or logical "or") of
|
||||
each element of the operand vectors.
|
||||
|
||||
.. bro:type:: record
|
||||
|
||||
A ``record`` is a collection of values. Each value has a field name
|
||||
and a type. Values do not need to have the same type and the types
|
||||
have no restrictions. An example record type definition:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
type MyRecordType: record {
|
||||
c: count;
|
||||
s: string &optional;
|
||||
};
|
||||
|
||||
Access to a record field uses the dollar sign (``$``) operator:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global r: MyRecordType;
|
||||
r$c = 13;
|
||||
|
||||
Record assignment can be done field by field or as a whole like:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
r = [$c = 13, $s = "thirteen"];
|
||||
|
||||
When assigning a whole record value, all fields that are not
|
||||
:bro:attr:`&optional` or have a :bro:attr:`&default` attribute must
|
||||
be specified.
|
||||
|
||||
To test for existence of a field that is :bro:attr:`&optional`, use the
|
||||
``?$`` operator:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
if ( r?$s )
|
||||
...
|
||||
|
||||
Records can also be created using a constructor syntax:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global r2: MyRecordType = record($c = 7);
|
||||
|
||||
And the constructor can be explicitly named by type, too, which
|
||||
is arguably more readable code:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global r3 = MyRecordType($c = 42);
|
||||
|
||||
.. bro:type:: opaque
|
||||
|
||||
A data type whose actual representation/implementation is
|
||||
intentionally hidden, but whose values may be passed to certain
|
||||
functions that can actually access the internal/hidden resources.
|
||||
Opaque types are differentiated from each other by qualifying them
|
||||
like ``opaque of md5`` or ``opaque of sha1``. Any valid identifier
|
||||
can be used as the type qualifier.
|
||||
|
||||
An example use of this type is the set of built-in functions which
|
||||
perform hashing:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
local handle: opaque of md5 = md5_hash_init();
|
||||
md5_hash_update(handle, "test");
|
||||
md5_hash_update(handle, "testing");
|
||||
print md5_hash_finish(handle);
|
||||
|
||||
Here the opaque type is used to provide a handle to a particular
|
||||
resource which is calculating an MD5 checksum incrementally over
|
||||
time, but the details of that resource aren't relevant, it's only
|
||||
necessary to have a handle as a way of identifying it and
|
||||
distinguishing it from other such resources.
|
||||
|
||||
.. bro:type:: file
|
||||
|
||||
Bro supports writing to files, but not reading from them. Files
|
||||
can be opened using either the :bro:id:`open` or :bro:id:`open_for_append`
|
||||
built-in functions, and closed using the :bro:id:`close` built-in
|
||||
function. For example, declare, open, and write to a file
|
||||
and finally close it like:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global f: file = open("myfile");
|
||||
print f, "hello, world";
|
||||
close(f);
|
||||
|
||||
Writing to files like this for logging usually isn't recommended, for better
|
||||
logging support see :doc:`/frameworks/logging`.
|
||||
|
||||
.. bro:type:: function
|
||||
|
||||
Function types in Bro are declared using::
|
||||
|
||||
function( argument* ): type
|
||||
|
||||
where *argument* is a (possibly empty) comma-separated list of
|
||||
arguments, and *type* is an optional return type. For example:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global greeting: function(name: string): string;
|
||||
|
||||
Here ``greeting`` is an identifier with a certain function type.
|
||||
The function body is not defined yet and ``greeting`` could even
|
||||
have different function body values at different times. To define
|
||||
a function including a body value, the syntax is like:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
function greeting(name: string): string
|
||||
{
|
||||
return "Hello, " + name;
|
||||
}
|
||||
|
||||
Note that in the definition above, it's not necessary for us to have
|
||||
done the first (forward) declaration of ``greeting`` as a function
|
||||
type, but when it is, the return type and argument list (including the
|
||||
name of each argument) must match exactly.
|
||||
|
||||
Function types don't need to have a name and can be assigned anonymously:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
greeting = function(name: string): string { return "Hi, " + name; };
|
||||
|
||||
And finally, the function can be called like:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
print greeting("Dave");
|
||||
|
||||
Function parameters may specify default values as long as they appear
|
||||
last in the parameter list:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global foo: function(s: string, t: string &default="abc", u: count &default=0);
|
||||
|
||||
If a function was previously declared with default parameters, the
|
||||
default expressions can be omitted when implementing the function
|
||||
body and they will still be used for function calls that lack those
|
||||
arguments.
|
||||
|
||||
.. code:: bro
|
||||
|
||||
function foo(s: string, t: string, u: count)
|
||||
{
|
||||
print s, t, u;
|
||||
}
|
||||
|
||||
And calls to the function may omit the defaults from the argument list:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
foo("test");
|
||||
|
||||
.. bro:type:: event
|
||||
|
||||
Event handlers are nearly identical in both syntax and semantics to
|
||||
a :bro:type:`function`, with the two differences being that event
|
||||
handlers have no return type since they never return a value, and
|
||||
you cannot call an event handler. Instead of directly calling an
|
||||
event handler from a script, event handler bodies are executed when
|
||||
they are invoked by one of three different methods:
|
||||
|
||||
- From the event engine
|
||||
|
||||
When the event engine detects an event for which you have
|
||||
defined a corresponding event handler, it queues an event for
|
||||
that handler. The handler is invoked as soon as the event
|
||||
engine finishes processing the current packet and flushing the
|
||||
invocation of other event handlers that were queued first.
|
||||
|
||||
- With the ``event`` statement from a script
|
||||
|
||||
Immediately queuing invocation of an event handler occurs like:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
event password_exposed(user, password);
|
||||
|
||||
This assumes that ``password_exposed`` was previously declared
|
||||
as an event handler type with compatible arguments.
|
||||
|
||||
- Via the ``schedule`` expression in a script
|
||||
|
||||
This delays the invocation of event handlers until some time in
|
||||
the future. For example:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
schedule 5 secs { password_exposed(user, password) };
|
||||
|
||||
Multiple event handler bodies can be defined for the same event handler
|
||||
identifier and the body of each will be executed in turn. Ordering
|
||||
of execution can be influenced with :bro:attr:`&priority`.
|
||||
|
||||
.. bro:type:: hook
|
||||
|
||||
A hook is another flavor of function that shares characteristics of
|
||||
both a :bro:type:`function` and a :bro:type:`event`. They are like
|
||||
events in that many handler bodies can be defined for the same hook
|
||||
identifier and the order of execution can be enforced with
|
||||
:bro:attr:`&priority`. They are more like functions in the way they
|
||||
are invoked/called, because, unlike events, their execution is
|
||||
immediate and they do not get scheduled through an event queue.
|
||||
Also, a unique feature of a hook is that a given hook handler body
|
||||
can short-circuit the execution of remaining hook handlers simply by
|
||||
exiting from the body as a result of a ``break`` statement (as
|
||||
opposed to a ``return`` or just reaching the end of the body).
|
||||
|
||||
A hook type is declared like::
|
||||
|
||||
hook( argument* )
|
||||
|
||||
where *argument* is a (possibly empty) comma-separated list of
|
||||
arguments. For example:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
global myhook: hook(s: string)
|
||||
|
||||
Here ``myhook`` is the hook type identifier and no hook handler
|
||||
bodies have been defined for it yet. To define some hook handler
|
||||
bodies the syntax looks like:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
hook myhook(s: string) &priority=10
|
||||
{
|
||||
print "priority 10 myhook handler", s;
|
||||
s = "bye";
|
||||
}
|
||||
|
||||
hook myhook(s: string)
|
||||
{
|
||||
print "break out of myhook handling", s;
|
||||
break;
|
||||
}
|
||||
|
||||
hook myhook(s: string) &priority=-5
|
||||
{
|
||||
print "not going to happen", s;
|
||||
}
|
||||
|
||||
Note that the first (forward) declaration of ``myhook`` as a hook
|
||||
type isn't strictly required. Argument types must match for all
|
||||
hook handlers and any forward declaration of a given hook.
|
||||
|
||||
To invoke immediate execution of all hook handler bodies, they
|
||||
are called similarly to a function, except preceded by the ``hook``
|
||||
keyword:
|
||||
|
||||
.. code:: bro
|
||||
|
||||
hook myhook("hi");
|
||||
|
||||
or
|
||||
|
||||
.. code:: bro
|
||||
|
||||
if ( hook myhook("hi") )
|
||||
print "all handlers ran";
|
||||
|
||||
And the output would look like::
|
||||
|
||||
priority 10 myhook handler, hi
|
||||
break out of myhook handling, bye
|
||||
|
||||
Note how the modification to arguments can be seen by remaining
|
||||
hook handlers.
|
||||
|
||||
The return value of a hook call is an implicit :bro:type:`bool`
|
||||
value with ``T`` meaning that all handlers for the hook were
|
||||
executed and ``F`` meaning that only some of the handlers may have
|
||||
executed due to one handler body exiting as a result of a ``break``
|
||||
statement.
|
||||
|
||||
Attributes
|
||||
----------
|
||||
|
||||
Attributes occur at the end of type/event declarations and change their
|
||||
behavior. The syntax is ``&key`` or ``&key=val``, e.g., ``type T:
|
||||
set[count] &read_expire=5min`` or ``event foo() &priority=-3``. The Bro
|
||||
scripting language supports the following built-in attributes.
|
||||
|
||||
.. bro:attr:: &optional
|
||||
|
||||
Allows a record field to be missing. For example the type ``record {
|
||||
a: int, b: port &optional }`` could be instantiated both as
|
||||
singleton ``[$a=127.0.0.1]`` or pair ``[$a=127.0.0.1, $b=80/tcp]``.
|
||||
|
||||
.. bro:attr:: &default
|
||||
|
||||
Uses a default value for a record field, a function/hook/event
|
||||
parameter, or container elements. For example, ``table[int] of
|
||||
string &default="foo" }`` would create a table that returns the
|
||||
:bro:type:`string` ``"foo"`` for any non-existing index.
|
||||
|
||||
.. bro:attr:: &redef
|
||||
|
||||
Allows for redefinition of initial object values. This is typically
|
||||
used with constants, for example, ``const clever = T &redef;`` would
|
||||
allow the constant to be redefined at some later point during script
|
||||
execution.
|
||||
|
||||
.. bro:attr:: &rotate_interval
|
||||
|
||||
Rotates a file after a specified interval.
|
||||
|
||||
.. bro:attr:: &rotate_size
|
||||
|
||||
Rotates a file after it has reached a given size in bytes.
|
||||
|
||||
.. bro:attr:: &add_func
|
||||
|
||||
Can be applied to an identifier with &redef to specify a function to
|
||||
be called any time a "redef <id> += ..." declaration is parsed. The
|
||||
function takes two arguments of the same type as the identifier, the first
|
||||
being the old value of the variable and the second being the new
|
||||
value given after the "+=" operator in the "redef" declaration. The
|
||||
return value of the function will be the actual new value of the
|
||||
variable after the "redef" declaration is parsed.
|
||||
|
||||
.. bro:attr:: &delete_func
|
||||
|
||||
Same as &add_func, except for "redef" declarations that use the "-="
|
||||
operator.
|
||||
|
||||
.. bro:attr:: &expire_func
|
||||
|
||||
Called right before a container element expires. The function's
|
||||
first parameter is of the same type of the container and the second
|
||||
parameter the same type of the container's index. The return
|
||||
value is a :bro:type:`interval` indicating the amount of additional
|
||||
time to wait before expiring the container element at the given
|
||||
index (which will trigger another execution of this function).
|
||||
|
||||
.. bro:attr:: &read_expire
|
||||
|
||||
Specifies a read expiration timeout for container elements. That is,
|
||||
the element expires after the given amount of time since the last
|
||||
time it has been read. Note that a write also counts as a read.
|
||||
|
||||
.. bro:attr:: &write_expire
|
||||
|
||||
Specifies a write expiration timeout for container elements. That
|
||||
is, the element expires after the given amount of time since the
|
||||
last time it has been written.
|
||||
|
||||
.. bro:attr:: &create_expire
|
||||
|
||||
Specifies a creation expiration timeout for container elements. That
|
||||
is, the element expires after the given amount of time since it has
|
||||
been inserted into the container, regardless of any reads or writes.
|
||||
|
||||
.. bro:attr:: &persistent
|
||||
|
||||
Makes a variable persistent, i.e., its value is writen to disk (per
|
||||
default at shutdown time).
|
||||
|
||||
.. bro:attr:: &synchronized
|
||||
|
||||
Synchronizes variable accesses across nodes. The value of a
|
||||
``&synchronized`` variable is automatically propagated to all peers
|
||||
when it changes.
|
||||
|
||||
.. bro:attr:: &encrypt
|
||||
|
||||
Encrypts files right before writing them to disk.
|
||||
|
||||
.. TODO: needs to be documented in more detail.
|
||||
|
||||
.. bro:attr:: &raw_output
|
||||
|
||||
Opens a file in raw mode, i.e., non-ASCII characters are not
|
||||
escaped.
|
||||
|
||||
.. bro:attr:: &mergeable
|
||||
|
||||
Prefers set union to assignment for synchronized state. This
|
||||
attribute is used in conjunction with :bro:attr:`&synchronized`
|
||||
container types: when the same container is updated at two peers
|
||||
with different value, the propagation of the state causes a race
|
||||
condition, where the last update succeeds. This can cause
|
||||
inconsistencies and can be avoided by unifying the two sets, rather
|
||||
than merely overwriting the old value.
|
||||
|
||||
.. bro:attr:: &priority
|
||||
|
||||
Specifies the execution priority of an event handler. Higher values
|
||||
are executed before lower ones. The default value is 0.
|
||||
|
||||
.. bro:attr:: &group
|
||||
|
||||
Groups event handlers such that those in the same group can be
|
||||
jointly activated or deactivated.
|
||||
|
||||
.. bro:attr:: &log
|
||||
|
||||
Writes a record field to the associated log stream.
|
||||
|
||||
.. bro:attr:: &error_handler
|
||||
|
||||
Internally set on the events that are associated with the reporter
|
||||
framework: :bro:id:`reporter_info`, :bro:id:`reporter_warning`, and
|
||||
:bro:id:`reporter_error`. It prevents any handlers of those events
|
||||
from being able to generate reporter messages that go through any of
|
||||
those events (i.e., it prevents an infinite event recursion). Instead,
|
||||
such nested reporter messages are output to stderr.
|
||||
|
||||
.. bro:attr:: &type_column
|
||||
|
||||
Used by the input framework. It can be used on columns of type
|
||||
:bro:type:`port` and specifies the name of an additional column in
|
||||
the input file which specifies the protocol of the port (tcp/udp/icmp).
|
||||
|
|
@ -1,229 +0,0 @@
|
|||
##! This is an example script that demonstrates documentation features.
|
||||
##! 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.
|
||||
##!
|
||||
##! There's also a custom role to reference any identifier node in
|
||||
##! the Bro Sphinx domain that's good for "see alsos", e.g.
|
||||
##!
|
||||
##! See also: :bro:see:`Example::a_var`, :bro:see:`Example::ONE`,
|
||||
##! :bro:see:`SSH::Info`
|
||||
##!
|
||||
##! And a custom directive does the equivalent references:
|
||||
##!
|
||||
##! .. bro:see:: Example::a_var Example::ONE SSH::Info
|
||||
|
||||
# Comments that use a single pound sign (#) are not significant to
|
||||
# a script's auto-generated documentation, but ones that use a
|
||||
# double pound sign (##) do matter. In some cases, like record
|
||||
# field comments, it's necessary to disambiguate the field with
|
||||
# which a comment associates: e.g. "##<" can be used on the same line
|
||||
# as a field to signify the comment relates to it and not the
|
||||
# following field. "##<" can also be used more generally in any
|
||||
# variable declarations to associate with the last-declared identifier.
|
||||
#
|
||||
# Generally, the auto-doc comments (##) are associated with the
|
||||
# next declaration/identifier found in the script, but the doc framework
|
||||
# will track/render identifiers regardless of whether they have any
|
||||
# of these special comments associated with them.
|
||||
#
|
||||
# The first sentence contained within the "##"-stylized comments for
|
||||
# a given identifier is special in that it will be used as summary
|
||||
# text in a table containing all such identifiers and short summaries.
|
||||
# If there are no sentences (text terminated with '.'), then everything
|
||||
# in the "##"-stylized comments up until the first empty comment
|
||||
# is taken as the summary text for a given identifier.
|
||||
|
||||
# @load directives are self-documenting
|
||||
@load frameworks/software/vulnerable
|
||||
|
||||
# "module" statements are self-documenting
|
||||
module Example;
|
||||
|
||||
# redefinitions of "capture_filters" are self-documenting and
|
||||
# go into the generated documentation's "Packet Filter" section
|
||||
redef capture_filters += {
|
||||
["ssl"] = "tcp port 443",
|
||||
["nntps"] = "tcp port 562",
|
||||
};
|
||||
|
||||
global example_ports = {
|
||||
443/tcp, 562/tcp,
|
||||
} &redef;
|
||||
|
||||
|
||||
event bro_init()
|
||||
{
|
||||
Analyzer::register_for_ports(Analyzer::ANALYZER_SSL, example_ports);
|
||||
}
|
||||
|
||||
# redefinitions of "Notice::Type" are self-documenting, but
|
||||
# more information can be supplied in two different ways
|
||||
redef enum Notice::Type += {
|
||||
## any number of this type of comment
|
||||
## will document "Notice_One"
|
||||
Notice_One,
|
||||
Notice_Two, ##< any number of this type of comment
|
||||
##< will document "Notice_Two"
|
||||
Notice_Three,
|
||||
Notice_Four,
|
||||
};
|
||||
|
||||
# Redef'ing the ID enumeration for logging streams is automatically tracked.
|
||||
# Comments of the "##" form can be use to further document it, but it's
|
||||
# better to do all documentation related to logging in the summary section
|
||||
# as is shown above.
|
||||
redef enum Log::ID += { LOG };
|
||||
|
||||
# Anything declared in the export section will show up in the rendered
|
||||
# documentation's "public interface" section
|
||||
|
||||
export {
|
||||
|
||||
# these headings don't mean anything special to the
|
||||
# doc framework right now, I'm just including them
|
||||
# to make it more clear to the reader how the doc
|
||||
# framework will actually categorize a script's identifiers
|
||||
|
||||
############## types ################
|
||||
|
||||
# Note that I'm just mixing the "##" and "##<"
|
||||
# types of comments in the following declarations
|
||||
# as a demonstration. Normally, it would be good style
|
||||
# to pick one and be consistent.
|
||||
|
||||
## documentation for "SimpleEnum"
|
||||
## goes here.
|
||||
type SimpleEnum: enum {
|
||||
## and more specific info for "ONE"
|
||||
## can span multiple lines
|
||||
ONE,
|
||||
TWO, ##< or more info like this for "TWO"
|
||||
##< can span multiple lines
|
||||
THREE,
|
||||
};
|
||||
|
||||
## document the "SimpleEnum" redef here
|
||||
redef enum SimpleEnum += {
|
||||
FOUR, ##< and some documentation for "FOUR"
|
||||
## also "FIVE" for good measure
|
||||
FIVE
|
||||
};
|
||||
|
||||
## general documentation for a type "SimpleRecord"
|
||||
## goes here.
|
||||
type SimpleRecord: record {
|
||||
## counts something
|
||||
field1: count;
|
||||
field2: bool; ##< toggles something
|
||||
};
|
||||
|
||||
## document the record extension redef here
|
||||
redef record SimpleRecord += {
|
||||
## document the extending field here
|
||||
field_ext: string &optional; ##< (or here)
|
||||
};
|
||||
|
||||
## general documentation for a type "ComplexRecord" goes here
|
||||
type ComplexRecord: record {
|
||||
field1: count; ##< counts something
|
||||
field2: bool; ##< toggles something
|
||||
field3: SimpleRecord;
|
||||
msg: string &default="blah"; ##< attributes are self-documenting
|
||||
} &redef;
|
||||
|
||||
## An example record to be used with a logging stream.
|
||||
type Info: record {
|
||||
ts: time &log;
|
||||
uid: string &log;
|
||||
status: count &log &optional;
|
||||
};
|
||||
|
||||
############## options ################
|
||||
# right now, I'm just defining an option as
|
||||
# any const with &redef (something that can
|
||||
# change at parse time, but not at run time.
|
||||
|
||||
## add documentation for "an_option" here
|
||||
const an_option: set[addr, addr, string] &redef;
|
||||
|
||||
# default initialization will be self-documenting
|
||||
const option_with_init = 0.01 secs &redef; ##< More docs can be added here.
|
||||
|
||||
############## state variables ############
|
||||
# right now, I'm defining this as any global
|
||||
# that's not a function/event. doesn't matter
|
||||
# if &redef attribute is present
|
||||
|
||||
## put some documentation for "a_var" here
|
||||
global a_var: bool;
|
||||
|
||||
# attributes are self-documenting
|
||||
global var_with_attr: count &persistent;
|
||||
|
||||
# it's fine if the type is inferred, that information is self-documenting
|
||||
global var_without_explicit_type = "this works";
|
||||
|
||||
## The first.sentence for the summary text ends here. And this second
|
||||
## sentence doesn't show in the short description.
|
||||
global dummy: string;
|
||||
|
||||
############## functions/events ############
|
||||
|
||||
## 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.
|
||||
##
|
||||
## tag: function arguments can be described
|
||||
## like this
|
||||
## msg: another param
|
||||
##
|
||||
## Returns: describe the return type here
|
||||
global a_function: function(tag: string, msg: string): string;
|
||||
|
||||
## Summarize "an_event" here.
|
||||
## Give more details about "an_event" here.
|
||||
## Example::an_event should not be confused as a parameter.
|
||||
## name: describe the argument here
|
||||
global an_event: event(name: string);
|
||||
|
||||
## This is a declaration of an example event that can be used in
|
||||
## logging streams and is raised once for each log entry.
|
||||
global log_example: event(rec: Info);
|
||||
}
|
||||
|
||||
function filter_func(rec: Info): bool
|
||||
{
|
||||
return T;
|
||||
}
|
||||
|
||||
# this function is documented in the "private interface" section
|
||||
# of generated documentation and any "##"-stylized comments would also
|
||||
# be rendered there
|
||||
function function_without_proto(tag: string): string
|
||||
{
|
||||
return "blah";
|
||||
}
|
||||
|
||||
# this record type is documented in the "private interface" section
|
||||
# of generated documentation and any "##"-stylized comments would also
|
||||
# be rendered there
|
||||
type PrivateRecord: record {
|
||||
field1: bool;
|
||||
field2: count;
|
||||
};
|
||||
|
||||
event bro_init()
|
||||
{
|
||||
Log::create_stream(Example::LOG, [$columns=Info, $ev=log_example]);
|
||||
Log::add_filter(Example::LOG, [
|
||||
$name="example-filter",
|
||||
$path="example-filter",
|
||||
$pred=filter_func,
|
||||
$exclude=set("ts")
|
||||
]);
|
||||
}
|
||||
|
|
@ -1,291 +0,0 @@
|
|||
.. 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.
|
||||
|
||||
: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.
|
||||
================================================= =============================================================
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
# ./genDocSourcesList.sh [output file]
|
||||
#
|
||||
# Run this script to a generate file that's used to tell CMake about all the
|
||||
# possible scripts for which reST documentation can be created.
|
||||
#
|
||||
# The optional argument can be used to avoid overwriting the file CMake uses
|
||||
# by default.
|
||||
#
|
||||
# Specific scripts can be blacklisted below when e.g. they currently aren't
|
||||
# parseable or they just aren't meant to be documented.
|
||||
|
||||
export LC_ALL=C # Make sorting stable.
|
||||
|
||||
blacklist ()
|
||||
{
|
||||
if [[ "$blacklist" == "" ]]; then
|
||||
blacklist="$1"
|
||||
else
|
||||
blacklist="$blacklist|$1"
|
||||
fi
|
||||
}
|
||||
|
||||
# files passed into this function are meant to be temporary workarounds
|
||||
# because they're not finished or otherwise can't be loaded for some reason
|
||||
tmp_blacklist ()
|
||||
{
|
||||
echo "Warning: temporarily blacklisted files named '$1'" 1>&2
|
||||
blacklist $1
|
||||
}
|
||||
|
||||
blacklist __load__.bro
|
||||
blacklist test-all.bro
|
||||
blacklist all.bro
|
||||
blacklist init-default.bro
|
||||
blacklist init-bare.bro
|
||||
|
||||
statictext="\
|
||||
# DO NOT EDIT
|
||||
# This file is auto-generated from the "genDocSourcesList.sh" script.
|
||||
#
|
||||
# This is a list of Bro script sources for which to generate reST documentation.
|
||||
# It will be included inline in the CMakeLists.txt found in the same directory
|
||||
# in order to create Makefile targets that define how to generate reST from
|
||||
# a given Bro script.
|
||||
#
|
||||
# Note: any path prefix of the script (2nd argument of rest_target macro)
|
||||
# will be used to derive what path under scripts/ the generated documentation
|
||||
# will be placed.
|
||||
|
||||
set(psd \${PROJECT_SOURCE_DIR}/scripts)
|
||||
|
||||
rest_target(\${CMAKE_CURRENT_SOURCE_DIR} example.bro internal)
|
||||
rest_target(\${psd} base/init-default.bro internal)
|
||||
rest_target(\${psd} base/init-bare.bro internal)
|
||||
"
|
||||
|
||||
if [[ $# -ge 1 ]]; then
|
||||
outfile=$1
|
||||
else
|
||||
outfile=DocSourcesList.cmake
|
||||
fi
|
||||
|
||||
thisdir="$( cd "$( dirname "$0" )" && pwd )"
|
||||
sourcedir=${thisdir}/../..
|
||||
|
||||
echo "$statictext" > $outfile
|
||||
|
||||
bifs=`( cd ${sourcedir}/build/scripts/base && find . -name \*\.bif.bro | sort )`
|
||||
|
||||
for file in $bifs
|
||||
do
|
||||
f=${file:2}
|
||||
echo "rest_target(\${CMAKE_BINARY_DIR}/scripts base/$f)" >> $outfile
|
||||
done
|
||||
|
||||
scriptfiles=`( cd ${sourcedir}/scripts && find . -name \*\.bro | sort )`
|
||||
|
||||
for file in $scriptfiles
|
||||
do
|
||||
f=${file:2}
|
||||
if [[ ! $f =~ $blacklist ]]; then
|
||||
echo "rest_target(\${psd} $f)" >> $outfile
|
||||
fi
|
||||
done
|
||||
|
|
@ -1,21 +0,0 @@
|
|||
.. This is a stub doc to which broxygen appends during the build process
|
||||
|
||||
================
|
||||
Script Reference
|
||||
================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
packages
|
||||
proto-analyzers
|
||||
file-analyzers
|
||||
notices
|
||||
builtins
|
||||
Built-in Functions (BIFs) <base/bif/index>
|
||||
internal
|
||||
scripts
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
.. This is a stub doc to which broxygen appends during the build process
|
||||
|
||||
Internal Scripts
|
||||
================
|
||||
|
||||
|
|
@ -1,14 +0,0 @@
|
|||
.. This is a stub doc to which broxygen appends during the build process
|
||||
|
||||
.. _script-packages:
|
||||
|
||||
Bro Script Packages
|
||||
===================
|
||||
|
||||
Bro has the following script packages (e.g. collections of related scripts in
|
||||
a common directory). If the package directory contains a ``__load__.bro``
|
||||
script, it supports being loaded in mass as a whole directory for convenience.
|
||||
|
||||
Packages/scripts in the ``base/`` directory are all loaded by default, while
|
||||
ones in ``policy/`` provide functionality and customization options that are
|
||||
more appropriate for users to decide whether they'd like to load it or not.
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
.. This is a stub doc to which broxygen appends during the build process
|
||||
|
||||
===============
|
||||
All Bro Scripts
|
||||
===============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
Loading…
Add table
Add a link
Reference in a new issue