Installing and Running fapolicyd

Changing Runtime Configuration

Runtime configuration options are set in /etc/fapolicyd/fapolicyd.conf. Options are described in detail in the fapolicyd.conf(6) manual page. For more information, see also https://github.com/linux-application-whitelisting/fapolicyd/blob/main/README.md.

Configuring Runtime Statistics Reporting

Fapolicyd can generate a runtime statistics report that provides information about accesses, denials, and cache performance. The runtime statistics report is generated when fapolicyd is stopped and can be useful for gathering information about performance. You can use the information in the statistics report to decide whether to change other configuration options or to perform debug work. The report is written to /var/log/fapolicyd-access.log and default output is similar to the following:

Permissive: false
q_size: 640
Inter-thread max queue depth 6
Allowed accesses: 668513
Denied accesses: 0
Trust database max pages: 25600
Trust database pages in use: 7567 (29%)

File access attempts from oldest to newest as of Wed Nov 15 16:46:59 2023

        FILE                                                ATTEMPTS
---------------------------------------------------------------------------
/var/tmp/dracut.kZVhRg/initramfs/usr/lib/kbd/keymaps/xkb/tr-alt.map.gz  1
/var/tmp/dracut.kZVhRg/initramfs/usr/lib/kbd/unimaps/koi8u.uni  1
/var/tmp/dracut.kZVhRg/initramfs/usr/bin/stgTP4DF               1
...
/usr/bin/mandb (?)                                              1
/usr/bin/mandb (?)                                              264
---

Subject cache size: 1549
Subject slots in use: 1549 (100%)
Subject hits: 666964
Subject misses: 46044
Subject evictions: 44495 (6%)

Configuration options that can be set to control this report include:

do_stat_report: Controls whether the statistics report is generated. By default the value is set to 1 to indicate that the option is enabled.
detailed_report Controls whether fapolicyd adds subject and object information to the usage statistics report, indicating the number of times particular subject-object events occur. This content can be useful when debugging but can be disabled to reduce the size of the log. The default value for this option is set to 1 to indicate that the option is enabled.

Logging Controls

Audit logging is mostly handled using fanotify events in the audit log, but you can also configure the policy to log to the system log. See Changing Default Policy Logging, Debugging and Permissive Mode and Auditing Denial Events.

When logging to the system log or running fapolicyd in debugging mode, you can control the content of the log output from access decisions by configuring the syslog_format option. The format is a comma separated list of the different values to indicate rule information with subject and object information delineated by use of a colon character. Note that system performance is affected by the amount of content that you log. The default value is: rule,dec,perm,auid,pid,exe,:,path,ftype,trust.

Values available for the syslog_format option include:

rule: The rule number from the compiled policy rules. See Listing Policy Rules.
dec: The decision that fapolicyd takes for the rule.
perm: The permission that's applied in the rule.
Any of the subject options.
:: The separator to delineate between subject and object options.
Any of the object options.

For more information about subject and object options, see Creating Policy Rules.

Performance Controls

Performance control options can help improve memory usage and processing.

The following options are available to control the size of the caches that are used by fapolicyd to improve performance. For both options, aim to keep the allocated memory as small as feasibly possible, but ensure that enough memory is allocated to the cache to maximize the hits to evictions ratio, that can be calculated from the statistics report. To avoid cache churn resulting from collisions, consider setting that cache size values to prime numbers.

subj_cache_size: Controls how many entries the subject cache holds. The default value is 1549.
obj_cache_size: Controls how many entries the object cache holds. The default value is 8191.

Debugging and Permissive Mode

By default, fapolicyd is configured in enforcing mode. Permissive mode allows events that fapolicyd might have blocked to run but continues to audit the event. Permissive mode, when used with an appropriate logging configuration enabled, can be helpful when debugging. Don't leave permissive mode enabled on a system that you want to protect by using fapolicyd.

You can enable permissive mode by editing /etc/fapolicyd/fapolicyd.conf and setting the permissive configuration option to 1. You must restart the fapolicyd service for the change to take effect.

You can optionally run fapolicyd as an active process in permissive mode with debugging enabled to get more information about events as they take place.

To run fapolicyd in permissive mode with debugging enabled:

Stop the fapolicyd service.
```
sudo systemctl stop fapolicyd
```

Run fapolicyd from the command line with the --permissive and --debug options enabled.

sudo fapolicyd --permissive --debug

Output similar to the following is displayed.

Loading rule file:
## This file is automatically generated from /etc/fapolicyd/rules.d
%languages=application/x-bytecode.ocaml,application/x-bytecode.python,application/java-archive,text/x-java,application/x-java-applet,application/javascript,text/javascript,text/x-awk,text/x-gawk,text/x-lisp,application/x-elc,text/x-lua,text/x-m4,text/x-nftables,text/x-perl,text/x-php,text/x-python,text/x-R,text/x-ruby,text/x-script.guile,text/x-tcl,text/x-luatex,text/x-systemtap
allow perm=any uid=0 : dir=/var/tmp/
allow perm=any uid=0 trust=1 : all
allow perm=open exe=/usr/bin/rpm : all
allow perm=open exe=/usr/bin/python3.9 comm=dnf : all
deny_audit perm=any pattern=ld_so : all
deny_audit perm=any all : ftype=application/x-bad-elf
allow perm=open all : ftype=application/x-sharedlib trust=1
deny_audit perm=open all : ftype=application/x-sharedlib
allow perm=execute all : trust=1
allow perm=open all : ftype=%languages trust=1
deny_audit perm=any all : ftype=%languages
allow perm=any all : ftype=text/x-shellscript
deny_audit perm=execute all : all
allow perm=open all : all
Loaded 14 rules
Changed to uid 980
Initializing the trust database
fapolicyd integrity is 0
backend rpmdb registered
backend file registered
Loading rpmdb backend
Loading file backend
Checking if the trust database up to date
Importing trust data from rpmdb backend
Importing trust data from file backend
Entries in trust DB: 86032
Loaded trust info from all backends(without duplicates): 86032
Trust database checks OK
added /dev/shm mount point
added / mount point
added /var/oled mount point
added /boot mount point
added /boot/efi mount point
added /run/user/982 mount point
added /run/user/1000 mount point
Starting to listen for events

Events that would be denied are tagged with dec=deny_audit.

Tip:

Debug output can be verbose. Use the --debug-deny option instead of the standard --debug option to only output denial events. You don't need to run in debug mode to audit denial events, though. See Auditing Denial Events for more information. If you need to get more information about denial events, you can change rules to log to the system log. See Changing Default Policy Logging for more information.

To exit the running daemon, use the Ctrl-C key combination to send a SIGINT to interrupt the process.

Auditing Denial Events

Use the ausearch command to view denied events in the audit log, as these are tracked by using fanotify messages.

You need at least one rule defined for auditd to start logging fapolicyd events. If you don't have any rules defined, no events appear in the audit log. You can create any rule for auditing to start working. For example, you can create a rule to audit changes to configuration in /etc/fapolicyd as follows:

sudo tee /etc/audit/rules.d/40-fapolicyd.rules > /dev/null <<'EOF'
# This policy monitors /etc/fapolicyd/ for changes to configuration
# This rule is generated to ensure that events are logged to the audit log for fapolicyd tracking                                  
-w /etc/fapolicyd/ -p wa -k fapolicyd_changes
EOF

You need to restart the auditd service or reboot the system for this change to take effect. To restart the auditd service run:

sudo service auditd restart

Note:

Auditd can't be restarted by using the systemctl command.

Denial events are logged to the audit log and can be reviewed by using the ausearch command. For example:

sudo ausearch --start today -m fanotify

Use aureport to create easier to read outputs. For example:

sudo ausearch --start today -m fanotify --raw | aureport --file