Merge pull request #27483 from bergerhoffer/term-updates-security

Terminology style updates for security book

Author: bergerhoffer

modules/checking-file-intergrity-cr-status.adoc

@@ -3,7 +3,7 @@
 // * security/file_integrity_operator/file-integrity-operator-understanding.adoc
 
 [id="checking-the-file-integrity-CR-status_{context}"]
-= Checking the FileIntegrity custom resource status
+= Checking the `FileIntegrity` custom resource status
 
 The `FileIntegrity` custom resource (CR) reports its status through the
 .`status.phase` subresource.

modules/compliance-anatomy.adoc

@@ -26,7 +26,7 @@ $ oc logs pods/<pod-name>
 $ oc describe pod/<pod-name> -c profileparser
 ----
 
-== The ScanSetting and ScanSettingBinding lifecycle and debugging
+== The `ScanSetting` and `ScanSettingBinding` lifecycle and debugging
 With valid compliance content sources, the high-level `ScanSetting` and `ScanSettingBinding` objects can be used to generate `ComplianceSuite` and `ComplianceScan` objects:
 
 [source,yaml]
@@ -72,9 +72,9 @@ Events:
 
 Now a `ComplianceSuite` object is created. The flow continues to reconcile the newly created `ComplianceSuite`.
 
-== ComplianceSuite lifecycle and debugging
+== `ComplianceSuite` lifecycle and debugging
 The `ComplianceSuite` CR is a wrapper around `ComplianceScan` CRs. The `ComplianceSuite` CR is handled by controller tagged with `logger=suitectrl`.
-This controller handles creating Scans from a Suite, reconciling and aggregating individual Scan statuses into a single Suite status. If a Suite is set to execute periodically, the `suitectrl` also handles creating a `CronJob` CR that re-runs the Scans in the Suite after the initial run is done:
+This controller handles creating scans from a suite, reconciling and aggregating individual Scan statuses into a single Suite status. If a suite is set to execute periodically, the `suitectrl` also handles creating a `CronJob` CR that re-runs the scans in the suite after the initial run is done:
 
 [source,terminal]
 ----
@@ -85,26 +85,26 @@ $ oc get cronjobs
 [source,terminal]
 ----
 NAME                                           SCHEDULE    SUSPEND   ACTIVE   LAST SCHEDULE   AGE
-<cron-name>                                    0 1 * * *   False     0        <none>          151m
+<cron_name>                                    0 1 * * *   False     0        <none>          151m
 ----
 
-For the most important issues, Events are emitted. View them with `oc describe compliancesuites/$name`. The Suite objects also have a Status subresource that is updated when any of Scan objects that belong to this suite update their Status subresource. After all expected scans are created, control is passed to the scan controller.
+For the most important issues, events are emitted. View them with `oc describe compliancesuites/<name>`. The `Suite` objects also have a `Status` subresource that is updated when any of `Scan` objects that belong to this suite update their `Status` subresource. After all expected scans are created, control is passed to the scan controller.
 
-== ComplianceScan lifecycle and debugging
+== `ComplianceScan` lifecycle and debugging
 The `ComplianceScan` CRs are handled by the `scanctrl` controller. This is also where the actual scans happen and the scan results are created. Each scan goes through several phases:
 
 === Pending phase
 The scan is validated for correctness in this phase. If some parameters like storage size are invalid, the scan transitions to DONE with ERROR result, otherwise proceeds to the Launching phase.
 
 === Launching phase
-In this phase, several `ConfigMaps` that contain either environment for the scanner pods or directly the script that the scanner pods will be evaluating. List the ConfigMaps:
+In this phase, several config maps that contain either environment for the scanner pods or directly the script that the scanner pods will be evaluating. List the config maps:
 
 [source,terminal]
 ----
 $ oc get cm -lcompliance.openshift.io/scan-name=rhcos4-e8-worker,complianceoperator.openshift.io/scan-script=
 ----
 
-These `ConfigMaps` will be used by the scanner pods. If you ever needed to modify the scanner behavior, change the scanner debug level or print the raw results, modifying the `ConfigMaps` is the way to go. Afterwards, a `PersistentVolumeClaim` is created per scan in order to store the raw ARF results:
+These config maps will be used by the scanner pods. If you ever needed to modify the scanner behavior, change the scanner debug level or print the raw results, modifying the config maps is the way to go. Afterwards, a persistent volume claim is created per scan in order to store the raw ARF results:
 
 [source,terminal]
 ----
@@ -135,7 +135,7 @@ The running phase waits until the scanner pods finish. The following terms and p
 
 * *scanner*: This container runs the scan. For node scans, the container mounts the node filesystem as `/host` and mounts the content delivered by the init container. The container also mounts the `entrypoint` `ConfigMap` created in the Launching phase and executes it. The default script in the entrypoint `ConfigMap` executes OpenSCAP and stores the result files in the `/results` directory shared between the pod's containers. Logs from this pod can be viewed to determine what the OpenSCAP scanner checked. More verbose output can be viewed with the `debug` flag.
 
-* *logcollector*: The logcollector container waits until the scanner container finishes. Then, it uploads the full ARF results to the `ResultServer` and separately uploads the XCCDF results along with scan result and OpenSCAP result code as a `ConfigMap.` These result Configaps are labeled with the scan name (`compliance.openshift.io/scan-name=$scan_name`):
+* *logcollector*: The logcollector container waits until the scanner container finishes. Then, it uploads the full ARF results to the `ResultServer` and separately uploads the XCCDF results along with scan result and OpenSCAP result code as a `ConfigMap.` These result config maps are labeled with the scan name (`compliance.openshift.io/scan-name=<scan_name>`):
 +
 [source,terminal]
 ----
@@ -165,14 +165,14 @@ Scanner pods for `Platform` scans are similar, except:
 
 * There is one extra init container called `api-resource-collector` that reads the OpenSCAP content provided by the content-container init, container, figures out which API resources the content needs to examine and stores those API resources to a shared directory where the `scanner` container would read them from.
 
-* The `scanner` container does not need to mount the host filesystem.
+* The `scanner` container does not need to mount the host file system.
 
 When the scanner pods are done, the scans move on to the Aggregating phase.
 
 === Aggregating phase
-In the aggregating phase, the scan controller spawns yet another pod called the aggregator pod. Its purpose it to take the result `ConfigMap` objects, read the results and for each check result create the corresponding k8s object. If the check failure can be automatically remediated, a `ComplianceRemediation` object is created. To provide human-readable metadata for the checks and remediations, the aggregator pod also mounts the OpenSCAP content using an init container.
+In the aggregating phase, the scan controller spawns yet another pod called the aggregator pod. Its purpose it to take the result `ConfigMap` objects, read the results and for each check result create the corresponding Kubernetes object. If the check failure can be automatically remediated, a `ComplianceRemediation` object is created. To provide human-readable metadata for the checks and remediations, the aggregator pod also mounts the OpenSCAP content using an init container.
 
-When a `ConfigMap` is processed by an aggregator pod,it is labeled the `compliance-remediations/processed` label. The result of this phase are `ComplianceCheckResult` objects:
+When a config map is processed by an aggregator pod, it is labeled the `compliance-remediations/processed` label. The result of this phase are `ComplianceCheckResult` objects:
 
 [source,terminal]
 ----
@@ -207,17 +207,17 @@ It is also possible to trigger a re-run of a scan in the Done phase by annotatin
 $ oc annotate compliancescans/<scan_name> compliance.openshift.io/rescan=
 ----
 
-After the scan reaches the Done phase, nothing else happens on its own unless the remediations are set to be applied automatically with `autoApplyRemediations: true`. The {product-title} administrator would now review the remediations and apply them as needed. If the remediations are set to be applied automatically, the `ComplianceSuite` controller takes over in the Done phase, pauses the `MachineConfigPool` to which the scan maps to and applies all the remediations in one go. If a remediation is applied, the `ComplianceRemediation` controller takes over.
+After the scan reaches the Done phase, nothing else happens on its own unless the remediations are set to be applied automatically with `autoApplyRemediations: true`. The {product-title} administrator would now review the remediations and apply them as needed. If the remediations are set to be applied automatically, the `ComplianceSuite` controller takes over in the Done phase, pauses the machine config pool to which the scan maps to and applies all the remediations in one go. If a remediation is applied, the `ComplianceRemediation` controller takes over.
 
-= ComplianceRemediation lifecycle and debugging
-The example scan has reported some findings. One of the remediations can be enabled by toggling it's `apply` attribute to `true`:
+== `ComplianceRemediation` lifecycle and debugging
+The example scan has reported some findings. One of the remediations can be enabled by toggling its `apply` attribute to `true`:
 
 [source,terminal]
 ----
 $ oc patch complianceremediations/rhcos4-e8-worker-audit-rules-dac-modification-chmod --patch '{"spec":{"apply":true}}' --type=merge
 ----
 
-The ComplianceRemediation controller (`logger=remediationctrl`) reconciles the modified object. The result of the reconciliation is change of status of the remediation object that is reconciled, but also a change of the rendered per-suite `MachineConfig` object that contains all the applied remediations.
+The `ComplianceRemediation` controller (`logger=remediationctrl`) reconciles the modified object. The result of the reconciliation is change of status of the remediation object that is reconciled, but also a change of the rendered per-suite `MachineConfig` object that contains all the applied remediations.
 
 The `MachineConfig` object always begins with `75-` and is named after the scan and the suite:
 
@@ -227,7 +227,7 @@ $ oc get mc | grep 75-
 75-rhcos4-e8-worker-my-companys-compliance-requirements                                                2.2.0             2m46s
 ----
 
-The remediations the `mc` currently consists of are listed in the MachineConfig's annotations:
+The remediations the `mc` currently consists of are listed in the machine config's annotations:
 
 [source,terminal]
 ----
@@ -237,15 +237,15 @@ Labels:       machineconfiguration.openshift.io/role=worker
 Annotations:  remediation/rhcos4-e8-worker-audit-rules-dac-modification-chmod:
 ----
 
-The ComplianceRemediation controller's algorithm works like this:
+The `ComplianceRemediation` controller's algorithm works like this:
 
 * All currently applied remediations are read into an initial remediation set.
 * If the reconciled remediation is supposed to be applied, it is added to the set.
 * A `MachineConfig` object is rendered from the set and annotated with names  of remediations in the set. If the set is empty (the last remediation was unapplied), the rendered `MachineConfig` object is removed.
-* If and only if the rendered `MachineConfig` is different from the one already applied in the cluster, the applied MC is updated (or created, or deleted).
-* Creating or modifying a `MachineConfig` object triggers a reboot of nodes that match the `machineconfiguration.openshift.io/role` label - see the MachineConfig Operator documentation for more details.
+* If and only if the rendered machine config is different from the one already applied in the cluster, the applied MC is updated (or created, or deleted).
+* Creating or modifying a `MachineConfig` object triggers a reboot of nodes that match the `machineconfiguration.openshift.io/role` label - see the Machine Config Operator documentation for more details.
 
-The remediation loop ends once the rendered MachineConfig is updated, if needed, and the reconciled remediation object status is updated. In our case, applying the remediation would trigger a reboot. After the reboot, annotate the scan to re-run it:
+The remediation loop ends once the rendered machine config is updated, if needed, and the reconciled remediation object status is updated. In our case, applying the remediation would trigger a reboot. After the reboot, annotate the scan to re-run it:
 
 [source,terminal]
 ----
@@ -261,6 +261,7 @@ NAME                                                  STATUS   SEVERITY
 rhcos4-e8-worker-audit-rules-dac-modification-chmod   PASS     medium
 ----
 
+// TODO: This shouldn't be a level one in this module
 = Useful labels
 
 Each pod that is spawned by the compliance-operator is labeled specifically with the scan it belongs to and the work it does. The scan identifier is labeled with the `compliance.openshift.io/scan-name` label. The workload identifier is labeled with the `workload` label.

modules/compliance-applying.adoc

@@ -5,18 +5,18 @@
 [id="compliance-applying_{context}"]
 = Applying a remediation
 
-The boolean attribute `spec.apply` controls whether the remediation should be applied by the Compliance Operator.  We can apply the remediation by setting the attribute to true:
+The boolean attribute `spec.apply` controls whether the remediation should be applied by the Compliance Operator.  You can apply the remediation by setting the attribute to `true`:
 
 [source,terminal]
 ----
 $ oc patch complianceremediations/<scan_name>-sysctl-net-ipv4-conf-all-accept-redirects --patch '{"spec":{"apply":true}}' --type=merge
 ----
 
-After the Compliance Operator processes the applied remediation, the `status.ApplicationState` attribute would change to *Applied* or to *Error* if incorrect. When a MachineConfig remediation is applied, that remediation along with all other applied remediations are rendered into a `MachineConfig` object named `75-$scan-name-$suite-name`. That `MachineConfig` object is subsequently rendered by the MachineConfigOperator and finally applied to all the nodes in a MachineConfigPool by an instance of the MachineControlDaemon running on each node.
+After the Compliance Operator processes the applied remediation, the `status.ApplicationState` attribute would change to *Applied* or to *Error* if incorrect. When a machine config remediation is applied, that remediation along with all other applied remediations are rendered into a `MachineConfig` object named `75-$scan-name-$suite-name`. That `MachineConfig` object is subsequently rendered by the Machine Config Operator and finally applied to all the nodes in a machine config pool by an instance of the machine control daemon running on each node.
 
-Note that when the MachineConfigOperator applies a new `MachineConfig` object to nodes in a pool, all the nodes belonging to the pool are rebooted. This might be inconvenient when applying multiple remediations, each of which re-renders the composite `75-$scan-name-$suite-name` `MachineConfig` object. To prevent applying the remediation immediately, you can pause the MachineConfigPool by setting the `.spec.paused` attribute of a MachineConfigPool to `true`.
+Note that when the Machine Config Operator applies a new `MachineConfig` object to nodes in a pool, all the nodes belonging to the pool are rebooted. This might be inconvenient when applying multiple remediations, each of which re-renders the composite `75-$scan-name-$suite-name` `MachineConfig` object. To prevent applying the remediation immediately, you can pause the machine config pool by setting the `.spec.paused` attribute of a `MachineConfigPool` object to `true`.
 
-The Compliance Operator can apply remediations automatically. Set `autoApplyRemediations: true` in the ScanSetting top-level object.
+The Compliance Operator can apply remediations automatically. Set `autoApplyRemediations: true` in the `ScanSetting` top-level object.
 
 [WARNING]
 ====

modules/compliance-custom-storage.adoc

@@ -4,7 +4,7 @@
 
 [id="compliance-custom-storage_{context}"]
 = Setting custom storage size for results
-While the custom resources such as ComplianceCheckResult represent an aggregated result of one check across all scanned nodes, it can be useful to review the raw results as produced by the scanner. The raw results are produced in the ARF format and can be large (tens of megabytes per node), it is impractical to store them in a Kubernetes resource backed by the `etcd` key-value store. Instead, every scan creates a PersistentVolume which defaults to 1GB size. Depending on your environment, you may want to increase the PV size accordingly. This is done using the `rawResultStorage.size` attribute that is exposed in both the ScanSetting and ComplianceScan resources.
+While the custom resources such as `ComplianceCheckResult` represent an aggregated result of one check across all scanned nodes, it can be useful to review the raw results as produced by the scanner. The raw results are produced in the ARF format and can be large (tens of megabytes per node), it is impractical to store them in a Kubernetes resource backed by the `etcd` key-value store. Instead, every scan creates a persistent volume (PV) which defaults to 1GB size. Depending on your environment, you may want to increase the PV size accordingly. This is done using the `rawResultStorage.size` attribute that is exposed in both the `ScanSetting` and `ComplianceScan` resources.
 
 A related parameter is `rawResultStorage.rotation` which controls how many scans are retained in the PV before the older scans are rotated. The default value is 3, setting the rotation policy to 0 disables the rotation. Given the default rotation policy and an estimate of 100MB per a raw ARF scan report, you can calculate the right PV size for your environment.
 
@@ -17,9 +17,9 @@ Because {product-title} can be deployed in a variety of public clouds or bare me
 If your cluster does not specify a default storage class, this attribute must be set.
 ====
 
-Configure the ScanSetting CustomResource to use a standard storage class and create PersistentVolumes that are 10GB in size and keep the last 10 results:
+Configure the `ScanSetting` custom resource to use a standard storage class and create persistent volumes that are 10GB in size and keep the last 10 results:
 
-.Example ScanSetting CR
+.Example `ScanSetting` CR
 
 [source,yaml]
 ----