The ComplianceAsCode project provides security guidance, baselines, and associated validation mechanisms utilizing the Security Content Automation Protocol (SCAP) to achieve security hardening for various products. ComplianceAsCode provides content for Red Hat OpenShift to comply with the requirements set by local government regulations and industry standards required for deploying the solution.
The ComplianceAsCode content follows the SCAP format to help translate the generic requirements set by the regulatory frameworks into implementation specifics and automate the remediations where possible. Refer to the SCAP Security Guide for more information on SCAP format.
ComplianceAsCode content guide provides the best practices and security relevant configuration guidelines to securely configure the Red Hat OpenShift Container Platform system. The guidelines written in SCAP format consists of two parts:
- Rules: Rules are written specific to a configuration setting with the automated remediation or the suggested remediation when the configuration item is not in desired state during compliance audit. Rules are described per the XCCDF standard in YAML format. Rules contain the checks written in OVAL format to verify the configuration setting and remediations when the configuration setting is not as suggested. Remediations can be executed on Ansible, Bash, Anaconda Installer, Puppet, and for OpenShift on ignition and Kubernetes.
- Profiles and Controls: Profiles and Controls are product-specific and groups the selected rules to align with a specific compliance or regulatory standard.
Writing a rule
The top level of the ComplianceAsCode content repository has directories created for different products and applications/openshift is for OpenShift, which contains rules in subdirectories grouped by components.
applications/openshift
├── accounts
├── api-server
├── authentication
├── controller
├── etcd
├── general
├── integrity
├── kubelet
├── logging
├── master
├── networking
├── openshift-api-server
├── rbac
├── registry
├── risk-assessment
├── scc
├── scheduler
├── secrets
└── worker
Create a directory for the rules in the matching component directory (e.g., registry). Directory naming follows snake casing and is referred to as rule ID.
applications/openshift/registry/
├── approved_registries
├── image_pruner_active
├── image_scanning
├── imagestream_sets_schedule
├── ocp_allowed_registries
├── ocp_allowed_registries_for_import
├── ocp_insecure_allowed_registries_for_import
├── ocp_insecure_registries
├── read_only_registry_access
└── registry_access
Each rule directory must contain rule.yml which contains details on the desired state of a configuration item. Rules should be written for a single configuration item. Complex configurations must be separated into smaller parts as independent rules. A rule can also contain the following subdirectories when required.
- Tests: Contain the unit tests for the rule. Bash scripts are used for setting the configurations to check the various scenarios. The following is an example test script that sets a configuration value:
#!/bin/bash # remediation = none mkdir -p /kubernetes-api-resources/apis/<api_name>/<api_version>/namespaces/<namespace_name>/<api_kind> cat << EOF > /kubernetes-api-resources/apis/<api_name>/<api_version>/namespaces/<namespace_name>/<api_kind>/<object_name> spec: <configuration_specifics> EOF
Specifying remediation = none in a comment informs the test framework that remediation is not expected for the rule. The test framework patches the yaml content present in the /kubernetes-api-resources/apis directory and checks the rules against it.
- Kubernetes: Contains the remediation to apply when the configuration set is not as desired in the shared.yml, which is a Kubernetes manifest patched to update the configuration setting.
- Oval: Contains the shared.xml which follows custom OVAL syntax for OR-ing rules, which can be used to break down complex rules into smaller rules and OVAL checks for the smaller rules for validating the actual rule. Each smaller rule should have its own rule directory the same as all other rules, including its own tests and remediations.
- Policy: Contains details of the regulatory policy for which the rule is created.
Rule sections
The rule.yml contains attributes in the following order:
- documentation_complete: Boolean value (true or false) indicating the documentation of the rule.
- prodtype: Product type for which the rule is valid. It will be ocp4 for Red Hat OpenShift Container Platform 4.
- title: The title for the rule must be in title case. It is similar to the expanded version of rule ID.
- description: HTML-like description of the rule, including the reason, details of the configuration parameter with the documentation link, command to check the configuration, and update the configuration to desired value.
- rationale: HTML-like description of the reason why the rule exists and the importance of setting the configuration as suggested.
- severity: Severity of the rule based upon the importance of improperly setting the configuration correctly.
- identifiers: Common Configuration Enumeration Identifiers (CCE ID) for the rule.
- cce@ocp4: Unique identifier to a compliance rule used for mapping it to the product (i.e., OCP). Pick an ID from the list of pre-generated IDs in shared/references/cce-redhat-avail.txt and delete the used ID to avoid reuse for other rules.
- references: References to the compliance or regulatory standards (e.g., NIST, SRG, DISA) to which the rule applies.
- ocil_clause: A statement which indicates the rule is valid and the system is not in a desired state.
- ocil: HTML-like description with details to check whether the rule is valid. It can contain the commands to assert the findings and the desired state.
- template: Predefined templates that can be used for checking the configurations. The yamlfile_value can be used for checking OpenShift configurations, which checks for a value in a YAML at a given path.
- yamlfile_value: Supports the following parameters used for writing the checks.
- ocp_data: Accept boolean value when set to true, file path would be treated as path in OCP yaml configuration dump.
- filepath: Full path of the configuration file such as: /apis/<api_type>/<api_version>/namespaces/<namespace_name>/<api_kind>/<object_name>
- filepath_suffix: The suffix to the file path.
- yaml_path: The YAML path of the configuration parameter under check. (e.g.,
.spec.<parameter_name>). - entity_check: Check the results of the values and decide the final outcome (e.g.
allmeans all the results ofvaluesmust be true to say check met the conditions). Possible options are all, at least one, none satisfy and only one. - check_existence: Check that the values exist.
- xccdf_variable: Use the XCCDF variable selector field if the comparison involves checking for a value selected by a XCCDF variable.
- yamlfile_value: Supports the following parameters used for writing the checks.
Define and set a default value for a variable as follows for the file (var_kubelet_tls_min_version_regex.var) in the component directory or as relevant based on the variable scope.
documentation_complete: true
title: 'Configure Kubelet to use secure TLS version'
description: 'TLS versions available for configuring Kubelet, excluding insecure versions'
type: string
operator: equals
interactive: false
options:
default: "^(?!VersionTLS10|VersionTLS11)"
- regex_data: If set to
trueand combined with the xccdf_variable, it will use the value of the xccdf_variable as a regex and does a pattern match operation instead of equal operation. - values: A list of values to check.
- key: This is the yaml key to check when the configuration parameter holds map data type.
- value: The value to check, which can be a regex too.
- type: The datatype of the field.
- operation: This is the operation value. Most common operations are: equals, not equal, pattern match, greater than or equal, and less than or equal.
The following is an example of a rule.yml file:
documentation_complete: true
prodtype: ocp4
title: "Ensure custom tlsSecurityProfile configured for IngressController uses secure TLS version"
description: |-
The configuration <tt>tlsSecurityProfile</tt> specifies TLS configurations
to be used while establishing connections with the externally exposed
servers. Though secure transport mode is used for establishing connections,
the protocols used may not always be strong enough to avoid interception and
manipulation of the data in transport. When Custom TLS Security profile is
used it's always better to configure TLS version 1.2 or newer to avoid any
security breaches.
Update minTLSVersion configured in Custom tlsSecurityProfile using the following command:
{{% raw %}}<pre>oc patch -n openshift-ingress-operator ingresscontrollers.operator.openshift.io default --type 'merge' --patch '{"spec":{"tlsSecurityProfile":{"custom":{"minTLSVersion":"VersionTLS12"}}}}'</pre>{{% endraw %}}
For more information, follow
OpenShift documentation:
{{{ weblink(link="https://docs.openshift.com/container-platform/latest/security/tls-security-profiles.html",
text="the relevant documentation") }}}.
rationale: |-
The authenticity and integrity of the container platform and communication
between nodes and components must be secure. If an insecure protocol,
cipher, or algorithms is used, during transmission of data, the data can be
intercepted and manipulated. To thwart the manipulation of the data during
transmission secure protocol, cipher and algorithms must be used.
severity: medium
identifiers:
cce@ocp4: CCE-86323-3
references:
nist: SC-8,SC-8(1)
srg: SRG-APP-000014-CTR-000040
ocil_clause: 'insecure TLS version configured in the Custom tlsSecurityProfile used for accessing external services'
ocil: |-
To check for the configured tlsSecurityProfile use below command:
<tt>$ oc get -n openshift-ingress-operator ingresscontrollers.operator.openshift.io default -o jsonpath='{.spec.tlsSecurityProfile.custom.minTLSVersion}{"\n"}'</tt>
The output shows the minTLSVersion configured in Custom tlsSecurityProfile
for IngressController, which should be TLSv1.2 or newer.
warnings:
- general: |-
{{{ openshift_cluster_setting("/apis/operator.openshift.io/v1/namespaces/openshift-ingress-operator/ingresscontrollers/default") | indent(8) }}}
template:
template:
name: yamlfile_value
vars:
ocp_data: "true"
filepath: "/apis/operator.openshift.io/v1/namespaces/openshift-ingress-operator/ingresscontrollers/default"
yamlpath: ".spec.tlsSecurityProfile.custom.minTLSVersion"
check_existence: "any_exist"
values:
- value: "^(?!VersionTLS10|VersionTLS11)"
operation: "pattern match"
