Merge pull request #10600 from maage/doc-2

Jinja macro fixes, sync definition with documentation and implementation

applications/openshift/integrity/crypto/machine_volume_encrypted/rule.yml

@@ -42,7 +42,7 @@ ocil: |-
     with <pre>$ oc get machineset --all-namespaces -o yaml</pre>
 
     Run the following command to retrieve if the Azure disk encryption is enabled:
-    <pre>$ oc get machineset --all-namespaces -o json | jq '{{{ azurejqfilter }}}}'</pre>
+    <pre>$ oc get machineset --all-namespaces -o json | jq '{{{ azurejqfilter }}}'</pre>
     Make sure that the result is an array of machineset names where
     disk encryption is enabled.
     This can be inspected by going through them

docs/manual/developer/04_style_guide.md

@@ -159,8 +159,11 @@ and keep these guidelines in mind when writing new code.
 * Shall use 4-space indentation
 * Shall have a docstring comment describe what the macro does
 * Shall have a docstring comment describing all parameters and their types
-    * Types shall be Python class names. (E.g. `str`, `bool`, `dict`, etc)
+    * Types shall be Python built-in types with | operator. (E.g. `str`,
+      `bool`, `dict`, `None | int`, `list[str]`, etc), with exceptions:
+        * `char`: `str` with length exactly 1
     * Shall be the last section of the docstring
+    * Shall start at the beginning of the line
     * Shall have one blank after a list before the close of the docstring block
 * Shall have two blank lines between macros
 

linux_os/guide/services/ftp/ftp_configure_vsftpd/ftp_configure_firewall/rule.yml

@@ -7,7 +7,7 @@ description: |-
     By default, <tt>firewalld</tt>
     blocks access to the ports used by the web server.
 
-    {{{ describe_firewalld_allow(proto="tcp", service="ftp") }}}
+    {{{ describe_firewalld_allow_service(service="ftp") }}}
     {{% else %}}
     By default, <tt>iptables</tt>
     blocks access to the ports used by the web server.

linux_os/guide/services/http/securing_httpd/httpd_configure_os_protect_web_server/httpd_configure_firewall/rule.yml

@@ -8,8 +8,8 @@ description: |-
     {{% if product == "rhel7" %}}
     By default, <tt>firewalld</tt>
     blocks access to the ports used by the web server.
-    {{{ describe_firewalld_allow(proto="tcp", service="http") }}}
-    {{{ describe_firewalld_allow(proto="tcp", service="https") }}}
+    {{{ describe_firewalld_allow_service(service="http") }}}
+    {{{ describe_firewalld_allow_service(service="https") }}}
     {{% else %}}
     By default, <tt>iptables</tt>
     blocks access to the ports used by the web server.
@@ -33,5 +33,5 @@ ocil: |-
     Review the web site to determine if HTTP and HTTPs are used in accordance with
     well known ports (e.g., 80 and 443) or those ports and services as registered
     and approved for use by the DoD PPSM.
-    {{{ describe_firewalld_allow(proto="tcp", service="http") }}}
-    {{{ describe_firewalld_allow(proto="tcp", service="https") }}}
+    {{{ describe_firewalld_allow_service(service="http") }}}
+    {{{ describe_firewalld_allow_service(service="https") }}}

linux_os/guide/services/imap/configure_dovecot/dovecot_allow_imap_access/group.yml

@@ -8,7 +8,7 @@ description: |-
     access to any services. This modification will allow remote hosts to
     initiate connections to the IMAP daemon, while keeping all other ports
     on the server in their default protected state.
-    {{{ describe_firewalld_allow(port="143", proto="tcp") }}}
+    {{{ describe_firewalld_allow_port(port="143", proto="tcp") }}}
     {{% else %}}
     The default iptables configuration does not allow inbound access to any services.
     This modification will allow remote hosts to initiate connections to the IMAP daemon,

linux_os/guide/services/ssh/firewalld_sshd_disabled/rule.yml

@@ -9,7 +9,7 @@ description: |-
     the SSH server is not being used, this exception should be removed from the
     firewall configuration.
     <br /><br />
-    {{{ describe_firewalld_prevent(proto="tcp", service="ssh") }}}
+    {{{ describe_firewalld_prevent_service(service="ssh") }}}
 
 rationale: |-
     If inbound SSH connections are not expected, disallowing access to the SSH port will

linux_os/guide/services/ssh/ssh_server/firewalld_sshd_port_enabled/rule.yml

@@ -9,7 +9,7 @@ description: |-
     remote access through SSH. In more restrictive firewalld settings, the SSH port should be
     added to the proper firewalld zone in order to allow SSH remote access.
     <br /><br />
-    {{{ describe_firewalld_allow(proto="tcp", service="ssh") }}}
+    {{{ describe_firewalld_allow_service(service="ssh") }}}
 
 rationale: |-
     If inbound SSH connections are expected, adding the SSH port to the proper firewalld zone
@@ -38,7 +38,7 @@ ocil: |
 fixtext: |-
     Enable SSH service in firewalld configuration.
 
-    {{{ describe_firewalld_allow(proto="tcp", service="ssh") }}}
+    {{{ describe_firewalld_allow_service(service="ssh") }}}
 
 warnings:
     - general: |-

linux_os/guide/system/software/integrity/crypto/harden_ssh_client_crypto_policy/oval/shared.xml

@@ -114,7 +114,7 @@
     - parameter (String): The parameter to be checked in the configuration file. Not used in the actual state definition, but only to connect the state to the test.
     - missing_parameter_pass (boolean): If set, the check will also pass if the parameter is not present in the configuration file (default is applied). Not used in the actual state definition, but only to connect the state to the test.
 #}}
-{{%- macro oval_line_in_file_state(value='', multi_value='', parameter='', missing_parameter_pass=false) -%}}
+{{%- macro oval_line_in_file_state(value='', multi_value=false, parameter='', missing_parameter_pass=false) -%}}
 {{%- if multi_value %}}
 {{%- set regex = "^.*\\b"+value+"\\b.*$" -%}}
 {{%- else %}}

shared/macros/01-general.jinja

@@ -4,7 +4,7 @@
   Operator to automatically figure out what resources to fetch.
 
 :param endpoint: The Kubernetes object path(s) to fetch
-:type endpoint: str/list
+:type endpoint: str | list[str]
 :param suppress: Whether to suppress the warning
 :type suppress: bool
 
@@ -14,6 +14,7 @@ This rule's check operates on the cluster configuration dump.
 Therefore, you need to use a tool that can query the OCP API, retrieve the {{% if endpoint is string %}}<code class="ocp-api-endpoint">{{{ endpoint }}}</code> API endpoint to the local <code class="ocp-dump-location">{{{ xccdf_value("ocp_data_root") }}}/{{{ endpoint.lstrip("/") }}}</code> file. {{% if suppress %}} {{{suppressed_warning()}}} {{% endif %}}{{% else %}}{{% for item in endpoint %}}<code class="ocp-api-endpoint">{{{ item }}}</code> API endpoint to the local <code class="ocp-dump-location">{{{ xccdf_value("ocp_data_root") }}}/{{{ item.lstrip("/") }}}</code> file {{% if suppress %}} {{{suppressed_warning()}}} {{% endif %}}{{% endfor %}}.{{% endif %}}
 {{%- endmacro %}}
 
+
 {{% macro openshift_cluster_setting_kubeletconfig() -%}}
 This rule's check operates on the cluster configuration dump. This will be a Platform rule, var_role_worker and var_role_master needed to be set if scan is not expected to run on master, and worker nodes.
 Therefore, you need to use a tool that can query the OCP API, retrieve KubeletConfig through <code class="ocp-api-endpoint-kubeletconfig">"/api/v1/nodes/NODE_NAME/proxy/configz"</code> {{{suppressed_warning()}}} API endpoint to the local <code class="ocp-dump-location-kubeletconfig">{{{ xccdf_value("ocp_data_root") }}}"/kubeletconfig/role/role"</code> file.
@@ -28,9 +29,9 @@ Therefore, you need to use a tool that can query the OCP API, retrieve KubeletCo
   by the jq command ( https://stedolan.github.io/jq/manual/ ).
 
 :param path_filter_pairs: Kubernetes object path/filter directive pairs
-:type path_filter_pairs: dict
+:type path_filter_pairs: dict[str, str]
 :param varargs: A list of path_filter_pairs (in case repeated paths need to be used)
-:type path_filter_pairs: list
+:type varargs: list[dict[str, str]]
 
 #}}
 {{% macro openshift_filtered_cluster_setting(path_filter_pairs) -%}}
@@ -171,7 +172,7 @@ Therefore, you need to use a tool that can query the OCP API, retrieve the follo
 
 #}}
 {{% macro hide_rule() -%}}
-This rule will be a hidden rule 
+This rule will be a hidden rule
 <code class="ocp-hide-rule" id="ocp-hide-rule">true</code>
 {{%- endmacro %}}
 
@@ -295,49 +296,45 @@ Therefore, you need to use a tool that can query the OCP API, retrieve the follo
 
 
 {{#
-    Describe preventing access a port or service in firewalld. If the :code:`service` parameter is defined
-    it is assumed to be a service and the :code:`port` and :code:`proto` parameters will have no effect.
+Describe preventing access to service in firewalld.
 
-:param port: The port to allow
-:type port: int
-:param proto: The protocol to allow
-:type proto: str
 :param service: The service to allow
 :type service: str
 
 #}}
-{{%- macro describe_firewalld_prevent(port, proto, service) %}}
+{{%- macro describe_firewalld_prevent_service(service) %}}
     To configure <code>firewalld</code> to prevent access, run the following command(s):
-    {{% if port %}}
-    <code>firewall-cmd --permanent --remove-port={{{ port }}}/{{{ proto }}}</code>
-    {{% endif %}}
-    {{% if service %}}
     <code>firewall-cmd --permanent --remove-service={{{ service }}}</code>
-    {{% endif %}}
 {{%- endmacro %}}
 
 
 {{#
-    Describe allowing access a port or service in firewalld. If the :code:`service` parameter is defined
-    it is assumed to be a service and the :code:`port` and :code:`proto` parameters will have no effect.
+Describe allowing access to a port in firewalld.
 
 :param port: The port to allow
 :type port: int
 :param proto: The protocol to allow
 :type proto: str
-:param service: The service to allow
-:type service: str
 
 #}}
-{{%- macro describe_firewalld_allow(port, proto, service) %}}
-    {{% if port %}}
+{{%- macro describe_firewalld_allow_port(port, proto) %}}
     To configure <code>firewalld</code> to allow <code>{{{ port }}}/{{{ proto }}}</code> access, run the following command(s):
     <pre>firewall-cmd --permanent --add-port={{{ port }}}/{{{ proto }}}</pre>
-    {{% endif %}}
-    {{% if service %}}
+    Then run the following command to load the newly created rule(s):
+    <pre>firewall-cmd --reload</pre>
+{{%- endmacro %}}
+
+
+{{#
+Describe allowing access to a service in firewalld.
+
+:param service: The service to allow
+:type service: str
+
+#}}
+{{%- macro describe_firewalld_allow_service(service) %}}
     To configure <code>firewalld</code> to allow <code>{{{ service }}}</code> access, run the following command(s):
     <pre>firewall-cmd --permanent --add-service={{{ service }}}</pre>
-    {{% endif %}}
     Then run the following command to load the newly created rule(s):
     <pre>firewall-cmd --reload</pre>
 {{%- endmacro %}}
@@ -979,25 +976,6 @@ substituting the correct package management software.
 {{%- endmacro %}}
 
 
-{{#
-    A warning about rule depending on another.
-
-:param rule_id: Rule id of the rule that must be selected.
-:type rule_id: str
-:param why: The reasoning for the dependency. Should fit into this part of the sentence "make sure that rule with ID is selected as well:".
-:type why: str
-
-#}}
-{{% macro body_of_warning_about_dependent_rule(rule_id, why) -%}}
-        When selecting this rule in a profile,
-        {{%- if why %}}
-            make sure that rule with ID <code>{{{ rule_id }}}</code> is selected as well: {{{ why }}}
-        {{%- else %}}
-            rule <code>{{{ rule_id }}}</code> has to be selected as well.
-        {{%- endif %}}
-{{% endmacro %}}
-
-
 {{#
     An openssl config file with strong entropy.
 
@@ -1112,41 +1090,6 @@ Configure the default Grub2 kernel command line to contain {{{ arg_name_value }}
 {{%- endmacro %}}
 
 
-{{#
-    Adds a default "no easy remediation" warning for kernel_build_config warning.
-
-#}}
-{{% macro kernel_build_config_warning() %}}
-- general: |-
-    There is no remediation for this besides re-compiling the kernel with the appropriate value for the config.
-{{% endmacro %}}
-
-
-{{#
-    OCIL for a kernel build config rule.
-
-    Example usage::
-
-        ocil_kernel_build_config(config="config_kernel_strict_rwx", value="y")
-
-:param config: The kernel config parameter
-:type config: str
-:param value: The value for the given config
-:type value: str
-
-#}}
-{{% macro kernel_build_config_ocil(config, value) -%}}
-    To determine the config value the kernel was built with, run the following command:
-    <pre>$ grep {{{ config }}} /boot/config.*</pre>
-    {{% if value == "n" %}}
-    Configs with value 'n' are not explicitly set in the file, so either commented lines or no
-    lines should be returned.
-    {{% else %}}
-    For each kernel installed, a line with value "{{{ value }}}" should be returned.
-    {{% endif %}}
-{{%- endmacro %}}
-
-
 {{#
     Returns the AIDE strings based on the current product
 
@@ -1262,8 +1205,8 @@ Part of the grub2_bootloader_argument(_absent) templates.
 Join list of items to create a human readable list in which the last item is
 separated by an and and others are separated by a comma.
 
-:param items: list of strings
-:type items: list
+:param items: list of strings to join
+:type items: list[str]
 
 #}}
 {{%- macro join_list(items) -%}}

shared/macros/10-ansible.jinja

@@ -142,7 +142,7 @@ value: :code:`Setting={{ varname1 }}`
   instead of lineinfile-based solutions.
 
 #}}
-{{%- macro ansible_set_config_file(msg, file, parameter, separator=' ', separator_regex='\s+', value='', prefix_regex='^\s*', create='no', validate='', insert_after='', insert_before='', escape_regex=False, mode='') %}}
+{{%- macro ansible_set_config_file(msg, file, parameter, separator=' ', separator_regex='\s+', value='', prefix_regex='^\s*', create='no', validate='', insert_after='', insert_before='', mode='') %}}
 {{{ ansible_only_lineinfile(msg, file, prefix_regex + parameter + separator_regex, parameter + separator + value, create=create, block=True, validate=validate, insert_after=insert_after, insert_before=insert_before, mode=mode) }}}
 {{%- endmacro %}}
 
@@ -263,18 +263,6 @@ value: :code:`Setting={{ varname1 }}`
 {{%- endmacro %}}
 
 
-{{#
-  High level macro to set a value in /etc/profile (and /etc/profile.d) bash
-  files. Note this is only suitable for calling a single command once with the
-  correct arguments and not for calling the same command multiple times with
-  different arguments. This includes setting an environment variable once.
-
-#}}
-{{%- macro ansible_etc_profile_set(msg='', parameter='', value='') %}}
-{{{ ansible_set_config_file_dir(msg, "/etc/profile", "/etc/profile.d", "/etc/profile", parameter, separator='=', separator_regex='=', value=value, create='yes', validate="bash -n %s") }}}
-{{%- endmacro %}}
-
-
 {{#
   High level macro to set a command in auditd configuration file /etc/audit/auditd.conf.
 
@@ -765,7 +753,7 @@ The following macro remediates Audit syscall rule in :code:`/etc/audit/audit.rul
 :param op: version comparison operator ("<", "<=", "==", "!=", ">", ">=")
 :type op: str
 :param ver: package version (optional argument, use together with "op")
-:type ver: version
+:type ver: str
 
 #}}
 {{%- macro ansible_pkg_conditional(package, op=None, ver=None) -%}}
@@ -1162,7 +1150,6 @@ The following macro remediates Audit syscall rule in :code:`/etc/audit/audit.rul
   when:
     - result_faillock_conf_check.stat.exists
 
-
 - name: {{{ rule_title }}} - Ensure the pam_faillock.so {{{ parameter }}} parameter in PAM files
   block:
     - name: {{{ rule_title }}} - Check if pam_faillock.so {{{ parameter }}} parameter is already enabled in pam files