Add guide to configure process_file_events on CentOS 7 (#12322)

#11890

---------

Co-authored-by: Rachael Shaw <r@rachael.wtf>

docs/Using-Fleet/Process-File-Events.md

@@ -0,0 +1,179 @@
+# Querying process_file_events on CentOS 7
+
+This guide contains step-by-step instructions for configuring the `process_file_events` table on CentOS 7.
+
+## Setup a CentOS 7 VM
+
+Setup a CentOS 7 VM. (VMWare Fusion was used for this guide.)
+The following kernel release was used:
+```sh
+$ uname --kernel-release
+3.10.0-1160.83.1.el7.x86_64
+```
+
+> All commands shown in this guide were executed as `root`.
+
+## Disable auditd
+
+The `process_file_events` table will not work if the `auditd` daemon is running (there can only be one audit daemon).
+To disable auditd run the following:
+```sh
+systemctl disable auditd
+systemctl stop auditd
+
+# Make sure auditd is not running by executing the following:
+ps -Af | grep auditd
+```
+
+If auditd is running, osquery will log the following error:
+```log
+I0613 11:25:39.959703 29626 auditdnetlink.cpp:686] Failed to set the netlink owner
+```
+
+## Create test files
+
+> The `process_file_events` table can only process events for files that existed before the osquery initialization.
+> New files created after osqueryd has initialized won't be tracked by the `process_file_events` table.
+
+Create the following test files in the CentOS VM:
+```sh
+mkdir /etc/foobar
+echo "zoo" > /etc/foobar/zoo.txt
+echo "other" > /etc/foobar/other.txt
+```
+
+## Create a test team in Fleet.
+
+We will use a test team with special settings to avoid impacting other hosts.
+
+## Install fleetd on the CentOS instance and enroll host
+
+Generate fleetd rpm package (This step was executed on macOS.)
+```sh
+fleetctl package --type=rpm --fleet-desktop --fleet-url=https://host.docker.internal:8080 --enroll-secret=[redacted team enroll secret] --insecure --debug
+```
+
+Install fleetd package on the CentOS 7 VM:
+```sh
+rpm --install fleet-osquery-1.10.0.x86_64.rpm
+```
+
+## Set team agent options
+
+Configure following settings on the team's agent options:
+```sh
+config:
+  options:
+    pack_delimiter: /
+    logger_tls_period: 10
+    distributed_plugin: tls
+    disable_distributed: false
+    logger_tls_endpoint: /api/osquery/log
+    distributed_interval: 10
+    distributed_tls_max_attempts: 3
+  decorators:
+    load:
+      - SELECT uuid AS host_uuid FROM system_info;
+      - SELECT hostname AS hostname FROM system_info;
+  file_paths:
+    etc:
+      - /etc/foobar/%%
+command_line_flags:
+  verbose: true
+  events_expiry: 3600
+  disable_events: false
+  disable_audit: false
+  audit_persist: true
+  audit_allow_fim_events: true
+  audit_allow_config: true
+  audit_backlog_limit: 60000
+  audit_allow_process_events: false
+  audit_allow_sockets: false
+  audit_allow_user_events: false
+  audit_allow_selinux_events: false
+  audit_allow_kill_process_events: false
+  audit_allow_apparmor_events: false
+  audit_allow_seccomp_events: false
+  enable_bpf_events: false
+```
+
+Check osquery `command_line_flags` were delivered successfully to the agent:
+```sh
+sudo cat /opt/orbit/osquery.flags 
+--audit_allow_apparmor_events=false
+--enable_bpf_events=false
+--audit_allow_config=true
+--audit_backlog_limit=60000
+--audit_allow_user_events=false
+--audit_allow_seccomp_events=false
+--audit_allow_selinux_events=false
+--audit_allow_sockets=false
+--audit_allow_process_events=false
+--audit_persist=true
+--audit_allow_fim_events=true
+--audit_allow_kill_process_events=false
+--disable_audit=false
+--verbose=true
+--events_expiry=3600
+--disable_events=false
+```
+
+### About the flags
+
+- `file_paths:` We set `/etc/foobar/%%` as the path to monitor for file changes.
+- `verbose: true`: We set this to `true` for troubleshooting purposes only.
+- `disable_events: false`: Must be set to `false` to enable evented tables in general.
+- `events_expiry: 3600`: The `events_expiry` value is the time it takes for events to be cleared from osquery local storage.
+- `disable_audit: false`: Must be set to `false` to enable the audit events. 
+- `audit_persist: true`: Set to `true` to attempt to retain control of audit.
+- `audit_allow_fim_events: true`: Must be set to `true` to generate FIM events (otherwise the `process_file_events` will generate no events). Once this is set correctly, the user should see "Enabling audit rules for the process_file_events table" in the logs.
+- `audit_allow_config: true`: Must be set to `true` to allow osquery to configure the audit service (basically set backlog limit and wait time below).
+- `audit_backlog_limit: 60000`: Sets the queue length for audit events awaiting transfer to osquery audit subscriber. We set this to a high value first to make sure the table is working, then it should be modified to a better value suited for production.
+- The following flags were set to `false` to avoid unnecessary load on the host: `audit_allow_process_events: false`, `audit_allow_sockets: false`, `audit_allow_user_events: false`, `audit_allow_selinux_events: false`, `audit_allow_kill_process_events: false`, `audit_allow_apparmor_events: false`, `audit_allow_seccomp_events: false`, `enable_bpf_events: false`.
+
+## Make sure osquery audit subscriber is working
+
+```sh
+auditctl -s
+
+enabled 1
+failure 0
+pid 21590
+rate_limit 0
+backlog_limit 60000
+lost 1137311
+backlog 991
+loginuid_immutable 0 unlocked
+```
+
+`enabled` should be `1` and `pid`'s value should be the process ID of osquery.
+
+## Modify the test files
+
+```sh
+echo "boo" >> /etc/foobar/zoo.txt
+rm /etc/foobar/other.txt
+```
+
+> Remember: the files must exist before the osquery process is initialized.
+> Creating or modifying new files won't generate `process_file_events` events.
+
+## Query the process_file_events table
+
+Run the following live query:
+```sql
+SELECT * from process_file_events;
+```
+
+It should return two events, one with `operation=write` and one with `operation=unlink`.
+
+## Additional notes
+
+Make sure to keep an eye on logs like the following:
+```log
+auditdnetlink.cpp:354 The Audit publisher has throttled reading records from Netlink for 0.2 seconds. Some events may have been lost.
+```
+Some events might get lost due to system load or low CPU/memory resources.
+
+<meta name="title" value="Querying process_file_events on CentOS 7">
+<meta name="pageOrderInSection" value="1900">

server/fleet/agent_options.go

@@ -505,6 +505,7 @@ type OsqueryCommandLineFlagsHidden struct {
 	AuditFIMDebug                 bool   `json:"audit_fim_debug"`
 	AuditShowPartialFIMEvents     bool   `json:"audit_show_partial_fim_events"`
 	AuditShowUntrackedResWarnings bool   `json:"audit_show_untracked_res_warnings"`
+	AuditFIMShowAccesses          bool   `json:"audit_fim_show_accesses"`
 }
 
 // while ValidateJSONAgentOptions validates an entire Agent Options payload,