Skip to content

Commit eb1030f

Browse files
darshan-nagarajdarshan-nagaraj
committed
BZ1964686: Adds Compliance Operator CRDs
1 parent cd7b285 commit eb1030f

13 files changed

+574
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -827,6 +827,9 @@ Topics:
827827
File: compliance-operator-uninstallation
828828
- Name: Using the oc-compliance plug-in
829829
File: oc-compliance-plug-in-using
830+
- Name: Understanding the Custom Resource Definitions
831+
File: compliance-operator-crd
832+
830833
- Name: File Integrity Operator
831834
Dir: file_integrity_operator
832835
Topics:

‎modules/compliance-crd-advanced-compliance-scan.adoc‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/compliance_operator/compliance-operator-crd.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="advance-compliance-scan-object_{context}"]
7+
= Advanced ComplianceScan Object
8+
The Compliance Operator includes options for advanced users for debugging or integrating with existing tooling. While it is recommended that you not create a `ComplianceScan` object directly, you can instead manage it using a `ComplianceSuite` object.
9+
10+
.Example Advanced `ComplianceScan` object
11+
[source,yaml]
12+
----
13+
apiVersion: compliance.openshift.io/v1alpha1
14+
kind: ComplianceScan
15+
metadata:
16+
name: <name of the scan>
17+
spec:
18+
scanType: Node <1>
19+
profile: xccdf_org.ssgproject.content_profile_moderate <2>
20+
content: ssg-ocp4-ds.xml
21+
contentImage: quay.io/complianceascode/ocp4:latest <3>
22+
rule: "xccdf_org.ssgproject.content_rule_no_netrc_files" <4>
23+
nodeSelector: <5>
24+
node-role.kubernetes.io/worker: ""
25+
status:
26+
phase: DONE <6>
27+
result: NON-COMPLIANT <7>
28+
----
29+
30+
<1> Specify either `Node` or `Platform`. Node profiles scan the cluster nodes and platform profiles scan the Kubernetes platform.
31+
<2> Specify the XCCDF identifier of the profile that you want to run.
32+
<3> Specify the container image that encapsulates the profile files.
33+
<4> It is optional. Specify the scan to run a single rule. This rule has to be identified with the XCCDF ID, and has to belong to the specified profile.
34+
+
35+
[NOTE]
36+
====
37+
If you skip the `rule` parameter, then scan runs for all the available rules of the specified profile.
38+
====
39+
<5> If you are on the {product-title} and wants to generate a remediation, then nodeSelector label has to match the `MachineConfigPool` label.
40+
+
41+
[NOTE]
42+
====
43+
If you do not specify `nodeSelector` parameter or match the `MachineConfig` label, scan will still run, but it will not create remediation.
44+
====
45+
<6> Indicates the current phase of the scan.
46+
<7> Indicates the verdict of the scan.
47+
48+
[IMPORTANT]
49+
====
50+
If you delete a `ComplianceSuite` object, then all the associated scans get deleted.
51+
====
52+
53+
When the scan is complete, it generates the result as Custom Resources of the `ComplianceCheckResult` object. However, the raw results are available in ARF format. These results are stored in a Persistent Volume (PV), which has a Persistent Volume Claim (PVC) associated with the name of the scan.
54+
You can programmatically fetch the `ComplianceScans` events. To generate events for the suite, run the following command:
55+
56+
[source,terminal]
57+
----
58+
oc get events --field-selector involvedObject.kind=ComplianceScan,involvedObject.name=<name of the suite>
59+
----

‎modules/compliance-crd-compliance-check-result.adoc‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/compliance_operator/compliance-operator-crd.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="compliance-check-result_{context}"]
7+
= ComplianceCheckResult object
8+
When you run a scan with a specific profile, several rules in the profiles are verified. For each of these rules, a `ComplianceCheckResult` object is created, which provides the state of the cluster for a specific rule.
9+
10+
.Example `ComplianceCheckResult` object
11+
[source,yaml]
12+
----
13+
apiVersion: compliance.openshift.io/v1alpha1
14+
kind: ComplianceCheckResult
15+
metadata:
16+
labels:
17+
compliance.openshift.io/check-severity: medium
18+
compliance.openshift.io/check-status: FAIL
19+
compliance.openshift.io/suite: example-compliancesuite
20+
compliance.openshift.io/scan-name: workers-scan
21+
name: workers-scan-no-direct-root-logins
22+
namespace: openshift-compliance
23+
ownerReferences:
24+
- apiVersion: compliance.openshift.io/v1alpha1
25+
blockOwnerDeletion: true
26+
controller: true
27+
kind: ComplianceScan
28+
name: workers-scan
29+
description: <description of scan check>
30+
instructions: <manual instructions for the scan>
31+
id: xccdf_org.ssgproject.content_rule_no_direct_root_logins
32+
severity: medium <1>
33+
status: FAIL <2>
34+
----
35+
36+
<1> Describes the severity of the scan check.
37+
<2> Describes the result of the check. The possible values are:
38+
* PASS: check was successful.
39+
* FAIL: check was unsuccessful.
40+
* INFO: check was successful and found something not severe enough to be considered an error.
41+
* MANUAL: check cannot automatically assess the status and manual check is required.
42+
* INCONSISTENT: different nodes report different results.
43+
* ERROR: check run successfully, but could not complete.
44+
* NOTAPPLICABLE: check did not run as it is not applicable.
45+
46+
To get all the check results from a suite, run the following command:
47+
[source,terminal]
48+
----
49+
oc get compliancecheckresults -l compliance.openshift.io/suite=<suit name>
50+
----

‎modules/compliance-crd-compliance-remediation.adoc‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/compliance_operator/compliance-operator-crd.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="compliance-remediation-object_{context}"]
7+
= ComplianceRemediation object
8+
For a specific check you can have a datastream specified fix. However, if a Kubernetes fix is available, then the Compliance Operator creates a `ComplianceRemediation` object.
9+
10+
.Example `ComplianceRemediation` object
11+
[source,yaml]
12+
----
13+
apiVersion: compliance.openshift.io/v1alpha1
14+
kind: ComplianceRemediation
15+
metadata:
16+
labels:
17+
compliance.openshift.io/suite: example-compliancesuite
18+
compliance.openshift.io/scan-name: workers-scan
19+
machineconfiguration.openshift.io/role: worker
20+
name: workers-scan-disable-users-coredumps
21+
namespace: openshift-compliance
22+
ownerReferences:
23+
- apiVersion: compliance.openshift.io/v1alpha1
24+
blockOwnerDeletion: true
25+
controller: true
26+
kind: ComplianceCheckResult
27+
name: workers-scan-disable-users-coredumps
28+
uid: <UID>
29+
spec:
30+
apply: false <1>
31+
object:
32+
current: <2>
33+
apiVersion: machineconfiguration.openshift.io/v1
34+
kind: MachineConfig
35+
spec:
36+
config:
37+
ignition:
38+
version: 2.2.0
39+
storage:
40+
files:
41+
- contents:
42+
source: data:,%2A%20%20%20%20%20hard%20%20%20core%20%20%20%200
43+
filesystem: root
44+
mode: 420
45+
path: /etc/security/limits.d/75-disable_users_coredumps.conf
46+
outdated: {} <3>
47+
----
48+
49+
<1> `true` indicates the remediation was applied. `false` indicates the remediation was not applied.
50+
<2> Includes the definition of the remediation.
51+
<3> Indicates remediation that was previously parsed from an earlier version of the content. The Compliance Operator still retains the outdated objects to give the administrator a chance to review the new remediations before applying them.
52+
53+
To get all the remediations from a suite, run the following command:
54+
[source,terminal]
55+
----
56+
oc get complianceremediations -l compliance.openshift.io/suite=<suite name>
57+
----
58+
59+
To list all failing checks that can be remediated automatically, run the following command:
60+
[source,terminal]
61+
----
62+
oc get compliancecheckresults -l 'compliance.openshift.io/check-status in (FAIL),compliance.openshift.io/automated-remediation'
63+
----
64+
65+
To list all failing checks that can be remediated manually, run the following command:
66+
[source,terminal]
67+
----
68+
oc get compliancecheckresults -l 'compliance.openshift.io/check-status in (FAIL),!compliance.openshift.io/automated-remediation'
69+
----

‎modules/compliance-crd-compliance-suite.adoc‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/compliance_operator/compliance-operator-crd.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="compliance-suite-object_{context}"]
7+
= ComplianceSuite object
8+
The `ComplianceSuite` object helps you keep track of the state of the scans. It contains the raw settings to create scans and the overall result.
9+
10+
For `Node` type scans, you should map the scan to the `MachineConfigPool`, since it contains the remediations for any issues. If you specify a label, ensure it directly applies to a pool.
11+
12+
.Example `ComplianceSuite` object
13+
[source,yaml]
14+
----
15+
apiVersion: compliance.openshift.io/v1alpha1
16+
kind: ComplianceSuite
17+
metadata:
18+
name: <name of the scan>
19+
spec:
20+
autoApplyRemediations: false <1>
21+
schedule: "0 1 * * *" <2>
22+
scans: <3>
23+
- name: workers-scan
24+
scanType: Node
25+
profile: xccdf_org.ssgproject.content_profile_moderate
26+
content: ssg-rhcos4-ds.xml
27+
contentImage: quay.io/complianceascode/ocp4:latest
28+
rule: "xccdf_org.ssgproject.content_rule_no_netrc_files"
29+
nodeSelector:
30+
node-role.kubernetes.io/worker: ""
31+
status:
32+
Phase: DONE <4>
33+
Result: NON-COMPLIANT <5>
34+
scanStatuses:
35+
- name: workers-scan
36+
phase: DONE
37+
result: NON-COMPLIANT
38+
----
39+
<1> Set to `true` to enable auto remediations. Set to `false` to disable auto remediations.
40+
<2> Specify how often the scan should be run in cron format.
41+
<3> Specify a list of scan specifications to run in the cluster.
42+
<4> Indicates the progress of the scans.
43+
<5> Indicates the overall verdict of the suite.
44+
45+
The suite in the background creates the `ComplianceScan` object based on the `scans` parameter.
46+
You can programmatically fetch the `ComplianceSuites` events. To get the events for the suite, run the following command:
47+
[source,terminal]
48+
----
49+
$ oc get events --field-selector involvedObject.kind=ComplianceSuite,involvedObject.name=<name of the suite>
50+
----
51+
52+
[IMPORTANT]
53+
====
54+
You might create errors when you manually define the `ComplianceSuite`, since it contains the XCCDF attributes.
55+
====

‎modules/compliance-crd-profile-bundle.adoc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/compliance_operator/compliance-operator-crd.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="profile-bundle-object_{context}"]
7+
= ProfileBundle object
8+
When you install the Compliance Operator, it includes ready-to-run `ProfileBundle` object. The Compliance Operator parses the `ProfileBundle` object and creates a `Profile` object for each profile in the bundle. It also parses `Rule` and `Variable` objects, which are used by the `Profile` object.
9+
10+
11+
.Example `ProfileBundle` object
12+
[source,yaml]
13+
----
14+
apiVersion: compliance.openshift.io/v1alpha1
15+
kind: ProfileBundle
16+
name: <profile bundle name>
17+
namespace: openshift-compliance
18+
spec:
19+
contentFile: ssg-ocp4-ds.xml <1>
20+
contentImage: quay.io/complianceascode/ocp4:latest <2>
21+
status:
22+
dataStreamStatus: VALID <3>
23+
----
24+
<1> Specify a path from the root directory (/) where the profile file is located.
25+
<2> Specify the container image that encapsulates the profile files.
26+
<3> Indicates whether the Compliance Operator was able to parse the content files.
27+
28+
[NOTE]
29+
====
30+
When the `contentFile` fails, an `errorMessage` attribute appears, which provides details of the error that occurred.
31+
====
32+
33+
.Troubleshooting
34+
35+
When you roll back to a known content image from an invalid image, the `ProfileBundle` object stops responding and displays `PENDING` state. As a workaround, you can move to a different image than the previous one. Alternatively, you can delete and re-create the `ProfileBundle` object to return to the working state.

‎modules/compliance-crd-profile.adoc‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/compliance_operator/compliance-operator-crd.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="profile-object_{context}"]
7+
= Profile object
8+
9+
The `Profile` object defines the rules and variables that can be evaluated for a certain compliance standard. It contains parsed out details about an OpenSCAP profile, such as its XCCDF identifier and profile checks for a `Node` or `Platform` type. You can either directly use the `Profile` object or further customize it using a `TailorProfile` object.
10+
11+
[NOTE]
12+
====
13+
You cannot create or modify the `Profile` object manually because it is derived from a single `ProfileBundle` object. Typically, a single `ProfileBundle` object can include several `Profile` objects.
14+
====
15+
16+
.Example `Profile` object
17+
[source,yaml]
18+
----
19+
apiVersion: compliance.openshift.io/v1alpha1
20+
description: <description of the profile>
21+
id: xccdf_org.ssgproject.content_profile_moderate <1>
22+
kind: Profile
23+
metadata:
24+
annotations:
25+
compliance.openshift.io/product: <product name>
26+
compliance.openshift.io/product-type: Node <2>
27+
creationTimestamp: "YYYY-MM-DDTMM:HH:SSZ"
28+
generation: 1
29+
labels:
30+
compliance.openshift.io/profile-bundle: <profile bundle name>
31+
name: rhcos4-moderate
32+
namespace: openshift-compliance
33+
ownerReferences:
34+
- apiVersion: compliance.openshift.io/v1alpha1
35+
blockOwnerDeletion: true
36+
controller: true
37+
kind: ProfileBundle
38+
name: <profile bundle name>
39+
uid: <uid string>
40+
resourceVersion: "<version number>"
41+
selfLink: /apis/compliance.openshift.io/v1alpha1/namespaces/openshift-compliance/profiles/rhcos4-moderate
42+
uid: <uid string>
43+
rules: <3>
44+
- rhcos4-account-disable-post-pw-expiration
45+
- rhcos4-accounts-no-uid-except-zero
46+
- rhcos4-audit-rules-dac-modification-chmod
47+
- rhcos4-audit-rules-dac-modification-chown
48+
title: <title of the profile>
49+
----
50+
<1> Specify the XCCDF name of the profile. Use this identifier when you define a `ComplianceScan` object as the value of the profile attribute of the scan.
51+
<2> Specify either a `Node` or `Platform`. Node profiles scan the cluster nodes and platform profiles scan the Kubernetes platform.
52+
<3> Specify the list of rules for the profile. Each rule corresponds to a single check.

‎modules/compliance-crd-rule.adoc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/compliance_operator/compliance-operator-crd.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="rule-object_{context}"]
7+
= Rule object
8+
The `Rule` object, which forms the profiles, are also exposed as objects. Use the `Rule` object to define your compliance check requirements and specify how it could be fixed.
9+
10+
.Example `Rule` object
11+
[source,yaml]
12+
----
13+
apiVersion: compliance.openshift.io/v1alpha1
14+
checkType: Platform <1>
15+
description: <description of the rule>
16+
id: xccdf_org.ssgproject.content_rule_configure_network_policies_namespaces <2>
17+
instructions: <manual instructions for the scan>
18+
kind: Rule
19+
metadata:
20+
annotations:
21+
compliance.openshift.io/rule: configure-network-policies-namespaces
22+
control.compliance.openshift.io/CIS-OCP: 5.3.2
23+
control.compliance.openshift.io/NERC-CIP: CIP-003-3 R4;CIP-003-3 R4.2;CIP-003-3
24+
R5;CIP-003-3 R6;CIP-004-3 R2.2.4;CIP-004-3 R3;CIP-007-3 R2;CIP-007-3 R2.1;CIP-007-3
25+
R2.2;CIP-007-3 R2.3;CIP-007-3 R5.1;CIP-007-3 R6.1
26+
control.compliance.openshift.io/NIST-800-53: AC-4;AC-4(21);CA-3(5);CM-6;CM-6(1);CM-7;CM-7(1);SC-7;SC-7(3);SC-7(5);SC-7(8);SC-7(12);SC-7(13);SC-7(18)
27+
labels:
28+
compliance.openshift.io/profile-bundle: ocp4
29+
name: ocp4-configure-network-policies-namespaces
30+
namespace: openshift-compliance
31+
rationale: <description of why this rule is checked>
32+
severity: high <3>
33+
title: <summary of the rule>
34+
----
35+
<1> Specify the type of check this rule executes. `Node` profiles scan the cluster nodes and `Platform` profiles scan the Kubernetes platform. An empty value indicates there is no automated check.
36+
<2> Specify the XCCDF name of the rule, which is parsed directly from the datastream.
37+
<3> Specify the severity of the rule when it fails.
38+
39+
[NOTE]
40+
====
41+
The `Rule` object gets an appropriate label for an easy identification of the associated `ProfileBundle` object. The `ProfileBundle` also gets specified in the `OwnerReferences` of this object.
42+
====

0 commit comments

Comments
 (0)