Table of Contents

1. Description
2. Setup - The basics of getting started with ima
   • What ima affects
   • Beginning with ima
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module
   • Acceptance Tests - Beaker env variables

Description

This module manages the Integrity Management Architecture (IMA), a tool that verifies the integrity of the system, based on filesystem and file hashes. The IMA class sets up IMA kernel boot flags if they are not enabled and when they are, mounts the securityfs. This module can manage the IMA policy, although modifying the policy incorrectly could cause your system to become read-only.

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet

If you find any issues, they may be submitted to our bug tracker.

This module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:

• When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.
• If used independently, all SIMP-managed security subsystems are disabled by default and must be explicitly opted into by administrators. Please review the $enable_* and $manage_* parameters in manifests/init.pp for details.

Setup

What ima affects

WARNING

Inserting poorly-formed or incorrect policy into the IMA policy file could cause your system to become read-only. This can be temporarily remedied by rebooting and setting ima_appraise to fix in the kernel command line parameters. This is the current case with the way the module manages the policy and it is not recommended to use this section of the module at this time.

This module will:

• Enable IMA on the host
• (OPTIONAL) Manage the IMA policy (BROKEN - See Limitations)

Beginning with the IMA module

classes:
  - ima::appraise
  - ima::policy

To remove IMA, first disable components by adding this to hiera:

ima::policy::enable: false
ima::appraise::enable: false
ima::enable: false

This removes systems parameters managed IMA. The classes can then be removed.

Usage

Reference

Please refer to the inline documentation within each source file, or to the module's generated YARD documentation for reference material.

Limitations

SIMP Puppet modules are generally intended for use on Red Hat Enterprise Linux and compatible distributions, such as CentOS. Please see the file metadata.json for the most up-to-date list of supported operating systems, Puppet versions, and module dependencies.

The default configuration of this module updates EFI boot parameters if they are present. If the system relies upon BIOS for boot, ensure there is not an EFI grub.cfg or grub2.cfg present or the BIOS grub config file will not be updated.

The current RedHat implementation of IMA does not seem to work after inserting our default policy (generated example in spec/files/default_ima_policy.conf). It causes the system to become read-only, even though it is only using supported configuration elements. The module will be updated soon with more sane defaults to allow for at least the minimal amount of a system to be measured.

To get started, include the ima::policy class and set these parameters. From there, they can be changed to true on one by one:

ima::policy::measure_root_read_files: false
ima::policy::measure_file_mmap: false
ima::policy::measure_bprm_check: false
ima::policy::measure_module_check: false
ima::policy::appraise_fowner: false

Development

Please read our Contribution Guide

Acceptance tests

To run the system tests, you need Vagrant installed.

You can then run the following to execute the acceptance tests:

   bundle exec rake beaker:suites

Some environment variables may be useful:

   BEAKER_debug=true
   BEAKER_provision=no
   BEAKER_destroy=no
   BEAKER_use_fixtures_dir_for_modules=yes

• BEAKER_debug: show the commands being run on the STU and their output.
• BEAKER_destroy=no: prevent the machine destruction after the tests finish so you can inspect the state.
• BEAKER_provision=no: prevent the machine from being recreated. This can save a lot of time while you're writing the tests.
• BEAKER_use_fixtures_dir_for_modules=yes: cause all module dependencies to be loaded from the spec/fixtures/modules directory, based on the contents of .fixtures.yml. The contents of this directory are usually populated by bundle exec rake spec_prep. This can be used to run acceptance tests to run on isolated networks.

Reference

Table of Contents

Classes

• ima: Sets up IMA kernel boot flags if they are not enabled, and mounts the securityfs when they are.
• ima::appraise: Manage IMA Appraisal To enable IMA appraisal first make sure all your locally mounted file systems with root files on them are mounted with
• ima::appraise::fixmode: set the ima appraise mode to fix
• ima::appraise::relabel: This module executes the script to label the files systems with the security.ima attributes and if it is complete, adds resources to set im
• ima::policy: Manage IMA Policy * The term watch, as used here, means both IMA policy fields dont_measure and dont_appraise. Both lines

Data types

• Ima::Template

Classes

ima

Sets up IMA kernel boot flags if they are not enabled, and mounts the securityfs when they are.

Parameters

The following parameters are available in the ima class:

• enable
• mount_dir
• ima_audit
• ima_template
• ima_hash
• ima_tcb
• log_max_size
• ima_tcb
• log_max_size

enable

Data type: Boolean

Enable IMA on the system

Default value: true

mount_dir

Data type: Stdlib::AbsolutePath

Where to mount the IMA securityfs

Default value: '/sys/kernel/security'

ima_audit

Data type: Boolean

Audit control. Can be set to: true - Enable additional integrity auditing messages false - Enable integrity auditing messages (default)

Default value: false

ima_template

Data type: Ima::Template

A predefined IMA measurement template format.

• NOTE: This is only valid in kernel version >= 3.13. It is always ima in older versions.

Default value: 'ima-ng'

ima_hash

Data type: String[1]

The list of supported hashes can be found in crypto/hash_infotru.h

Default value: 'sha256'

ima_tcb

Data type: Boolean

Toggle the TCB policy. This means IMA will measure all programs exec'd, files mmap'd for exec, and all file opened for read by uid=0. Defaults to true.

Default value: true

log_max_size

Data type: Integer[1]

The size of the /sys/kernel/security/ima/ascii_runtime_measurements, in bytes, that will cause a reboot notification will be sent to the user.

Default value: 30000000

ima_tcb

Toggle the TCB policy

• IMA will measure all programs called via exec, files copied via mmap, and all files opened by uid=0.

Default value: true

log_max_size

The size of /sys/kernel/security/ima/ascii_runtime_measurements, in bytes, that will cause a reboot notification will be sent to the user.

Default value: 30000000

ima::appraise

Manage IMA Appraisal

To enable IMA appraisal first make sure all your locally mounted file systems with root files on them are mounted with i_version option.

(TODO: check for this and set if possible)

Then include the ima::appraise module in your classes.

It is also recommended, although not necessary, to enable the management of the ima

policy by including the ima::policy module in you classes because the default

policy is over zealous

When puppet runs it will configure the system to reboot into ima_appraise mode fix.

The system will then need to be rebooted and will notify with an ima_appraise_fix_reboot notice.

When the system is rebooted it will be in fix mode and it will label all the files with the required security.ima filesystem attribute. This takes a while. Puppet will notify not to reboot until this script completes. Puppet will notify with an ima_appraise_enforce_reboot notice when the script completes.

When the system is rebooted it will boot into ima_appraisal in enforce mode.

If you need to update files after the system has been in enforce mode:

1. Set ima::appraise::force_fixmode to true,
2. Run puppet and reboot when prompted.

When you have completed the upgrade, run the script /usr/local/bin/ima_security_attr_update.sh.

When the completes, set force_fixmode back to false, rerun puppet, and reboot when prompted.

Troubleshooting:

• If you reboot and are getting SELinux errors or you do not have permissions to access your files then you probably forgot to set i_version on your mounts in /etc/fstab.

• If you reboot and it won't load the initramfs then the dracut update didn't run. You can fix this by rebooting without the ima kernel settings, running dracut -f and then rebooting in ima appraise mode.

• See also

  • https://wiki.gentoo.org/wiki/Integrity_Measurement_Architecture
  • Kernel
    • documentation Documentation/ABI/testing/ima_policy
  • https://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/Documentation/ABI/testing/ima_policy?id=refs/tags/v3.10.103

Parameters

The following parameters are available in the ima::appraise class:

• enable
• relabel_file
• scriptdir
• force_fixmode
• ensure_packages

enable

Data type: Boolean

Enable IMA appraise capability. Setting to false will remove IMA appraise boot settings from the system.

Default value: true

relabel_file

Data type: Stdlib::AbsolutePath

The file to touch when the file system needs relabeling

Default value: "${facts['puppet_vardir']}/simp/.ima_relabel"

scriptdir

Data type: Stdlib::AbsolutePath

The directory to place scripts.

Default value: '/usr/local/bin'

force_fixmode

Data type: Boolean

This will force the system into fix_mode so you can update files and then relabel the system - requires a reboot.

Default value: false

ensure_packages

Data type: Simplib::PackageEnsure

Ensure setting for all packages installed by this module

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })

ima::appraise::fixmode

set the ima appraise mode to fix

Parameters

The following parameters are available in the ima::appraise::fixmode class:

• relabel_file
• relabel

relabel_file

Data type: StdLib::AbsolutePath

relabel

Data type: Boolean

ima::appraise::relabel

This module executes the script to label the files systems with the security.ima attributes and if it is complete, adds resources to set ima_appraise to enforce mode.

When a the file system needs to be labeled a file, relabel file is created in the appraise class. If this file exists then the script to relabel the files is called and passed the file name. The script will remove the file when it is complete.

The fact ima_security checks the status of the file and also checks if the script is running. If the script is active, no resources are created, if the relabel file exists and and the script is not active, it launches the script if the file does not exist, it calls the class to create the resources for setting the system into enforce mode.

@param relabel_file The location of the file that that indicates a labeling of the file system is needed.

@param scriptdir The directory containing the scripts.

Parameters

The following parameters are available in the ima::appraise::relabel class:

• relabel_file
• scriptdir

relabel_file

Data type: Stdlib::AbsolutePath

scriptdir

Data type: Stdlib::AbsolutePath

Default value: $ima::appraise::scriptdir

ima::policy

Manage IMA Policy

• The term watch, as used here, means both IMA policy fields dont_measure and dont_appraise. Both lines will be dropped for each entry here.

• See also

  • https://wiki.gentoo.org/wiki/Integrity_Measurement_Architecture
  • Kernel
    • documentation Documentation/ABI/testing/ima_policy
  • https://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/Documentation/ABI/testing/ima_policy?id=refs/tags/v3.10.103

Parameters

The following parameters are available in the ima::policy class:

• manage
• dont_watch_proc
• dont_watch_sysfs
• dont_watch_debugfs
• dont_watch_tmpfs
• dont_watch_ramfs
• dont_watch_securityfs
• dont_watch_devpts
• dont_watch_binfmtfs
• dont_watch_selinux
• dont_watch_nfs
• dont_watch_cgroup
• dont_watch_initrc_var_log_t
• dont_watch_rpm_var_cache_t
• dont_watch_puppet_log_t
• dont_watch_auditd_log_t
• dont_watch_auth_cache_t
• dont_watch_fsadm_log_t
• dont_watch_rsync_log_t
• dont_watch_getty_log_t
• dont_watch_nscd_log_t
• dont_watch_cron_log_t
• dont_watch_lastlog_t
• dont_watch_var_log_t
• dont_watch_wtmp_t
• dont_watch_list
• measure_root_read_files
• measure_file_mmap
• measure_bprm_check
• measure_module_check
• appraise_fowner

manage

Data type: Boolean

Manage IMA policy capability. Setting to false will stop IMA policy services on the system.

Default value: true

dont_watch_proc

Data type: Boolean

Disable IMA hashing of procfs filesystems

Default value: true

dont_watch_sysfs

Data type: Boolean

Disable IMA hashing of sysfs filesystems

Default value: true

dont_watch_debugfs

Data type: Boolean

Disable IMA hashing of debugfs filesystems

Default value: true

dont_watch_tmpfs

Data type: Boolean

Disable IMA hashing of tmpfs filesystems

Default value: true

dont_watch_ramfs

Data type: Boolean

Disable IMA hashing of ramfs filesystems

Default value: true

dont_watch_securityfs

Data type: Boolean

Disable IMA hashing of securityfs filesystems

Default value: true

dont_watch_devpts

Data type: Boolean

Disable IMA hashing of /dev/pts filesystems

Default value: true

dont_watch_binfmtfs

Data type: Boolean

Disable IMA hashing of binfmtfs filesystems

Default value: true

dont_watch_selinux

Data type: Boolean

Disable IMA hashing of selinux_fs filesystems

Default value: true

dont_watch_nfs

Data type: Boolean

Disable IMA hashing of nfs filesystems

Default value: true

dont_watch_cgroup

Data type: Boolean

Disable IMA hashing of cgroup filesystems

Default value: true

dont_watch_initrc_var_log_t

Data type: Boolean

Default value: true

dont_watch_rpm_var_cache_t

Data type: Boolean

Default value: true

dont_watch_puppet_log_t

Data type: Boolean

Default value: true

dont_watch_auditd_log_t

Data type: Boolean

Default value: true

dont_watch_auth_cache_t

Data type: Boolean

Default value: true

dont_watch_fsadm_log_t

Data type: Boolean

Default value: true

dont_watch_rsync_log_t

Data type: Boolean

Default value: true

dont_watch_getty_log_t

Data type: Boolean

Default value: true

dont_watch_nscd_log_t

Data type: Boolean

Default value: true

dont_watch_cron_log_t

Data type: Boolean

Default value: true

dont_watch_lastlog_t

Data type: Boolean

Default value: true

dont_watch_var_log_t

Data type: Boolean

Default value: true

dont_watch_wtmp_t

Data type: Boolean

Default value: true

dont_watch_list

Data type: Array[String]

A list of selinux contexts that shouldn't be watched, merged with all of the parameters above

Default value: []

measure_root_read_files

Data type: Boolean

Monitor all files opened by root

Default value: false

measure_file_mmap

Data type: Boolean

Monitor all files mmapped executable in file_mmap

Default value: false

measure_bprm_check

Data type: Boolean

Monitor all executables in bprm_check

Default value: false

measure_module_check

Data type: Boolean

Default value: false

appraise_fowner

Data type: Boolean

Appraises all files owned by root

Default value: false

Data types

Ima::Template

The Ima::Template data type.

Alias of Enum['ima', 'ima-ng', 'ima-sig']

• Mon Jul 15 2024 Steven Pritchard steve@sicura.us - 0.8.1

• Fixes for Puppet 8 compatibility

• Mon Oct 23 2023 Steven Pritchard steve@sicura.us - 0.8.0

• [puppetsync] Add EL9 support

• Wed Oct 11 2023 Steven Pritchard steve@sicura.us - 0.7.0

• [puppetsync] Updates for Puppet 8
  • These updates may include the following:
    • Update Gemfile
    • Add support for Puppet 8
    • Drop support for Puppet 6
    • Update module dependencies

• Wed Aug 23 2023 Steven Pritchard steve@sicura.us - 0.6.0

• Add AlmaLinux 8 support

• Mon Jun 12 2023 Chris Tessmer chris.tessmer@onyxpoint.com - 0.5.0

• Add RockyLinux 8 support

• Tue Jun 15 2021 Chris Tessmer chris.tessmer@onyxpoint.com - 0.4.0

• Removed support for Puppet 5
• Ensured support for Puppet 7 in requirements and stdlib

• Fri Dec 18 2020 Chris Tessmer chris.tessmer@onyxpoint.com - 0.3.1

• Removed EL6 support

• Mon Dec 16 2019 Trevor Vaughan tvaughan@onyxpoint.com - 0.3.0-0

• Add EL8 support

• Tue Jul 16 2019 Robert Vincent pillarsdotnet@gmail.com - 0.2.0-0

• Provide Puppet-6 compatibility.
• Facter.value(:cmdline) is not always set.

• Thu Mar 07 2019 Liz Nemsick lnemsick.simp@gmail.com - 0.1.1-0

• Update the upper bound of stdlib to < 6.0.0
• Update a URL in the README.md

• Thu Nov 01 2018 Jeanne Greulich jeanne.greulich@onypoint.com - 0.1.0-0

• static asset updates

• Fri Sep 14 2018 Michael Morrone michael.morrone@onypoint.com - 0.1.0-0

• Made ima::appraise and ima::policy unambiguously public classes

• Thu Aug 09 2018 Michael Morrone michael.morrone@onypoint.com - 0.1.0-0

• Initial module
• Originially developed in SIMP TPM module