Merge remote-tracking branch 'origin/topic/dnthayer/doc-fixes-updates'

BIT-1748 #merged

CHANGES

@@ -1,4 +1,16 @@
 
+2.5-beta2-15 | 2016-11-14 17:52:55 -0800
+
+  * Remove unused "bindist" make target. (Daniel Thayer)
+
+  * Improve the "How to Upgrade" page in the Bro docs. (Daniel Thayer)
+
+  * Update the quickstart guide for the deploy command. (Daniel Thayer)
+
+  * Improved installation instructions for Mac OS X. (Daniel Thayer)
+
+  * Lots of more small updates to documentation. (Daniel Thayer)
+
 2.5-beta2 | 2016-11-02 12:13:11 -0700
 
   * Release 2.5-beta2.

Makefile

@@ -42,10 +42,6 @@ dist:
 	@$(HAVE_MODULES) && find $(VERSION_MIN) -name .git\* | xargs rm -rf || exit 0
 	@$(HAVE_MODULES) && tar -czf $(VERSION_MIN).tgz $(VERSION_MIN) && echo Package: $(VERSION_MIN).tgz && rm -rf $(VERSION_MIN) || exit 0
 
-bindist:
-	@( cd pkg && ( ./make-deb-packages || ./make-mac-packages || \
-	               ./make-rpm-packages ) )
-
 distclean:
 	rm -rf $(BUILD)
 	$(MAKE) -C testing $@
@@ -65,4 +61,4 @@ configured:
 	@test -d $(BUILD) || ( echo "Error: No build/ directory found. Did you run configure?" && exit 1 )
 	@test -e $(BUILD)/Makefile || ( echo "Error: No build/Makefile found. Did you run configure?" && exit 1 )
 
-.PHONY : all install clean doc docclean dist bindist distclean configured
+.PHONY : all install clean doc docclean dist distclean configured

NEWS

@@ -31,17 +31,18 @@ New Functionality
      transferred over SMB can be analyzed.
    - Includes GSSAPI and NTLM analyzer and reimplements the DCE-RPC
      analyzer.
-   - New logs: smb_cmd.log, smb_files.log, smb_mapping.log, ntlm.log, and dce_rpc.log
+   - New logs: smb_cmd.log, smb_files.log, smb_mapping.log, ntlm.log,
+     and dce_rpc.log
    - Not every possible SMB command or functionality is implemented, but
      generally, file handling should work whenever files are transferred.
      Please speak up on the mailing list if there is an obvious oversight.
 
 - Bro now includes the NetControl framework. The framework allows for easy
   interaction of Bro with hard- and software switches, firewalls, etc.
-  New log files: net_control.log, netcontrol_catch_release.log,
+  New log files: netcontrol.log, netcontrol_catch_release.log,
   netcontrol_drop.log, and netcontrol_shunt.log.
 
-- Bro now includes the OpenFlow framework which exposes the datastructures
+- Bro now includes the OpenFlow framework which exposes the data structures
   necessary to interface to OpenFlow capable hardware.
 
 - Bro's Intelligence Framework was refactored and new functionality
@@ -89,8 +90,8 @@ New Functionality
     groups in TLS 1.3.
 
   - The new event ssl_application_data gives information about application data
-    that is exchanged before encryption fully starts. This is used to detect when
+    that is exchanged before encryption fully starts. This is used to detect
-    encryption starts in TLS 1.3.
+    when encryption starts in TLS 1.3.
 
 - Bro now tracks VLAN IDs. To record them inside the connection log,
   load protocols/conn/vlan-logging.bro.
@@ -119,7 +120,7 @@ New Functionality
   - matching_subnets(subnet, table) returns all subnets of the set or table
     that contain the given subnet.
 
-  - filter_subnet_table(subnet, table) works like check_subnet, but returns
+  - filter_subnet_table(subnet, table) works like matching_subnets, but returns
     a table containing all matching entries.
 
 - Several built-in functions for handling IP addresses and subnets were added:
@@ -320,6 +321,10 @@ Changed Functionality
     the crash report includes instructions on how to get backtraces
     included in future crash reports.
 
+  - There is a new option SitePolicyScripts that replaces SitePolicyStandalone
+    (the old option is still available, but will be removed in the next
+    release).
+
 Removed Functionality
 ---------------------
 

VERSION

@@ -1 +1 @@
-2.5-beta2
+2.5-beta2-15

doc/configuration/index.rst

@@ -105,24 +105,9 @@ a Bro cluster (do this as the Bro user on the manager host only):
 
     > broctl install
 
-- Some tasks need to be run on a regular basis. On the manager node,
+- See the :doc:`BroControl <../components/broctl/README>` documentation
-  insert a line like this into the crontab of the user running the
+  for information on setting up a cron job on the manager host that can
-  cluster::
+  monitor the cluster.
-
-      0-59/5 * * * * <prefix>/bin/broctl cron
-
-  (Note: if you are editing the system crontab instead of a user's own
-  crontab, then you need to also specify the user which the command
-  will be run as. The username must be placed after the time fields
-  and before the broctl command.)
-
-  Note that on some systems (FreeBSD in particular), the default PATH
-  for cron jobs does not include the directories where bash and python
-  are installed (the symptoms of this problem would be that "broctl cron"
-  works when run directly by the user, but does not work from a cron job).
-  To solve this problem, you would either need to create symlinks
-  to bash and python in a directory that is in the default PATH for
-  cron jobs, or specify a new PATH in the crontab.
 
 
 PF_RING Cluster Configuration

doc/frameworks/netcontrol.rst

@@ -31,12 +31,12 @@ NetControl Architecture
     NetControl architecture (click to enlarge).
 
 The basic architecture of the NetControl framework is shown in the figure above.
-Conceptually, the NetControl framework sits inbetween the user provided scripts
+Conceptually, the NetControl framework sits between the user provided scripts
 (which use the Bro event engine) and the network device (which can either be a
 hardware or software device), that is used to implement the commands.
 
 The NetControl framework supports a number of high-level calls, like the
-:bro:see:`NetControl::drop_address` function, or lower a lower level rule
+:bro:see:`NetControl::drop_address` function, or a lower level rule
 syntax. After a rule has been added to the NetControl framework, NetControl
 sends the rule to one or several of its *backends*. Each backend is responsible
 to communicate with a single hard- or software device. The NetControl framework
@@ -90,16 +90,12 @@ high-level functions.
 
     * - :bro:see:`NetControl::drop_address`
       - Calling this function causes NetControl to block all packets involving
-        an IP address from being forwarded
+        an IP address from being forwarded.
 
     * - :bro:see:`NetControl::drop_connection`
       - Calling this function stops all packets of a specific connection
         (identified by its 5-tuple) from being forwarded.
 
-    * - :bro:see:`NetControl::drop_address`
-      - Calling this function causes NetControl to block all packets involving
-        an IP address from being forwarded
-
     * - :bro:see:`NetControl::drop_address_catch_release`
       - Calling this function causes all packets of a specific source IP to be
         blocked. This function uses catch-and-release functionality and the IP
@@ -114,7 +110,7 @@ high-level functions.
         resources by shunting flows that have been identified as being benign.
 
     * - :bro:see:`NetControl::redirect_flow`
-      - Calling this function causes NetControl to redirect an uni-directional
+      - Calling this function causes NetControl to redirect a uni-directional
         flow to another port of the networking hardware.
 
     * - :bro:see:`NetControl::quarantine_host`
@@ -122,7 +118,7 @@ high-level functions.
         traffic to a host with a special DNS server, which resolves all queries
         as pointing to itself. The quarantined host is only allowed between the
         special server, which will serve a warning message detailing the next
-        steps for the user
+        steps for the user.
 
     * - :bro:see:`NetControl::whitelist_address`
       - Calling this function causes NetControl to push a whitelist entry for an
@@ -154,7 +150,7 @@ entries, which show that the debug plugin has been initialized and added.
 Afterwards, there are two :bro:see:`NetControl::RULE` entries; the first shows
 that the addition of a rule has been requested (state is
 :bro:see:`NetControl::REQUESTED`). The following line shows that the rule was
-successfully added (the state is  :bro:see:`NetControl::SUCCEEDED`). The
+successfully added (the state is :bro:see:`NetControl::SUCCEEDED`). The
 remainder of the log line gives more information about the added rule, which in
 our case applies to a specific 5-tuple.
 
@@ -227,14 +223,14 @@ The *target* of a rule specifies if the rule is applied in the *forward path*,
 and affects packets as they are forwarded through the network, or if it affects
 the *monitor path* and only affects the packets that are sent to Bro, but not
 the packets that traverse the network. The *entity* specifies the address,
-connection, etc. that the rule applies to. In addition, each notice has a
+connection, etc. that the rule applies to. In addition, each rule has a
 *timeout* (which can be left empty), a *priority* (with higher priority rules
 overriding lower priority rules). Furthermore, a *location* string with more
 text information about each rule can be provided.
 
-There are a couple more fields that only needed for some rule types. For
+There are a couple more fields that are only needed for some rule types. For
 example, when you insert a redirect rule, you have to specify the port that
-packets should be redirected too. All these fields are shown in the
+packets should be redirected to. All these fields are shown in the
 :bro:see:`NetControl::Rule` documentation.
 
 To give an example on how to construct your own rule, we are going to write
@@ -243,7 +239,7 @@ difference between our function and the one provided by NetControl is the fact
 that the NetControl function has additional functionality, e.g. for logging.
 
 Once again, we are going to test our function with a simple example that simply
-drops all connections on the Network:
+drops all connections on the network:
 
 .. btest-include:: ${DOC_ROOT}/frameworks/netcontrol-4-drop.bro
 
@@ -254,7 +250,7 @@ drops all connections on the Network:
 
 The last example shows that :bro:see:`NetControl::add_rule` returns a string
 identifier that is unique for each rule (uniqueness is not preserved across
-restarts or Bro). This rule id can be used to later remove rules manually using
+restarts of Bro). This rule id can be used to later remove rules manually using
 :bro:see:`NetControl::remove_rule`.
 
 Similar to :bro:see:`NetControl::add_rule`, all the high-level functions also
@@ -264,7 +260,7 @@ Interacting with Rules
 ----------------------
 
 The NetControl framework offers a number of different ways to interact with
-Rules. Before a rule is applied by the framework, a number of different hooks
+rules. Before a rule is applied by the framework, a number of different hooks
 allow you to either modify or discard rules before they are added. Furthermore,
 a number of events can be used to track the lifecycle of a rule while it is
 being managed by the NetControl framework. It is also possible to query and
@@ -276,7 +272,7 @@ Rule Policy
 The hook :bro:see:`NetControl::rule_policy` provides the mechanism for modifying
 or discarding a rule before it is sent onwards to the backends. Hooks can be
 thought of as multi-bodied functions and using them looks very similar to
-handling events. In difference to events, they are processed immediately. Like
+handling events. In contrast to events, they are processed immediately. Like
 events, hooks can have priorities to sort the order in which they are applied.
 Hooks can use the ``break`` keyword to show that processing should be aborted;
 if any :bro:see:`NetControl::rule_policy` hook uses ``break``, the rule will be
@@ -315,7 +311,7 @@ this order:
 
     * - :bro:see:`NetControl::rule_new`
       - Signals that a new rule is created by the NetControl framework due to
-        :bro:see:`NetControl::add_rule`. At this point of time, the rule has not
+        :bro:see:`NetControl::add_rule`. At this point, the rule has not
         yet been added to any backend.
 
     * - :bro:see:`NetControl::rule_added`
@@ -328,15 +324,15 @@ this order:
     * - :bro:see:`NetControl::rule_timeout`
       - Signals that a rule timeout was reached. If the hardware does not support
         automatic timeouts, the NetControl framework will automatically call
-        bro:see:`NetControl::remove_rule`.
+        :bro:see:`NetControl::remove_rule`.
 
     * - :bro:see:`NetControl::rule_removed`
       - Signals that a new rule has successfully been removed a backend.
 
     * - :bro:see:`NetControl::rule_destroyed`
       - This event is the pendant to :bro:see:`NetControl::rule_added`, and
-        reports that a rule is no longer be tracked by the NetControl framework.
+        reports that a rule is no longer being tracked by the NetControl framework.
-        This happens, for example, when a rule was removed from all backend.
+        This happens, for example, when a rule was removed from all backends.
 
     * - :bro:see:`NetControl::rule_error`
       - This event is raised whenever an error occurs during any rule operation.
@@ -385,7 +381,7 @@ NetControl also comes with a blocking function that uses an approach called
 
 Catch and release is a blocking scheme that conserves valuable rule space in
 your hardware. Instead of using long-lasting blocks, catch and release first
-only installs blocks for short amount of times (typically a few minutes). After
+only installs blocks for a short amount of time (typically a few minutes). After
 these minutes pass, the block is lifted, but the IP address is added to a
 watchlist and the IP address will immediately be re-blocked again (for a longer
 amount of time), if it is seen reappearing in any traffic, no matter if the new
@@ -397,7 +393,7 @@ addresses that only are seen once for a short time are only blocked for a few
 minutes, monitored for a while and then forgotten. IP addresses that keep
 appearing will get re-blocked for longer amounts of time.
 
-In difference to the other high-level functions that we documented so far, the
+In contrast to the other high-level functions that we documented so far, the
 catch and release functionality is much more complex and adds a number of
 different specialized functions to NetControl. The documentation for catch and
 release is contained in the file
@@ -481,7 +477,7 @@ The plugins that currently ship with NetControl are:
         plugin is contained in :doc:`/scripts/base/frameworks/netcontrol/plugins/acld.bro`.
 
     * - PacketFilter plugin
-      - This plugin adds uses the Bro process-level packet filter (see
+      - This plugin uses the Bro process-level packet filter (see
         :bro:see:`install_src_net_filter` and
         :bro:see:`install_dst_net_filter`). Since the functionality of the
         PacketFilter is limited, this plugin is mostly for demonstration purposes. The source of this
@@ -496,7 +492,7 @@ Activating plugins
 
 In the API reference part of this document, we already used the debug plugin. To
 use the plugin, we first had to instantiate it by calling
-:bro:see:`NetControl::NetControl::create_debug` and then add it to NetControl by
+:bro:see:`NetControl::create_debug` and then add it to NetControl by
 calling :bro:see:`NetControl::activate`.
 
 As we already hinted before, NetControl supports having several plugins that are
@@ -607,7 +603,7 @@ Writing plugins
 
 In addition to using the plugins that are part of NetControl, you can write your
 own plugins to interface with hard- or software that we currently do not support
-out of the Box.
+out of the box.
 
 Creating your own plugin is easy; besides a bit of boilerplate, you only need to
 create two functions: one that is called when a rule is added, and one that is

doc/install/guidelines.rst

@@ -10,40 +10,53 @@ there's two suggested approaches: either install Bro using the same
 installation prefix directory as before, or pick a new prefix and copy
 local customizations over.
 
-Regardless of which approach you choose, if you are using BroControl, then
-before doing the upgrade you should stop all running Bro processes with the
-"broctl stop" command.  After the upgrade is complete then you will need
-to run "broctl deploy".
-
 In the following we summarize general guidelines for upgrading, see
 the :ref:`release-notes` for version-specific information.
 
 
 Reusing Previous Install Prefix
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you choose to configure and install Bro with the same prefix
-directory as before, local customization and configuration to files in
+directory as before, first stop all running Bro instances in your
-``$prefix/share/bro/site`` and ``$prefix/etc`` won't be overwritten
+cluster (if using BroControl, issue the "broctl stop" command on the
-(``$prefix`` indicating the root of where Bro was installed). Also, logs
+manager host).  Next, make a backup of the Bro install prefix directory.
-generated at run-time won't be touched by the upgrade. Backing up local
-changes before upgrading is still recommended.
 
-After upgrading, remember to check ``$prefix/share/bro/site`` and
+During the upgrade, any file in the install prefix may be
-``$prefix/etc`` for ``.example`` files, which indicate that the
+overwritten or removed, except for local customization of
-distribution's version of the file differs from the local one, and therefore,
+files in the ``$prefix/share/bro/site`` and ``$prefix/etc``
-may include local changes.  Review the differences and make adjustments
+directories (``$prefix`` indicating the root
-as necessary. Use the new version for differences that aren't a result of
+of where Bro was installed).  Also, logs generated at run-time
-a local change.
+won't be touched by the upgrade.
+
+After upgrading, remember to check the ``$prefix/share/bro/site`` and
+``$prefix/etc`` directories for files with a file extension of ``.example``,
+which indicate that the distribution's version of the file differs from the
+local one, and therefore, may include local changes.  Review the
+differences and make adjustments as necessary. Use the new version
+for differences that aren't a result of a local change.
+
+Finally, if using BroControl, then issue the "broctl deploy" command.  This
+command will check for any policy script errors, install the new version
+of Bro to all machines in your cluster, and then it will start Bro.
 
 Using a New Install Prefix
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To install the newer version in a different prefix directory than before,
-copy local customization and configuration files from ``$prefix/share/bro/site``
+first stop all running Bro instances in your cluster (if using BroControl,
-and ``$prefix/etc`` to the new location (``$prefix`` indicating the root of
+then issue a "broctl stop" command on the manager host).  Next,
-where Bro was originally installed).  Review the files for differences
+install the new version of Bro in a new directory.
+
+Next, copy local customization and configuration files
+from the ``$prefix/share/bro/site`` and ``$prefix/etc`` directories to the
+new location (``$prefix`` indicating the root of where Bro was originally
+installed).  Review the files for differences
 before copying and make adjustments as necessary (use the new version for
 differences that aren't a result of a local change).  Of particular note,
 the copied version of ``$prefix/etc/broctl.cfg`` is likely to need changes
 to any settings that specify a pathname.
+
+Finally, if using BroControl, then issue the "broctl deploy" command.  This
+command will check for any policy script errors, install the new version
+of Bro to all machines in your cluster, and then it will start Bro.

doc/install/install.rst

@@ -31,7 +31,7 @@ before you begin:
     * BIND8 library
     * Libz
     * Bash (for BroControl)
-    * Python (for BroControl)
+    * Python 2.6 or greater (for BroControl)
 
 To build Bro from source, the following additional dependencies are required:
 
@@ -69,9 +69,6 @@ To install the required dependencies, you can use:
 
       sudo pkg install bash cmake swig bison python py27-sqlite3
 
-  Note that in older versions of FreeBSD, you might have to use the
-  "pkg_add -r" command instead of "pkg install".
-
   For older versions of FreeBSD (especially FreeBSD 9.x), the system compiler
   is not new enough to compile Bro. For these systems, you will have to install
   a newer compiler using pkg; the ``clang34`` package should work.
@@ -89,19 +86,23 @@ To install the required dependencies, you can use:
 
 * Mac OS X:
 
-  Compiling source code on Macs requires first installing Xcode_ (in older
+  Compiling source code on Macs requires first installing either Xcode_
-  versions of Xcode, you would then need to go through its
+  or the "Command Line Tools" (which is a much smaller download).  To check
-  "Preferences..." -> "Downloads" menus to install the "Command Line Tools"
+  if either is installed, run the ``xcode-select -p`` command.  If you see
-  component).
+  an error message, then neither is installed and you can then run
+  ``xcode-select --install`` which will prompt you to either get Xcode (by
+  clicking "Get Xcode") or to install the command line tools (by
+  clicking "Install").
 
   OS X comes with all required dependencies except for CMake_, SWIG_,
-  and OpenSSL. (OpenSSL used to be part of OS X versions 10.10
+  and OpenSSL (OpenSSL headers were removed in OS X 10.11, therefore OpenSSL
-  and older, for which it does not need to be installed manually. It
+  must be installed manually for OS X versions 10.11 or newer).
-  was removed in OS X 10.11). Distributions of these dependencies can
+  Distributions of these dependencies can
   likely be obtained from your preferred Mac OS X package management
   system (e.g. Homebrew_, MacPorts_, or Fink_). Specifically for
   Homebrew, the ``cmake``, ``swig``, and ``openssl`` packages
-  provide the required dependencies.
+  provide the required dependencies.  For MacPorts, the ``cmake``, ``swig``,
+  ``swig-python``, and ``openssl`` packages provide the required dependencies.
 
 
 Optional Dependencies

doc/quickstart/index.rst

@@ -78,15 +78,6 @@ You can leave it running for now, but to stop this Bro instance you would do:
 
    [BroControl] > stop
 
-We also recommend to insert the following entry into the crontab of the user
-running BroControl::
-
-      0-59/5 * * * * $PREFIX/bin/broctl cron
-
-This will perform a number of regular housekeeping tasks, including
-verifying that the process is still running (and restarting if not in
-case of any abnormal termination).
-
 Browsing Log Files
 ------------------
 
@@ -232,23 +223,25 @@ That's exactly what we want to do for the first notice.  Add to ``local.bro``:
    inside the module.
 
 Then go into the BroControl shell to check whether the configuration change
-is valid before installing it and then restarting the Bro instance:
+is valid before installing it and then restarting the Bro instance.  The
+"deploy" command does all of this automatically:
 
 .. console::
 
-   [BroControl] > check
+   [BroControl] > deploy
-   bro scripts are ok.
+   checking configurations ...
-   [BroControl] > install
+   installing ...
-   removing old policies in /usr/local/bro/spool/policy/site ... done.
+   removing old policies in /usr/local/bro/spool/installed-scripts-do-not-touch/site ...
-   removing old policies in /usr/local/bro/spool/policy/auto ... done.
+   removing old policies in /usr/local/bro/spool/installed-scripts-do-not-touch/auto ...
-   creating policy directories ... done.
+   creating policy directories ...
-   installing site policies ... done.
+   installing site policies ...
-   generating standalone-layout.bro ... done.
+   generating standalone-layout.bro ...
-   generating local-networks.bro ... done.
+   generating local-networks.bro ...
-   generating broctl-config.bro ... done.
+   generating broctl-config.bro ...
-   updating nodes ... done.
+   generating broctl-config.sh ...
-   [BroControl] > restart
+   stopping ...
    stopping bro ...
+   starting ...
    starting bro ...
 
 Now that the SSL notice is ignored, let's look at how to send an email
@@ -281,8 +274,8 @@ connection field is in the set of watched servers.
    order to avoid ambiguity with the built-in address type's use of '.'
    in IPv4 dotted decimal representations.
 
-Remember, to finalize that configuration change perform the ``check``,
+Remember, to finalize that configuration change perform the ``deploy``
-``install``, ``restart`` commands in that order inside the BroControl shell.
+command inside the BroControl shell.
 
 Next Steps
 ----------

scripts/base/frameworks/broker/main.bro

@@ -14,6 +14,7 @@ module Broker;
 export {
 
 	## A name used to identify this endpoint to peers.
+	##
 	## .. bro:see:: Broker::connect Broker::listen
 	const endpoint_name = "" &redef;
 

scripts/base/frameworks/intel/cluster.bro

@@ -12,7 +12,7 @@ redef record Item += {
 	first_dispatch: bool &default=T;
 };
 
-# If this process is not a manager process, we don't want the full metadata
+# If this process is not a manager process, we don't want the full metadata.
 @if ( Cluster::local_node_type() != Cluster::MANAGER )
 redef have_full_data = F;
 @endif
@@ -20,7 +20,7 @@ redef have_full_data = F;
 # Internal event for cluster data distribution.
 global cluster_new_item: event(item: Item);
 
-# Primary intelligence management is done by the manager:
+# Primary intelligence management is done by the manager.
 # The manager informs the workers about new items and item removal.
 redef Cluster::manager2worker_events += /^Intel::(cluster_new_item|purge_item)$/;
 # A worker queries the manager to insert, remove or indicate the match of an item.

scripts/base/frameworks/intel/files.bro

@@ -1,5 +1,5 @@
 ##! File analysis framework integration for the intelligence framework. This
-##! script manages file information in intelligence framework datastructures.
+##! script manages file information in intelligence framework data structures.
 
 @load ./main
 

scripts/base/frameworks/intel/main.bro

@@ -1,6 +1,7 @@
-##! The intelligence framework provides a way to store and query intelligence data
+##! The intelligence framework provides a way to store and query intelligence
-##! (e.g. IP addresses, URLs and hashes). The intelligence items can be associated
+##! data (e.g. IP addresses, URLs and hashes). The intelligence items can be
-##! with metadata to allow informed decisions about matching and handling.
+##! associated with metadata to allow informed decisions about matching and
+##! handling.
 
 @load base/frameworks/notice
 

scripts/base/frameworks/logging/main.bro

@@ -79,7 +79,7 @@ export {
 
 	## Information passed into rotation callback functions.
 	type RotationInfo: record {
-		writer: Writer;		##< The :bro:type:`Log::Writer` being used.
+		writer: Writer;		##< The log writer being used.
 		fname: string;		##< Full name of the rotated file.
 		path: string;		##< Original path value.
 		open: time;		##< Time when opened.
@@ -131,7 +131,7 @@ export {
 	## Default log extension function in the case that you would like to
 	## apply the same extensions to all logs.  The function *must* return
 	## a record with all of the fields to be included in the log. The
-	## default function included here does not return a value to indicate
+	## default function included here does not return a value, which indicates
 	## that no extensions are added.
 	const Log::default_ext_func: function(path: string): any =
 		function(path: string) { } &redef;
@@ -348,7 +348,7 @@ export {
 	##          to handle, or one of the stream's filters has an invalid
 	##          ``path_func``.
 	##
-	## .. bro:see: Log::enable_stream Log::disable_stream
+	## .. bro:see:: Log::enable_stream Log::disable_stream
 	global write: function(id: ID, columns: any) : bool;
 
 	## Sets the buffering status for all the writers of a given logging stream.

scripts/base/frameworks/netcontrol/catch-and-release.bro

@@ -10,39 +10,39 @@ export {
 
 	redef enum Log::ID += { CATCH_RELEASE };
 
-	## Thhis record is used is used for storing information about current blocks that are
+	## This record is used for storing information about current blocks that are
 	## part of catch and release.
 	type BlockInfo: record {
-		## Absolute time indicating until when a block is inserted using NetControl
+		## Absolute time indicating until when a block is inserted using NetControl.
 		block_until: time &optional;
-		## Absolute time indicating until when an IP address is watched to reblock it
+		## Absolute time indicating until when an IP address is watched to reblock it.
 		watch_until: time;
-		## Number of times an IP address was reblocked
+		## Number of times an IP address was reblocked.
 		num_reblocked: count &default=0;
-		## Number indicating at which catch and release interval we currently are
+		## Number indicating at which catch and release interval we currently are.
 		current_interval: count;
 		## ID of the inserted block, if any.
 		current_block_id: string;
-		## User specified string
+		## User specified string.
 		location: string &optional;
 	};
 
 	## The enum that contains the different kinds of messages that are logged by
-	## catch and release
+	## catch and release.
 	type CatchReleaseActions: enum {
-		## Log lines marked with info are purely informational; no action was taken
+		## Log lines marked with info are purely informational; no action was taken.
 		INFO,
 		## A rule for the specified IP address already existed in NetControl (outside
 		## of catch-and-release). Catch and release did not add a new rule, but is now
-		## watching the IP address and will add a new rule after the current rule expired.
+		## watching the IP address and will add a new rule after the current rule expires.
 		ADDED,
-		## A drop was requested by catch and release
+		## A drop was requested by catch and release.
 		DROP,
-		## A address was succesfully blocked by catch and release
+		## An address was successfully blocked by catch and release.
 		DROPPED,
-		## An address was unblocked after the timeout expired
+		## An address was unblocked after the timeout expired.
 		UNBLOCK,
-		## An address was forgotten because it did not reappear within the `watch_until` interval
+		## An address was forgotten because it did not reappear within the `watch_until` interval.
 		FORGOTTEN,
 		## A watched IP address was seen again; catch and release will re-block it.
 		SEEN_AGAIN
@@ -52,7 +52,7 @@ export {
 	type CatchReleaseInfo: record {
 		## The absolute time indicating when the action for this log-line occured.
 		ts: time &log;
-		## The rule id that this log lone refers to.
+		## The rule id that this log line refers to.
 		rule_id: string &log &optional;
 		## The IP address that this line refers to.
 		ip: addr &log;
@@ -85,7 +85,7 @@ export {
 	##
 	## a: The address to be dropped.
 	##
-	## t: How long to drop it, with 0 being indefinitly.
+	## t: How long to drop it, with 0 being indefinitely.
 	##
 	## location: An optional string describing where the drop was triggered.
 	##
@@ -101,17 +101,17 @@ export {
 	##
 	## a: The address to be unblocked.
 	##
-	## reason: A reason for the unblock
+	## reason: A reason for the unblock.
 	##
 	## Returns: True if the address was unblocked.
 	global unblock_address_catch_release: function(a: addr, reason: string &default="") : bool;
 
-	## This function can be called to notify the cach and release script that activity by
+	## This function can be called to notify the catch and release script that activity by
 	## an IP address was seen. If the respective IP address is currently monitored by catch and
-	## release and not blocked, the block will be re-instated. See the documentation of watch_new_connection
+	## release and not blocked, the block will be reinstated. See the documentation of watch_new_connection
 	## which events the catch and release functionality usually monitors for activity.
 	##
-	## a: The address that was seen and should be re-dropped if it is being watched
+	## a: The address that was seen and should be re-dropped if it is being watched.
 	global catch_release_seen: function(a: addr);
 
 	## Get the :bro:see:`NetControl::BlockInfo` record for an address currently blocked by catch and release.
@@ -144,7 +144,7 @@ export {
 	## should have been blocked.
 	const catch_release_warn_blocked_ip_encountered = F &redef;
 
-	## Time intervals for which a subsequent drops of the same IP take
+	## Time intervals for which subsequent drops of the same IP take
 	## effect.
 	const catch_release_intervals: vector of interval = vector(10min, 1hr, 24hrs, 7days) &redef;
 
@@ -160,7 +160,7 @@ export {
 	global catch_release_encountered: event(a: addr);
 }
 
-# set that is used to only send seen notifications to the master every ~30 seconds.
+# Set that is used to only send seen notifications to the master every ~30 seconds.
 global catch_release_recently_notified: set[addr] &create_expire=30secs;
 
 event bro_init() &priority=5

scripts/base/frameworks/netcontrol/cluster.bro

@@ -23,7 +23,7 @@ redef Cluster::manager2worker_events += /NetControl::rule_(added|removed|timeout
 
 function activate(p: PluginState, priority: int)
 	{
-	# we only run the activate function on the manager.
+	# We only run the activate function on the manager.
 	if ( Cluster::local_node_type() != Cluster::MANAGER )
 		return;
 
@@ -38,8 +38,8 @@ function add_rule(r: Rule) : string
 		return add_rule_impl(r);
 	else
 		{
-		# we sync rule entities accross the cluster, so we
+		# We sync rule entities accross the cluster, so we
-		# acually can test if the rule already exists. If yes,
+		# actually can test if the rule already exists. If yes,
 		# refuse insertion already at the node.
 
 		if ( [r$entity, r$ty] in rule_entities )

scripts/base/frameworks/netcontrol/drop.bro

@@ -11,34 +11,34 @@ export {
 	##
 	## a: The address to be dropped.
 	##
-	## t: How long to drop it, with 0 being indefinitly.
+	## t: How long to drop it, with 0 being indefinitely.
 	##
 	## location: An optional string describing where the drop was triggered.
 	##
-	## Returns: The id of the inserted rule on succes and zero on failure.
+	## Returns: The id of the inserted rule on success and zero on failure.
 	global drop_address: function(a: addr, t: interval, location: string &default="") : string;
 
-	## Stops all packets involving an connection address from being forwarded.
+	## Stops all packets involving a connection address from being forwarded.
 	##
 	## c: The connection to be dropped.
 	##
-	## t: How long to drop it, with 0 being indefinitly.
+	## t: How long to drop it, with 0 being indefinitely.
 	##
 	## location: An optional string describing where the drop was triggered.
 	##
-	## Returns: The id of the inserted rule on succes and zero on failure.
+	## Returns: The id of the inserted rule on success and zero on failure.
 	global drop_connection: function(c: conn_id, t: interval, location: string &default="") : string;
 
 	type DropInfo: record {
 		## Time at which the recorded activity occurred.
 		ts: time		&log;
-		## ID of the rule; unique during each Bro run
+		## ID of the rule; unique during each Bro run.
 		rule_id: string  &log;
 		orig_h: addr 	&log;	##< The originator's IP address.
 		orig_p: port 	&log &optional;	##< The originator's port number.
 		resp_h: addr	&log &optional;	##< The responder's IP address.
 		resp_p: port	&log &optional;	##< The responder's port number.
-		## Expiry time of the shunt
+		## Expiry time of the shunt.
 		expire: interval &log;
 		## Location where the underlying action was triggered.
 		location: string	&log &optional;
@@ -47,7 +47,7 @@ export {
 	## Hook that allows the modification of rules passed to drop_* before they
 	## are passed on. If one of the hooks uses break, the rule is ignored.
 	##
-	## r: The rule to be added
+	## r: The rule to be added.
 	global NetControl::drop_rule_policy: hook(r: Rule);
 
 	## Event that can be handled to access the :bro:type:`NetControl::ShuntInfo`

scripts/base/frameworks/netcontrol/main.bro

@@ -7,7 +7,7 @@
 ##! restrictions on entities, such as specific connections or IP addresses.
 ##!
 ##! This framework has two APIs: a high-level and low-level. The high-level API
-##! provides convinience functions for a set of common operations. The
+##! provides convenience functions for a set of common operations. The
 ##! low-level API provides full flexibility.
 
 module NetControl;
@@ -25,7 +25,7 @@ export {
 
 	## Activates a plugin.
 	##
-	## p: The plugin to acticate.
+	## p: The plugin to activate.
 	##
 	## priority: The higher the priority, the earlier this plugin will be checked
 	##           whether it supports an operation, relative to other plugins.
@@ -48,37 +48,37 @@ export {
 
 	## Allows all traffic involving a specific IP address to be forwarded.
 	##
-	## a: The address to be whitelistet.
+	## a: The address to be whitelisted.
 	##
-	## t: How long to whitelist it, with 0 being indefinitly.
+	## t: How long to whitelist it, with 0 being indefinitely.
 	##
 	## location: An optional string describing whitelist was triddered.
 	##
-	## Returns: The id of the inserted rule on succes and zero on failure.
+	## Returns: The id of the inserted rule on success and zero on failure.
 	global whitelist_address: function(a: addr, t: interval, location: string &default="") : string;
 
 	## Allows all traffic involving a specific IP subnet to be forwarded.
 	##
-	## s: The subnet to be whitelistet.
+	## s: The subnet to be whitelisted.
 	##
-	## t: How long to whitelist it, with 0 being indefinitly.
+	## t: How long to whitelist it, with 0 being indefinitely.
 	##
 	## location: An optional string describing whitelist was triddered.
 	##
-	## Returns: The id of the inserted rule on succes and zero on failure.
+	## Returns: The id of the inserted rule on success and zero on failure.
 	global whitelist_subnet: function(s: subnet, t: interval, location: string &default="") : string;
 
-	## Redirects an uni-directional flow to another port.
+	## Redirects a uni-directional flow to another port.
 	##
 	## f: The flow to redirect.
 	##
-	## out_port: Port to redirect the flow to
+	## out_port: Port to redirect the flow to.
 	##
-	## t: How long to leave the redirect in place, with 0 being indefinitly.
+	## t: How long to leave the redirect in place, with 0 being indefinitely.
 	##
 	## location: An optional string describing where the redirect was triggered.
 	##
-	## Returns: The id of the inserted rule on succes and zero on failure.
+	## Returns: The id of the inserted rule on success and zero on failure.
 	global redirect_flow: function(f: flow_id, out_port: count, t: interval, location: string &default="") : string;
 
 	## Quarantines a host. This requires a special quarantine server, which runs a HTTP server explaining
@@ -87,13 +87,13 @@ export {
 	## instead. Only http communication infected to quarantinehost is allowed. All other network communication
 	## is blocked.
 	##
-	## infected: the host to quarantine
+	## infected: the host to quarantine.
 	##
-	## dns: the network dns server
+	## dns: the network dns server.
 	##
-	## quarantine: the quarantine server running a dns and a web server
+	## quarantine: the quarantine server running a dns and a web server.
 	##
-	## t: how long to leave the quarantine in place
+	## t: how long to leave the quarantine in place.
 	##
 	## Returns: Vector of inserted rules on success, empty list on failure.
 	global quarantine_host: function(infected: addr, dns: addr, quarantine: addr, t: interval, location: string &default="") : vector of string;
@@ -111,7 +111,7 @@ export {
 	##
 	## r: The rule to install.
 	##
-	## Returns: If succesful, returns an ID string unique to the rule that can
+	## Returns: If successful, returns an ID string unique to the rule that can
 	##          later be used to refer to it. If unsuccessful, returns an empty
 	##          string. The ID is also assigned to ``r$id``. Note that
 	##          "successful" means "a plugin knew how to handle the rule", it
@@ -126,19 +126,19 @@ export {
 	##
 	## reason: Optional string argument giving information on why the rule was removed.
 	##
-	## Returns: True if succesful, the relevant plugin indicated that it knew
+	## Returns: True if successful, the relevant plugin indicated that it knew
 	##          how to handle the removal. Note that again "success" means the
-	##          plugin accepted the removal. They might still fail to put it
+	##          plugin accepted the removal. It might still fail to put it
 	##          into effect, as that might happen asynchronously and thus go
 	##          wrong at that point.
 	global remove_rule: function(id: string, reason: string &default="") : bool;
 
-	## Deletes a rule without removing in from the backends to which it has been
+	## Deletes a rule without removing it from the backends to which it has been
-	## added before. This mean that no messages will be sent to the switches to which
+	## added before. This means that no messages will be sent to the switches to which
 	## the rule has been added; if it is not removed from them by a separate mechanism,
 	## it will stay installed and not be removed later.
 	##
-	## id: The rule to delete, specified as the ID returned by :bro:see:`add_rule` .
+	## id: The rule to delete, specified as the ID returned by :bro:see:`NetControl::add_rule`.
 	##
 	## reason: Optional string argument giving information on why the rule was deleted.
 	##
@@ -152,9 +152,9 @@ export {
 	## the worker, the internal rule variables (starting with _) will not reflect the
 	## current state.
 	##
-	## ip: The ip address to search for
+	## ip: The ip address to search for.
 	##
-	## Returns: vector of all rules affecting the IP address
+	## Returns: vector of all rules affecting the IP address.
 	global find_rules_addr: function(ip: addr) : vector of Rule;
 
 	## Searches all rules affecting a certain subnet.
@@ -171,9 +171,9 @@ export {
 	## the worker, the internal rule variables (starting with _) will not reflect the
 	## current state.
 	##
-	## sn: The subnet to search for
+	## sn: The subnet to search for.
 	##
-	## Returns: vector of all rules affecting the subnet
+	## Returns: vector of all rules affecting the subnet.
 	global find_rules_subnet: function(sn: subnet) : vector of Rule;
 
 	###### Asynchronous feedback on rules.
@@ -201,7 +201,7 @@ export {
 	global rule_exists: event(r: Rule, p: PluginState, msg: string &default="");
 
 	## Reports that a plugin reports a rule was removed due to a
-	## remove: function() vall.
+	## remove_rule function call.
 	##
 	## r: The rule now removed.
 	##
@@ -234,9 +234,9 @@ export {
 
 	## This event is raised when a new rule is created by the NetControl framework
 	## due to a call to add_rule. From this moment, until the rule_destroyed event
-	## is raised, the rule is tracked internally by the NetControl framewory.
+	## is raised, the rule is tracked internally by the NetControl framework.
 	##
-	## Note that this event does not mean that a rule was succesfully added by
+	## Note that this event does not mean that a rule was successfully added by
 	## any backend; it just means that the rule has been accepted and addition
 	## to the specified backend is queued. To get information when rules are actually
 	## installed by the hardware, use the rule_added, rule_exists, rule_removed, rule_timeout
@@ -248,15 +248,15 @@ export {
 	## was removed by all plugins to which it was added, by the fact that it timed out
 	## or due to rule errors.
 	##
-	## To get the cause or a rule remove, hook the rule_removed, rule_timeout and
+	## To get the cause of a rule remove, catch the rule_removed, rule_timeout and
-	## rule_error calls.
+	## rule_error events.
 	global rule_destroyed: event(r: Rule);
 
 	## Hook that allows the modification of rules passed to add_rule before they
 	## are passed on to the plugins. If one of the hooks uses break, the rule is
 	## ignored and not passed on to any plugin.
 	##
-	## r: The rule to be added
+	## r: The rule to be added.
 	global NetControl::rule_policy: hook(r: Rule);
 
 	##### Plugin functions
@@ -279,19 +279,19 @@ export {
 
 	## State of an entry in the NetControl log.
 	type InfoState: enum {
-		REQUESTED, ##< The request to add/remove a rule was sent to the respective backend
+		REQUESTED, ##< The request to add/remove a rule was sent to the respective backend.
-		SUCCEEDED, ##< A rule was succesfully added by a backend
+		SUCCEEDED, ##< A rule was successfully added by a backend.
-		EXISTS, ##< A backend reported that a rule was already existing
+		EXISTS, ##< A backend reported that a rule was already existing.
-		FAILED, ##< A rule addition failed
+		FAILED, ##< A rule addition failed.
-		REMOVED, ##< A rule was succesfully removed by a backend
+		REMOVED, ##< A rule was successfully removed by a backend.
-		TIMEOUT, ##< A rule timeout was triggered by the NetControl framework or a backend
+		TIMEOUT, ##< A rule timeout was triggered by the NetControl framework or a backend.
 	};
 
 	## The record type defining the column fields of the NetControl log.
 	type Info: record {
 		## Time at which the recorded activity occurred.
 		ts: time		&log;
-		## ID of the rule; unique during each Bro run
+		## ID of the rule; unique during each Bro run.
 		rule_id: string  &log &optional;
 		## Type of the log entry.
 		category: InfoCategory	&log &optional;
@@ -311,9 +311,9 @@ export {
 		mod: string		&log &optional;
 		## String with an additional message.
 		msg: string		&log &optional;
-		## Number describing the priority of the log entry
+		## Number describing the priority of the log entry.
 		priority: int &log &optional;
-		## Expiry time of the log entry
+		## Expiry time of the log entry.
 		expire: interval &log &optional;
 		## Location where the underlying action was triggered.
 		location: string	&log &optional;
@@ -333,7 +333,7 @@ redef record Rule += {
 	_active_plugin_ids: set[count] &default=count_set();
 	## Internally set to plugins where the rule should not be removed upon timeout.
 	_no_expire_plugins: set[count] &default=count_set();
-	## Track if the rule was added succesfully by all responsible plugins.
+	## Track if the rule was added successfully by all responsible plugins.
 	_added: bool &default=F;
 };
 

scripts/base/frameworks/netcontrol/plugin.bro

@@ -9,7 +9,7 @@ export {
 	##
 	## Individual plugins commonly extend this record to suit their needs.
 	type PluginState: record {
-		## Table for a plugin to store custom, instance-specfific state. 
+		## Table for a plugin to store custom, instance-specific state.
 		config: table[string] of string &default=table();
 
 		## Unique plugin identifier -- used for backlookup of plugins from Rules. Set internally.
@@ -18,14 +18,14 @@ export {
 		## Set internally.
 		_priority: int &default=+0;
 
-		## Set internally. Signifies if the plugin has returned that it has activated succesfully
+		## Set internally. Signifies if the plugin has returned that it has activated successfully.
 		_activated: bool &default=F;
 	};
 
 	## Definition of a plugin.
 	##
 	## Generally a plugin needs to implement only what it can support.  By
-	## returning failure, it indicates that it can't support something and the
+	## returning failure, it indicates that it can't support something and
 	## the framework will then try another plugin, if available; or inform the
 	## that the operation failed. If a function isn't implemented by a plugin,
 	## that's considered an implicit failure to support the operation.
@@ -33,7 +33,7 @@ export {
 	## If plugin accepts a rule operation, it *must* generate one of the reporting
 	## events ``rule_{added,remove,error}`` to signal if it indeed worked out;
 	## this is separate from accepting the operation because often a plugin
-	## will only know later (i.e., asynchrously) if that was an error for
+	## will only know later (i.e., asynchronously) if that was an error for
 	## something it thought it could handle.
 	type Plugin: record {
 		## Returns a descriptive name of the plugin instance, suitable for use in logging
@@ -64,7 +64,7 @@ export {
 		add_rule: function(state: PluginState, r: Rule) : bool &optional;
 
 		## Implements the remove_rule() operation. This will only be called for
-		## rules that the plugins has previously accepted with add_rule(). The
+		## rules that the plugin has previously accepted with add_rule(). The
 		## ``id`` field will match that of the add_rule() call.  Generally,
 		## a plugin that accepts an add_rule() should also accept the
 		## remove_rule().

scripts/base/frameworks/netcontrol/plugins/README

@@ -1 +1 @@
-Plugins for the NetControl framework
+Plugins for the NetControl framework.

scripts/base/frameworks/netcontrol/plugins/acld.bro

@@ -17,24 +17,24 @@ export {
 	};
 
 	type AcldConfig: record {
-		## The acld topic used to send events to
+		## The acld topic to send events to.
 		acld_topic: string;
-		## Broker host to connect to
+		## Broker host to connect to.
 		acld_host: addr;
-		## Broker port to connect to
+		## Broker port to connect to.
 		acld_port: port;
-		## Do we accept rules for the monitor path? Default false
+		## Do we accept rules for the monitor path? Default false.
 		monitor: bool &default=F;
-		## Do we accept rules for the forward path? Default true
+		## Do we accept rules for the forward path? Default true.
 		forward: bool &default=T;
 
 		## Predicate that is called on rule insertion or removal.
 		##
-		## p: Current plugin state
+		## p: Current plugin state.
 		##
-		## r: The rule to be inserted or removed
+		## r: The rule to be inserted or removed.
 		##
-		## Returns: T if the rule can be handled by the current backend, F otherwhise
+		## Returns: T if the rule can be handled by the current backend, F otherwise.
 		check_pred: function(p: PluginState, r: Rule): bool &optional;
 	};
 
@@ -43,27 +43,27 @@ export {
 
 	redef record PluginState += {
 		acld_config: AcldConfig &optional;
-		## The ID of this acld instance - for the mapping to PluginStates
+		## The ID of this acld instance - for the mapping to PluginStates.
 		acld_id: count &optional;
 	};
 
 	## Hook that is called after a rule is converted to an acld rule.
 	## The hook may modify the rule before it is sent to acld.
 	## Setting the acld command to F will cause the rule to be rejected
-	## by the plugin
+	## by the plugin.
 	##
-	## p: Current plugin state
+	## p: Current plugin state.
 	##
-	## r: The rule to be inserted or removed
+	## r: The rule to be inserted or removed.
 	##
-	## ar: The acld rule to be inserted or removed
+	## ar: The acld rule to be inserted or removed.
 	global NetControl::acld_rule_policy: hook(p: PluginState, r: Rule, ar: AclRule);
 
-	## Events that are sent from us to Broker
+	## Events that are sent from us to Broker.
 	global acld_add_rule: event(id: count, r: Rule, ar: AclRule);
 	global acld_remove_rule: event(id: count, r: Rule, ar: AclRule);
 
-	## Events that are sent from Broker to us
+	## Events that are sent from Broker to us.
 	global acld_rule_added: event(id: count, r: Rule, msg: string);
 	global acld_rule_removed: event(id: count, r: Rule, msg: string);
 	global acld_rule_exists: event(id: count, r: Rule, msg: string);

scripts/base/frameworks/netcontrol/plugins/broker.bro

@@ -1,4 +1,4 @@
-##! Broker plugin for the netcontrol framework. Sends the raw data structures
+##! Broker plugin for the NetControl framework. Sends the raw data structures
 ##! used in NetControl on to Broker to allow for easy handling, e.g., of
 ##! command-line scripts.
 
@@ -13,25 +13,25 @@ module NetControl;
 export {
 	## This record specifies the configuration that is passed to :bro:see:`NetControl::create_broker`.
 	type BrokerConfig: record {
-		## The broker topic used to send events to
+		## The broker topic to send events to.
 		topic: string &optional;
-		## Broker host to connect to
+		## Broker host to connect to.
 		host: addr &optional;
-		## Broker port to connect to
+		## Broker port to connect to.
 		bport: port &optional;
 
-		## Do we accept rules for the monitor path? Default true
+		## Do we accept rules for the monitor path? Default true.
 		monitor: bool &default=T;
-		## Do we accept rules for the forward path? Default true
+		## Do we accept rules for the forward path? Default true.
 		forward: bool &default=T;
 
 		## Predicate that is called on rule insertion or removal.
 		##
-		## p: Current plugin state
+		## p: Current plugin state.
 		##
-		## r: The rule to be inserted or removed
+		## r: The rule to be inserted or removed.
 		##
-		## Returns: T if the rule can be handled by the current backend, F otherwhise
+		## Returns: T if the rule can be handled by the current backend, F otherwise.
 		check_pred: function(p: PluginState, r: Rule): bool &optional;
 	};
 
@@ -39,9 +39,9 @@ export {
 	global create_broker: function(config: BrokerConfig, can_expire: bool) : PluginState;
 
 	redef record PluginState += {
-		## OpenFlow controller for NetControl Broker plugin
+		## OpenFlow controller for NetControl Broker plugin.
 		broker_config: BrokerConfig &optional;
-		## The ID of this broker instance - for the mapping to PluginStates
+		## The ID of this broker instance - for the mapping to PluginStates.
 		broker_id: count &optional;
 	};
 

scripts/base/frameworks/netcontrol/plugins/openflow.bro

@@ -9,11 +9,11 @@ module NetControl;
 export {
 	## This record specifies the configuration that is passed to :bro:see:`NetControl::create_openflow`.
 	type OfConfig: record {
-		monitor: bool &default=T; ##< accept rules that target the monitor path
+		monitor: bool &default=T; ##< Accept rules that target the monitor path.
-		forward: bool &default=T; ##< accept rules that target the forward path
+		forward: bool &default=T; ##< Accept rules that target the forward path.
-		idle_timeout: count &default=0; ##< default OpenFlow idle timeout
+		idle_timeout: count &default=0; ##< Default OpenFlow idle timeout.
-		table_id: count &optional; ##< default OpenFlow table ID.
+		table_id: count &optional; ##< Default OpenFlow table ID.
-		priority_offset: int &default=+0; ##< add this to all rule priorities. Can be useful if you want the openflow priorities be offset from the netcontrol priorities without having to write a filter function.
+		priority_offset: int &default=+0; ##< Add this to all rule priorities. Can be useful if you want the openflow priorities be offset from the netcontrol priorities without having to write a filter function.
 
 		## Predicate that is called on rule insertion or removal.
 		##
@@ -21,7 +21,7 @@ export {
 		##
 		## r: The rule to be inserted or removed.
 		##
-		## Returns: T if the rule can be handled by the current backend, F otherwhise.
+		## Returns: T if the rule can be handled by the current backend, F otherwise.
 		check_pred: function(p: PluginState, r: Rule): bool &optional;
 
 		## This predicate is called each time an OpenFlow match record is created.
@@ -34,10 +34,10 @@ export {
 		##
 		## m: The openflow match structures that were generated for this rules.
 		##
-		## Returns: The modified OpenFlow match structures that will be used in place the structures passed in m.
+		## Returns: The modified OpenFlow match structures that will be used in place of the structures passed in m.
 		match_pred: function(p: PluginState, e: Entity, m: vector of OpenFlow::ofp_match): vector of OpenFlow::ofp_match &optional;
 
-		## This predicate is called before an FlowMod message is sent to the OpenFlow
+		## This predicate is called before a FlowMod message is sent to the OpenFlow
 		## device. It can modify the FlowMod message before it is passed on.
 		##
 		## p: Current plugin state.
@@ -46,14 +46,14 @@ export {
 		##
 		## m: The OpenFlow FlowMod message.
 		##
-		## Returns: The modified FloMod message that is used in lieu of m.
+		## Returns: The modified FlowMod message that is used in lieu of m.
 		flow_mod_pred: function(p: PluginState, r: Rule, m: OpenFlow::ofp_flow_mod): OpenFlow::ofp_flow_mod &optional;
 	};
 
 	redef record PluginState += {
-		## OpenFlow controller for NetControl OpenFlow plugin
+		## OpenFlow controller for NetControl OpenFlow plugin.
 		of_controller: OpenFlow::Controller &optional;
-		## OpenFlow configuration record that is passed on initialization
+		## OpenFlow configuration record that is passed on initialization.
 		of_config: OfConfig &optional;
 	};
 
@@ -66,11 +66,11 @@ export {
 		duration_sec: double &default=0.0;
 	};
 
-	## the time interval after which an openflow message is considered to be timed out
+	## The time interval after which an openflow message is considered to be timed out
 	## and we delete it from our internal tracking.
 	const openflow_message_timeout = 20secs &redef;
 
-	## the time interval after we consider a flow timed out. This should be fairly high (or
+	## The time interval after we consider a flow timed out. This should be fairly high (or
 	## even disabled) if you expect a lot of long flows. However, one also will have state
 	## buildup for quite a while if keeping this around...
 	const openflow_flow_timeout = 24hrs &redef;

scripts/base/frameworks/netcontrol/shunt.bro

@@ -11,21 +11,21 @@ export {
 	##
 	## f: The flow to shunt.
 	##
-	## t: How long to leave the shunt in place, with 0 being indefinitly.
+	## t: How long to leave the shunt in place, with 0 being indefinitely.
 	##
 	## location: An optional string describing where the shunt was triggered.
 	##
-	## Returns: The id of the inserted rule on succes and zero on failure.
+	## Returns: The id of the inserted rule on success and zero on failure.
 	global shunt_flow: function(f: flow_id, t: interval, location: string &default="") : string;
 
 	type ShuntInfo: record {
 		## Time at which the recorded activity occurred.
 		ts: time &log;
-		## ID of the rule; unique during each Bro run
+		## ID of the rule; unique during each Bro run.
 		rule_id: string  &log;
-		## Flow ID of the shunted flow
+		## Flow ID of the shunted flow.
 		f: flow_id &log;
-		## Expiry time of the shunt
+		## Expiry time of the shunt.
 		expire: interval &log;
 		## Location where the underlying action was triggered.
 		location: string &log &optional;

scripts/base/frameworks/netcontrol/types.bro

@@ -1,4 +1,4 @@
-##! This file defines the that are used by the NetControl framework.
+##! This file defines the types that are used by the NetControl framework.
 ##!
 ##! The most important type defined in this file is :bro:see:`NetControl::Rule`,
 ##! which is used to describe all rules that can be expressed by the NetControl framework. 
@@ -17,17 +17,16 @@ export {
 	## that have a :bro:see:`NetControl::RuleType` of :bro:enum:`NetControl::WHITELIST`.
 	const whitelist_priority: int = +5 &redef;
 
-	## The EntityType is used in :bro:id:`Entity` for defining the entity that a rule
+	## Type defining the entity that a rule applies to.
-	## applies to.
 	type EntityType: enum {
 		ADDRESS,	##< Activity involving a specific IP address.
 		CONNECTION,	##< Activity involving all of a bi-directional connection's activity.
-		FLOW,		##< Actitivy involving a uni-directional flow's activity. Can contain wildcards.
+		FLOW,		##< Activity involving a uni-directional flow's activity. Can contain wildcards.
 		MAC,		##< Activity involving a MAC address.
 	};
 
-	## Flow is used in :bro:id:`Entity` together with :bro:enum:`NetControl::FLOW` to specify
+	## Flow is used in :bro:type:`NetControl::Entity` together with :bro:enum:`NetControl::FLOW` to specify
-	## a uni-directional flow that a :bro:id:`Rule` applies to.
+	## a uni-directional flow that a rule applies to.
 	##
 	## If optional fields are not set, they are interpreted as wildcarded.
 	type Flow: record {
@@ -39,7 +38,7 @@ export {
 		dst_m: string &optional;	##< The destination MAC address.
 	};
 
-	## Type defining the entity an :bro:id:`Rule` is operating on.
+	## Type defining the entity a rule is operating on.
 	type Entity: record {
 		ty: EntityType;			##< Type of entity.
 		conn: conn_id &optional;	##< Used with :bro:enum:`NetControl::CONNECTION`.
@@ -48,7 +47,7 @@ export {
 		mac: string &optional;		##< Used with :bro:enum:`NetControl::MAC`.
 	};
 
-	## The :bro:id`TargetType` defined the target of a :bro:id:`Rule`.
+	## Type defining the target of a rule.
 	##
 	## Rules can either be applied to the forward path, affecting all network traffic, or
 	## on the monitor path, only affecting the traffic that is sent to Bro. The second
@@ -60,7 +59,7 @@ export {
 	};
 
 	## Type of rules that the framework supports. Each type lists the extra
-	## :bro:id:`Rule` argument(s) it uses, if any.
+	## :bro:type:`NetControl::Rule` fields it uses, if any.
 	##
 	## Plugins may extend this type to define their own.
 	type RuleType: enum {
@@ -81,7 +80,7 @@ export {
 		REDIRECT,
 
 		## Whitelists all packets of an entity, meaning no restrictions will be applied.
-		## While whitelisting is the default if no rule matches an this can type can be
+		## While whitelisting is the default if no rule matches, this type can be
 		## used to override lower-priority rules that would otherwise take effect for the
 		## entity.
 		WHITELIST,
@@ -92,7 +91,7 @@ export {
 		src_h: addr &optional;	##< The source IP address.
 		src_p: count &optional;	##< The source port number.
 		dst_h: addr &optional;	##< The destination IP address.
-		dst_p: count &optional;	##< The desintation port number.
+		dst_p: count &optional;	##< The destination port number.
 		src_m: string &optional;	##< The source MAC address.
 		dst_m: string &optional;	##< The destination MAC address.
 		redirect_port: count &optional;
@@ -121,8 +120,8 @@ export {
 	## That being said - their design makes sense and this is probably the data one
 	## can expect to be available.
 	type FlowInfo: record {
-		duration: interval &optional; ##< total duration of the rule
+		duration: interval &optional; ##< Total duration of the rule.
-		packet_count: count &optional; ##< number of packets exchanged over connections matched by the rule
+		packet_count: count &optional; ##< Number of packets exchanged over connections matched by the rule.
-		byte_count: count &optional; ##< total bytes exchanged over connections matched by the rule
+		byte_count: count &optional; ##< Total bytes exchanged over connections matched by the rule.
 	};
 }

scripts/base/frameworks/openflow/README

@@ -1,2 +1,2 @@
-The OpenFlow framework exposes the datastructures and functions
+The OpenFlow framework exposes the data structures and functions
 necessary to interface to OpenFlow capable hardware.

scripts/base/frameworks/openflow/consts.bro

@@ -1,7 +1,7 @@
 ##! Constants used by the OpenFlow framework.
 
 # All types/constants not specific to OpenFlow will be defined here
-# unitl they somehow get into Bro.
+# until they somehow get into Bro.
 
 module OpenFlow;
 
@@ -122,9 +122,9 @@ export {
 
 	## Return value for a cookie from a flow
 	## which is not added, modified or deleted
-	## from the bro openflow framework
+	## from the bro openflow framework.
 	const INVALID_COOKIE = 0xffffffffffffffff;
-	# Openflow pysical port definitions
+	# Openflow physical port definitions
 	## Send the packet out the input port. This
 	## virual port must be explicitly used in
 	## order to send back out of the input port.
@@ -135,10 +135,10 @@ export {
 	const OFPP_TABLE = 0xfffffff9;
 	## Process with normal L2/L3 switching.
 	const OFPP_NORMAL = 0xfffffffa;
-	## All pysical ports except input port and
+	## All physical ports except input port and
 	## those disabled by STP.
 	const OFPP_FLOOD = 0xfffffffb;
-	## All pysical ports except input port.
+	## All physical ports except input port.
 	const OFPP_ALL = 0xfffffffc;
 	## Send to controller.
 	const OFPP_CONTROLLER = 0xfffffffd;
@@ -162,7 +162,7 @@ export {
 	# flow stats and flow deletes.
 	const OFPTT_ALL = 0xff;
 
-	## Openflow action_type definitions
+	## Openflow action_type definitions.
 	##
 	## The openflow action type defines
 	## what actions openflow can take
@@ -180,7 +180,7 @@ export {
 		OFPAT_SET_DL_SRC = 0x0004,
 		## Ethernet destination address.
 		OFPAT_SET_DL_DST = 0x0005,
-		## IP source address
+		## IP source address.
 		OFPAT_SET_NW_SRC = 0x0006,
 		## IP destination address.
 		OFPAT_SET_NW_DST = 0x0007,
@@ -192,11 +192,11 @@ export {
 		OFPAT_SET_TP_DST = 0x000a,
 		## Output to queue.
 		OFPAT_ENQUEUE = 0x000b,
-		## Vendor specific
+		## Vendor specific.
 		OFPAT_VENDOR = 0xffff,
 	};
 
-	## Openflow flow_mod_command definitions
+	## Openflow flow_mod_command definitions.
 	##
 	## The openflow flow_mod_command describes
 	## of what kind an action is.
@@ -213,7 +213,7 @@ export {
 		OFPFC_DELETE_STRICT = 0x4,
 	};
 
-	## Openflow config flag definitions
+	## Openflow config flag definitions.
 	##
 	## TODO: describe
 	type ofp_config_flags: enum {

scripts/base/frameworks/openflow/main.bro

@@ -1,11 +1,11 @@
-##! Bro's OpenFlow control framework
+##! Bro's OpenFlow control framework.
 ##!
 ##! This plugin-based framework allows to control OpenFlow capable
 ##! switches by implementing communication to an OpenFlow controller
 ##! via plugins. The framework has to be instantiated via the new function
 ##! in one of the plugins. This framework only offers very low-level
 ##! functionality; if you want to use OpenFlow capable switches, e.g.,
-##! for shunting, please look at the PACF framework, which provides higher
+##! for shunting, please look at the NetControl framework, which provides higher
 ##! level functions and can use the OpenFlow framework as a backend.
 
 module OpenFlow;
@@ -16,7 +16,7 @@ module OpenFlow;
 export {
 	## Global flow_mod function.
 	##
-	## controller: The controller which should execute the flow modification
+	## controller: The controller which should execute the flow modification.
 	##
 	## match: The ofp_match record which describes the flow to match.
 	##
@@ -27,7 +27,7 @@ export {
 
 	## Clear the current flow table of the controller.
 	##
-	## controller: The controller which should execute the flow modification
+	## controller: The controller which should execute the flow modification.
 	##
 	## Returns: F on error or if the plugin does not support the operation, T when the operation was queued.
 	global flow_clear: function(controller: Controller): bool;
@@ -66,21 +66,21 @@ export {
 	##
 	## priority: The priority that was specified when creating the flow.
 	##
-	## reason: The reason for flow removal (OFPRR_*)
+	## reason: The reason for flow removal (OFPRR_*).
 	##
-	## duration_sec: duration of the flow in seconds
+	## duration_sec: Duration of the flow in seconds.
 	##
-	## packet_count: packet count of the flow
+	## packet_count: Packet count of the flow.
 	##
-	## byte_count: byte count of the flow
+	## byte_count: Byte count of the flow.
 	global flow_removed: event(name: string, match: ofp_match, cookie: count, priority: count, reason: count, duration_sec: count, idle_timeout: count, packet_count: count, byte_count: count);
 
 	## Convert a conn_id record into an ofp_match record that can be used to
 	## create match objects for OpenFlow.
 	##
-	## id: the conn_id record that describes the record.
+	## id: The conn_id record that describes the record.
 	##
-	## reverse: reverse the sources and destinations when creating the match record (default F)
+	## reverse: Reverse the sources and destinations when creating the match record (default F).
 	##
 	## Returns: ofp_match object for the conn_id record.
 	global match_conn: function(id: conn_id, reverse: bool &default=F): ofp_match;
@@ -113,18 +113,18 @@ export {
 	## Function to register a controller instance. This function
 	## is called automatically by the plugin _new functions.
 	##
-	## tpe: type of this plugin
+	## tpe: Type of this plugin.
 	##
-	## name: unique name of this controller instance.
+	## name: Unique name of this controller instance.
 	##
-	## controller: The controller to register
+	## controller: The controller to register.
 	global register_controller: function(tpe: OpenFlow::Plugin, name: string, controller: Controller);
 
 	## Function to unregister a controller instance. This function
 	## should be called when a specific controller should no longer
 	## be used.
 	##
-	## controller: The controller to unregister
+	## controller: The controller to unregister.
 	global unregister_controller: function(controller: Controller);
 
 	## Function to signal that a controller finished activation and is
@@ -134,16 +134,16 @@ export {
 
 	## Event that is raised once a controller finishes initialization
 	## and is completely activated.
-	## name: unique name of this controller instance.
+	## name: Unique name of this controller instance.
 	##
 	## controller: The controller that finished activation.
 	global OpenFlow::controller_activated: event(name: string, controller: Controller);
 
-	## Function to lookup a controller instance by name
+	## Function to lookup a controller instance by name.
 	##
-	## name: unique name of the controller to look up
+	## name: Unique name of the controller to look up.
 	##
-	## Returns: one element vector with controller, if found. Empty vector otherwhise.
+	## Returns: One element vector with controller, if found. Empty vector otherwise.
 	global lookup_controller: function(name: string): vector of Controller;
 }
 

scripts/base/frameworks/openflow/plugins/broker.bro

@@ -18,11 +18,11 @@ export {
 	##
 	## host_port: Controller listen port.
 	##
-	## topic: broker topic to send messages to.
+	## topic: Broker topic to send messages to.
 	##
 	## dpid: OpenFlow switch datapath id.
 	##
-	## Returns: OpenFlow::Controller record
+	## Returns: OpenFlow::Controller record.
 	global broker_new: function(name: string, host: addr, host_port: port, topic: string, dpid: count): OpenFlow::Controller;
 
 	redef record ControllerState += {
@@ -32,7 +32,7 @@ export {
 		broker_port: port &optional;
 		## OpenFlow switch datapath id.
 		broker_dpid: count &optional;
-		## Topic to sent events for this controller to
+		## Topic to send events for this controller to.
 		broker_topic: string &optional;
 	};
 

scripts/base/frameworks/openflow/plugins/log.bro

@@ -19,25 +19,25 @@ export {
 	##
 	## success_event: If true, flow_mod_success is raised for each logged line.
 	##
-	## Returns: OpenFlow::Controller record
+	## Returns: OpenFlow::Controller record.
 	global log_new: function(dpid: count, success_event: bool &default=T): OpenFlow::Controller;
 
 	redef record ControllerState += {
 		## OpenFlow switch datapath id.
 		log_dpid: count &optional;
-		## Raise or do not raise success event
+		## Raise or do not raise success event.
 		log_success_event: bool &optional;
 	};
 
 	## The record type which contains column fields of the OpenFlow log.
 	type Info: record {
-		## Network time
+		## Network time.
 		ts: time &log;
-		## OpenFlow switch datapath id
+		## OpenFlow switch datapath id.
 		dpid: count &log;
-		## OpenFlow match fields
+		## OpenFlow match fields.
 		match: ofp_match &log;
-		## OpenFlow modify flow entry message
+		## OpenFlow modify flow entry message.
 		flow_mod: ofp_flow_mod &log;
 	};
 

scripts/base/frameworks/openflow/plugins/ryu.bro

@@ -20,7 +20,7 @@ export {
 	##
 	## dpid: OpenFlow switch datapath id.
 	##
-	## Returns: OpenFlow::Controller record
+	## Returns: OpenFlow::Controller record.
 	global ryu_new: function(host: addr, host_port: count, dpid: count): OpenFlow::Controller;
 
 	redef record ControllerState += {
@@ -30,7 +30,7 @@ export {
 		ryu_port: count &optional;
 		## OpenFlow switch datapath id.
 		ryu_dpid: count &optional;
-		## Enable debug mode - output JSON to stdout; do not perform actions
+		## Enable debug mode - output JSON to stdout; do not perform actions.
 		ryu_debug: bool &default=F;
 	};
 }

scripts/base/frameworks/openflow/types.bro

@@ -5,9 +5,9 @@ module OpenFlow;
 @load ./consts
 
 export {
-	## Available openflow plugins
+	## Available openflow plugins.
 	type Plugin: enum {
-		## Internal placeholder plugin
+		## Internal placeholder plugin.
 		INVALID,
 	};
 
@@ -19,7 +19,7 @@ export {
 		_plugin: Plugin &optional;
 		## Internally set to the unique name of the controller.
 		_name: string &optional;
-		## Internally set to true once the controller is activated
+		## Internally set to true once the controller is activated.
 		_activated: bool &default=F;
 	} &redef;
 
@@ -58,29 +58,29 @@ export {
 	} &log;
 
 	## The actions that can be taken in a flow.
-	## (Sepearate record to make ofp_flow_mod less crowded)
+	## (Separate record to make ofp_flow_mod less crowded)
 	type ofp_flow_action: record {
 		## Output ports to send data to.
 		out_ports: vector of count &default=vector();
-		## set vlan vid to this value
+		## Set vlan vid to this value.
 		vlan_vid: count &optional;
-		## set vlan priority to this value
+		## Set vlan priority to this value.
 		vlan_pcp: count &optional;
-		## strip vlan tag
+		## Strip vlan tag.
 		vlan_strip: bool &default=F;
-		## set ethernet source address
+		## Set ethernet source address.
 		dl_src: string &optional;
-		## set ethernet destination address
+		## Set ethernet destination address.
 		dl_dst: string &optional;
-		## set ip tos to this value
+		## Set ip tos to this value.
 		nw_tos: count &optional;
-		## set source to this ip
+		## Set source to this ip.
 		nw_src: addr &optional;
-		## set destination to this ip
+		## Set destination to this ip.
 		nw_dst: addr &optional;
-		## set tcp/udp source port
+		## Set tcp/udp source port.
 		tp_src: count &optional;
-		## set tcp/udp destination port
+		## Set tcp/udp destination port.
 		tp_dst: count &optional;
 	} &log;
 
@@ -112,21 +112,21 @@ export {
 		actions: ofp_flow_action &default=ofp_flow_action();
 	} &log;
 
-	## Controller record representing an openflow controller
+	## Controller record representing an openflow controller.
 	type Controller: record {
 		## Controller related state.
 		state: ControllerState;
 		## Does the controller support the flow_removed event?
 		supports_flow_removed: bool;
-		## function that describes the controller. Has to be implemented.
+		## Function that describes the controller. Has to be implemented.
 		describe: function(state: ControllerState): string;
-		## one-time initialization function. If defined, controller_init_done has to be called once initialization finishes.
+		## One-time initialization function. If defined, controller_init_done has to be called once initialization finishes.
 		init: function (state: ControllerState) &optional;
-		## one-time destruction function
+		## One-time destruction function.
 		destroy: function (state: ControllerState) &optional;
-		## flow_mod function
+		## flow_mod function.
 		flow_mod: function(state: ControllerState, match: ofp_match, flow_mod: ofp_flow_mod): bool &optional;
-		## flow_clear function
+		## flow_clear function.
 		flow_clear: function(state: ControllerState): bool &optional;
 	};
 }

scripts/base/init-bare.bro

@@ -1129,7 +1129,7 @@ const CONTENTS_BOTH = 3;	##< Record both originator and responder contents.
 # Values for code of ICMP *unreachable* messages. The list is not exhaustive.
 # todo:: these should go into an enum to make them autodoc'able
 #
-# .. bro:see:: :bro:see:`icmp_unreachable `
+# .. bro:see:: icmp_unreachable
 const ICMP_UNREACH_NET = 0;	##< Network unreachable.
 const ICMP_UNREACH_HOST = 1;	##< Host unreachable.
 const ICMP_UNREACH_PROTOCOL = 2;	##< Protocol unreachable.
@@ -2540,7 +2540,7 @@ export {
 	## only comes into play as a heuristic to identify named
 	## pipes when the drive mapping wasn't seen by Bro.
 	##
-	## .. bro:see::smb_pipe_connect_heuristic
+	## .. bro:see:: smb_pipe_connect_heuristic
 	const SMB::pipe_filenames: set[string] &redef;
 }
 
@@ -2556,7 +2556,6 @@ export {
 	##    smb1_echo_response smb1_negotiate_request
 	##    smb1_negotiate_response smb1_nt_cancel_request
 	##    smb1_nt_create_andx_request smb1_nt_create_andx_response
-	##    smb1_open_andx_request smb1_open_andx_response
 	##    smb1_query_information_request smb1_read_andx_request
 	##    smb1_read_andx_response smb1_session_setup_andx_request
 	##    smb1_session_setup_andx_response smb1_transaction_request
@@ -2844,7 +2843,7 @@ export {
 	##    smb2_create_request smb2_create_response smb2_negotiate_request
 	##    smb2_negotiate_response smb2_read_request
 	##    smb2_session_setup_request smb2_session_setup_response
-	##    smb2_set_info_request smb2_file_rename smb2_file_delete
+	##    smb2_file_rename smb2_file_delete
 	##    smb2_tree_connect_request smb2_tree_connect_response
 	##    smb2_write_request
 	type SMB2::Header: record {
@@ -3099,7 +3098,7 @@ type dns_edns_additional: record {
 
 ## An additional DNS TSIG record.
 ##
-## bro:see:: dns_TSIG_addl
+## .. bro:see:: dns_TSIG_addl
 type dns_tsig_additional: record {
 	query: string;	##< Query.
 	qtype: count;	##< Query type.

scripts/base/protocols/dce-rpc/main.bro

@@ -26,29 +26,29 @@ export {
 		operation  : string   &log &optional;
 	};
 
-	## These are DCE-RPC operations that are ignored, typically due 
+	## These are DCE-RPC operations that are ignored, typically due to
-	## the operations being noisy and low valueon most networks.
+	## the operations being noisy and low value on most networks.
 	const ignored_operations: table[string] of set[string] = {
 		["winreg"] = set("BaseRegCloseKey", "BaseRegGetVersion", "BaseRegOpenKey", "BaseRegQueryValue", "BaseRegDeleteKeyEx", "OpenLocalMachine", "BaseRegEnumKey", "OpenClassesRoot"),
 		["spoolss"] = set("RpcSplOpenPrinter", "RpcClosePrinter"),
 		["wkssvc"] = set("NetrWkstaGetInfo"),
 	} &redef;
+
+	type State: record {
+		uuid       : string &optional;
+		named_pipe : string &optional;
+	};
+
+	# This is to store the log and state information
+	# for multiple DCE/RPC bindings over a single TCP connection (named pipes).
+	type BackingState: record {
+		info: Info;
+		state: State;
+	};
 }
 
 redef DPD::ignore_violations += { Analyzer::ANALYZER_DCE_RPC };
 
-type State: record {
-	uuid       : string &optional;
-	named_pipe : string &optional;
-};
-
-# This is to store the log and state information 
-# for multiple DCE/RPC bindings over a single TCP connection (named pipes).
-type BackingState: record {
-	info: Info;
-	state: State;
-};
-
 redef record connection += {
 	dce_rpc: Info &optional;
 	dce_rpc_state: State &optional;
@@ -158,7 +158,7 @@ event dce_rpc_response(c: connection, fid: count, opnum: count, stub_len: count)
 	{
 	if ( c?$dce_rpc )
 		{
-		# If there is noendpoint, there isn't much reason to log.
+		# If there is no endpoint, there isn't much reason to log.
 		# This can happen if the request isn't seen.
 		if ( ( c$dce_rpc?$endpoint && c$dce_rpc?$operation ) &&
 		     ( c$dce_rpc$endpoint !in ignored_operations

scripts/base/protocols/http/entities.bro

@@ -17,7 +17,7 @@ export {
 		## An ordered vector of file unique IDs.
 		orig_fuids:      vector of string &log &optional;
 
-		## An order vector of filenames from the client.
+		## An ordered vector of filenames from the client.
 		orig_filenames:  vector of string &log &optional;
 
 		## An ordered vector of mime types.
@@ -26,7 +26,7 @@ export {
 		## An ordered vector of file unique IDs.
 		resp_fuids:      vector of string &log &optional;
 
-		## An order vector of filenames from the server.
+		## An ordered vector of filenames from the server.
 		resp_filenames:  vector of string &log &optional;
 
 		## An ordered vector of mime types.

scripts/base/protocols/rfb/main.bro

@@ -18,12 +18,12 @@ export {
 		client_minor_version: string &log &optional;
 		## Major version of the server.
 		server_major_version: string &log &optional;
-		## Major version of the client.
+		## Minor version of the server.
 		server_minor_version: string &log &optional;
 
 		## Identifier of authentication method used.
 		authentication_method: string &log &optional;
-		## Whether or not authentication was succesful.
+		## Whether or not authentication was successful.
 		auth: bool &log &optional;
 
 		## Whether the client has an exclusive or a shared session.

scripts/base/protocols/smb/consts.bro

@@ -24,13 +24,13 @@ export {
 		"MsFteWds",
 	};
 
-	## The UUIDs used by the various RPC endpoints
+	## The UUIDs used by the various RPC endpoints.
 	const rpc_uuids: table[string] of string = {
 		["4b324fc8-1670-01d3-1278-5a47bf6ee188"] = "Server Service",
 		["6bffd098-a112-3610-9833-46c3f87e345a"] = "Workstation Service",
 	} &redef &default=function(i: string):string { return fmt("unknown-uuid-%s", i); };
 
-	## Server service sub commands
+	## Server service sub commands.
 	const srv_cmds: table[count] of string = {
 		[8]  = "NetrConnectionEnum",
 		[9]  = "NetrFileEnum",
@@ -81,7 +81,7 @@ export {
 		[57] = "NetrShareDelEx",
 	} &redef &default=function(i: count):string { return fmt("unknown-srv-command-%d", i); };
 
-	## Workstation service sub commands
+	## Workstation service sub commands.
 	const wksta_cmds: table[count] of string = {
 		[0]  = "NetrWkstaGetInfo",
 		[1]  = "NetrWkstaSetInfo",
@@ -108,7 +108,7 @@ export {
 
 	type rpc_cmd_table: table[count] of string;
 	
-	## The subcommands for RPC endpoints
+	## The subcommands for RPC endpoints.
 	const rpc_sub_cmds: table[string] of rpc_cmd_table = {
 		["4b324fc8-1670-01d3-1278-5a47bf6ee188"] = srv_cmds,
 		["6bffd098-a112-3610-9833-46c3f87e345a"] = wksta_cmds,	

scripts/base/protocols/ssl/consts.bro

@@ -30,7 +30,7 @@ export {
 		return fmt("unknown-%d", i);
 		};
 
-	## TLS content types:
+	# TLS content types:
 	const CHANGE_CIPHER_SPEC = 20;
 	const ALERT = 21;
 	const HANDSHAKE = 22;
@@ -41,7 +41,7 @@ export {
 	const V2_CLIENT_MASTER_KEY = 302;
 	const V2_SERVER_HELLO = 304;
 
-	## TLS Handshake types:
+	# TLS Handshake types:
 	const HELLO_REQUEST       = 0;
 	const CLIENT_HELLO        = 1;
 	const SERVER_HELLO        = 2;
@@ -215,7 +215,7 @@ export {
 		[0xFF02] = "arbitrary_explicit_char2_curves"
 	} &default=function(i: count):string { return fmt("unknown-%d", i); };
 
-	## Mapping between numeric codes and human readable string for SSL/TLC EC point formats.
+	## Mapping between numeric codes and human readable string for SSL/TLS EC point formats.
 	# See http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-9
 	const ec_point_formats: table[count] of string = {
 		[0] = "uncompressed",

scripts/base/protocols/ssl/files.bro

@@ -11,7 +11,7 @@ export {
 		## complete signing chain.
 		cert_chain: vector of Files::Info &optional;
 
-		## An ordered vector of all certicate file unique IDs for the
+		## An ordered vector of all certificate file unique IDs for the
 		## certificates offered by the server.
 		cert_chain_fuids: vector of string &optional &log;
 
@@ -19,7 +19,7 @@ export {
 		## complete signing chain.
 		client_cert_chain: vector of Files::Info &optional;
 
-		## An ordered vector of all certicate file unique IDs for the
+		## An ordered vector of all certificate file unique IDs for the
 		## certificates offered by the client.
 		client_cert_chain_fuids: vector of string &optional &log;
 
@@ -116,8 +116,8 @@ event file_over_new_connection(f: fa_file, c: connection, is_orig: bool) &priori
 		}
 
 	Files::add_analyzer(f, Files::ANALYZER_X509);
-	# always calculate hashes. They are not necessary for base scripts
+	# Always calculate hashes. They are not necessary for base scripts
-	# but very useful for identification, and required for policy scripts
+	# but very useful for identification, and required for policy scripts.
 	Files::add_analyzer(f, Files::ANALYZER_MD5);
 	Files::add_analyzer(f, Files::ANALYZER_SHA1);
 	}

scripts/base/protocols/ssl/main.bro

@@ -44,10 +44,10 @@ export {
 		## is being resumed. It's not logged.
 		client_key_exchange_seen: bool     &default=F;
 		## Count to track if the server already sent an application data
-		## packet fot TLS 1.3. Used to track when a session was established.
+		## packet for TLS 1.3. Used to track when a session was established.
 		server_appdata:   count            &default=0;
 		## Flag to track if the client already sent an application data
-		## packet fot TLS 1.3. Used to track when a session was established.
+		## packet for TLS 1.3. Used to track when a session was established.
 		client_appdata:   bool             &default=F;
 
 		## Last alert that was seen during the connection.
@@ -62,7 +62,7 @@ export {
 		analyzer_id:      count            &optional;
 
 		## Flag to indicate if this ssl session has been established
-		## succesfully, or if it was aborted during the handshake.
+		## successfully, or if it was aborted during the handshake.
 		established:      bool             &log &default=F;
 
 		## Flag to indicate if this record already has been logged, to

scripts/policy/frameworks/intel/do_notice.bro

@@ -7,7 +7,7 @@ module Intel;
 
 export {
 	redef enum Notice::Type += {
-		## Intel::Notice is a notice that happens when an intelligence
+		## This notice is generated when an intelligence
 		## indicator is denoted to be notice-worthy.
 		Intel::Notice
 	};

scripts/policy/misc/stats.bro

@@ -74,7 +74,7 @@ export {
 		reassem_file_size: count &log;
 		## Current size of packet fragment data in reassembly.
 		reassem_frag_size: count &log;
-		## Current size of unkown data in reassembly (this is only PIA buffer right now).
+		## Current size of unknown data in reassembly (this is only PIA buffer right now).
 		reassem_unknown_size: count &log;
 	};
 

scripts/policy/protocols/conn/vlan-logging.bro

@@ -1,4 +1,4 @@
-##! This script add VLAN information to the connection logs
+##! This script adds VLAN information to the connection log.
 
 @load base/protocols/conn
 

scripts/policy/protocols/smb/main.bro

@@ -64,7 +64,7 @@ export {
 		name			: string  &log &optional;
 		## Total size of the file.
 		size			: count   &log &default=0;
-		## If the rename action was seen, this will 
+		## If the rename action was seen, this will be
 		## the file's previous name.
 		prev_name		: string  &log &optional;
 		## Last time this file was modified.
@@ -82,7 +82,7 @@ export {
 
 		## Name of the tree path.
 		path                : string &log &optional;
-		## The type of resource of the tree (disk share, printer share, named pipe, etc.)
+		## The type of resource of the tree (disk share, printer share, named pipe, etc.).
 		service             : string &log &optional;
 		## File system of the tree.
 		native_file_system  : string &log &optional;
@@ -93,34 +93,34 @@ export {
 
 	## This record is for the smb_cmd.log
 	type CmdInfo: record {
-		## Timestamp of the command request
+		## Timestamp of the command request.
 		ts				: time &log;
-		## Unique ID of the connection the request was sent over
+		## Unique ID of the connection the request was sent over.
 		uid				: string &log;
-		## ID of the connection the request was sent over
+		## ID of the connection the request was sent over.
 		id				: conn_id &log;
 		
-		## The command sent by the client
+		## The command sent by the client.
 		command			: string &log;
-		## The subcommand sent by the client, if present
+		## The subcommand sent by the client, if present.
 		sub_command		: string &log &optional;
-		## Command argument sent by the client, if any
+		## Command argument sent by the client, if any.
 		argument		: string &log &optional;
 		
-		## Server reply to the client's command
+		## Server reply to the client's command.
 		status			: string &log &optional;
 		## Round trip time from the request to the response.
 		rtt				: interval &log &optional;
-		## Version of SMB for the command
+		## Version of SMB for the command.
 		version			: string &log;
 
-		## Authenticated username, if available
+		## Authenticated username, if available.
 		username		: string &log &optional;
 		
 		## If this is related to a tree, this is the tree
 		## that was used for the current command.
 		tree			: string &log &optional;
-		## The type of tree (disk share, printer share, named pipe, etc.)
+		## The type of tree (disk share, printer share, named pipe, etc.).
 		tree_service	: string &log &optional;
 		
 		## If the command referenced a file, store it here.
@@ -166,8 +166,8 @@ export {
 		smb_state : State &optional;
 	};
 	
-	## Internal use only
+	## Internal use only.
-	## Some commands shouldn't be logged by the smb1_message event
+	## Some commands shouldn't be logged by the smb1_message event.
 	const deferred_logging_cmds: set[string] = {
 		"NEGOTIATE",
 		"READ_ANDX",
@@ -186,7 +186,7 @@ redef record FileInfo += {
 	## ID referencing this file.
 	fid  : count   &optional;
 
-	## UUID referencing this file if DCE/RPC
+	## UUID referencing this file if DCE/RPC.
 	uuid : string &optional;
 };
 
@@ -264,4 +264,4 @@ event file_state_remove(f: fa_file) &priority=-5
 			}
 		return;
 		}
-	}
+	}

scripts/policy/protocols/smb/smb1-main.bro

@@ -3,7 +3,7 @@
 module SMB1;
 
 redef record SMB::CmdInfo += {
-	## Dialects offered by the client	
+	## Dialects offered by the client.
 	smb1_offered_dialects: string_vec &optional;
 };
 

scripts/policy/protocols/smb/smb2-main.bro

@@ -3,7 +3,7 @@
 module SMB2;
 
 redef record SMB::CmdInfo += {
-	## Dialects offered by the client	
+	## Dialects offered by the client.
 	smb2_offered_dialects: index_vec &optional;
 };
 

scripts/policy/protocols/ssl/heartbleed.bro

@@ -13,7 +13,7 @@ export {
 		SSL_Heartbeat_Attack_Success,
 		## Indicates we saw heartbeat requests with odd length. Probably an attack or scan.
 		SSL_Heartbeat_Odd_Length,
-		## Indicates we saw many heartbeat requests without an reply. Might be an attack.
+		## Indicates we saw many heartbeat requests without a reply. Might be an attack.
 		SSL_Heartbeat_Many_Requests
 	};
 }

src/analyzer/protocol/smb/smb2_com_set_info.bif

@@ -11,7 +11,7 @@
 ##
 ## dst_filename: The filename to rename the file into.
 ##
-## .. bro:see:: smb2_message smb2_set_info_request smb2_file_delete
+## .. bro:see:: smb2_message smb2_file_delete
 event smb2_file_rename%(c: connection, hdr: SMB2::Header, file_id: SMB2::GUID, dst_filename: string%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
@@ -26,7 +26,7 @@ event smb2_file_rename%(c: connection, hdr: SMB2::Header, file_id: SMB2::GUID, d
 ## delete_pending: A boolean value to indicate that a file should be deleted 
 ##                 when it's closed if set to T.
 ##
-## .. bro:see:: smb2_message smb2_set_info_request smb2_file_rename
+## .. bro:see:: smb2_message smb2_file_rename
 event smb2_file_delete%(c: connection, hdr: SMB2::Header, file_id: SMB2::GUID, delete_pending: bool%);
 
 # TODO - Not implemented

src/bro.bif

@@ -1029,7 +1029,7 @@ function clear_table%(v: any%): any
 	return 0;
 	%}
 
-## Gets all subnets that contain a given subnet from a set/table[subnet]
+## Gets all subnets that contain a given subnet from a set/table[subnet].
 ##
 ## search: the subnet to search for.
 ##
@@ -1047,8 +1047,8 @@ function matching_subnets%(search: subnet, t: any%): subnet_vec
 	return t->AsTableVal()->LookupSubnets(search);
 	%}
 
-## For a set[subnet]/table[subnet], create a new table that contains all entries that
+## For a set[subnet]/table[subnet], create a new table that contains all entries
-## contain a given subnet.
+## that contain a given subnet.
 ##
 ## search: the subnet to search for.
 ##
@@ -1067,7 +1067,7 @@ function filter_subnet_table%(search: subnet, t: any%): any
 	%}
 
 ## Checks if a specific subnet is a member of a set/table[subnet].
-## In difference to the ``in`` operator, this performs an exact match, not
+## In contrast to the ``in`` operator, this performs an exact match, not
 ## a longest prefix match.
 ##
 ## search: the subnet to search for.
@@ -1994,7 +1994,7 @@ function is_v6_addr%(a: addr%): bool
 ##
 ## s: the subnet to check.
 ##
-## Returns: true if *a* is an IPv4 subnet, else false.
+## Returns: true if *s* is an IPv4 subnet, else false.
 function is_v4_subnet%(s: subnet%): bool
 	%{
 	if ( s->AsSubNet().Prefix().GetFamily() == IPv4 )
@@ -2007,7 +2007,7 @@ function is_v4_subnet%(s: subnet%): bool
 ##
 ## s: the subnet to check.
 ##
-## Returns: true if *a* is an IPv6 subnet, else false.
+## Returns: true if *s* is an IPv6 subnet, else false.
 function is_v6_subnet%(s: subnet%): bool
 	%{
 	if ( s->AsSubNet().Prefix().GetFamily() == IPv6 )
@@ -2311,7 +2311,7 @@ function to_subnet%(sn: string%): subnet
 ##
 ## a: The address to convert.
 ##
-## Returns: The *a* address as a :bro:type:`subnet`.
+## Returns: The address as a :bro:type:`subnet`.
 ##
 ## .. bro:see:: to_subnet
 function addr_to_subnet%(a: addr%): subnet
@@ -2320,12 +2320,12 @@ function addr_to_subnet%(a: addr%): subnet
 	return new SubNetVal(a->AsAddr(), width);
 	%}
 
-## Converts a :bro:type:`subnet` to a :bro:type:`addr` by
+## Converts a :bro:type:`subnet` to an :bro:type:`addr` by
 ## extracting the prefix.
 ##
-## s: The subnet to convert.
+## sn: The subnet to convert.
 ##
-## Returns: The *s* subnet as a :bro:type:`addr`.
+## Returns: The subnet as an :bro:type:`addr`.
 ##
 ## .. bro:see:: to_subnet
 function subnet_to_addr%(sn: subnet%): addr
@@ -2335,7 +2335,7 @@ function subnet_to_addr%(sn: subnet%): addr
 
 ## Returns the width of a :bro:type:`subnet`.
 ##
-## s: The subnet to convert.
+## sn: The subnet.
 ##
 ## Returns: The width of the subnet.
 ##

testing/btest/Baseline/scripts.base.frameworks.intel.remove-non-existing/output

@@ -6,6 +6,6 @@
 #open	2016-09-20-22-35-58
 #fields	ts	level	message	location
 #types	time	enum	string	string
-0.000000	Reporter::INFO	Tried to remove non-existing item '192.168.1.1' (Intel::ADDR).	/home/jgras/devel/bro/scripts/base/frameworks/intel/./main.bro, lines 506-507
+0.000000	Reporter::INFO	Tried to remove non-existing item '192.168.1.1' (Intel::ADDR).	/home/jgras/devel/bro/scripts/base/frameworks/intel/./main.bro, lines 507-508
 0.000000	Reporter::INFO	received termination signal	(empty)
 #close	2016-09-20-22-35-59