{"id":15014002,"url":"https://github.com/simp/pupmod-simp-auditd","last_synced_at":"2025-08-21T12:31:15.907Z","repository":{"id":32298672,"uuid":"35873632","full_name":"simp/pupmod-simp-auditd","owner":"simp","description":"The SIMP auditd Puppet Module","archived":false,"fork":false,"pushed_at":"2023-11-25T01:36:23.000Z","size":739,"stargazers_count":3,"open_issues_count":6,"forks_count":36,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-05-19T16:22:09.995Z","etag":null,"topics":["auditd","kernel","puppet","simp","simp-ecosystem"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-19T09:49:32.000Z","updated_at":"2024-06-18T22:52:03.967Z","dependencies_parsed_at":"2024-06-18T22:51:57.536Z","dependency_job_id":"e8389fc0-e958-416d-bc52-613d79a14915","html_url":"https://github.com/simp/pupmod-simp-auditd","commit_stats":{"total_commits":150,"total_committers":36,"mean_commits":4.166666666666667,"dds":0.8,"last_synced_commit":"06e49ce8e44c7e136ed12268fc7cbd3f6fe89e0f"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-auditd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-auditd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-auditd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-auditd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simp","download_url":"https://codeload.github.com/simp/pupmod-simp-auditd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230511483,"owners_count":18237658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auditd","kernel","puppet","simp","simp-ecosystem"],"created_at":"2024-09-24T19:45:03.106Z","updated_at":"2024-12-19T23:15:36.282Z","avatar_url":"https://github.com/simp.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License](https://img.shields.io/:license-apache-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/73/badge)](https://bestpractices.coreinfrastructure.org/projects/73)\n[![Puppet Forge](https://img.shields.io/puppetforge/v/simp/auditd.svg)](https://forge.puppetlabs.com/simp/auditd)\n[![Puppet Forge Downloads](https://img.shields.io/puppetforge/dt/simp/auditd.svg)](https://forge.puppetlabs.com/simp/auditd)\n[![Build Status](https://travis-ci.org/simp/pupmod-simp-auditd.svg)](https://travis-ci.org/simp/pupmod-simp-auditd)\n\n#### Table of Contents\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [Overview](#overview)\n* [This is a SIMP module](#this-is-a-simp-module)\n* [Module Description](#module-description)\n* [Setup](#setup)\n  * [Setup Requirements](#setup-requirements)\n  * [What Auditd Affects](#what-auditd-affects)\n* [Usage](#usage)\n  * [Basic Usage](#basic-usage)\n  * [Disabling Auditd](#disabling-auditd)\n  * [Changing Key Values](#changing-key-values)\n  * [Understanding Auditd Profiles](#understanding-auditd-profiles)\n    * [Stacking Profiles](#stacking-profiles)\n    * [The Custom Profile](#the-custom-profile)\n      * [Override All Other Profiles](#override-all-other-profiles)\n      * [Prepend Before the SIMP Profile](#prepend-before-the-simp-profile)\n      * [Append After the SIMP and STIG Profiles](#append-after-the-simp-and-stig-profiles)\n    * [The Built-in Profile](#the-built-in-profile)\n      * [Disabling All SIMP-provided Profiles](#disabling-all-simp-provided-profiles)\n      * [Enabling Sample Rulesets with Built-in Profile](#enabling-sample-rulesets-with-built-in-profile)\n      * [Configuring Complete Rulesets with Built-in Profile](#configuring-complete-rulesets-with-built-in-profile)\n  * [Adding One-Off Rules](#adding-one-off-rules)\n    * [Adding Regular Filter Rules](#adding-regular-filter-rules)\n    * [Prepend and Drop Everything From a User](#prepend-and-drop-everything-from-a-user)\n* [Development](#development)\n  * [Acceptance tests](#acceptance-tests)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## Overview\n\nThis module manages the Audit daemon, kernel parameters, and related subsystems.\n\n## This is a SIMP module\n\nThis module is a component of the [System Integrity Management Platform](https://simp-project.com),\na compliance-management framework built on Puppet.\n\nIf you find any issues, they can be submitted to our [JIRA](https://simp-project.atlassian.net/).\n\nThis module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:\n* When included within the SIMP ecosystem, security compliance settings will be\n  managed from the Puppet server.\n* If used independently, all SIMP-managed security subsystems will be disabled by\n  default and must be explicitly opted into by administrators.  Please review\n  ``simp_options`` for details.\n\n## Module Description\n\nYou can use this module for the management of all components of auditd\nincluding configuration, service management, kernel parameters, and custom rule\nsets.\n\nBy default, a rule set is provided that should meet a reasonable set of\noperational goals for most environments.\n\nThe `audit` kernel parameter may optionally be managed independently of the\nrest of the module using the `::auditd::config::grub` class.\n\n## Setup\n\n### Setup Requirements\n\nIf `auditd::syslog` is `true`, you will need to install\n[simp/rsyslog](https://forge.puppet.com/simp/rsyslog) as a dependency.\n\n### What Auditd Affects\n\n* The `audit` kernel parameter\n  * NOTE: This will be applied to *all* kernels in your standard grub configuration\n* The auditd service\n* The audid configuration in /etc/auditd.conf\n* The auditd rules in /etc/audit/rules.d\n* The audispd configuration in /etc/audisp/audispd.conf\n* The audispd `syslog` configuration if manage_syslog_plugin is enabled.\n     audit version 2 : /etc/audisp/plugins.d/syslog.conf\n     audit version 3 : /etc/auditd/plugins.d/syslog.conf\n\n## Usage\n\n### Basic Usage\n\n```puppet\n# Set up auditd with the default settings and SIMP default ruleset\n# A message will be printed indicating that you need to reboot for this option\n# to take full effect at each Puppet run until you reboot your system.\n\ninclude 'auditd'\n```\n\n### Disabling Auditd\n\nTo disable auditd at boot, set the following in hieradata:\n\n```yaml\nauditd::at_boot: false\n```\n\n### Enable/Disable sending audit event to syslog:\n\nThis capability is most useful for forwarding audit records to\nremote servers as syslog messages, since these records are already\npersisted locally in audit logs.  For most sites, however, using\nthis capability for all audit records can quickly overwhelm host\nand/or network resources, especially if the messages are forwarded\nto multiple remote syslog servers or persisted\nlocally. Site-specific, rsyslog actions to implement filtering will\nlikely be required to reduce this message traffic.\n\nThe setting ``auditd::syslog``, defaults to ``false`` or\n``syslog_options::syslog`` if you include ``simp_options``.  If you set\n``auditd::syslog: false``, it will not necessarily disable auditd logging to\nsyslog, puppet will just no longer manage the ``syslog.conf`` plugin file.\n\nThe settings needed for enabling/disabling sending audit log messages to syslog\nare shown below.\n\nTo enable:\n```yaml\nauditd::syslog: true\nauditd::config::audisp::syslog::enable: true\nauditd::config::audisp::syslog::drop_audit_logs: false\n# The setting for drop_audit_logs enabled for backwards compatability\n# but should be set to false if you want auditd to log to syslog.\n```\n\nTo disable:\n```yaml\nauditd::syslog: true\nauditd::config::audisp::syslog::enable: false\n```\n\n### Changing Key Values\n\nTo override the default values included in the module, you can either\ninclude new values for the keys at the time that the classes are declared,\nor set the values in hieradata:\n\n```puppet\n\nclass { 'auditd':\n  ignore_failures =\u003e true,\n  log_group       =\u003e 'root',\n  flush           =\u003e 'INCREMENTAL'\n}\n```\n\n```yaml\nauditd::ignore_failures: true\nauditd::log_group: 'root'\nauditd::flush: 'INCREMENTAL'\n```\n\n### Understanding Auditd Profiles\n\nThis module supports various configurations both independently and\nsimultaneously to meet varying end user requirements.\n\n\u003e NOTE: The default behavior of this module is to ignore any invalid rules and\n\u003e apply as much of the rule set as possible. This is done so that you end up\n\u003e with an effective level of auditing regardless of a simply typo or\n\u003e conflicting rule.  Please test your final rule sets to ensure that your\n\u003e system is auditing as expected.\n\nThe ``auditd::default_audit_profiles`` parameter determines which profiles are\nincluded, and in what order the rules are added to the system.\n\nThe ``auditd::default_audit_profiles`` has a default setting of ``[ 'simp' ]``\nwhich applies the optimized SIMP auditing profile which is suitable for meeting\nmost generally available compliance requirements. It does not, however,\ngenerally appease the scanning utilities since it optimizes the rules for\nperformance and most scanners cannot handle audit rule optimizations.\n\nThere are three other profiles available in the system by default:\n\n* ``stig``     =\u003e Applies the rules as defined in the latest covered DISA STIG\n* ``custom``   =\u003e Allows users to define their own rules easily via Hiera\n* ``built_in`` =\u003e Allows usage of EL8+ included sample rulesets to configure system\n\nThere are a large number of parameters exposed for each profile that are meant\nto be set via Hiera and you should take a look at the REFERENCE.md file to\nunderstand the full capabilities of each profile.\n\n#### Stacking Profiles\n\nIn some cases, you may want to combine profiles in different orders. This may\neither be done in order to pass a particular scanning engine or to ensure that\nitems that are not caught by the first profile are caught by the second.\n\nProfiles are included and ordered by passing an Array to the\n``auditd::default_audit_profiles`` parameter and are added to auditd in the\norder in which they are defined in the Array.\n\nFor example, this (the default) would only add the ``simp`` profile:\n\n```yaml\nauditd::default_audit_profiles:\n  - 'simp'\n```\n\nLikewise, this would add the ``stig`` rules prior to the ``simp`` profile:\n\n```yaml\nauditd::default_audit_profiles:\n  - 'stig'\n  - 'simp'\n```\n\n#### The Custom Profile\n\nUsers may wish to either completely override the default profiles or\nprepend/append their own rules to the stack for compliance purposes.\n\nYou can easily do this via Hiera as shown in the following example:\n\n```yaml\nauditd::config::audit_profiles::custom::rules:\n  - '-w /etc/passwd -wa -k passwd_files'\n  - '-w /etc/shadow -wa -k passwd_files'\n```\n\nTo activate the custom profile, you will need to set the\n``auditd::default_audit_profiles`` parameter as shown in the following\nexamples:\n\n##### Override All Other Profiles\n\n```yaml\nauditd::default_audit_profiles:\n  - 'custom'\n```\n\n##### Prepend Before the SIMP Profile\n\n```yaml\nauditd::default_audit_profiles:\n  - 'custom'\n  - 'simp'\n```\n\n##### Append After the SIMP and STIG Profiles\n\n```yaml\nauditd::default_audit_profiles:\n  - 'simp'\n  - 'stig'\n  - 'custom'\n```\n\n#### The Built-in Profile\n\nStarting with release 3.0.0-17 on EL8 hosts, the audit package includes a number\nof ``sample-rules`` under ``/usr/share/audit/sample-rules`` that can be used\nto configure a system fairly completely. Within these rules are sets for STIG,\nOSPP, etc. that can simply be moved to ``/etc/audit/rules.d`` and compiled with\n``augenrules`` to configure a system.\n\n##### Disabling All SIMP-provided Profiles\n\nMost likely, if using the sample rulesets from the built-in profile, you will\nwant to disable included SIMP profiles (not necessary, but may include\noverlapping rules if not). To do this:\n\n```yaml\nauditd::default_audit_profiles:\n  - 'built_in'\n```\n\n##### Enabling Sample Rulesets with Built-in Profile\n\nTo enable specific sample rulesets, simply include them in the built-in profile\nparameter:\n\n```yaml\nauditd::config::audit_profiles::built_in::rulesets:\n  - 'base-config'\n  - 'stig'\n  - 'finalize'\n```\n\nwhere the ruleset names are found via the custom fact ``auditd_sample_rulesets``\n\n##### Configuring Complete Rulesets with Built-in Profile\n\nIf you are only planning to use the ``built_in`` profile and the included sample\nrulesets to configure the system, it will be worth noting that profile-specific\nsample files include configuration information within comments in the files as well.\n\nAs an example, the STIG rules sample file will note that it relies on ``base-config``\nand ``finalize`` rulesets to be feature-complete. Other rulesets will contain similar\ninformation.\n\n### Adding One-Off Rules\n\nRules are alphanumerically ordered based on file-system globbing. It is\nrecommended that users use the ``auditd::rule`` defined type for adding rules.\n\nOther options are available with ``auditd::rule`` but these are the most\ncommonly used.\n\n#### Adding Regular Filter Rules\n\n```puppet\n\nauditd::rule { 'failed_file_creation':\n  content =\u003e '-a always,exit -F arch=b64 -S creat -F exit=-EACCES -k failed_file_creation'\n}\n```\n\n```puppet\n\nauditd::rule { 'passwd_file_watches':\n  content =\u003e [\n    '-w /etc/passwd -wa -k passwd_files',\n    '-w /etc/shadow -wa -k passwd_files'\n  ]\n}\n```\n\n#### Prepend and Drop Everything From a User\n\nThis will make your rule land in the ``00`` set of rules.\n\n```puppet\n\nauditd::rule { 'pre_drop_user_5000':\n  content =\u003e '-a exit,never -F auid=5000',\n  prepend =\u003e true\n}\n```\n\n## Development\n\nPlease read our [Contribution Guide](https://simp.readthedocs.io/en/stable/contributors_guide/Contribution_Procedure.html)\n\n### Acceptance tests\n\nThis module includes [Beaker](https://github.com/puppetlabs/beaker) acceptance\ntests using the SIMP [Beaker Helpers](https://github.com/simp/rubygem-simp-beaker-helpers).\nBy default the tests use [Vagrant](https://www.vagrantup.com/) with\n[VirtualBox](https://www.virtualbox.org) as a back-end; Vagrant and VirtualBox\nmust both be installed to run these tests without modification. To execute the\ntests run the following:\n\n```shell\nbundle exec rake beaker:suites\n```\n\nSome environment variables may be useful:\n\n```shell\nBEAKER_debug=true\nBEAKER_provision=no\nBEAKER_destroy=no\nBEAKER_use_fixtures_dir_for_modules=yes\nBEAKER_fips=yes\n```\n\n* `BEAKER_debug`: show the commands being run on the STU and their output.\n* `BEAKER_destroy=no`: prevent the machine destruction after the tests finish so you can inspect the state.\n* `BEAKER_provision=no`: prevent the machine from being recreated. This can save a lot of time while you're writing the tests.\n* `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.\n* `BEAKER_fips=yes`: enable FIPS-mode on the virtual instances. This can\n  take a very long time, because it must enable FIPS in the kernel\n  command-line, rebuild the initramfs, then reboot.\n\nPlease refer to the [SIMP Beaker Helpers documentation](https://github.com/simp/rubygem-simp-beaker-helpers/blob/master/README.md)\nfor more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimp%2Fpupmod-simp-auditd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimp%2Fpupmod-simp-auditd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimp%2Fpupmod-simp-auditd/lists"}