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

Changes to make generated script docs understand new policy/ hierarchy.

Browse source 
Added an arg to the search_for_files() util function that can return
the subpath of BROPATH's policy/ dir in which the loaded file is found.
This subpath is then used in both the the reST file's document title
(so that script's named e.g. "base.bro" actually have some context) and
in figuring out how to interlink with other generated docs of other
scripts that are found in @load directives.

I still need to overhaul things so the loading of "packages" is
documented in a meaningful way and that the CMake targets are able
to generate indexes for packages.
This commit is contained in:
Jon Siwek 2011-06-30 11:37:15 -05:00
parent f307a3f408
commit fe5f4b8e53
12 changed files with 262 additions and 148 deletions
Download patch file Download diff file Expand all files Collapse all files

196
doc/scripts/CMakeLists.txt
View file

@ -94,7 +94,7 @@ macro(REST_TARGET srcDir broInput)
set(group "")
endif ()
if (${group} STREQUAL "default" OR ${group} STREQUAL "bifs")
if ("${group}" STREQUAL "default" OR "${group}" STREQUAL "bifs")
set(BRO_ARGS --doc-scripts --exec '')
else ()
set(BRO_ARGS --doc-scripts ${broInput})
@ -127,117 +127,127 @@ macro(REST_TARGET srcDir broInput)
endmacro(REST_TARGET)
# Schedule Bro scripts for which to generate documentation.
# Note: the script may be located in a subdirectory off of one of the main
# directories in BROPATH. In that case, just list the script as 'foo/bar.bro'
rest_target(${CMAKE_CURRENT_SOURCE_DIR} example.bro internal)
#
# Note: any path prefix of the script (2nd argument of rest_target macro)
# will be used to derive what path under policy/ the generated documentation
# will be placed.
rest_target(${POLICY_SRC_DIR} conn.bro user)
rest_target(${POLICY_SRC_DIR} conn/base.bro user)
rest_target(${POLICY_SRC_DIR} conn/contents.bro user)
rest_target(${CMAKE_CURRENT_SOURCE_DIR} example.bro)
rest_target(${POLICY_SRC_DIR} dns.bro policy/dns-index)
rest_target(${POLICY_SRC_DIR} dns/auth-addl.bro policy/dns-index)
rest_target(${POLICY_SRC_DIR} dns/base.bro policy/dns-index)
rest_target(${POLICY_SRC_DIR} dns/consts.bro policy/dns-index)
rest_target(${POLICY_SRC_DIR} dns/detect.bro policy/dns-index)
rest_target(${POLICY_SRC_DIR} dns/passive-replication.bro policy/dns-index)
rest_target(${CMAKE_BINARY_DIR}/src bro.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src const.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src event.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src logging.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src strings.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src types.bif.bro)
# TODO: these don't currently work due to something that looks like a
# circular dependency. They'll also change to the 'default' group once
# loaded from bro.init.
#rest_target(${POLICY_SRC_DIR} dpd.bro policy/dpd-index)
#rest_target(${POLICY_SRC_DIR} dpd/base.bro policy/dpd-index)
#rest_target(${POLICY_SRC_DIR} dpd/dyn-disable.bro policy/dpd-index)
#rest_target(${POLICY_SRC_DIR} dpd/packet-segment-logging.bro policy/dpd-index)
set(psd ${POLICY_SRC_DIR})
rest_target(${POLICY_SRC_DIR} ftp.bro policy/ftp-index)
rest_target(${POLICY_SRC_DIR} ftp/base.bro policy/ftp-index)
rest_target(${POLICY_SRC_DIR} ftp/detect.bro policy/ftp-index)
rest_target(${POLICY_SRC_DIR} ftp/file-extract.bro policy/ftp-index)
rest_target(${POLICY_SRC_DIR} ftp/software.bro policy/ftp-index)
rest_target(${POLICY_SRC_DIR} ftp/utils-commands.bro policy/ftp-index)
rest_target(${psd} bro.init)
rest_target(${psd} site.bro)
rest_target(${POLICY_SRC_DIR} functions.bro user)
rest_target(${psd} detectors/http-MHR.bro)
# TODO: hot.conn.bro currently won't load because hot.bro doesn't exist
#rest_target(${POLICY_SRC_DIR} hot.conn.bro user)
rest_target(${psd} frameworks/communication/base.bro)
rest_target(${psd} frameworks/communication/listen-clear.bro)
rest_target(${psd} frameworks/communication/listen-ssl.bro)
rest_target(${POLICY_SRC_DIR} http.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/base-extended.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/base.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/detect-intel.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/detect-sqli.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/detect-webapps.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/file-extract.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/file-hash.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/file-ident.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/headers.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/software.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/utils.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/var-extraction-cookies.bro policy/http-index)
rest_target(${POLICY_SRC_DIR} http/var-extraction-uri.bro policy/http-index)
rest_target(${psd} frameworks/dpd/base.bro)
rest_target(${psd} frameworks/dpd/dyn-disable.bro)
rest_target(${psd} frameworks/dpd/packet-segment-logging.bro)
rest_target(${POLICY_SRC_DIR} irc.bro policy/irc-index)
rest_target(${POLICY_SRC_DIR} irc/base.bro policy/irc-index)
rest_target(${POLICY_SRC_DIR} irc/dcc-send.bro policy/irc-index)
rest_target(${psd} frameworks/intel/base.bro)
rest_target(${POLICY_SRC_DIR} known-services.bro user)
rest_target(${POLICY_SRC_DIR} known-hosts.bro user)
rest_target(${psd} frameworks/logging/base.bro)
rest_target(${psd} frameworks/logging/plugins/ascii.bro)
rest_target(${POLICY_SRC_DIR} metrics.bro policy/metrics-index)
rest_target(${POLICY_SRC_DIR} metrics/base.bro policy/metrics-index)
rest_target(${POLICY_SRC_DIR} metrics/conn-example.bro policy/metrics-index)
rest_target(${POLICY_SRC_DIR} metrics/http-example.bro policy/metrics-index)
rest_target(${psd} frameworks/metrics/base.bro)
rest_target(${psd} frameworks/metrics/conn-example.bro)
rest_target(${psd} frameworks/metrics/http-example.bro)
rest_target(${POLICY_SRC_DIR} mime.bro policy/mime-index)
rest_target(${POLICY_SRC_DIR} mime/base.bro policy/mime-index)
rest_target(${POLICY_SRC_DIR} mime/file-extract.bro policy/mime-index)
rest_target(${POLICY_SRC_DIR} mime/file-hash.bro policy/mime-index)
rest_target(${POLICY_SRC_DIR} mime/file-ident.bro policy/mime-index)
rest_target(${psd} frameworks/notice/action-filters.bro)
rest_target(${psd} frameworks/notice/base.bro)
rest_target(${psd} frameworks/notice/weird.bro)
rest_target(${POLICY_SRC_DIR} notice-action-filters.bro user)
rest_target(${POLICY_SRC_DIR} notice.bro user)
rest_target(${POLICY_SRC_DIR} site.bro user)
rest_target(${psd} frameworks/packet-filter/base.bro)
rest_target(${psd} frameworks/packet-filter/netstats.bro)
rest_target(${POLICY_SRC_DIR} signatures.bro policy/sig-index)
rest_target(${POLICY_SRC_DIR} signatures/base.bro policy/sig-index)
rest_target(${psd} frameworks/signatures/base.bro)
rest_target(${POLICY_SRC_DIR} smtp.bro policy/smtp-index)
rest_target(${POLICY_SRC_DIR} smtp/base-extended.bro policy/smtp-index)
rest_target(${POLICY_SRC_DIR} smtp/base.bro policy/smtp-index)
rest_target(${POLICY_SRC_DIR} smtp/detect.bro policy/smtp-index)
rest_target(${POLICY_SRC_DIR} smtp/software.bro policy/smtp-index)
rest_target(${POLICY_SRC_DIR} smtp/utils.bro policy/smtp-index)
rest_target(${POLICY_SRC_DIR} smtp/webmail-ident.bro policy/smtp-index)
rest_target(${psd} frameworks/software/base.bro)
rest_target(${psd} frameworks/software/vulnerable.bro)
rest_target(${POLICY_SRC_DIR} software.bro policy/software-index)
rest_target(${POLICY_SRC_DIR} software/base.bro policy/software-index)
rest_target(${POLICY_SRC_DIR} software/vulnerable.bro policy/software-index)
rest_target(${psd} integration/barnyard2/base.bro)
rest_target(${psd} integration/barnyard2/event.bro)
rest_target(${psd} integration/barnyard2/types.bro)
rest_target(${POLICY_SRC_DIR} ssh.bro policy/ssh-index)
rest_target(${POLICY_SRC_DIR} ssh/base.bro policy/ssh-index)
rest_target(${POLICY_SRC_DIR} ssh/software.bro policy/ssh-index)
rest_target(${psd} protocols/conn/base.bro)
rest_target(${psd} protocols/conn/contents.bro)
rest_target(${psd} protocols/conn/inactivity.bro)
rest_target(${psd} protocols/conn/known-hosts.bro)
rest_target(${psd} protocols/conn/known-services.bro)
rest_target(${POLICY_SRC_DIR} ssl-ciphers.bro policy/ssl-index)
rest_target(${POLICY_SRC_DIR} ssl-errors.bro policy/ssl-index)
rest_target(${POLICY_SRC_DIR} ssl.bro policy/ssl-index)
rest_target(${psd} protocols/dns/auth-addl.bro)
rest_target(${psd} protocols/dns/base.bro)
rest_target(${psd} protocols/dns/consts.bro)
rest_target(${psd} protocols/dns/detect.bro)
rest_target(${POLICY_SRC_DIR} utils/pattern.bro user)
rest_target(${POLICY_SRC_DIR} weird.bro user)
rest_target(${psd} protocols/ftp/base.bro)
rest_target(${psd} protocols/ftp/detect.bro)
rest_target(${psd} protocols/ftp/file-extract.bro)
rest_target(${psd} protocols/ftp/software.bro)
rest_target(${psd} protocols/ftp/utils-commands.bro)
# Finding out what scripts bro will generate documentation for by default
# can be done like: `bro --doc-scripts --exec ""`
rest_target(${POLICY_SRC_DIR} bro.init default)
rest_target(${POLICY_SRC_DIR} logging-ascii.bro default)
rest_target(${POLICY_SRC_DIR} logging.bro default)
rest_target(${POLICY_SRC_DIR} pcap.bro default)
rest_target(${POLICY_SRC_DIR} server-ports.bro default)
rest_target(${CMAKE_BINARY_DIR}/src bro.bif.bro bifs)
rest_target(${CMAKE_BINARY_DIR}/src const.bif.bro bifs)
rest_target(${CMAKE_BINARY_DIR}/src event.bif.bro bifs)
rest_target(${CMAKE_BINARY_DIR}/src logging.bif.bro bifs)
rest_target(${CMAKE_BINARY_DIR}/src strings.bif.bro bifs)
rest_target(${CMAKE_BINARY_DIR}/src types.bif.bro bifs)
rest_target(${psd} protocols/http/base.bro)
rest_target(${psd} protocols/http/detect-intel.bro)
rest_target(${psd} protocols/http/detect-sqli.bro)
rest_target(${psd} protocols/http/detect-webapps.bro)
rest_target(${psd} protocols/http/file-extract.bro)
rest_target(${psd} protocols/http/file-hash.bro)
rest_target(${psd} protocols/http/file-ident.bro)
rest_target(${psd} protocols/http/headers.bro)
rest_target(${psd} protocols/http/software.bro)
rest_target(${psd} protocols/http/utils.bro)
rest_target(${psd} protocols/http/var-extraction-cookies.bro)
rest_target(${psd} protocols/http/var-extraction-uri.bro)
rest_target(${psd} protocols/irc/base.bro)
rest_target(${psd} protocols/irc/dcc-send.bro)
rest_target(${psd} protocols/mime/base.bro)
rest_target(${psd} protocols/mime/file-extract.bro)
rest_target(${psd} protocols/mime/file-hash.bro)
rest_target(${psd} protocols/mime/file-ident.bro)
rest_target(${psd} protocols/smtp/base.bro)
rest_target(${psd} protocols/smtp/detect.bro)
rest_target(${psd} protocols/smtp/software.bro)
rest_target(${psd} protocols/ssh/base.bro)
rest_target(${psd} protocols/ssh/software.bro)
#rest_target(${psd} protocols/ssl/base.bro)
#rest_target(${psd} protocols/ssl/ssl-ciphers.bro)
#rest_target(${psd} protocols/ssl/ssl-errors.bro)
#rest_target(${psd} protocols/ssl/ssl.bro)
#rest_target(${psd} protocols/ssl/validate.bro)
rest_target(${psd} protocols/syslog/base.bro)
rest_target(${psd} protocols/syslog/consts.bro)
rest_target(${psd} tuning/defaults/packet-fragments.bro)
rest_target(${psd} tuning/defaults/remove-high-volume-notices.bro)
rest_target(${psd} tuning/track-all-assets.bro)
rest_target(${psd} utils/addrs.bro)
rest_target(${psd} utils/conn_ids.bro)
rest_target(${psd} utils/directions-and-hosts.bro)
rest_target(${psd} utils/files.bro)
rest_target(${psd} utils/numbers.bro)
rest_target(${psd} utils/paths.bro)
rest_target(${psd} utils/pattern.bro)
rest_target(${psd} utils/strings.bro)
rest_target(${psd} utils/thresholds.bro)
# create temporary list of all docs to include in the master policy/index file
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/tmp_policy_index

1
doc/scripts/source/index.rst
View file

@ -13,7 +13,6 @@ Contents:
builtins
default
bifs
user
policy/dns-index
policy/ftp-index
policy/http-index

5
doc/scripts/source/user.rst
View file

@ -1,5 +0,0 @@
.. This is a stub doc to which the build process can append.
Other User-Facing Policy Scripts
================================