Skip to content

Commit 6308beb

Browse files
ahardin-rhahardin-rh
authored
Merge pull request #31599 from ahardin-rh/oc-compliance-plug-in
OSDOCS-1862, add oc Compliance Plug-in docs
2 parents 1eae44c + 3f24798 commit 6308beb

8 files changed

+366
-0
lines changed

‎_topic_map.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -637,6 +637,11 @@ Topics:
637637
File: file-integrity-operator-advanced-usage
638638
- Name: Troubleshooting the File Integrity Operator
639639
File: file-integrity-operator-troubleshooting
640+
- Name: The oc-compliance Plug-in
641+
Dir: oc_compliance_plug_in
642+
Topics:
643+
- Name: Using the oc-compliance Plug-in
644+
File: oc-compliance-plug-in-using
640645
- Name: Container security
641646
Dir: container_security
642647
Topics:

‎modules/oc-compliance-fetching-compliance-remediation-details.adoc

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/oc_compliance_plug_in/oc-compliance-plug-in-using.adoc
4+
5+
[id="fetching-compliance-remediation-details_{context}"]
6+
= Fetching compliance remediation details
7+
8+
The Compliance Operator provides remediation objects that are used to automate the changes required to make the cluster compliant. The `fetch-fixes` subcommand can help you understand exactly which configuration remediations are used. Use the `fetch-fixes` subcommand to extract the remediation objects from a profile, rule, or `ComplianceRemediation` object into a directory to inspect.
9+
10+
.Procedure
11+
12+
. View the remediations for a profile:
13+
+
14+
[source,terminal]
15+
----
16+
$ oc compliance fetch-fixes profile ocp4-cis -o /tmp
17+
----
18+
+
19+
.Example output
20+
[source,terminal]
21+
----
22+
No fixes to persist for rule 'ocp4-api-server-api-priority-flowschema-catch-all' <1>
23+
No fixes to persist for rule 'ocp4-api-server-api-priority-gate-enabled'
24+
No fixes to persist for rule 'ocp4-api-server-audit-log-maxbackup'
25+
Persisted rule fix to /tmp/ocp4-api-server-audit-log-maxsize.yaml
26+
No fixes to persist for rule 'ocp4-api-server-audit-log-path'
27+
No fixes to persist for rule 'ocp4-api-server-auth-mode-no-aa'
28+
No fixes to persist for rule 'ocp4-api-server-auth-mode-node'
29+
No fixes to persist for rule 'ocp4-api-server-auth-mode-rbac'
30+
No fixes to persist for rule 'ocp4-api-server-basic-auth'
31+
No fixes to persist for rule 'ocp4-api-server-bind-address'
32+
No fixes to persist for rule 'ocp4-api-server-client-ca'
33+
Persisted rule fix to /tmp/ocp4-api-server-encryption-provider-cipher.yaml
34+
Persisted rule fix to /tmp/ocp4-api-server-encryption-provider-config.yaml
35+
----
36+
<1> The `No fixes to persist` warning is expected whenever there are rules in a profile that do not have a corresponding remediation, because either the rule cannot be remediated automatically or a remediation was not provided.
37+
38+
. You can view a sample of the YAML file. The `head` command will show you the first 10 lines:
39+
+
40+
[source,terminal]
41+
----
42+
$ head /tmp/ocp4-api-server-audit-log-maxsize.yaml
43+
----
44+
+
45+
.Example output
46+
[source,terminal]
47+
----
48+
apiVersion: config.openshift.io/v1
49+
kind: APIServer
50+
metadata:
51+
name: cluster
52+
spec:
53+
maximumFileSizeMegabytes: 100
54+
----
55+
56+
. View the remediation from a `ComplianceRemediation` object created after a scan:
57+
+
58+
[source,terminal]
59+
----
60+
$ oc get complianceremediations -n openshift-compliance
61+
----
62+
+
63+
.Example output
64+
[source,terminal]
65+
----
66+
NAME STATE
67+
ocp4-cis-api-server-encryption-provider-cipher NotApplied
68+
ocp4-cis-api-server-encryption-provider-config NotApplied
69+
----
70+
+
71+
[source,terminal]
72+
----
73+
$ oc compliance fetch-fixes complianceremediations ocp4-cis-api-server-encryption-provider-cipher -o /tmp
74+
----
75+
+
76+
.Example output
77+
[source,terminal]
78+
----
79+
Persisted compliance remediation fix to /tmp/ocp4-cis-api-server-encryption-provider-cipher.yaml
80+
----
81+
82+
. You can view a sample of the YAML file. The `head` command will show you the first 10 lines:
83+
+
84+
[source,terminal]
85+
----
86+
$ head /tmp/ocp4-cis-api-server-encryption-provider-cipher.yaml
87+
----
88+
+
89+
.Example output
90+
[source,terminal]
91+
----
92+
apiVersion: config.openshift.io/v1
93+
kind: APIServer
94+
metadata:
95+
name: cluster
96+
spec:
97+
encryption:
98+
type: aescbc
99+
----
100+
101+
[WARNING]
102+
====
103+
Use caution before applying remediations directly. Some remediations might not be applicable in bulk, such as the usbguard rules in the moderate profile. In these cases, allow the Compliance Operator to apply the rules because it addresses the dependencies and ensures that the cluster remains in a good state.
104+
====

‎modules/oc-compliance-fetching-raw-results.adoc

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/oc_compliance_plug_in/oc-compliance-plug-in-using.adoc
4+
5+
[id="fetching-raw-results_{context}"]
6+
= Fetching raw results
7+
8+
When a compliance scan finishes, the results of the individual checks are listed in the resulting `ComplianceCheckResult` custom resource (CR). However, an administrator or auditor might require the complete details of the scan. The OpenSCAP tool creates an Advanced Recording Format (ARF) formatted file with the detailed results. This ARF file is too large to store in a config map or other standard Kubernetes resource, so a persistent volume (PV) is created to contain it.
9+
10+
.Procedure
11+
12+
* Fetching the results from the PV with the Compliance Operator is a four-step process. However, with the `oc-compliance` plug-in, you can use a single command:
13+
+
14+
[source,terminal]
15+
----
16+
$ oc compliance fetch-raw <object-type> <object-name> -o <output-path>
17+
----
18+
+
19+
* `<object-type>` can be either `scansettingbinding`, `compliancescan` or `compliancesuite`, depending on which of these objects the scans were launched with.
20+
* `<object-name>` is the name of the binding, suite, or scan object to gather the ARF file for, and `<output-path>` is the local directory to place the results.
21+
+
22+
For example:
23+
+
24+
[source.terminal]
25+
----
26+
$ oc compliance fetch-raw scansettingbindings my-binding -o /tmp/
27+
----
28+
+
29+
.Example output
30+
[source.terminal]
31+
----
32+
Fetching results for my-binding scans: ocp4-cis, ocp4-cis-node-worker, ocp4-cis-node-master
33+
Fetching raw compliance results for scan 'ocp4-cis'.......
34+
The raw compliance results are avaliable in the following directory: /tmp/ocp4-cis
35+
Fetching raw compliance results for scan 'ocp4-cis-node-worker'...........
36+
The raw compliance results are avaliable in the following directory: /tmp/ocp4-cis-node-worker
37+
Fetching raw compliance results for scan 'ocp4-cis-node-master'......
38+
The raw compliance results are avaliable in the following directory: /tmp/ocp4-cis-node-master
39+
----
40+
41+
View the list of files in the directory:
42+
43+
[source.terminal]
44+
----
45+
$ ls /tmp/ocp4-cis-node-master/
46+
----
47+
48+
.Example output
49+
[source.terminal]
50+
----
51+
ocp4-cis-node-master-ip-10-0-128-89.ec2.internal-pod.xml.bzip2 ocp4-cis-node-master-ip-10-0-150-5.ec2.internal-pod.xml.bzip2 ocp4-cis-node-master-ip-10-0-163-32.ec2.internal-pod.xml.bzip2
52+
----
53+
54+
Extract the results:
55+
56+
[source.terminal]
57+
----
58+
$ bunzip2 -c resultsdir/worker-scan/worker-scan-stage-459-tqkg7-compute-0-pod.xml.bzip2 > resultsdir/worker-scan/worker-scan-ip-10-0-170-231.us-east-2.compute.internal-pod.xml
59+
----
60+
61+
View the results:
62+
[source.terminal]
63+
----
64+
$ ls resultsdir/worker-scan/
65+
----
66+
67+
.Example output
68+
[source.terminal]
69+
----
70+
worker-scan-ip-10-0-170-231.us-east-2.compute.internal-pod.xml
71+
worker-scan-stage-459-tqkg7-compute-0-pod.xml.bzip2
72+
worker-scan-stage-459-tqkg7-compute-1-pod.xml.bzip2
73+
----

‎modules/oc-compliance-printing-controls.adoc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/oc_compliance_plug_in/oc-compliance-plug-in-using.adoc
4+
5+
[id="printing-controls_{context}"]
6+
= Printing controls
7+
8+
Compliance standards are generally organized into a hierarchy as follows:
9+
10+
* A benchmark is the top-level definition of a set of controls for a particular standard. For example, FedRAMP Moderate or Center for Internet Security (CIS) v.1.6.0.
11+
* A control describes a family of requirements that must be met in order to be in compliance with the benchmark. For example, FedRAMP AC-01 (access control policy and procedures).
12+
* A rule is a single check that is specific for the system being brought into compliance, and one or more of these rules map to a control.
13+
* The Compliance Operator handles the grouping of rules into a profile for a single benchmark. It can be difficult to determine which controls that the set of rules in a profile satisfy.
14+
15+
.Procedure
16+
17+
* The `oc compliance` `controls` subcommand provides a report of the standards and controls that a given profile satisfies:
18+
+
19+
[source,terminal]
20+
----
21+
$ oc compliance controls profile ocp4-cis-node
22+
----
23+
+
24+
.Example output
25+
[source,terminal]
26+
----
27+
+-----------+----------+
28+
| FRAMEWORK | CONTROLS |
29+
+-----------+----------+
30+
| CIS-OCP | 1.1.1 |
31+
+ +----------+
32+
| | 1.1.10 |
33+
+ +----------+
34+
| | 1.1.11 |
35+
+ +----------+
36+
...
37+
----

‎modules/oc-compliance-rerunning-scans.adoc

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/oc_compliance_plug_in/oc-compliance-plug-in-using.adoc
4+
5+
[id="re-running-scans_{context}"]
6+
= Re-running scans
7+
8+
Although it is possible to run scans as scheduled jobs, you must often re-run a scan on demand, particularly after remediations are applied or when other changes to the cluster are made.
9+
10+
.Procedure
11+
12+
* Triggering a re-scan with the Compliance Operator requires use of an annotation on the scan object. However, with the `oc-compliance` plug-in you can re-scan with a single command:
13+
+
14+
[source,terminal]
15+
----
16+
$ oc compliance rerun-now <scan-object> <object-name>
17+
----
18+
+
19+
* `<scan-object>` can be `compliancescan`, `compliancesuite`, or `scansettingbinding`.
20+
* `<object-name>`` is the name of the given `scan-object`.
21+
+
22+
For example, to re-run the scans for the `ScanSettingBinding` object named `my-binding`:
23+
+
24+
[source,terminal]
25+
----
26+
$ oc compliance rerun-now scansettingbindings my-binding
27+
----
28+
+
29+
.Example output
30+
[source,terminal]
31+
----
32+
Rerunning scans from 'my-binding': ocp4-cis
33+
Re-running scan 'openshift-compliance/ocp4-cis'
34+
----

‎modules/oc-compliance-using-scan-setting-bindings.adoc

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/oc_compliance_plug_in/oc-compliance-plug-in-using.adoc
4+
5+
[id="using-scan-setting-bindings_{context}"]
6+
= Using ScanSettingBinding custom resources
7+
8+
When using the `ScanSetting` and `ScanSettingBinding` custom resources (CRs) that the Compliance Operator provides, it is possible to run scans for multiple profiles while using a common set of scan options, such as `schedule`, `machine roles`, `tolerations`, and so on. While that is easier than working with multiple `ComplianceSuite` or `ComplianceScan` objects, it can confuse new users.
9+
10+
The `oc compliance bind` subcommand helps you create a `ScanSettingBinding` CR.
11+
12+
.Procedure
13+
14+
. Run:
15+
+
16+
[source,terminal]
17+
----
18+
$ oc compliance bind [--dry-run] -N <binding name> [-S <scansetting name>] <objtype/objname> [..<objtype/objname>]
19+
----
20+
+
21+
* If you omit the `-S` flag, the `default` scan setting provided by the Compliance Operator is used.
22+
* The object type is the Kubernetes object type, which can be `profile` or `tailoredprofile`. More than one object can be provided.
23+
* The object name is the name of the Kubernetes resource, such as `.metadata.name`.
24+
* Add the `--dry-run` option to display the YAML file of the objects that are created.
25+
+
26+
For example, given the following profiles and scan settings:
27+
+
28+
[source,terminal]
29+
----
30+
$ oc get profile.compliance -n openshift-compliance
31+
----
32+
+
33+
.Example output
34+
[source,terminal]
35+
----
36+
NAME AGE
37+
ocp4-cis 9m54s
38+
ocp4-cis-node 9m54s
39+
ocp4-e8 9m54s
40+
ocp4-moderate 9m54s
41+
ocp4-ncp 9m54s
42+
rhcos4-e8 9m54s
43+
rhcos4-moderate 9m54s
44+
rhcos4-ncp 9m54s
45+
rhcos4-ospp 9m54s
46+
rhcos4-stig 9m54s
47+
----
48+
+
49+
[source,terminal]
50+
----
51+
$ oc get scansettings -n openshift-compliance
52+
----
53+
+
54+
.Example output
55+
[source,terminal]
56+
----
57+
NAME AGE
58+
default 10m
59+
default-auto-apply 10m
60+
----
61+
62+
. To apply the `default` settings to the `ocp4-cis` and `ocp4-cis-node` profiles, run:
63+
+
64+
[source,terminal]
65+
----
66+
$ oc compliance bind -N my-binding profile/ocp4-cis profile/ocp4-cis-node
67+
----
68+
+
69+
.Example output
70+
[source,terminal]
71+
----
72+
Creating ScanSettingBinding my-binding
73+
----
74+
+
75+
Once the `ScanSettingBinding` CR is created, the bound profile begins scanning for both profiles with the related settings. Overall, this is the fastest way to begin scanning with the Compliance Operator.

‎modules/oc-compliance-viewing-compliance-check-result-details.adoc

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/oc_compliance_plug_in/oc-compliance-plug-in-using.adoc
4+
5+
[id="viewing-compliance-remediation-details_{context}"]
6+
= Viewing ComplianceCheckResult object details
7+
8+
When scans are finished running, `ComplianceCheckResult` objects are created for the individual scan rules. The `view-result` subcommand provides a human-readable output of the `ComplianceCheckResult` object details.
9+
10+
.Procedure
11+
12+
* Run:
13+
+
14+
[source,terminal]
15+
----
16+
$ oc compliance view-result ocp4-cis-scheduler-no-bind-address
17+
----

‎security/oc_compliance_plug_in/oc-compliance-plug-in-using.adoc

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[id="using-oc-compliance-plug-in"]
2+
= Using the oc-compliance Plug-in
3+
include::modules/common-attributes.adoc[]
4+
:context: oc-compliance-plug-in-understanding
5+
6+
toc::[]
7+
8+
Although the xref:../../security/compliance_operator/compliance-operator-understanding.adoc#understanding-compliance-operator[Compliance Operator] automates many of the checks and remediations for the cluster, the full process of bringing a cluster into compliance often requires administrator interaction with the Compliance Operator API and other components. The `oc-compliance` plug-in makes the process easier.
9+
10+
11+
include::modules/oc-compliance-fetching-raw-results.adoc[leveloffset=+1]
12+
13+
include::modules/oc-compliance-rerunning-scans.adoc[leveloffset=+1]
14+
15+
include::modules/oc-compliance-using-scan-setting-bindings.adoc[leveloffset=+1]
16+
17+
include::modules/oc-compliance-printing-controls.adoc[leveloffset=+1]
18+
19+
include::modules/oc-compliance-fetching-compliance-remediation-details.adoc[leveloffset=+1]
20+
21+
include::modules/oc-compliance-viewing-compliance-check-result-details.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)