Merge remote-tracking branch 'origin/topic/christian/file-event-docst…

…rings'

* origin/topic/christian/file-event-docstrings:
  Expand docstrings of file_new and file_over_new_connection events

CHANGES

@@ -1,3 +1,39 @@
+5.2.0-dev.464 | 2023-01-10 10:25:28 +0100
+
+  * Expand docstrings of file_new and file_over_new_connection events (Christian Kreibich, Corelight)
+
+  * GH-2031: analyzer: Add analyzer.log for logging violations/confirmations (Arne Welzel, Corelight)
+
+    By default this only logs all the violations, regardless of the
+    confirmation state (for which there's still dpd.log). It includes
+    packet, protocol and file analyzers.
+
+    This uses options, change handlers and event groups for toggling
+    the functionality at runtime.
+
+  * GH-2647: intel/seen/file-names: Use file_over_new_connection() (Arne Welzel, Corelight)
+
+    The seen/file-names script relies on f$info$filename to be populated.
+    For HTTP and other network protocols, however, this field is only
+    populated during file_over_new_connection() that's running after
+    file_new().
+
+    Use the file_new() event only for files without connections and
+    file_over_new_connection() implies that f$conns is populated, anyway.
+
+    Special case SMB to avoid finding files twice, because there's a
+    custom implementation in seen/smb-filenames.zeek.
+
+  * scripts/analyzer: Introduce Analyzer::requested_analyzers (Arne Welzel, Corelight)
+
+    In certain deployment scenarios, all analyzers are disabled by default.
+    However, conditionally/optionally loaded scripts may rely on analyzers
+    functioning and declare a request for them.
+
+    Add a global set set to the Analyzer module where external scripts can record
+    their requirement/request for a certain analyzer. Analyzers found in this
+    set are enabled at zeek_init() time.
+
 5.2.0-dev.453 | 2023-01-05 09:53:47 -0700
 
   * Add error and abort if fuzzer requested is not found (Tim Wojtulewicz, Corelight)

VERSION

@@ -1 +1 @@
-5.2.0-dev.453
+5.2.0-dev.464

src/event.bif

@@ -737,17 +737,28 @@ event event_queue_flush_point%(%);
 ## .. zeek:see:: set_file_handle
 event get_file_handle%(tag: Analyzer::Tag, c: connection, is_orig: bool%);
 
-## Indicates that an analysis of a new file has begun. The analysis can be
-## augmented at this time via :zeek:see:`Files::add_analyzer`.
+## Indicates that analysis of a new file has begun.  The analysis can be
+## augmented at this time via :zeek:see:`Files::add_analyzer`.  This event
+## triggers once when Zeek first establishes state for the file.  Zeek does not
+## base identity on content (it cannot, since analysis has only just begun), but
+## on the relevant protocol analyzer's notion of file identity as per the
+## :zeek:see:`get_file_handle`/:zeek:see:`set_file_handle` mechanism.  That is,
+## Zeek triggers this event whenever a protocol analyzer thinks it's
+## encountering a new file.
 ##
 ## f: The file.
 ##
 ## .. zeek:see:: file_over_new_connection file_timeout file_gap
 ##    file_sniff file_state_remove
 event file_new%(f: fa_file%);
 
-## Indicates that a file has been seen being transferred over a connection
-## different from the original.
+## Indicates that Zeek has begun to observe a file for the first time on the
+## given connection.  This is similar to :zeek:see:`file_new`, but also triggers
+## once on each subsequent connection in which the relevant protocol analyzer
+## encounters any part of the file.  As with :zeek:see:`file_new`, the protocol
+## analyzer defines file identity.  When Zeek encounters a file for the first
+## time, it first triggers :zeek:see:`file_new`, then
+## :zeek:see:`file_over_new_connection`.
 ##
 ## f: The file.
 ##