A graphical user interface (GUI) tool that assists with operation and maintenance of the File Access Policy Daemon (fapolicyd).
In the remainder of this document we will refer to the File Access Policy Analyzer as the analyzer.
The analyzer is currently available for Fedora EPEL 8, and Fedora 37 or later, including Rawhide.
sh
dnf install fapolicy-analyzer
The RPM install will install a Desktop entry for the analyzer, which can be launched from desktop shortcut or applications menu.
If launching the application as an unprivileged user the system should present an elevation prompt requesting the users password to execute the application as root. This prompt is provided though integration with PolicyKit (polkit).
Launching the analyzer from the command line can be done as
sudo fapolicy-analyzer
This entry point script integrates polkit for privilege elevation allowing users to execute the application without the need for sudo.
When executing without sudo the polkit prompt will look something like
$ fapolicy-analyzer
pkttyagent registering on the dbus...
==== AUTHENTICATING FOR org.freedesktop.policykit.exec ====
Authentication is needed to run `/usr/bin/env' as the super user
Authenticating as: root
Password:
At this point the user's password (not the root password) can be entered and the user may be elevated, dependent on the PolicyKit policy.
There are additional options that can be passed through the command line, use the --help argument for more details.
This application consists of four primary tools
In addition the application offers an interface to control the fapolicyd service via DBUS.
The analyzer is driven by two toolbars that are common to all screens.
The top section is the menu bar which provides access to global functionality such as switching tools, analyzing a log, or controlling the fapolicyd daemon.
The bottom section is the context-sensitive portion of the toolbar which contains actions for the current tool, such as validating rules, or controlling profiling.
The Tool menu item provides access to each of the major components of the application and users may switch freely between them, and will be prompted if any action should be taken before switching.
The Analyze menu item provides entry point to analyzing fapolicyd logs from each of the supported input sources. Once clicked the user will be taken to the analysis view where they will be prompted for more information depending on the type of analysis being performed.
The Daemon menu option provides control for the fapolicyd daemon via DBUS.
The status of the daemon will be shown in the status bar at the bottom of the application; green for active, red for stopped.
The term "system trust" refers to an immutable list of trusted files sourced from the RPM database on the host machine. This trust is updated when fapolicyd starts or receives a reload signal, at which time the RPM database is parsed and filtered, and applicable entries are used to populate the fapolicyd trust store.
When the analyzer is started the fapolicyd trust store is parsed and file locations on disk are checked against the expected size and sha256 hashes to determine trusted/untrusted status. The trust administration view highlights the untrusted files in red while trusted are in green.
The intent here is to clearly indicate the trusted/untrusted status of the file on disk. Untrusted status in the system trust view indicates that the file on disk has changed from what was installed from the RPM.
Trust column, T/Green = Trusted, D/Red = DiscrepancyAfter adding trust entries the deployment options on the toolbar become active. See the Deployment section for more details.
From this view you are able to resolve trust issues by adding files with discrepancies to the ancillary trust.
In addition to the RPM database, fapolicyd can source trust from a text file or collection of text files. In the GUI we call this trust Ancillary trust.
From this view you are able to add additional files or directories of files that will add to system trust when the files are not know, or override it if the file was already in the rpm db.
Again the intent here is to clearly indicate the trusted/untrusted status of the file on disk. Untrusted status in the ancillary trust view indicates that the file on disk has changed from what was originally marked as trusted by an administrator.
Mixed support for the fapolicyd trust.d backend exists. The analyzer can fully load all trust files from the directory specified as the trust.d source.
When any trust entry sourced from trust.d is modified, it will be written back to the file it originated in.
When new trust entries are added there is currently no way to direct it to a trust.d file. In this case entries are written to the default fapolicyd.trust file, which is located in /etc/fapolicyd.
This configuration for trust.d is specified in the config.toml.
The GUI contains a text based rule editor that provides text highlighting and rules.d flattening to improve the rule editing experience.
The tree view of rules bridges some gaps in rendering of rules within the text editor. The ability to provide the flattened rule id and perform mouse operations on specific rules is currently limited to this view.
This view is currently read-only.
Within the rules.d directory there is a structure of one or more files that each may contain multiple rules. Determining the overall order of rules, as fapolicyd will interpret them, while editing can be tedious within the limited context of a single file. To ease this, the editor implements a flattening approach that displays all .d files within a single editor view. Transient delimiter annotations are inserted into the text view that identify file breaks. These annotations are editable which enables the user to rename, split, and merge file content by changing annotation content and location.
The file delimiters in the editor will be referred to as file markers. The file markers annotate the content of the editor to inform it where to break files when writing to disk.
File markers consist of the file name wrapped in square braces
[01-my.rules]
File markers are inserted automatically when loading rules.d. While editing, markers may be added or removed to split or merge rules into the corresponding rules files.
A rule set that contains two rules, originally sourced from a single file
allow perm=execute all : trust=1
deny perm=execute all : all
Can be split into multiple rule files by adding file markers as follows
[01-my-rules.rules]
allow perm=execute all : trust=1
[02-my-rules.rules]
deny perm=execute all : all
When the rules are deployed the file markers will be used identify what files will be present and what rules exist in each. The content following a marker, up to the point of another marker, will be included in the file specified by the marker.
The rules files are named relative to the configured rules.d location in the config.toml file. This location defaults to /etc/fapolicyd/rules.d/, so the example above would create two files,
1-my-rules.rules and 02-my-rules.rules, under /etc/fapolicyd/rules.d/.
The previous set of rules can be merged together into a single file by removing one of the markers.
[00-my-rules.rules]
allow perm=execute all : trust=1
deny perm=execute all : all
A root marker is required, if not specified it will be inserted by the application using a default file name.
So if all markers were to be removed, the content in the editor would be saved under /etc/fapolicyd/rules.d/00-analyzer.rules.
The profile execution is configured similarly to a launch profile in an IDE. Provide the target, args, working directory, and environment variables. Additionally we support the ability to run as a different user.
The working directory for the execution will be defined using the following rules: 1. Use the directory specified in the profiler GUI Working Directory field, if specified 2. Use the home directory of the user specified in the profiler GUI Run as user field, if specified 3. Use the root user home directory
The start and stop buttons on the toolbar will control the profiling process.
The output view will display the process id (PID), timer, and diagnostic messages while the profiler is executing the target.
The Policy Analysis can be exected by clicking the analyze button on the toolbar once the profiler session has ended.
The ouput view also shows the path to the temporary file containing the log in the case where there are other uses for it.
The Policy Analyzer tool displays a three column faceted view that allows one to quickly drill into a fapolicyd event log. The three column configuration represents data from a log entry split across the user/group, subject part, and object part. Each line representing a single log entry.
The first two columns are reversible, allowing the user to use a starting perspective of either user/group or subject. The double arrow button within the first column header flips the perspective.
Each column contains a search field to perform filtering of entries. There are also right click options available for entries that provide trust reconciliation.
The Trust column indicates the trust source of the subject, System Trust (ST), Ancillary Trust (AT), or Untrusted (U).
The Access column indicates a rollup of access decisions across all objects associated to this call, all Allowed (A), Partially allowed (P), all Denied (D).
The file is the path to the Subject as literally indicated in the log source.
The row color also indicates a rollup of access decisions across all objects associated to this call where Green indicates all objects were approved, Red is all objects were denied, Yellow is mixed approvals.
The Rule column indicates the rule number that generated the logged event.
The Trust column indicates the trust source of the object, System Trust (ST), Ancillary Trust (AT), or Untrusted (U).
The row color also indicates trust status where Green indicates trusted and allowed, Red is denied, Yellow is allowed but unknown.
The Perm column indicates the requested permission of the access in the logged event. This will be one of "open" or "execute".
Access indicates the decision made by fapolicyd, Allowed (A) or Denied (D).
The File column is the path to the object as literally indicated in the log source.
Note: There is a known issue with the analyzer not following links which creates a discrepancy in the log dislpay. This will be resolved in v1.1
When the Policy Analyzer shows that a file access was denied due to trust issue, the user can use a right click operation to reconcile the trust issue by updating the trust database with the content that matches the on-disk file.
The Policy Analyzer view can be populated from a number of sources that provide fapolicyd event log data.
Entrypoint to the Policy Analyzer using the Analyze > Debug log menu item will allow the user to pick a fapolicyd debug log.
The fapolicyd debug log may be generated by using the --debug option on the daemon
Entrypoint to the Policy Analyzer Using the Analyze > Syslog menu item will load the systems current syslog journal.
The required format for syslog entries must be added to the fapolicyd configuration.
syslog_format = rule,dec,perm,uid,gid,pid,exe,:,path,ftype,trust
Future: Analyzing kernel audit log entries will be added to a future release, tracked in issue #294
Deployment involves applying the current state held within the GUI to disk and having fapolicyd apply it to its state.
To accomplish this we do the following
After a deployment to disk is completed the user will be presented with a dialog asking if they want to keep the applied settings. There is a 30 second count down during which time you may test the system for functionality. If the dialog does not receive a confirmation that the changes should be kept in place, the changes deployed to disk will rollback to the previous state.
This is intended to be a fail safe in the case where a misconfiguration disables interaction with the host.
If the analyzer can limit the disk access it requires then it is in a unique position control fapolicyd after deploying new configuration.
It is important to consider that simply loading the application is not enough. As polices are created and deployed, the ability to return to disk to access anything may be limited.
Reducing disk access after starting is critical to providing a high level of resiliency and control in the case of fapolicyd limiting access.
User sessions with undeployed operations can be saved either explicitly by the user, or automatically in the event of an unexpected application termination.
At any point between deployments, a user can save their current work on the host system through the File menu: Session > Save or Session > Save As... with the former's operation identical to the latter's for the first save operation.
In either of those scenarios, the File Choser dialog will be displayed. Navigate to the desired directory and specify the filename:
Note that there is a known issue where the analyzer session file's default file suffix (json) is not correctly set, affecting the files displayed within both the Save As and Open File Chooser dialogs.
Additionally, the default json suffix is not automatically appended to the saved session file.
The work-around for the above bug is for the user to explicitly set the display filtering option for both Save and Open operations to Any files in order for the existing files to be visible
in the File Chooser dialog. On session file saves, the user will need to explicitly add the json file suffix is desired. Ultimately, the session file suffix has no functional consequences on the
operation of the analyzer.
To restore a previously saved user session the user can invoke the Open file operation via the Session > Open menu item:
And as mentioned in the note above, set the File Chooser dialog's display filter option to Any files in order to see the filesystems's files as the user navigates to the desired saved session file.
Upon reloading the saved session, the user's edit session can continue at the point of the prior session save:
The application uses a single toml file to provide the options that will be described in the following sections.
This config file will be located under the XDG config directory, $HOME/.config/fapolicy-analyzer/config.toml.
An example toml configuration file
[ui]
initial_view = 'rules'
[system]
rules_file_path = '/etc/fapolicyd/rules.d'
trust_lmdb_path = '/var/lib/fapolicyd'
system_trust_path = '/var/lib/rpm'
trust_dir_path = '/etc/fapolicyd/trust.d'
trust_file_path = '/etc/fapolicyd/fapolicyd.trust'
syslog_file_path = '/var/log/messages'
[application]
data_dir = '/home/dev/.local/share/fapolicy-analyzer'
User interface configuration options
initial_view - the tool view the application loads into. This can be set to one of rules, trust, profiler, "debug log", and "syslog". If this option is not specified the default is the rules view.These options are for configuring the location of fapolicyd and other system resources. The default options should remain unless in testing or debugging specific functionality.
General application configuration entries.
data_dir - the location where application data such as backup files are stored. Defaults to the XDG data directory.