> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-30-security-auditing/di-30.1-jie-an-quan-shi-jian-shen-ji.md). # 30.1 Security Event Auditing Process accounting records execution information for each command, which can be used to trace intrusion pathways. ## Process Accounting Process accounting is one of the security measures that allows administrators to track system resource usage and its distribution among different users, monitor the system, and minimally trace the commands executed by users. Process accounting has both advantages and disadvantages. The advantage is that intrusions can be traced back to the point of entry; the disadvantage is that it generates massive logs, placing high demands on disk space. ### Enabling and Using Process Accounting Before enabling process accounting, execute: ```sh # service accounting enable # service accounting start ``` Accounting information is stored in the **/var/account** directory, which is automatically created on first start of the accounting service. These files contain sensitive information, recording every command executed by all users. The default directory permissions are `0750` (`drwxr-x---`, owner root, group wheel), meaning only root and wheel group members can access it; the default accounting file permissions are `0640` (`rw-r-----`). If further restriction to root-only access is needed, the **/var/account** directory permissions can be changed to `700`. Once enabled, accounting begins tracking CPU information, executed commands, and more. All accounting logs are in binary format and must be viewed using `sa`. When run without options, `sa` prints information such as the number of invocations per user, total elapsed time (minutes), total CPU time and user time (minutes), and average number of I/O operations. To display commands executed by users, use `lastcomm`. For example, this command prints all usage records of `ls` by `trhodes` on the `ttyp1` terminal: ```sh # lastcomm ls trhodes ttyp1 ``` ## Security Event Auditing Overview The FreeBSD operating system supports security event auditing. Event auditing provides reliable, fine-grained, and configurable logging of various security-related system events, including logins, configuration changes, and file and network access. These logs are valuable for real-time monitoring, intrusion detection, and post-incident analysis. FreeBSD implements the Basic Security Module (BSM) API and file format published by Sun, which is interoperable with the auditing implementations of Solaris and macOS. This section focuses on the installation and configuration of event auditing, explains auditing policies, and provides an auditing configuration example. The auditing facility has some known limitations. Not all security-related system events can be audited, and some login mechanisms (such as Xorg-based display managers and third-party daemons) cannot properly configure auditing for user login sessions. The security event auditing facility can generate extremely detailed logs of system activity. On a busy system configured for a high level of detail, the volume of trail file data can be enormous, potentially exceeding several GB per week under certain configurations. Administrators should consider the disk space requirements of high-volume auditing configurations. For example, it may be necessary to allocate a dedicated file system for **/var/audit** to prevent it from filling up and affecting other file systems. ### Security Event Auditing Key Terminology The following terms are related to security event auditing: * **Event**: An auditable event is any event that the audit subsystem can record. Examples of security events include creating a file, establishing a network connection, or a user login. Events are categorized as "attributable" (traceable to an authenticated user) and "non-attributable". An example of a non-attributable event is an incorrect password attempt that occurs before authentication. * **Class**: A named group of related events used in selection expressions. Common event classes include "file creation" (fc), "execution" (ex), and "login\_logout" (lo). * **Record**: An audit log entry that describes a security event. A record includes the event type, information about the subject (user) performing the action, date and time, the objects or parameters involved, and success or failure conditions. * **Trail**: A log file consisting of a sequence of audit records describing security events. The trail is roughly ordered by event completion time. Only authorized processes may submit records to the audit trail. * **Selection expression**: A string containing a list of prefixes and audit event class names used to match events. * **Preselection**: The process by which the system determines which events the administrator is interested in. Preselection configuration uses a series of selection expressions to determine which event classes are audited for which users, as well as global settings that apply to both authenticated and unauthenticated processes. * **Reduction**: The process of filtering records from an existing audit trail for preservation, printing, or analysis; also the process of removing unwanted audit records from an audit trail. Administrators can use reduction to implement audit data retention policies. For example, a detailed audit trail may be retained for one month, after which the trail can be reduced to retain only login information for archiving. ### Audit Configuration User-space support for event auditing is installed with the FreeBSD base system. The GENERIC kernel provides kernel support by default. Enable auditd: ```sh # service auditd enable ``` Then start the audit daemon: ```sh # service auditd start ``` Users with a custom kernel must add the following to their configuration file: ```sh options AUDIT ``` #### Event Selection Expressions Selection expressions are used in audit configuration to determine which events should be audited. An expression contains a list of event classes to match, evaluated from left to right. Merging two expressions is done by concatenating them. The following summarizes the default audit event classes: | Class | Description | Action | | ----- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | all | All | Matches all event classes. | | aa | Authentication and Authorization | | | ad | Administrative | Administrative operations targeting the system as a whole. | | ap | Application | Application-defined operations. | | cl | File Close | Audit invocations of the `close` system call. | | ex | Execution | Audit program execution. Auditing of command line arguments and environment variables is controlled through the `policy` setting in audit\_control, using the `argv` and `envv` parameters. | | fa | File Attribute Access | Audit access to object attributes, such as stat(1) and pathconf(2). | | fc | File Creation | Audit file creation-related events. | | fd | File Deletion | Audit file deletion-related events. | | fm | File Attribute Modification | Audit file attribute modification events, such as chown(8), chflags(1), and flock(2). | | fr | File Read | Audit events involving reading data or opening files for reading. | | fw | File Write | Audit events involving writing data or writing/modifying files. | | io | ioctl | Audit use of the `ioctl` system call. | | ip | Inter-process Communication | Audit various forms of inter-process communication, including POSIX pipes and System V IPC operations. | | lo | Login\_Logout | Audit login and logout events. | | na | Non-attributable | Audit non-attributable events. | | no | Invalid Class | Does not match any audit events. | | nt | Network | Audit events related to network operations, such as connect(2) and accept(2). | | ot | Other | Audit miscellaneous other events. | | pc | Process | Audit process operations, such as exec(3) and exit(3). | The above audit event classes can be customized by modifying the configuration files **/etc/security/audit\_class** and **/etc/security/audit\_event**. Each audit event class can be accompanied by a prefix indicating whether to match successful or failed operations, and whether the entry adds or removes matching for that class and type. The audit event class prefixes are summarized as follows: | Prefix | Action | | ------ | --------------------------------------------------------- | | + | Audit successful events in this class. | | - | Audit failed events in this class. | | ^ | Audit neither successful nor failed events in this class. | | ^+ | Do not audit successful events in this class. | | ^- | Do not audit failed events in this class. | If no prefix is present, both successful and failed instances of the event are audited. The following example selection string selects successful and failed login/logout events, but only successful execution events: ``` lo,+ex ``` #### Configuration Files The following configuration files for security event auditing are located in the path **/etc/security**: ```sh /etc/security ├── audit_control -> Controls the audit subsystem ├── audit_class -> Audit class definitions ├── audit_event -> System audit events ├── audit_user -> User-specific audit requirements └── audit_warn -> Warning message script ``` | File | Description | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **/etc/security/audit\_control** | Controls aspects of the audit subsystem, such as default audit classes, minimum disk space to reserve on the audit log volume, and maximum audit trail size | | **/etc/security/audit\_class** | Contains audit class definitions | | **/etc/security/audit\_event** | Text names and descriptions of system audit events, along with the list of classes to which each event belongs | | **/etc/security/audit\_user** | User-specific audit requirements, merged with global defaults at login time | | **/etc/security/audit\_warn** | A customizable shell script used by auditd to generate warning messages under exceptional circumstances, such as when audit record space is running low or an audit trail file has completed rotation | Audit configuration files should be edited and maintained with care, as configuration errors may result in improper event logging. In most cases, administrators only need to modify **/etc/security/audit\_control** and **/etc/security/audit\_user**. The former controls system-level audit attributes and policies, while the latter allows fine-tuning auditing on a per-user basis. **audit\_control File** Several defaults for the audit subsystem can be specified in the **/etc/security/audit\_control** file: ```ini dir:/var/audit dist:off flags:lo,aa minfree:5 naflags:lo,aa policy:cnt,argv filesz:2M expire-after:10M ``` The above are the default values for the **/etc/security/audit\_control** file in the base system, whose source code is located at **contrib/openbsm/etc/audit\_control**. Explanation of each entry: | Entry | Function | Description | | -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `dir` | Audit log directory | Sets one or more directories for storing audit logs; if there are multiple, they are used sequentially, switching when one fills up; it is generally recommended to use a dedicated file system to avoid filling up affecting other system components. | | `dist` | Distribution (hard link) | When set to `on` or `yes`, creates hard links for all audit trail files in **/var/audit/dist**. | | `flags` | Default preselection mask (attributable events) | Defines the default audit classes for "attributable events" system-wide; for example, login/logout success and failure, authentication and authorization events. | | `minfree` | Minimum free space | Specifies the minimum percentage of free space allowed on the file system containing the audit logs. | | `naflags` | Non-attributable event mask | Specifies the classes that should be audited for "non-attributable events", such as the login/logout process and authentication and authorization. | | `policy` | Audit policy | A comma-separated list of policy flags; `cnt` indicates the system continues running when auditing fails (recommended), `argv` indicates recording command line arguments of execve(2). | | `filesz` | Trail file size limit | Specifies the maximum size of a single audit trail file before it is automatically terminated and rotated; `0` disables automatic rotation; values less than 512k are ignored and logged. | | `expire-after` | Log expiration policy | Specifies the expiration time for audit log files, which are automatically deleted upon expiration. | **audit\_user File** Administrators can specify additional audit requirements for specific users in the **/etc/security/audit\_user** file. Each line configures auditing for a user with two fields: * The `alwaysaudit` field specifies the set of events that are always audited for this user * The `neveraudit` field specifies the set of events that are never audited for this user. The default values for the **audit\_user** file are as follows: ```ini root:lo:no ``` The following example entries audit login/logout events and successful command execution for the `root` user, and audit file creation and successful command execution for the `www` user. When combined with the default audit\_control, the `lo` entry for `root` is redundant, and login/logout events for `www` will also be audited. ```ini root:lo,+ex:no www:fc,+ex:no ``` ### Processing Audit Trails Since audit trails are stored in BSM binary format, FreeBSD provides several built-in tools for modifying or converting them to text. To convert a trail file to simple text format, use `praudit`. To reduce audit trail files for analysis, archiving, or printing, use `auditreduce`. This tool supports various selection parameters: event type, event class, user, event date or time, and the file path or object involved in the operation. For example, to dump the entire contents of a specified audit log in plain text: ```sh # praudit /var/audit/audit_log ``` Where **audit\_log** is the audit log to dump. An audit trail consists of a sequence of audit records, each composed of several tokens, and `praudit` prints one token per line in order. Each token belongs to a specific type, such as `header` (audit record header) or `path` (file path resulting from a name lookup). The following is an example of an `execve` event: ```ini header,133,10,execve(2),0,Mon Sep 25 15:58:03 2006, + 384 msec exec arg,finger,doug path,/usr/bin/finger attribute,555,root,wheel,90,24918,104944 subject,robert,root,wheel,root,wheel,38439,38032,42086,128.232.9.100 return,success,0 trailer,133 ``` This audit record represents a successful `execve` call that executed the `finger doug` command. Explanation: * The `exec arg` token contains the processed command line passed by the shell to the kernel. * The `path` token holds the executable file path found by the kernel. * The `attribute` token describes the binary file, including the file mode. * The `subject` token stores the audit user ID, effective user ID and group ID, real user ID and group ID, process ID, session ID, port ID, and login address. > **Note** > > The audit user ID differs from the real user ID because user `robert` had switched to the `root` account before executing this command, but the command is still audited under the original authenticated user. * The `return` token indicates successful execution, and the `trailer` ends the record. Since audit logs can be extremely large, `auditreduce` can be used to select a subset of records. The following example selects all audit records generated for user `trhodes` from an audit log file (AUDITFILE is a placeholder; replace it with the actual file name, such as `20240521140528.not_terminated`): ```sh # auditreduce -u trhodes /var/audit/AUDITFILE | praudit ``` The `audit` group is empty by default, so only `root` can read the audit trails in **/var/audit**; adding users to the `audit` group grants audit review privileges. Audit logs contain sensitive information, so it is recommended to grant audit review privileges with caution. #### Real-time Monitoring Using Audit Pipes Audit pipes are cloneable pseudo-devices that allow applications to tap into the real-time audit record stream, primarily intended for intrusion detection and system monitoring program developers. Audit pipe devices also provide administrators with a convenient means of real-time monitoring, unaffected by audit trail file ownership or log rotation interrupting the event stream. To track the real-time audit event stream: ```sh # praudit /dev/auditpipe ``` By default, audit pipe device nodes are only accessible by the `root` user. To allow members of the `audit` group to access them as well, add a `devfs` rule in **/etc/devfs.rules**: ```sh add path 'auditpipe*' mode 0440 group audit ``` Audit events can easily create feedback loops: viewing each audit event generates more audit events. For example, if all network I/O is audited and `praudit` is run over an SSH session, audit events will be generated continuously at high speed because each printed event triggers a new event. Therefore, it is recommended to run `praudit` (connected to an audit pipe device) in a session without fine-grained I/O auditing. #### Rotating and Compressing Audit Trail Files Audit trails are written by the kernel and managed by the audit daemon auditd. Administrators should not use tools such as newsyslog.conf(5) to directly rotate audit logs; instead, use `audit` to shut down auditing, reconfigure, and rotate logs. The following command causes the audit daemon to create a new audit log and notify the kernel to switch. The old log is terminated and renamed, available for subsequent processing by the administrator: ```sh # audit -n ``` If auditd is not currently running, this command fails with an error. Add the following line to **/etc/crontab** to perform rotation every 12 hours: ```sh 0 */12 * * * root /usr/sbin/audit -n ``` The change takes effect after saving the **/etc/crontab** file. Automatic rotation of audit trail files based on file size can be achieved through the `filesz` setting in audit\_control. Audit trail files can become extremely large, and after the audit daemon closes a trail, it typically needs to be compressed or archived. The audit\_warn script can execute custom actions for various audit events, including the case where a trail is normally terminated during rotation. For example, the following can be added to **/etc/security/audit\_warn** to compress audit trails on close: ```sh # # Compress audit trail files on close. # if [ "$1" = closefile ]; then gzip -9 $2 fi ``` Other archiving actions may include copying trail files to a central server, deleting old trail files, or reducing audit trails to remove unwanted records. This script only runs when an audit trail file is normally terminated; unterminated trails left behind by an unclean shutdown do not trigger it. ## Exercises 1. After enabling process accounting, perform a series of operations on the system (create files, run commands, switch users), use `lastcomm` to export the records and explain the meaning of each field, and find the corresponding record entries. 2. Use `sa -u` to generate a command usage report by user, analyze the difference in meaning between the "cpu" and "re" columns, and explain why these two values are usually not equal. 3. Discuss the potential privacy issues that process accounting may raise and countermeasures in multi-user systems. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://book.bsdcn.org/ask/flat/chapter-30-security-auditing/di-30.1-jie-an-quan-shi-jian-shen-ji.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.