fapolicyd

A Puppet module that is used to configure fapolicyd on Red Hat Enterprise Linux 8 or 9 systems.

For more information about fapolicyd, please refer to Introduction to fapolicyd

Table of Contents

1. Description
2. Setup - The basics of getting started with fapolicyd
   • What fapolicyd affects
   • Setup requirements
   • Beginning with fapolicyd
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

This Puppet module can be used to do a basic installation and configuration of fapolicyd - A simple application whitelisting daemon for Linux.

Setup

What fapolicyd affects

This fapolicyd Puppet module currently manages the following configurations:

• Installation of fapolicyd package
• Management of the fapolicyd service
• Configuration of /etc/fapolicyd/fapolicyd.conf file
• Configuration of trusted applications via files under /etc/fapolicyd/trusted.d/
• Configuration of rules via files under /etc/fapolicyd/rules.d/

Setup Requirements

In order to use this module, make sure to have the following Puppet modules installed:

• puppetlabs-stdlib

Beginning with fapolicyd

In order to get started with the fapolicyd Puppet module to install the fapolicyd package and start the fapolicyd service with default settings:

include fapolicyd

Usage

For additional information regarding the usage of the fapolicyd Puppet module, please refer to REFERENCES

Whitelist applications using a trust file under /etc/fapolicyd/trusted.d/

The following example demonstrates how mark an application as trusted using Puppet.

To mark the applications /tmp/ls and /tmp/cat as trusted into the file /etc/fapolicyd/trusted.d/myapp

fapolicyd::trust_file { 'myapp':
  trusted_apps => [
    '/tmp/ls',
    '/tmp/cat',
  ],
}

Note: If an application being whitelisted does not currently exist on a machine, the trust file will instead include a comment. Once the application does exist on the machine, the comment will be updated to be a trusted application on the next Puppet run. The comment included will be similar to the following:

#<application path> is trusted but does not currently exist on the machine

For more information regarding trust files, refer to the Red Hat Enterprise Linux documentation for Marking files as trusted using an additional source of trust

Allow or deny applications using a rule file under /etc/fapolicyd/rules.d/

The following example demonstrates how to add an fapolicyd rule using Puppet.

The fapolicyd rule: allow perm=execute exe=/usr/bin/bash trust=1 : path=/tmp/ls ftype=application/x-executable trust=0 can be added to the file /etc/fapolicyd/rules.d/80-myapps.rules using the following Puppet code:

fapolicyd::rule_file { 'myapps':
  priority => 80,
  comment  => 'Rules for myapps',
  rules    => [
  {
    decision => 'allow',
    perm     => 'execute',
    subjects => [
      {
        type    => 'exe',
        setting => '/usr/bin/bash',
      },
      {
        type    => 'trust',
        setting => '1',
      },
    ],
    objects  => [
      {
        type    => 'path',
        setting => '/tmp/ls',
      },
      {
        type    => 'ftype',
        setting => 'application/x-executable'
      },
      {
        type    => 'trust',
        setting => '0'
      },
    ]
    }
  ],
}

For more information regarding fapolicyd rules, refer to the Red Hat Enterprise Linux documentation for Adding custom allow and deny rules for fapolicyd

Limitations

This module has only been tested on Red Hat Enterprise Linux 8 and 9.

Development

If you would like to contribute with the development of this module, please feel free to log development changes in the issues register for this project

Reference

Table of Contents

Classes

• fapolicyd: A class for installing and configuring fapolicyd

Defined types

• fapolicyd::rule_file: A type for managing fapolicyd rules files
• fapolicyd::trust_file: A type for managing fapolicyd trust files

Functions

Private Functions

• fapolicyd::format_rule: A function for formatting a rule to be added to a .rules file
• fapolicyd::get_trusted_file_info: A function that returns the trusted application's file information in the format <file absolute path> <file size> <file sha256 hash>

Data types

• Fapolicyd::Object: A type for defining a fapolicyd rule object
• Fapolicyd::Rule: A type for defining a fapolicyd rule
• Fapolicyd::Subject: A type for defining a fapolicyd rule subject

Classes

fapolicyd

This class installs and configures fapolicyd

Examples

include fapolicyd

Parameters

The following parameters are available in the fapolicyd class:

• package_ensure
• service_ensure
• service_enable
• permissive
• nice_val
• q_size
• uid
• gid
• do_stat_report
• detailed_report
• db_max_size
• subj_cache_size
• obj_cache_size
• watch_fs
• trust
• integrity
• syslog_format
• rpm_sha256_only
• allow_filesystem_mark

package_ensure

Data type: Enum['present', 'installed', 'absent']

Set the state of the package

Default value: 'present'

service_ensure

Data type: Enum['running', 'stopped']

Set the state of the service

Default value: 'running'

service_enable

Data type: Boolean

Set whether the service is enabled/disabled

Default value: true

permissive

Data type: Integer[0,1]

Set to 0 to send policy decision to the kernel for enforcement. Set to 1 to always allow access even if a policy would block it.

Default value: 0

nice_val

Data type: Integer[0,20]

Set a process niceness value scheduler boost

Default value: 14

q_size

Data type: Integer[1]

Set the queue size for the internal queue that fapolicyd will use.

Default value: 800

uid

Data type: String[1]

Set the uid or name of the user account under which fapolicy should switch to during startup

Default value: 'fapolicyd'

gid

Data type: String[1]

Set the gid or name of the group under which fapolicy should switch to during startup

Default value: 'fapolicyd'

do_stat_report

Data type: Integer[0,1]

Set whether fapolicy do should (1) or should not (0) create a usage statistics policy on shutdown

Default value: 1

detailed_report

Data type: Integer[0,1]

Set whether fapolicyd should(1) or should not(0) add subject and object information to the usage statistics report

Default value: 1

db_max_size

Data type: Integer[1]

Set how many megabytes to allow the trust database to grow to

Default value: 50

subj_cache_size

Data type: Integer[1]

Set how many entries the subject cache holds

Default value: 1549

obj_cache_size

Data type: Integer[1]

Set how many entries the object cache holds

Default value: 8191

watch_fs

Data type: Array[String[1]]

Set a list of file systems that should be watched for access permission

Default value: ['ext2','ext3','ext4','tmpfs','xfs','vfat','iso9660','btrfs']

trust

Data type: Array[Enum['rpmdb','file'],1,2]

Set list of trust back-ends

Default value: ['rpmdb','file']

integrity

Data type: Enum['none','size','ima','sha256']

Set the integrity strategy that should be used

Default value: 'none'

syslog_format

Data type: String[1]

Set the format of the output from the access decision

Default value: 'rule,dec,perm,auid,pid,exe,:,path,ftype,trust'

rpm_sha256_only

Data type: Integer[0,1]

Set option (0 or 1) for whether the daemon should be forced to only work with SHA256 hashes

Default value: 0

allow_filesystem_mark

Data type: Integer[0,1]

Set option (0 or 1) for whether to allow fapolicyd to monitor file access events on the underlying file system when they are bind mounted or are overlayed

Default value: 0

Defined types

fapolicyd::rule_file

A type for managing fapolicyd rules files under /etc/fapolicyd/rules.d/

Examples

fapolicyd::rule_file { 'myapps':
  priority => 80,
  comment  => 'Rules for myapps',
  rules    => [
    {
      decision => 'allow',
      perm     => 'execute',
       subjects => [
        {
          type    => 'exe',
          setting => '/usr/bin/bash',
        },
        {
          type    => 'trust',
          setting => '1',
        },
      ],
      objects  => [
        {
          type    => 'path',
          setting => '/tmp/ls',
        },
        {
          type    => 'ftype',
          setting => 'application/x-executable'
        },
        {
          type    => 'trust',
          setting => '0'
        },
      ]
    }
  ],
}

Parameters

The following parameters are available in the fapolicyd::rule_file defined type:

• priority
• comment
• rules

priority

Data type: Integer[0]

Priority of the rules in the rule file

Default value: 100

comment

Data type: String[1]

A comment to place into the rules file for describing the rules

Default value: "${priority}-${title}.rules"

rules

Data type: Array[Fapolicyd::Rule]

An array of rules to add to the rules file

Default value: []

fapolicyd::trust_file

A type for managing fapolicyd trust files under /etc/fapolicyd/trust.d/

Examples

fapolicyd::trust_file { 'myapp':
  trusted_apps => [
    '/tmp/ls',
  ],
}

Parameters

The following parameters are available in the fapolicyd::trust_file defined type:

• trusted_apps

trusted_apps

Data type: Array[Stdlib::Absolutepath]

An array of the absolute path of applications to trust

Default value: []

Data types

Fapolicyd::Object

A type for defining a fapolicyd rule object

Alias of

Struct['type' => Enum['all','path','dir','device','ftype','trust','sha256hash'],
  'setting' => Optional[String[1]]]

Fapolicyd::Rule

A type for defining a fapolicyd rule

Alias of

Struct['decision' => Enum['allow', 'deny', 'allow_audit', 'deny_audit', 'allow_syslog', 'deny_syslog', 'allow_log', 'deny_log'],
  'perm' => Optional[Enum['open', 'execute', 'any']],
  'subjects' => Array[Fapolicyd::Subject,1],
  'objects' => Array[Fapolicyd::Object]]

Fapolicyd::Subject

A type for defining a fapolicyd rule subject

Alias of

Struct['type' => Enum['all','auid','uid','gid','sessionid','pid','ppid','trust','comm','exe','dir','ftype','device','pattern'],
  'setting' => Optional[Variant[String[1],Integer]]]

Changelog

All notable changes to this project will be documented in this file.

Release 0.1.1

Features

Bugfixes

• Fix incorrect match rule in trust file #4
• Minor updates to README documentation

Known Issues

Release 0.1.0

Features

Initial release - basic configuration of fapolicyd

Bugfixes

Known Issues