Add descriptions for what the SMB1 events do, and references to the specification.

scripts/base/init-bare.bro

@@ -2519,10 +2519,18 @@ module SMB;
 
 export {
 	## MAC times for a file.
+	##
+	## For more information, see MS-SMB2:2.2.16
+	##
+	## .. bro:see:: smb1_nt_create_andx_response smb2_create_response
 	type SMB::MACTimes: record {
+		## The time when data was last written to the file.
 		modified : time &log;
+		## The time when the file was last accessed.
 		accessed : time &log;
+		## The time the file was created.
 		created  : time &log;
+		## The time when the file was last modified.
 		changed  : time &log;
 	} &log;
 }

src/analyzer/protocol/smb/smb1_com_check_directory.bif

@@ -1,5 +1,8 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *check directory*.
+## version 1 requests of type *check directory*. This is used by the client to verify that
+## a specified path resolves to a valid directory on the server.
+##
+## For more information, see MS-CIFS:2.2.4.17
 ##
 ## c: The connection.
 ##
@@ -11,7 +14,10 @@
 event smb1_check_directory_request%(c: connection, hdr: SMB1::Header, directory_name: string%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 responses of type *check directory*.
+## version 1 responses of type *check directory*. This is the server response to the
+## *check directory* request.
+##
+## For more information, see MS-CIFS:2.2.4.17
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_close.bif

@@ -1,5 +1,8 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *close*.
+## version 1 requests of type *close*. This is used by the client to close an instance of an object
+## associated with a valid file ID.
+##
+## For more information, see MS-CIFS:2.2.4.5
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_create_directory.bif

@@ -1,6 +1,9 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *create directory*.  This is also a deprecated command which
+## version 1 requests of type *create directory*. This is a deprecated command which
-## has been replaced by the trans2_create_directory subcommand.
+## has been replaced by the *trans2_create_directory* subcommand. This is used by the client to
+## create a new directory on the server, relative to a connected share.
+##
+## For more information, see MS-CIFS:2.2.4.1
 ##
 ## c: The connection.
 ##
@@ -12,8 +15,11 @@
 event smb1_create_directory_request%(c: connection, hdr: SMB1::Header, directory_name: string%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 responses of type *create directory*.  This is also a deprecated command which
+## version 1 responses of type *create directory*. This is a deprecated command which
-## has been replaced by the trans2_create_directory subcommand.
+## has been replaced by the *trans2_create_directory* subcommand. This is the server response
+## to the *create directory* request.
+##
+## For more information, see MS-CIFS:2.2.4.1
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_echo.bif

@@ -1,5 +1,8 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *echo*.
+## version 1 requests of type *echo*. This is sent by the client to test the transport layer
+## connection with the server.
+##
+## For more information, see MS-CIFS:2.2.4.39
 ##
 ## c: The connection.
 ##
@@ -13,7 +16,9 @@
 event smb1_echo_request%(c: connection, echo_count: count, data: string%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 responses of type *echo*.
+## version 1 responses of type *echo*. This is the server response to the *echo* request.
+##
+## For more information, see MS-CIFS:2.2.4.39
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_logoff_andx.bif

@@ -1,5 +1,10 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *logoff andx*.
+## version 1 requests of type *logoff andx*. This is used by the client to logoff the user
+## connection represented by UID in the SMB Header. The server releases all locks and closes
+## all files currently open by this user, disconnects all tree connects, cancels any outstanding
+## requests for this UID, and invalidates the UID.
+##
+## For more information, see MS-CIFS:2.2.4.54
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_negotiate.bif

@@ -1,5 +1,9 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *negotiate*.
+## version 1 requests of type *negotiate*. This is sent by the client to initiate an SMB
+## connection between the client and the server. A *negotiate* exchange MUST be completed
+## before any other SMB messages are sent to the server.
+##
+## For more information, see MS-CIFS:2.2.4.52
 ##
 ## c: The connection.
 ##
@@ -11,7 +15,10 @@
 event smb1_negotiate_request%(c: connection, hdr: SMB1::Header, dialects: string_vec%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 responses of type *negotiate*.
+## version 1 responses of type *negotiate*. This is the server response to the *negotiate*
+## request.
+##
+## For more information, see MS-CIFS:2.2.4.52
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_nt_cancel.bif

@@ -1,5 +1,8 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *nt cancel*.
+## version 1 requests of type *nt cancel*. This is sent by the client to request that a currently
+## pending request be cancelled.
+##
+## For more information, see MS-CIFS:2.2.4.65
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_nt_create_andx.bif

@@ -1,5 +1,9 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *nt create andx*.
+## version 1 requests of type *nt create andx*. This is sent by the client to create and open
+## a new file, or to open an existing file, or to open and truncate an existing file to zero
+## length, or to create a directory, or to create a connection to a named pipe.
+##
+## For more information, see MS-CIFS:2.2.4.64
 ##
 ## c: The connection.
 ##
@@ -11,7 +15,10 @@
 event smb1_nt_create_andx_request%(c: connection, hdr: SMB1::Header, file_name: string%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 responses of type *nt create andx*.
+## version 1 responses of type *nt create andx*. This is the server response to the
+## *nt create andx* request.
+##
+## For more information, see MS-CIFS:2.2.4.64
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_open_andx.bif

@@ -1,5 +1,8 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *open andx*.
+## version 1 requests of type *open andx*. This is sent by the client to create and open a new
+## file or open an existing regular file and chain additional messages along with the request.
+##
+## For more information, see MS-CIFS:2.2.4.41
 ##
 ## c: The connection.
 ##
@@ -23,7 +26,9 @@
 event smb1_open_andx_request%(c: connection, hdr: SMB1::Header, file_id: count, offset: count, length: count%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 responses of type *open andx*.
+## version 1 responses of type *open andx*. This is the server response to the *open andx* request.
+##
+## For more information, see MS-CIFS:2.2.4.41
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_query_information.bif

@@ -1,5 +1,9 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *query information*.
+## version 1 requests of type *query information*. This is a deprecated command which
+## has been replaced by the *trans2_query_path_information* subcommand. This is used by the
+## client to obtain attribute information about a file.
+##
+## For more information, see MS-CIFS:2.2.4.9
 ##
 ## c: The connection.
 ##
@@ -7,6 +11,6 @@
 ##
 ## filename: The filename that the client is querying.
 ##
-## .. bro:see:: smb1_message
+## .. bro:see:: smb1_message smb1_transaction2_request
 event smb1_query_information_request%(c: connection, hdr: SMB1::Header, filename: string%);
 

src/analyzer/protocol/smb/smb1_com_read_andx.bif

@@ -1,5 +1,9 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *read andx*.
+## version 1 requests of type *read andx*. This is sent by the client to read bytes from a regular
+## file, a named pipe, or a directly accessible device such as a serial port (COM) or printer
+## port (LPT).
+##
+## For more information, see MS-CIFS:2.2.4.42
 ##
 ## c: The connection.
 ##
@@ -15,7 +19,9 @@
 event smb1_read_andx_request%(c: connection, hdr: SMB1::Header, file_id: count, offset: count, length: count%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 responses of type *read andx*.
+## version 1 responses of type *read andx*. This is the server response to the *read andx* request.
+##
+## For more information, see MS-CIFS:2.2.4.42
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_session_setup_andx.bif

@@ -1,5 +1,7 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *setup andx*.
+## version 1 requests of type *setup andx*. This is sent by the client to configure an SMB session.
+##
+## For more information, see MS-CIFS:2.2.4.53
 ##
 ## c: The connection.
 ##
@@ -11,7 +13,9 @@
 event smb1_session_setup_andx_request%(c: connection, hdr: SMB1::Header, request: SMB1::SessionSetupAndXRequest%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 responses of type *setup andx*.
+## version 1 responses of type *setup andx*. This is the server response to the *setup andx* request.
+##
+## For more information, see MS-CIFS:2.2.4.53
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_transaction.bif

@@ -1,5 +1,9 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *transaction*.
+## version 1 requests of type *transaction*. This command serves as the transport for the
+## Transaction Subprotocol Commands. These commands operate on mailslots and named pipes,
+## which are interprocess communication endpoints within the CIFS file system.
+##
+## For more information, see MS-CIFS:2.2.4.33
 ##
 ## c: The connection.
 ##
@@ -10,5 +14,5 @@
 ##
 ## sub_cmd: The sub command, some may be parsed and have their own events.
 ##
-## .. bro:see:: smb1_message
+## .. bro:see:: smb1_message smb1_transaction2_request
 event smb1_transaction_request%(c: connection, hdr: SMB1::Header, name: string, sub_cmd: count%);

src/analyzer/protocol/smb/smb1_com_transaction2.bif

@@ -1,6 +1,13 @@
 ### Requests
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *transaction2*.
+## version 1 requests of type *transaction2*. This command serves as the transport for the
+## Transaction2 Subprotocol Commands. These commands operate on mailslots and named pipes,
+## which are interprocess communication endpoints within the CIFS file system. Compared to the
+## Transaction Subprotocol Commands, these commands allow clients to set and retrieve Extended
+## Attribute key/value pairs, make use of long file names (longer than the original 8.3 format
+## names), and perform directory searches, among other tasks.
+##
+## For more information, see MS-CIFS:2.2.4.46
 ##
 ## c: The connection.
 ##
@@ -8,11 +15,15 @@
 ##
 ## sub_cmd: The sub command, some are parsed and have their own events.
 ##
-## .. bro:see:: smb1_message smb1_trans2_find_first2_request smb1_trans2_query_path_info_request smb1_trans2_get_dfs_referral_request
+## .. bro:see:: smb1_message smb1_trans2_find_first2_request smb1_trans2_query_path_info_request
+##    smb1_trans2_get_dfs_referral_request smb1_transaction_request
 event smb1_transaction2_request%(c: connection, hdr: SMB1::Header, sub_cmd: count%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *find first2*.
+## version 1 *transaction2* requests of subtype *find first2*. This transaction is used to begin
+## a search for file(s) within a directory or for a directory
+##
+## For more information, see MS-CIFS:2.2.6.2
 ##
 ## c: The connection.
 ##
@@ -20,11 +31,15 @@ event smb1_transaction2_request%(c: connection, hdr: SMB1::Header, sub_cmd: coun
 ##
 ## args: A record data structure with arguments given to the command.
 ##
-## .. bro:see:: smb1_message smb1_transaction2_request smb1_trans2_query_path_info_request smb1_trans2_get_dfs_referral_request
+## .. bro:see:: smb1_message smb1_transaction2_request smb1_trans2_query_path_info_request
+##    smb1_trans2_get_dfs_referral_request
 event smb1_trans2_find_first2_request%(c: connection, hdr: SMB1::Header, args: SMB1::Find_First2_Request_Args%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *query path info*.
+## version 1 *transaction2* requests of subtype *query path info*. This transaction is used to
+## get information about a specific file or directory.
+##
+## For more information, see MS-CIFS:2.2.6.6
 ##
 ## c: The connection.
 ##
@@ -32,11 +47,15 @@ event smb1_trans2_find_first2_request%(c: connection, hdr: SMB1::Header, args: S
 ##
 ## file_name: File name the request is in reference to. 
 ##
-## .. bro:see:: smb1_message smb1_transaction2_request smb1_trans2_find_first2_request smb1_trans2_get_dfs_referral_request
+## .. bro:see:: smb1_message smb1_transaction2_request smb1_trans2_find_first2_request
+##    smb1_trans2_get_dfs_referral_request
 event smb1_trans2_query_path_info_request%(c: connection, hdr: SMB1::Header, file_name: string%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *get DFS referral*.
+## version 1 *transaction2* requests of subtype *get DFS referral*. This transaction is used
+## to request a referral for a disk object in DFS.
+##
+## For more information, see MS-CIFS:2.2.6.16
 ##
 ## c: The connection.
 ##
@@ -44,7 +63,8 @@ event smb1_trans2_query_path_info_request%(c: connection, hdr: SMB1::Header, fil
 ##
 ## file_name: File name the request is in reference to.
 ##
-## .. bro:see:: smb1_message smb1_transaction2_request smb1_trans2_find_first2_request smb1_trans2_query_path_info_request
+## .. bro:see:: smb1_message smb1_transaction2_request smb1_trans2_find_first2_request
+##    smb1_trans2_query_path_info_request
 event smb1_trans2_get_dfs_referral_request%(c: connection, hdr: SMB1::Header, file_name: string%);
 
 # TODO - This is implemented, but not being generated right now

src/analyzer/protocol/smb/smb1_com_tree_connect_andx.bif

@@ -1,5 +1,8 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *tree connect andx*.
+## version 1 requests of type *tree connect andx*. This is sent by the client to establish a
+## connection to a server share.
+##
+## For more information, see MS-CIFS:2.2.4.55
 ##
 ## c: The connection.
 ##
@@ -13,7 +16,10 @@
 event smb1_tree_connect_andx_request%(c: connection, hdr: SMB1::Header, path: string, service: string%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 responses of type *tree connect andx*.
+## version 1 responses of type *tree connect andx*. This is the server reply to the *tree connect andx*
+## request.
+##
+## For more information, see MS-CIFS:2.2.4.55
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_tree_disconnect.bif

@@ -1,5 +1,8 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *tree disconnect*.
+## version 1 requests of type *tree disconnect*. This is sent by the client to logically disconnect
+## client access to a server resource.
+##
+## For more information, see MS-CIFS:2.2.4.51
 ##
 ## c: The connection.
 ##

src/analyzer/protocol/smb/smb1_com_write_andx.bif

@@ -1,5 +1,9 @@
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 requests of type *write andx*.
+## version 1 requests of type *write andx*. This is sent by the client to write bytes to a
+## regular file, a named pipe, or a directly accessible I/O device such as a serial port (COM)
+## or printer port (LPT).
+##
+## For more information, see MS-CIFS:2.2.4.43
 ##
 ## c: The connection.
 ##
@@ -13,7 +17,10 @@
 event smb1_write_andx_request%(c: connection, hdr: SMB1::Header, file_id: count, offset: count, data_len: count%);
 
 ## Generated for :abbr:`SMB (Server Message Block)`/:abbr:`CIFS (Common Internet File System)`
-## version 1 responses of type *write andx*.
+## version 1 responses of type *write andx*. This is the server response to the *write andx*
+## request.
+##
+## For more information, see MS-CIFS:2.2.4.43
 ##
 ## c: The connection.
 ##