readme: Clarify post v0.4.0 changes.

README.md

@@ -4,27 +4,42 @@ audito-maldito is a daemon that monitors OpenSSH server logins and produces
 structured audit events describing what authenticated users did while logged
 in (e.g., what programs they executed).
 
-For more information about consuming audit events produced by this program,
-please refer to [the auditevent library][auditevent-library].
+audito-maldito monitors OpenSSH logins and then attempts to correlate
+authenticated user sessions with Linux kernel audit sessions. Once an
+audit session has been identified, new audito-maldito events are generated
+each time the Linux audit session receives a new event. This allows the
+application to tie an OpenSSH user's identity to their Linux audit session.
+For example, if a user authenticates using an SSH certificate, certificate
+details like the fingerprint and key ID will appear in each resulting
+audito-maldito audit event. These resulting events are written to
+a customizable file path.
 
-[auditevent-library]: https://github.com/metal-toolbox/auditevent
+Sysadmins define audit policy using auditd's [audit.rules](audit.rules).
+audito-maldito simply honors whatever Linux audit events appear in
+the Linux auditd event stream.
+
+For more information about configuring audito-maldito, please refer to
+the [Configuration section](#configuration).
+
+[audit.rules]: https://man7.org/linux/man-pages/man7/audit.rules.7.html
 
 ## System requirements
 
 - Linux
-- auditd
-- systemd
-- OpenSSH server (sshd)
+- [auditd](https://man7.org/linux/man-pages/man8/auditd.8.html)
+- [OpenSSH server (sshd)](https://www.openssh.com/)
 
 ## Audit event types
 
-### Session Tracking using Audito Maldito
+The following subsections detail the different types of audit events
+generated by audito-maldito. For more information about the structure
+of these events, please refer to [the auditevent library][auditevent-library].
 
-More Ddetails [here](processors/auditd/sessiontracker/READme.md)
+[auditevent-library]: https://github.com/metal-toolbox/auditevent
 
 #### `UserLogin`
 
-Occurs when a user logs in.
+Occurs when a user logs in via sshd.
 
 Example:
 
@@ -64,7 +79,7 @@ Example:
 
 #### `UserAction`
 
-Occurs when an authenticated user does something (example: the user
+Occurs when an authenticated sshd user does something (example: the user
 executes `rizin`).
 
 Example:
@@ -105,19 +120,16 @@ Example:
 }
 ```
 
-## Cautions
-
-#### inotify limits
-
-This program relies on inotify. As a result, it may hit limits on inotify
-resources. This can be more problematic on systems running scaling workloads
-(such as container hosts). Check the following sysctls for more information
-with `sysctl <sysctl-name>`:
+## Installation and deployment
 
-  - `fs.inotify.max_user_instances`
-  - `fs.inotify.max_user_watches`
+audito-maldito can be run as a standalone application (such as a systemd
+unit) or as a Kubernetes Daemonset. At Equinix Metal, we deploy the
+application in kubernetes using a Helm chart. The chart relies on rsyslog,
+which is responsible for passing OpenSSH daemon logs and Linux audit logs
+to audito-maldito using named pipes. audito-maldito reads from these named
+pipes and then writes its audit events to another named pipe.
 
-## Installation
+The following subsections discuss several installation and deployment methods.
 
 #### From source
 
@@ -140,30 +152,34 @@ A pre-built container image can be found in GitHub's container registry:
 
 - https://github.com/metal-toolbox/audito-maldito/pkgs/container/audito-maldito%2Faudito-maldito
 
-## Usage
+## Configuration
 
-This is meant to be used as a Kubernetes Daemonset. To run it, you need
-to mount the following directories for the host:
+The following subsections discuss audito-maldito's configuration.
 
-* `/var/log`
-* `/etc/os-release`
-* `/etc/machine-id`
-* `/var/run/audito-maldito`
+#### Required data sources
 
-Audit events are written to `/app-audit/audit.log` by default (this can be
-a regular file or a pipe). The audit file path can be customized using
-command line arguments.
+audito-maldito reads input data from named pipes (FIFOs). It expects these
+data sources to be specified using the following arguments:
 
-## Options
+- `-auditd-log-file-path` - The file path to a named pipe that produces
+  Linux auditd events (i.e., events from "/var/log/audit/audit.log")
+- `-sshd-log-file-path` - The file path to a named pipe that produces
+  OpenSSH sshd logs
 
-```
-  -audit-dir-path string
-    	Path to the Linux audit log directory (default "/var/log/audit")
-  -audit-log-path string
-    	Path to the audit log file (default "/app-audit/audit.log")
-  -boot-id string
-    	Optional Linux boot ID to use when reading from the journal
-```
+#### Required files
+
+The following files are required by audito-maldito to run:
+
+- `/etc/os-release` - Many Linux distributions provide this file.
+  It specifies details such as the distribution name and version
+- `/etc/machine-id` - This file is managed by systemd. It contains
+  an identifier for the computer
+
+#### Output data
+
+Audit events produced by audito-maldito are written to `/app-audit/audit.log`
+by default (this can be a regular file or a named pipe). This file path can
+be customized using the `-app-events-output` argument.
 
 ## Development