PD-2437 / 25.10 / Pd 2437 auditing field changes

content/SCALETutorials/SystemSettings/AuditingSCALE.md

@@ -64,8 +64,8 @@ The event data for a sudo event includes the command.
 
 ### SMB and NFS Auditing Events
 
-SMB and NFS events are omitted by default from the **System > Audit** screen.
-To view these audit results, go to **System > Services** and click <i class="material-icons" aria-hidden="true" title="Audit Logs">receipt_long</i> **Audit Logs** for the SMB or NFS service or use advanced search on the main **Audit** screen to query {{< cli >}}"Service" = "SMB"{{< /cli >}}.
+SMB events are omitted by default from the **System > Audit** screen.
+To view these audit results, go to **System > Services** and click <i class="material-icons" aria-hidden="true" title="Audit Logs">receipt_long</i> **Audit Logs** for the SMB service or use the **Service** dropdown on the main **Audit** screen to select **SMB**.
 
 {{< hint type=info title="SMB Service Audit Logs" >}}
 SMB audit logs include all SMB protocol events, but do not include changes to SMB configuration, such as creating an SMB share or querying and modifying SMB ACLs.
@@ -137,7 +137,7 @@ Each audit message is a single JSON file containing mandatory fields.
 It can also include additional optional records.
 Message size is limited to not exceeding 1024 bytes for maximum portability with different syslog implementations.
 
-Use the **Export to CSV** button on an audit screen to download audit logs in a format readable in a spreadsheet program.
+Use the **Export** button on an audit screen to download audit logs in CSV, JSON, or YAML format. CSV format is readable in spreadsheet programs.
 Use the **Copy to Clipboard** option on the **Event Data** widget to copy the selected audit message event record to a text or JSON object file.
 The JSON object for an audit message contains the version information, the service that might be the name of the SMB share, a session ID, and the tree connection (tcon_id).
 
@@ -174,29 +174,31 @@ Users have access to audit information from three locations in the TrueNAS UI:
 
 ## Searching Audit Logs
 
-{{< trueimage src="/images/SCALE/SystemSettings/SystemSettingsAuditScreen.png" alt="Audit Screen" id="Audit Screen" >}}
+{{< trueimage src="/images/SCALE/SystemSettings/AuditScreen.png" alt="Audit Screen" id="Audit Screen" >}}
+
+Use the **Service** dropdown at the top of the screen to filter audit entries by service type (SMB, Middleware, etc.).
 
 The audit screen includes basic and advanced search options.
 Click **Switch to Basic** to change to the basic search function or click **Switch to Advanced** to show the advanced search operators.
 
 You can enter any filters in the basic **Search** field to show events matching the entry.
 
-To enter advanced search parameters, use the format displayed in the field, for example, *Service = "SMB" AND Event = "CLOSE"* to show closed SMB events.
+To enter advanced search parameters, use the format displayed in the field, for example, *Event = "CLOSE"* to show close events. Use the **Service** dropdown to filter by service type (SMB, Middleware, etc.) before or after applying advanced search filters.
 Event types are listed in [Auditing Event Types](#auditing-event-types).
 
 Advanced search uses a syntax similar to SQL/JQL and allows several custom variables for filtering.
 Parentheses define query priority.
 Clicking the advanced **Search** field prompts you with a dropdown of available event types, options, and operators to help you complete the search string.
 
-For example, to search for any SMB connect or close event from the user *smbuser* or any non-authentication SMB events, enter `(Service = "SMB" AND Event in ("Connect", "Close") AND User in ("smbuser")) OR (Event != "Authentication"  AND Service = "SMB")`.
+For example, to search for connect or close events from the user *smbuser*, select **SMB** from the **Service** dropdown and enter `Event in ("Connect", "Close") AND User = "smbuser"` in the advanced search field. To exclude authentication events, enter `Event != "Authentication"`.
 
 {{< trueimage src="/images/SCALE/SystemSettings/AuditAdvancedSearch.png" alt="Advanced Search" id="Advanced Search" >}}
 
 The advanced search automatically checks syntax and shows <i class="material-icons" aria-hidden="true" title="done">done</i> when the syntax is valid and <i class="material-icons" aria-hidden="true" title="warning">warning</i> for invalid syntax.
 
 Click on a row to show details of that event in the **Metadata** and **Event Data** widgets.
 
-**Export as CSV** sends the event log data to a CSV file you can open in a spreadsheet program (i.e., MS Excel, Google Sheets, etc.) or other data management app that accepts CSV files.
+**Export** provides a dropdown to export event log data in CSV, JSON, or YAML format. CSV files can be opened in spreadsheet programs (i.e., MS Excel, Google Sheets, etc.). JSON and YAML formats are useful for importing into data management applications or automation tools.
 
 The <i class="material-icons" aria-hidden="true" title="Copy to Clipboard">assignment</i> (**Copy to Clipboard**) icon shows two options, **Copy Text** and **Copy Json**.
 **Copy Text** copies the event to a text file.

content/SCALEUIReference/Shares/SMBSharesScreens.md

@@ -142,16 +142,16 @@ This behavior is enabled by default and matches FreeBSD behavior.
 
 #### Audit Logging
 
-The **Audit Logging** settings enable the auditing function for the SMB share and allow configuring a watch list and ignore list groups that administrators want to monitor. All share options listed in the **Purpose** dropdown show these settings.
+The **Audit Logging** settings enable the auditing function for the SMB share. Configure a watch list to audit specific groups, or an ignore list to audit all groups except those specified. At least one list (Watch or Ignore) must contain entries for auditing to function. All share options listed in the **Purpose** dropdown show these settings.
 
 {{< trueimage src="/images/SCALE/Shares/AddSMBAdvancedAuditLoggingSettings.png" alt="SMB Audit Logging" id="SMB Audit Logging" >}}
 
 {{< truetable >}}
 | Setting | Description |
 |---------|-------------|
-| **Enable Logging** | Enables audit logging for the SMB share, and shows two additional options: **Watch List** and **Ignore List**. This controls whether audit messages are generated for the share. <br>Note: Auditing might not be enabled if SMB1 support is enabled for the server. |
-| **Watch List** | Sets up a list of groups for which you want to generate audit logging messages. Clicking in the field shows the dropdown list of group options. Leave blank to include all SMB users with access to the share. If also setting a limit list, the watch list takes precedence when a conflict occurs. |
-| **Ignore List** | When selected, this sets up a list of groups to ignore when auditing. If conflict arises where the same groups are in the **Watch List** and **Ignore List** (based on user group membership), the watch listing takes precedence, and ops is audited. |
+| **Enable Logging** | Enables audit logging for the SMB share and displays two additional options: **Watch List** and **Ignore List**. This controls whether audit messages are generated for the share after configuring at least one list. <br>Note: Auditing is not available when SMB1 support is enabled for the server. |
+| **Watch List** | Specifies groups to audit. Click the field to display the dropdown list of group options. Auditing applies only to user accounts that are members of groups in this list. If the same user belongs to groups in both the **Watch List** and **Ignore List**, the watch list takes precedence and operations are audited. |
+| **Ignore List** | Specifies groups to exclude from auditing. Click the field to display the dropdown list of group options. If the same user belongs to groups in both the **Watch List** and **Ignore List**, the watch list takes precedence and operations are audited. |
 {{< /truetable >}}
 
 #### Other Options Settings

content/SCALEUIReference/SystemSettings/AuditScreen.md

@@ -24,14 +24,16 @@ The **Audit** screen lists all session or user events, facilitating comprehensiv
 
 The **Audit** screen lists log entries in a table that shows:
 
-* **Service** - The service performing the operation (e.g. **Midddleware**).
-* **User** - Name of the user (login or internal process user (e.g., **admin**, **UNAUTHENTICATED**, etc.)
+* **Service** - The service performing the operation (e.g. **Middleware**).
+* **User** - Name of the user (login or internal process user (e.g. **admin**, **UNAUTHENTICATED**, etc.)).
 * **Timestamp** - Date and time the event occurred.
-* **Event** - Name of the process (e.g., **Authentication**, **Method Call**, etc.)
-* **Event Data** - A short description of the operation (e.g., **Credentials: Password Login**, **System advanced update**, etc.).
+* **Event** - Name of the process (e.g. **Authentication**, **Method Call**, etc.).
+* **Event Data** - A short description of the operation (e.g. **Credentials: Password Login**, **System advanced update**, etc.).
+
+The **Service** dropdown at the top of the screen filters audit entries by service type. Options include **SMB**, **Middleware**, **Sudo**, and **System**. Select a specific service to view only entries for that service. When no service is selected, the screen displays entries from all services.
 
 **Audit Settings** opens the **System > Advanced Settings** screen showing the **Audit** widget.
-For more information on configuring audit settings, see [Advanced Settings Screen]({{< relref "AdvancedSettingsScreen.md #Audit-Widget" >}})
+For more information on configuring audit settings, see [Advanced Settings Screen]({{< relref "AdvancedSettingsScreen.md#Audit-Widget" >}})
 
 TrueNAS includes a manual page with more information on the [VFS auditing functions](https://github.com/truenas/samba/blob/SCALE-v4-19-stable/docs-xml/manpages/vfs_truenas_audit.8.xml).
 
@@ -48,7 +50,7 @@ Clicking in the **Search** field does not show search filter options in basic se
 
 **Search** starts the search operation based on the search parameters entered.
 
-**Export to CSV** generates a CSV file of audit log records and downloads it to the **Downloads** folder on the server.
+**Export** dropdown exports audit log records in multiple formats. Select **CSV**, **JSON**, or **YAML** to generate a compressed file (tar.gz format) that downloads to your browser's default download location. The export includes all audit entries that match the current filter settings.
 
 ### Audit Screen Log Details Widgets
 
@@ -59,4 +61,4 @@ The **Audit** screen shows two widgets for a selected record in the audit table:
 * **Event Data** - Shows the selected audit record method, a description of the recorded event, authentication status, and authorization information.
   The data varies based on the type of event.
 
-The **Copy to Clipboard** icon on the **Event Data** widget copies the fields listed on the **Event Data** widget formatted as straight text or a JSON file record that you can paste into any text editor.
+The **Copy to Clipboard** icon on the **Event Data** widget copies the fields listed on the **Event Data** widget formatted as straight text or a JSON file record that you can paste into any text editor.

static/includes/ConfigureSMBShareAuditingSCALE.md

@@ -11,16 +11,34 @@ From the **Add SMB Share** or **Edit SMB Share** screen, click **Advanced Option
 
 Selecting **Enable** turns auditing on for the share you are creating or editing.
 
-Use the **Watch List** and **Ignore List** functions to add audit logging groups to include or exclude.
-Click in **Watch List** to see a list of user groups on the system.
-Click on a group to add it to the list and record events generated by user accounts that are members of the group.
-Leave **Watch List** blank to include all groups, otherwise auditing is restricted to only the groups added.
+{{< hint type=important >}}
+At least one of **Watch List** or **Ignore List** must contain entries when enabling audit logging.
 
-Click in **Ignore List** to see a list of user groups on the system..
-Click on a group to add it to the list and explicitly avoid recording any events generated by user accounts that are members of this group.
+Auditing all SMB operations without restrictions creates large audit databases that grow rapidly and consume significant disk space. High-volume SMB environments can generate hundreds of thousands of audit entries per day, leading to increased disk I/O that affects overall system performance and database query delays when reviewing audit logs.
 
-The **Watch List** takes precedence over the **Ignore List** when using both lists.
+Configure filtering to audit only necessary operations.
+{{< /hint >}}
+
+Use **Watch List** to specify which groups should have their SMB operations audited. Use **Ignore List** to exclude specific groups from auditing.
+
+**Configuring Watch List:**
+1. Click the **Watch List** field to display available groups on the system.
+2. Select a group to add it to the list.
+3. Repeat to add additional groups.
+
+When **Watch List** contains entries, TrueNAS audits only SMB operations performed by members of the listed groups.
+
+**Configuring Ignore List:**
+1. Click the **Ignore List** field to display available groups on the system.
+2. Select a group to exclude it from auditing.
+3. Repeat to exclude additional groups.
+
+TrueNAS does not record SMB operations performed by members of groups in the **Ignore List**.
+
+**When using both lists:** If a user is a member of groups in both **Watch List** and **Ignore List**, the **Watch List** takes precedence and TrueNAS audits that user's operations.
+
+Review your settings to verify that at least one list contains entries and the correct groups are selected.
 
 Click **Save**.
 
-You might need to stop and restart the SMB service in order to view logged events.
+After saving, you may need to restart the SMB service for audit logging to begin. Go to **System Settings > Services**, toggle the **SMB** service off then on, and verify the service is running before testing audit log generation.