Ansible

TEMPLATE ansible_instantiate_variables

Pass strings that correspond to XCCDF value names as arguments to this macro:

ansible_instantiate_variables("varname1", "varname2")

Then, assume that the task that follows can work with the variable by referencing it, e.g. value: Setting={{ varname1 }}

ansible_instantiate_variables()

TEMPLATE ansible_lineinfile

A wrapper over the Ansible lineinfile module. This handles the most common options for us. regex is optional and when blank, it won’t be included in the Ansible script; this allows arbitrary additions to files. new_line will only be passed when state is present. with_items will be specified only if non-empty, allowing for iterating through a variable of content (with the appropriate macro-based path). register will be specified only if non-empty, allowing for saving the output of this lineinfile module. check_mode allows an idempotent way to gather output, or run a task without changes. Useful when calling the ansible_only_lineinfile macro to handle deduplication of values.

Note that all string-like parameters are single quoted in the YAML.

ansible_lineinfile(msg=’’, path=’’, mode=’’, regex=’’, new_line=’’, create=’no’, state=’present’, with_items=’’, register=’’, when=’’, validate=’’, insert_after=’’, insert_before=’’, check_mode=False)

TEMPLATE ansible_stat

Check the file system status of an object. Not a full implementation.

Parameters:

  • msg (str) – Optional task title

  • path (str) – Path to file

  • register (str) – variable to register

ansible_stat(msg=’’, path=’’, register=’’)

TEMPLATE ansible_find

Find files matching a particular value. Not a full implementation.

ansible_find(msg=’’, paths=’’, recurse=’yes’, follow=’no’, contains=’’, register=’’, when=’’)

TEMPLATE ansible_only_lineinfile

A wrapper for adding one, unique line to a file. A regex must be specified to tell if the line is unique. This is helpful in configuration files where a single configuration parameter might have multiple values, but only one value is approved. All lines matching the regex are first removed and then the new line is appended to the file.

ansible_only_lineinfile(msg, path, line_regex, new_line, create=’no’, block=False, validate=’’, insert_after=’’, insert_before=’’, mode=’’)

TEMPLATE ansible_set_config_file

Ensure the configuration is set in a file. Note this handles generic key-seperator-value files with no sense of structure. In particular, ini configuration files are best served with the ini Ansible module instead of lineinfile-based solutions.

ansible_set_config_file(msg, file, parameter, separator=’ ‘, separator_regex=’s+’, value=’’, prefix_regex=’^s*’, create=’no’, validate=’’, insert_after=’’, insert_before=’’, mode=’’)

TEMPLATE ansible_set_config_file_dir

Ensure the configuration is set in a file and not conflicted by a configuration in a directory. Note this handles generic key-separator-value files with no sense of structure. In particular, ini configuration files are best served with the ini Ansible module instead of lineinfile-based solutions.

ansible_set_config_file_dir(msg, config_file, config_dir, set_file, parameter, separator=’ ‘, separator_regex=’s+’, value=’’, prefix_regex=’^s*’, create=’no’, validate=’’, insert_after=’’, insert_before=’’)

TEMPLATE ansible_sshd_set

High level macro to set a value in the ssh daemon configuration file. We specify a case insensitive comparison in the prefix since this is used to deduplicate since sshd_config has case-insensitive parameters (but case-sensitive values). We also specify the validation program here; -t specifies test and -f allows Ansible to pass a file at a different path.

Set set a parameter in /etc/sshd_config or /etc/ssh/sshd_config.d/

Parameters:

  • msg (str) – Message to be set as Task Title, if not set the rule’s title will be used instead

  • parameter (str) – Parameter to set

  • value (str) – The value to set

  • config_is_distributed (str) – If true, will ok look in /etc/ssh/sshd_config.d

  • config_basename (str) – Filename of configuration file when using distributed configuration

ansible_sshd_set(msg=’’, parameter=’’, value=’’, config_is_distributed=”false”, config_basename=”00-complianceascode-hardening.conf”)

TEMPLATE ansible_shell_set

High level macro to set a value in a shell-related file that contains var assignments.

We also specify the validation program here; see

bash -c “help set” | grep -e -n

Parameters:

  • msg (str) – The name for the Ansible task

  • path (str) – to the file

  • parameter (str) – Parameter to be set in the configuration file

  • value (str) – value of the parameter

ansible_shell_set(msg, path, parameter, value=’’, no_quotes=false)

TEMPLATE ansible_tmux_set

High level macro to set a command in tmux configuration file /etc/tmux.conf. Automatically adds “set -g “ before the parameter.

Parameters:

  • msg (str) – The name for the Ansible task

  • parameter (str) – Parameter to be set in the configuration file

  • value (str) – Value of the parameter

ansible_tmux_set(msg=’’, parameter=’’, value=’’)

TEMPLATE ansible_auditd_set

High level macro to set a command in auditd configuration file /etc/audit/auditd.conf.

Parameters:

  • msg (str) – The name for the Ansible task

  • parameter (str) – Parameter to be set in the configuration file

  • value (str) – Value of the parameter

ansible_auditd_set(msg=’’, parameter=’’, value=’’)

TEMPLATE ansible_coredump_config_set

High level macro to set a parameter in /etc/systemd/coredump.conf. For SLE platforms put remediation in drop-in configuration file /etc/systemd/coredump.conf.d/oscap-autoremedy.conf.

Parameters:

  • msg (str) – The name for the Ansible task

  • parameter (str) – Parameter to be set in the configuration file

  • value (str) – Value of the parameter

ansible_coredump_config_set(msg=’’, parameter=’’, value=’’)

TEMPLATE ansible_selinux_config_set

High level macro to set a parameter in /etc/selinux/config.

Parameters:

  • msg (str) – The name for the Ansible task

  • parameter (str) – Parameter to be set in the configuration file

  • value (str) – Value of the parameter

ansible_selinux_config_set(msg=’’, parameter=’’, value=’’)

TEMPLATE ansible_file_contents

Generates an Ansible task that puts ‘contents’ into a file at ‘filepath’

Parameters:

  • filepath (str) – filepath of the file to check

  • contents (str) – contents that should be in the file

ansible_file_contents(filepath=’’, contents=’’)

TEMPLATE ansible_deregexify_banner_etc_issue

Formats a banner regex for use in /etc/issue, /etc/issue.net or /etc/motd

Parameters:

  • banner_var_name (str) – name of ansible variable with the banner regex

ansible_deregexify_banner_etc_issue(banner_var_name)

TEMPLATE ansible_deregexify_banner_dconf_gnome

Formats a banner regex for use in dconf

Parameters:

  • banner_var_name (str) – name of ansible variable with the banner regex

ansible_deregexify_banner_dconf_gnome(banner_var_name)

TEMPLATE ansible_deregexify_banner_anchors

Strips anchors around the banner

ansible_deregexify_banner_anchors()

TEMPLATE ansible_deregexify_multiple_banners

Strips multibanner regex and keeps only the first banner

ansible_deregexify_multiple_banners()

TEMPLATE ansible_deregexify_banner_space

Strips whitespace or newline regex

ansible_deregexify_banner_space()

TEMPLATE ansible_deregexify_banner_newline

Strips newline or newline escape sequence regex

ansible_deregexify_banner_newline(newline)

TEMPLATE ansible_deregexify_banner_newline_token

Strips newline token for a newline escape sequence regex

ansible_deregexify_banner_newline_token()

TEMPLATE ansible_deregexify_banner_backslash

Strips backslash regex

ansible_deregexify_banner_backslash()

TEMPLATE ansible_audit_augenrules_add_watch_rule

The following macro remediates one audit watch rule in /etc/audit/rules.d directory.

Parameters:

  • path (str) – path to watch

  • permissions (str) – permissions changes to watch for

  • key (str) – key to use as identifier. Note that if there exists any other rule with the same find_mac_key in some file within /etc/audit/rules.d/, the new rule will be appended to this file.

ansible_audit_augenrules_add_watch_rule(path=’’, permissions=’’, key=’’)

TEMPLATE ansible_audit_auditctl_add_watch_rule

The following macro remediates one audit watch rule in /etc/audit/audit.rules.

Parameters:

  • path (str) – Path to watch

  • permissions (str) – Permissions changes to watch for

  • key (str) – Key to use as identifier

ansible_audit_auditctl_add_watch_rule(path=’’, permissions=’’, key=’’)

TEMPLATE ansible_audit_augenrules_add_syscall_rule

The following macro remediates Audit syscall rule in /etc/audit/rules.d directory. The macro requires following parameters:

Parameters:

  • action_arch_filters (str) – The action and arch filters of the rule. For example, “-a always,exit -F arch=b64”

  • other_filters (str) – Other filters that may characterize the rule. For example, “-F a2&03 -F path=/etc/passwd”

  • auid_filters (str) – The auid filters of the rule. For example, “-F auid>=” ~ uid_min ~ “ -F auid!=unset”

  • syscalls (list[str]) – List of syscalls to ensure presense among audit rules. For example, “[‘fchown’, ‘lchown’, ‘fchownat’]”

  • syscall_grouping (list[str]) – List of other syscalls that can be grouped with ‘syscalls’. For example, “[‘fchown’, ‘lchown’, ‘fchownat’]”

  • key (str) – The key to use when appending a new rule

ansible_audit_augenrules_add_syscall_rule(action_arch_filters=””, other_filters=””, auid_filters=””, syscalls=[], key=””, syscall_grouping=[])

TEMPLATE ansible_audit_auditctl_add_syscall_rule

The following macro remediates Audit syscall rule in /etc/audit/audit.rules file.

Parameters:

  • action_arch_filters (str) – The action and arch filters of the rule. For example, “-a always,exit -F arch=b64”

  • other_filters (str) – Other filters that may characterize the rule. For example, “-F a2&03 -F path=/etc/passwd”

  • auid_filters (str) – The auid filters of the rule. For example, “-F auid>=” ~ uid_min ~ “ -F auid!=unset”

  • syscalls (list[str]) – List of syscalls to ensure presense among audit rules. For example, “[‘fchown’, ‘lchown’, ‘fchownat’]”

  • key (str) – The key to use when appending a new rule

  • syscall_grouping (list[str]) – List of other syscalls that can be grouped with ‘syscalls’. For example, “[‘fchown’, ‘lchown’, ‘fchownat’]”

ansible_audit_auditctl_add_syscall_rule(action_arch_filters=””, other_filters=””, auid_filters=””, syscalls=[], key=””, syscall_grouping=[])

TEMPLATE ansible_sudo_remove_config

This macro comments out a given line of the sudoers and then validates it before saving.

Parameters:

  • parameter (str) – The parameter to remove

  • pattern (str) – The pattern to remove

ansible_sudo_remove_config(parameter, pattern)

TEMPLATE ansible_pkg_conditional

This macro creates an Ansible snipped which is used in when clause to determine applicability of a task. If the package passed as a parameter is installed, the task is applicable. The macro respects platform_package_overrides variable.

Parameters:

  • package (str) – package name

  • op (str) – version comparison operator (“<”, “<=”, “==”, “!=”, “>”, “>=”)

  • ver (str) – package version (optional argument, use together with “op”)

ansible_pkg_conditional(package, op=None, ver=None)

TEMPLATE ansible_check_authselect_integrity

Macro used to check if authselect files are intact. When used, it will exit the respective script if any authselect file was modified without proper use of authselect tool and respective profiles.

ansible_check_authselect_integrity()

TEMPLATE ansible_apply_authselect_changes

Macro used to apply changes on authselect profiles. The command automatically creates a backup of the current settings before applying the changes. It is possible to inform a custom backup name through the “backup_name” parameter. If the “backup_name” parameter is not defined, the authselect default name is used. The default name is formed by the current date and time suffixed by 6 random alphanumeric characters. The authselect backups are stored in sub-folders inside the “/var/lib/authselect/backups” folder, identified by their respective backup names. Note: An existing backup can be overwritten if the same backup name is informed. If this is not desired, avoid defining a backup name.

Parameters:

  • backup_name (str) – Changes the default backup name used by authselect.

ansible_apply_authselect_changes(backup_name=’’)

TEMPLATE ansible_disable_authselect_feature

Disable authselect feature if the authselect current profile is intact or inform that its integrity check failed.

ansible_disable_authselect_feature(feature)

TEMPLATE ansible_enable_authselect_feature

Enable authselect feature if the authselect current profile is intact or inform that its integrity check failed.

ansible_enable_authselect_feature(feature)

TEMPLATE ansible_check_authselect_presence

Used to identify if authselect is present or not in the system. Some macros can change the remediation behavior based on the presence of authselect.

ansible_check_authselect_presence()

TEMPLATE ansible_pam_lastlog_enable_showfailed

Ensure pam_lastlog.so PAM module shows the failed logins according to the system capabilities. If authselect is present and the “with-silent-lastlog” feature is available, the feature will be disabled. If authselect is present but the “with-silent-lastlog” feature is not yet available, a custom profile will be used. If authselect is not present, PAM files will be directly edited.

Parameters:

  • pam_file (str) – PAM config file.

  • control (str) – PAM control flags.

  • after_match (str) – Regex used as reference to append a line, if necessary. Optional parameter. Note: For this macro, there is a special value used to include a line at the beginning of the file: “BOF”

ansible_pam_lastlog_enable_showfailed(pam_file, control, after_match=’’)

TEMPLATE ansible_pam_pwhistory_enable

Enable pam_pwhistory.so PAM module according to the system capabilities. If authselect is present and the “with-pwhistory” feature is available, the feature will be enabled. If authselect is present but the “with-pwhistory” feature is not yet available, a custom profile will be used. If authselect is not present, PAM files will be directly edited.

Parameters:

  • pam_file (str) – PAM config file.

  • control (str) – PAM control flags.

  • after_match (str) – Regex used as reference to append a line, if necessary. Optional parameter. Note: For this macro, there is a special value used to include a line at the beginning of the file: “BOF”

ansible_pam_pwhistory_enable(pam_file, control, after_match=’’)

TEMPLATE ansible_pam_pwhistory_parameter_value

Set pam_pwhistory.so PAM module options and values. In case the file /etc/security/pwhistory.conf is present in the system, the option is ensured there and removed from pam files to avoid conflicts or confusion.

Parameters:

  • pam_file (str) – PAM config file.

  • parameter (str) – pwhistory parameter/option e.g.: remember, retry, debug

  • pwhistory_var_name (str) – Literal variable name.

ansible_pam_pwhistory_parameter_value(pam_file, parameter, pwhistory_var_name=’’)

TEMPLATE ansible_pam_faillock_enable

This macro ensures the pam_faillock.so PAM module is enabled. It is enabled using the authselect tool or editing the PAM files, only if authselect tool is not available.

ansible_pam_faillock_enable()

TEMPLATE ansible_pam_faillock_parameter_value

This macro make sure the informed parameter from pam_faillock.so PAM module is properly set. In case the file /etc/security/faillock.conf is present in the system, the option is removed from PAM files since it is not needed there in that case.

Parameters:

  • parameter (str) – The pam_faillock.so parameter name.

  • faillock_var_name (str) – If the parameter expects a value from a variable, the variable name is informed here.

  • authfail (bool) – check the pam_faillock.so conf line with authfail

ansible_pam_faillock_parameter_value(parameter, faillock_var_name=’’, authfail=True)

TEMPLATE ansible_grub2_bootloader_argument

Macro for Ansible remediation for adding a kernel command line argument to the GRUB 2 bootloader. Part of the grub2_bootloader_argument template.

Parameters:

  • arg_name (str) – Kernel command line argument

  • arg_name_value (str) – Kernel command line argument concatenated with the value of this argument using an equal sign, eg. “noexec=off”.

ansible_grub2_bootloader_argument(arg_name, arg_name_value)

TEMPLATE ansible_grub2_bootloader_argument_absent

Macro for Ansible remediation for removing a kernel command line argument from the GRUB 2 bootloader. Part of the grub2_bootloader_argument_absent template.

Parameters:

  • arg_name (str) – Name of the kernel command line argument that will be removed from GRUB 2 configuration.

ansible_grub2_bootloader_argument_absent(arg_name)

TEMPLATE ansible_restrict_permissions_home_directories

Macro to restrict permissions in home directories of interactive users

ansible_restrict_permissions_home_directories(recursive=false)

TEMPLATE ansible_ensure_pam_module_line

Make sure that a line with a specific PAM module is present with the correct control. If the line is not present, it will be included after the regex informed in the “after_match” parameter. If the “after_match” parameter is empty, the line will be included at the end of the file informed in the “pam_file” parameter. If the line was already present, but with a different control, the control will be updated. Note: If there are multiple lines matching the “group” + “module”, no lines will be updated. Instead, a new line will be included after the regex informed in “after_match” or at the end of file if “after_match” parameter is empty or there is no match. This is a conservative safeguard for improper use of this macro in rare cases of modules configured by multiple lines, like pam_sss.so, pam_faillock.so and pam_lastlog.so. In some situations, these special modules may have similar lines sharing the same “group” and “module”. For these specific cases, this macro is not recommened without careful tests to make sure the PAM module is working as expected. Otherwise, a custom remediation should be considered.

Parameters:

  • pam_file (str) – PAM config file.

  • group (str) – PAM management group: auth, account, password or session. Also known as “type”.

  • control (str) – PAM control flags.

  • module (str) – PAM module name.

  • after_match (str) – Regex used as reference to include the line below, if necessary. Optional parameter.

ansible_ensure_pam_module_line(pam_file, group, control, module, after_match=’’)

TEMPLATE ansible_ensure_pam_module_option

Make sure that an existing PAM module line is properly configured with an option.

Parameters:

  • pam_file (str) – PAM config file.

  • group (str) – PAM management group: auth, account, password or session. Also known as “type”.

  • control (str) – PAM control flags.

  • module (str) – PAM module name.

  • option (str) – PAM module option.

  • value (str) – PAM module option argument, if is case. Optional parameter.

  • after_match (str) – Regex used as reference to include the PAM line below, if necessary. Optional parameter.

ansible_ensure_pam_module_option(pam_file, group, control, module, option, value=’’, after_match=’’)

TEMPLATE ansible_remove_pam_module_option

Remove a PAM module option if present in a PAM module line.

Parameters:

  • pam_file (str) – PAM config file.

  • group (str) – PAM management group: auth, account, password or session. Also known as “type”.

  • control (str) – PAM control flags. Optional parameter, but recommended to be informed whenever possible.

  • module (str) – PAM module name.

  • option (str) – PAM module option.

ansible_remove_pam_module_option(pam_file, group, control, module, option)

TEMPLATE ansible_ensure_authselect_custom_profile

Macro used to ensure a custom authselect profile is in use before changing any PAM file. This macro is useful in cases where an authselect profile doesn’t provide a feature to enable the desired PAM module or option. In these cases, a custom authselect profile is necessary. If the system already uses a custom authselect profile, no action is taken. Otherwise, a new custom profile will be created based on the current profile and preserving the already enabled features. Custom profiles are only recommeded if an authselect feature for the same purpose is not available.

ansible_ensure_authselect_custom_profile()

TEMPLATE ansible_ensure_pam_facts_and_authselect_profile

Check if the system is using authselect. If so, check the profile integrity and make sure a custom profile is ready to be updated. Otherwise, ensures the ansible fact referring to the PAM file to be edited is correctly set.

Parameters:

  • pam_file (str) – PAM config file.

ansible_ensure_pam_facts_and_authselect_profile(pam_file)

TEMPLATE ansible_ensure_pam_module_configuration

Make sure that an existing PAM module line is properly configured, in aligment to the current system configuration. This macro is compatible with custom authselect profiles if the system relies on authselect. Otherwise, the PAM files will be directly edited.

Parameters:

  • pam_file (str) – PAM config file.

  • group (str) – PAM management group: auth, account, password or session. Also known as “type”.

  • control (str) – PAM control flags.

  • module (str) – PAM module name.

  • option (str) – PAM module option. Optional parameter.

  • value (str) – PAM module option argument, if is case. Optional parameter.

  • after_match (str) – Regex used as reference to include the PAM line below, if necessary. Optional parameter.

ansible_ensure_pam_module_configuration(pam_file, group, control, module, option, value=’’, after_match=’’)

TEMPLATE ansible_remove_pam_module_option_configuration

Remove a PAM module option from an existing PAM module line. This macro is compatible with custom authselect profiles if the system relies on authselect. Otherwise, the PAM files will be directly edited.

Parameters:

  • pam_file (str) – PAM config file.

  • group (str) – PAM management group: auth, account, password or session. Also known as “type”.

  • control (str) – PAM control flags. Optional parameter, but recommended to be informed whenever possible.

  • module (str) – PAM module name.

  • option (str) – PAM module option.

ansible_remove_pam_module_option_configuration(pam_file, group, control, module, option)

TEMPLATE ansible_create_list_of_local_paths

Create a list of paths composed by root directories and mount points representing local file systems. This list excludes all local directories and mount points using known remote file systems. It also excludes local directories and mount points with pseudo file systems. The list of paths created by this macro can be used to efficiently locate local files or directories in a system.

Parameters:

  • list_name – Prefered list name to be used in subsequent tasks.

ansible_create_list_of_local_paths(list_name=”search_paths”)