File Access Policy Analyzer

Introduction

Terminology

• File Access based notification and interception of events generated by the Linux Kernel fanotify API.
• Trust is based on expected size or sha256 hash of a file at a path. The trusted state of the system is stored in a fapolicyd database and compared against the actual state. Files that match the database are recognized as trusted.
• Rules are defined as a list of first-match-win patterns that when matched to a file access request are used to allow or deny that request.
• A File Access Policy is the union of trust and rules that provides the fapolicyd daemon the information it needs to make a decision whether to allow or deny a file access request.

What is the File Access Policy Analyzer?

A graphical user interface (GUI) tool that assists with operation and maintenance of the File Access Policy Daemon (fapolicyd).

Goals

• Detect and resolve file trust discrepancies between the trusted system configuration and the actual system configuration.
• Author file access rules using GUI components that make understanding and editing easier compared to a plain-text editor.
• Analyze file access logs and display in GUI components simplifying navigation of events compared to reading the raw logs.
• Diagnose file access policy issues and guide along path to resolution.
• Reduce repetitively stressful operations with an ergonomic GUI.

Components

This application consists of several GUI tools:

1. Trust Administration
2. Rule Administration
3. Policy Profiling
4. Log Analysis

Trust Administration

System Trust

The term "system trust" represents an immutable store of trust that is 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 fapolicy-analyzer GUI is started the fapolicyd trust store is parsed and file locations on disk are checked against the expected size and sha256 hashes to determin 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 by the originating RPM.

Available User Interactions

1. Sort entries based on their trusted status. T = Trusted, D = Discrepancy
2. Sort entries based on the file modified time.
3. Sort entries based on file name.
4. Search for entries using the search field.
5. Select entries and view the metadata displayed in the right hand columns a. Path, hash, size in the fapolicyd database b. Stat of actual file on disk c. File trusted status summary
6. Select one or more files with discrepancies and click the "Add to Ancillary Trust" button to create trust entries for them.
7. Deploy changes to disk and apply to fapolicyd

After adding trust entries the deployment options on the toolbar become active. See the Deployment section for more details.

Known issue: large RPM databases can take some time to load on single core machines. The system trust code does utilize additional cores so there will be a linear drop in loading time as more cores are available.

From this view you are able to resolve trust issues by adding files with discrepancies to the ancillary trust.

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.

Available User Interactions

1. Sort entries based on their trusted status. T = Trusted, D = Discrepancy
2. Sort entries based on the file modified time.
3. Sort entries based on file name.
4. Search for entries using the search field.
5. Add trusted entries to the database using a file selection tool.
6. Select entries and view the metadata displayed in the right hand columns a. Path, hash, size in the fapolicyd database b. Stat of actual file on disk c. File trusted status summary
7. Select one or more files with discrepancies and click the "Trust" button to add the selection to the trust database.
8. Select one or more Trusted entries and click the "Untrust" button to remove the selection from the trust database.
9. Deploy changes to disk and apply to fapolicyd

Trust.d support

Ancillary trust currently only supports the single file configuration. Near term improvements are planned to add support for the trust.d backend.

Rules Administration

Rule Editor

The GUI contains a text based rule editor that provides text highlighting and rules.d flattening to improve the rule editing experience.

Available User Interactions

1. Deploy changes to disk and apply to fapolicyd
2. Validate and lint the current editor content, without saving it
3. Save the current editor content to the session, validates prior to saving
4. Editor for text based rules, with syntax highlighting
5. Collapse / expand the Status Information tree that display messages from the rule parse
6. File marker annotations allow manipulating file content from within the text editor

Rule Viewer

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.

Available User Interactions

1. Deploy changes to disk and apply to fapolicyd
2. Validate and lint the current editor content, without saving it
3. Save the current editor content to the session, validates prior to saving
4. Search field to search for rules based on text content
5. Collapse / expand the rules tree at the file level
6. File marker annotations
7. Collapse / expand the Status Information tree that display messages from the rule parse

This view is currently read-only.

Flattening of rules.d

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.

File markers

The file delimeters in the editor are referred to as file markers. These 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.

Examples

A rule set that contains three rules, originally sourced from a single file

``` allow perm=any uid=0 trust=1 : all allow perm=execute all : trust=1 deny perm=execute all : all

```

Can be split into multiple rule files

[00-my-rules.rules] allow perm=any uid=0 trust=1 : all [01-my-rules.rules] allow perm=execute all : trust=1 [02-my-rules.rules] deny perm=execute all : all

And then two rules are merged together into a single file by removing a marker

[00-my-rules.rules] allow perm=any uid=0 trust=1 : all [01-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.

Policy Profiler

Available User Interactions

1. Start Profiling
2. Stop Profiling
3. Load results in Policy Analyzer
4. Clear Profiler launch configuration entry text fields
5. Executable target path, relative or absolute (required)
6. Arguments to pass to the executable target (optional)
7. User to execute target as (optional: default root)
8. Working directory to launch target from (optional)
9. Environment variables to pass to target (optional)
10. Keep profiling session active for more than one profiler run
11. Display text output from stderr and stdout logs from both fapolicyd and target executable

How the Profiler works

1. Take fapolicyd offline
2. Restart fapolicyd service in debug mode, redirecting logs
3. Execute an application
4. Take profiling fapolicyd offline
5. Restart standard fapolicyd service
6. Send the logs to the Policy Analyzer

Configuring a profiler session

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.

Future: Allow specification of gid(s) for the target execution, #664.

Profiling an application

Known issue: there is no feedback to indicate the status of the running application during profiling. This will be addressed in the future by displaying the log output of the target application.

Analyzing after profiling

The analyzer can be accessed in two ways

1. Load the fapolicyd log file from the profiling session using the tools load from debug log option.
2. Click the analyze button on the toolbar once the profiler session has ended.

Policy Analyzer

The analyzer tool displays a three column faceted view that allows for graphical browsing of a fapolicyd log. The three column configuration represents data from a log entry per line, with the columns representing the user/group, subject, object.

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.

Available User Interactions

1. Deploy changes to disk and apply to fapolicyd
2. Refresh the data display based on the original source
3. Filter the User / Group column based on text content
4. Perspective switch between the User / Group and Subject
5. Filter the Subject display based on text content
6. Filter the Object display based on text content
7. Metadata for selected User / Group
8. Stat output for selected Subject
9. Stat output for selected Object
10. Right click operations a. Reconcile trust discrepancy b. Jump to rule view

Debug logs

Entrypoint to the analyzer using the Tool > Analyze from Debug log menu item will allow the user to pick a fapolicyd debug log that was generated by using the --debug option on the daemon.

Syslog

Entrypoint to the analyzer Using the Tool > Analyze from Syslog menu item will load the systems current syslog journal into the analyzer.

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

Audit log

Future: Analyzing kernel audit log entries will be added to a future release, tracked in issue #294

Reconciling trust

When the 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.

Deployment

What happens during deployment

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

1. Stop fapolicyd service
2. Write ancillary trust to disk
3. Write rules.d to disk
4. Start fapolicyd service

Rolling back a deployment

After deployment 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 confirm that the changes should be kept in place the changes made to the hist will rollback to the previous state.

1. Status message indicating the deployment was successful
2. Modal dialog that allows selection up to when the timer expires

This is intended to be a fail safe in the case where a misconfiguration disables interaction with the host.

Fapolicyd service control

Start and Stop

Fapolicyd-proof control

Because fapolicyd has the ability to reject any disk accesses we must be very careful when considering the resiliency of control the application provides. If we were to rely on controlling the fapolicyd service using the systemctl utility there is a chance that deploying a stringent rule such as deny perm=any all : all we could lose the ability to control the daemon.

To ensure resiliency we control fapolicyd using DBUS messages to signal system operations. This ensures we can start / stop the fapolicyd service even given stringent rules. This is used for both deployments and manual control (via the System menu), and gives the application resiliency that is hard to accomplish using existing command line tools.

Session management

User sessions with undeployed operations can be saved either explicitly by the user, or automatically in the event of an unexpected application termination.

Saving edits that have not been deployed

At any point between deployments, a user can save their current work on the host system through the File menu: File > Save or File > 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 fapolicy-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 fapolicy-analyzer.

Restoring edits saved to a file

To restore a previously saved user session the user can invoke the Open file operation via the File > 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.

n save Upon reloading the saved session, the user's edit session can continue at the point of the prior session save: