Skip to content

Commit

Permalink
Merge pull request #397 from yuumasato/workshop-doc-fixes
Browse files Browse the repository at this point in the history 
Update Workshop instructions and outputs
  • Loading branch information
@openshift-merge-robot
openshift-merge-robot authored Sep 6, 2023
2 parents 877fc75 + 956c39f commit c93d4e6
Show file tree
Hide file tree
Showing 6 changed files with 112 additions and 85 deletions.
2 changes: 1 addition & 1 deletion config/catalog/catalog-source.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,6 @@ metadata:
namespace: openshift-marketplace
spec:
displayName: Compliance Operator Upstream
publisher: github.com/openshift/compliance-operator
publisher: github.com/complianceascode/compliance-operator
sourceType: grpc
image: ghcr.io/complianceascode/compliance-operator-catalog:latest
46 changes: 23 additions & 23 deletions doc/tutorials/workshop/content/exercises/02-installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ NextPage: 03-creating-your-first-scan
---

Assuming you have the cluster up and running and you are logged as a user who has the
`cluster-admin` role, the first task it to install the operator. Even though
`cluster-admin` role, the first task is to install the operator. Even though
we're going to be installing the latest release packaged by upstream and
not deploying from the source, we're going to be creating several Kubernetes
objects from manifests in the upstream repository.

Start by creating the `openshift-compliance` namespace:
```
$ oc create -f https://raw.githubusercontent.com/openshift/compliance-operator/master/deploy/ns.yaml
$ oc create -f https://raw.githubusercontent.com/ComplianceAsCode/compliance-operator/master/config/ns/ns.yaml
namespace/openshift-compliance created
```

Expand All @@ -21,25 +21,25 @@ so we'll continue by creating several objects that describe the operator for
the OLM. First, we'll create the `CatalogSource` and verify that it's been
created successfully:
```
$ oc create -f https://raw.githubusercontent.com/openshift/compliance-operator/master/deploy/olm-catalog/catalog-source.yaml
$ oc create -f https://raw.githubusercontent.com/ComplianceAsCode/compliance-operator/master/config/catalog/catalog-source.yaml
catalogsource.operators.coreos.com/compliance-operator created
$ oc get catalogsource -nopenshift-marketplace
NAME DISPLAY TYPE PUBLISHER AGE
certified-operators Certified Operators grpc Red Hat 24m
community-operators Community Operators grpc Red Hat 24m
compliance-operator Compliance Operator Upstream grpc github.com/openshift/compliance-operator 17s
redhat-marketplace Red Hat Marketplace grpc Red Hat 24m
redhat-operators Red Hat Operators grpc Red Hat 24m
NAME DISPLAY TYPE PUBLISHER AGE
certified-operators Certified Operators grpc Red Hat 24m
community-operators Community Operators grpc Red Hat 24m
compliance-operator Compliance Operator Upstream grpc github.com/complianceascode/compliance-operator 17s
redhat-marketplace Red Hat Marketplace grpc Red Hat 24m
redhat-operators Red Hat Operators grpc Red Hat 24m
```

The `CatalogSource` represents metadata that OLM can use to discover and
install Operators. Once the `CatalogSource` is created, we can continue by
telling OLM that we want to install the Compliance Operator to the `openshift-compliance`
namespace by creating the `OperatorGroup` and the `Subscription` objects:
```
$ oc create -f https://raw.githubusercontent.com/openshift/compliance-operator/master/deploy/olm-catalog/operator-group.yaml
$ oc create -f https://raw.githubusercontent.com/ComplianceAsCode/compliance-operator/master/config/catalog/operator-group.yaml
operatorgroup.operators.coreos.com/compliance-operator created
$ oc create -f https://raw.githubusercontent.com/openshift/compliance-operator/master/deploy/olm-catalog/subscription.yaml
$ oc create -f https://raw.githubusercontent.com/ComplianceAsCode/compliance-operator/master/config/catalog/subscription.yaml
subscription.operators.coreos.com/compliance-operator-sub created
```

Expand All @@ -56,18 +56,18 @@ $ oc get pods -nopenshift-compliance
You should see output similar to this one:
```
$ oc get deploy -nopenshift-compliance
NAME READY UP-TO-DATE AVAILABLE AGE
compliance-operator 1/1 1 1 8m9s
ocp4-pp 1/1 1 1 7m22s
rhcos4-pp 1/1 1 1 7m22s
NAME READY UP-TO-DATE AVAILABLE AGE
compliance-operator 1/1 1 1 8m9s
ocp4-openshift-compliance-pp 1/1 1 1 7m22s
rhcos4-openshift-compliance-pp 1/1 1 1 7m22s
$ oc get pods -nopenshift-compliance
NAME READY STATUS RESTARTS AGE
compliance-operator-6fb8c75499-wkmjg 1/1 Running 0 8m11s
ocp4-pp-6d45b4664d-ztflt 1/1 Running 0 7m24s
rhcos4-pp-5cd48cff6-98kl2 1/1 Running 0 7m24s
$ oc get pods -nopenshift-compliance
NAME READY STATUS RESTARTS AGE
compliance-operator-6fb8c75499-wkmjg 1/1 Running 0 8m11s
ocp4-openshift-compliance-pp-6d45b4664d-ztflt 1/1 Running 0 7m24s
rhcos4-openshift-compliance-pp-5cd48cff6-98kl2 1/1 Running 0 7m24s
```
Note: The `ocp4-pp` and the `rhcos4-pp` `Deployment` and `Pods` are created
Note: The `ocp4-openshift-compliance-pp` and the `rhcos4-openshift-compliance-pp` `Deployment` and `Pods` are created
by the operator and can take up to a minute to appear. The most important
object to see is the `compliance-operator` deployment and the associated pod.

Expand All @@ -77,10 +77,10 @@ one below:
```
$ oc get csv -nopenshift-compliance
NAME DISPLAY VERSION REPLACES PHASE
compliance-operator.v0.1.15 Compliance Operator 0.1.15 Succeeded
compliance-operator.v1.2.0 Compliance Operator 1.2.0 Succeeded
$ oc get ip -nopenshift-compliance
NAME CSV APPROVAL APPROVED
install-mlxkz compliance-operator.v0.1.15 Automatic true
install-mlxkz compliance-operator.v1.2.0 Automatic true
```

If the deployment is there, but pods don't appear, check the `Deployment`
Expand Down
106 changes: 63 additions & 43 deletions doc/tutorials/workshop/content/exercises/03-creating-your-first-scan.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,10 @@ usability:
product where product might be `ocp4` or `rhcos4`.

By default, the Compliance Operator creates two `profilebundle` objects, one for
OCP and one for RHCOS based on the [upstream ComplianceAsCode content images](https://quay.io/repository/compliance-operator/compliance-operator-content):
OCP and one for RHCOS based on the [upstream ComplianceAsCode content images](https://github.com/complianceascode/compliance-operator/pkgs/container/compliance-operator):
```
$ oc get profilebundle.compliance
NAME CONTENTIMAGE CONTENTFILE STATUS
NAME CONTENTIMAGE CONTENTFILE STATUS
ocp4 ghcr.io/complianceascode/k8scontent:latest ssg-ocp4-ds.xml VALID
rhcos4 ghcr.io/complianceascode/k8scontent:latest ssg-rhcos4-ds.xml VALID
```
Expand All @@ -50,14 +50,24 @@ $ oc get profilebundle.compliance rhcos4 -o yaml
apiVersion: compliance.openshift.io/v1alpha1
kind: ProfileBundle
metadata:
creationTimestamp: "2023-08-31T08:42:10Z"
finalizers:
- profilebundle.finalizers.compliance.openshift.io
generation: 1
name: rhcos4
namespace: openshift-compliance
selfLink: /apis/compliance.openshift.io/v1alpha1/namespaces/openshift-compliance/profilebundles/rhcos4
uid: f5516313-5f16-4ff8-9c69-d79d44126b8b
resourceVersion: "64537"
uid: ca1cf53a-71b5-4492-acd7-6c79b99c4b4f
spec:
contentFile: ssg-rhcos4-ds.xml
contentImage: ghcr.io/complianceascode/k8scontent:latest
status:
conditions:
- lastTransitionTime: "2023-08-31T08:43:30Z"
message: Profile bundle successfully parsed
reason: Valid
status: "True"
type: Ready
dataStreamStatus: VALID
```
The `status.dataStreamStatus` field is set by the operator and reflects
Expand All @@ -66,35 +76,36 @@ the result of the content parsing.
Several `Profile` objects are parsed out of each bundle, for the `rhcos4` bundle we'd have:
```
$ oc get profile.compliance -lcompliance.openshift.io/profile-bundle=rhcos4 -nopenshift-compliance
NAME AGE
rhcos4-e8 5h2m
rhcos4-moderate 5h2m
rhcos4-ncp 5h2m
rhcos4-ospp 5h2m
rhcos4-stig 5h2m
NAME AGE
rhcos4-anssi-bp28-enhanced 19m
rhcos4-anssi-bp28-high 19m
rhcos4-anssi-bp28-intermediary 19m
rhcos4-anssi-bp28-minimal 19m
rhcos4-e8 19m
rhcos4-high 19m
rhcos4-moderate 19m
rhcos4-nerc-cip 19m
rhcos4-stig 19m
```

For the rest of the chapter we'll be working with the `e8` profile. Inspecting
the profile shows the following:
```
$ oc get profile.compliance rhcos4-e8 -o yaml
apiVersion: compliance.openshift.io/v1alpha1
description: |-
This profile contains configuration checks for Red Hat Enterprise Linux CoreOS
that align to the Australian Cyber Security Centre (ACSC) Essential Eight.
A copy of the Essential Eight in Linux Environments guide can be found at the
ACSC website:
https://www.cyber.gov.au/publications/essential-eight-in-linux-environments
description: 'This profile contains configuration checks for Red Hat Enterprise Linux
CoreOS that align to the Australian Cyber Security Centre (ACSC) Essential Eight.
A copy of the Essential Eight in Linux Environments guide can be found at the ACSC
website: https://www.cyber.gov.au/acsc/view-all-content/publications/hardening-linux-workstations-and-servers'
id: xccdf_org.ssgproject.content_profile_e8
kind: Profile
metadata:
annotations:
compliance.openshift.io/image-digest: pb-rhcos496gpm
compliance.openshift.io/image-digest: pb-rhcos4lv4h8
compliance.openshift.io/product: redhat_enterprise_linux_coreos_4
compliance.openshift.io/product-type: Node
creationTimestamp: "2020-09-08T07:44:10Z"
creationTimestamp: "2023-08-31T08:42:24Z"
generation: 1
labels:
compliance.openshift.io/profile-bundle: rhcos4
Expand All @@ -106,10 +117,9 @@ metadata:
controller: true
kind: ProfileBundle
name: rhcos4
uid: a130fef5-054c-431e-91c7-306995ee86c4
resourceVersion: "39697"
selfLink: /apis/compliance.openshift.io/v1alpha1/namespaces/openshift-compliance/profiles/rhcos4-e8
uid: d2c28fb8-0bfe-4c7e-884e-d5e1be790d3e
uid: ca1cf53a-71b5-4492-acd7-6c79b99c4b4f
resourceVersion: "62455"
uid: 8312087a-87ee-44e7-8e5e-3760dcadbed6
rules:
- rhcos4-accounts-no-uid-except-zero
- rhcos4-audit-rules-dac-modification-chmod
Expand Down Expand Up @@ -156,33 +166,43 @@ The (trimmed) result looks somewhat like:
```
$ oc get rule.compliance rhcos4-accounts-no-uid-except-zero -o yaml
apiVersion: compliance.openshift.io/v1alpha1
description: <br />If the account is associated with system commands or applications the UID&#xA;should be changed to one greater than &#34;0&#34; but less than &#34;1000.&#34;&#xA;Otherwise assign a UID greater than &#34;1000&#34; that has not already been&#xA;assigned.
checkType: Node
description: |-
If any account other than root has a UID of 0, this misconfiguration should be investigated and the accounts other than root should be removed or have their UID changed.
If the account is associated with system commands or applications the UID should be changed to one greater than "0" but less than "1000." Otherwise assign a UID greater than "1000" that has not already been assigned.
id: xccdf_org.ssgproject.content_rule_accounts_no_uid_except_zero
instructions: |-
Verify that only the "root" account has a UID "0" assignment with the
following command:
$ awk -F: '$3 == 0 {print $1}' /etc/passwd
root
kind: Rule
metadata:
annotations:
compliance.openshift.io/image-digest: pb-rhcos4mxp5c
compliance.openshift.io/image-digest: pb-rhcos4lv4h8
compliance.openshift.io/rule: accounts-no-uid-except-zero
control.compliance.openshift.io/NERC-CIP: CIP-003-8 R5.1.1;CIP-003-8 R5.3;CIP-004-6
R2.2.3;CIP-004-6 R2.3;CIP-007-3 R5.1;CIP-007-3 R5.1.2;CIP-007-3 R5.2;CIP-007-3
R5.3.1;CIP-007-3 R5.3.2;CIP-007-3 R5.3.3
control.compliance.openshift.io/NIST-800-53: IA-2;AC-6(5);IA-4(b)
policies.open-cluster-management.io/controls: IA-2,AC-6(5),IA-4(b)
policies.open-cluster-management.io/standards: NIST-800-53
creationTimestamp: "2020-09-09T07:34:16Z"
control.compliance.openshift.io/PCI-DSS: Req-8.5
policies.open-cluster-management.io/controls: CIP-003-8 R5.1.1,CIP-003-8 R5.3,CIP-004-6
R2.2.3,CIP-004-6 R2.3,CIP-007-3 R5.1,CIP-007-3 R5.1.2,CIP-007-3 R5.2,CIP-007-3
R5.3.1,CIP-007-3 R5.3.2,CIP-007-3 R5.3.3,IA-2,AC-6(5),IA-4(b),Req-8.5
policies.open-cluster-management.io/standards: NERC-CIP,NIST-800-53,PCI-DSS
creationTimestamp: "2023-08-31T08:42:32Z"
generation: 1
labels:
compliance.openshift.io/profile-bundle: rhcos4
name: rhcos4-accounts-no-uid-except-zero
namespace: openshift-compliance
ownerReferences:
- apiVersion: compliance.openshift.io/v1alpha1
blockOwnerDeletion: true
controller: true
kind: ProfileBundle
name: rhcos4
uid: 597792a5-1caa-4857-8611-ac2301b7f4c2
resourceVersion: "40165"
selfLink: /apis/compliance.openshift.io/v1alpha1/namespaces/openshift-compliance/rules/rhcos4-accounts-no-uid-except-zero
uid: 6794bf39-630a-4592-9d00-10a4279d14fb
rationale: An account has root authority if it has a UID of 0. Multiple accounts&#xA;with a UID of 0 afford more opportunity for potential intruders to&#xA;guess a password for a privileged account. Proper configuration of&#xA;sudo is recommended to afford multiple system administrators&#xA;access to root privileges in an accountable manner.
resourceVersion: "62760"
uid: fd09c9c5-756a-4888-807c-f920fa031183
rationale: An account has root authority if it has a UID of 0. Multiple accounts with
a UID of 0 afford more opportunity for potential intruders to guess a password for
a privileged account. Proper configuration of sudo is recommended to afford multiple
system administrators access to root privileges in an accountable manner.
severity: high
title: Verify Only Root Has UID 0
```
Expand Down Expand Up @@ -436,10 +456,10 @@ tar: Removing leading `/' from member names
The results are stored in directories numbered sequentially with the
number of the scan, up to the rotation policy, then reused:
```
$ ls
$ ls ./extract_results_dir/
0 lost+found
$ ls 0
openscap-pod-9294a45c73ef807cf82327f147f061fe3833eab7.xml.bzip2 openscap-pod-c41c6ef35a2ed0e442ae209120013ae708417c13.xml.bzip2 openscap-pod-e3f56090e7127d8499113d5188e2a83c18060007.xml.bzip2
$ ls ./extract_results_dir/0
rhcos4-e8-master-ip-10-0-110-230.us-east-2.compute.internal-pod.xml.bzip2 rhcos4-e8-master-ip-10-0-114-17.us-east-2.compute.internal-pod.xml.bzip2 rhcos4-e8-master-ip-10-0-25-60.us-east-2.compute.internal-pod.xml.bzip2
```
Expand Down
14 changes: 8 additions & 6 deletions doc/tutorials/workshop/content/exercises/04-remediations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,13 +92,18 @@ You'll notice that this remediation merely creates a MachineConfig object that s
sysctl. You'll also notice that there is a controller set in the `ownerReferences` key in the metadata
of the remediation. This object points to a **ComplianceCheckResult** object which contains further
explanations about what was checked and why this remediation needs to be applied. We already examined
the results in the previous chapter, so for this exercise, let's just just see what the check is about:
the results in the previous chapter, so for this exercise, let's just see what the check is about:

```
$ oc get compliancecheckresult rhcos4-e8-worker-sysctl-kernel-dmesg-restrict -o jsonpath="{.description}"
Restrict Access to Kernel Message Buffer
Unprivileged access to the kernel syslog can expose sensitive kernel
address information.
To set the runtime status of the kernel.dmesg_restrict kernel parameter, run the following command:
$ sudo sysctl -w kernel.dmesg_restrict=1
To make sure that the setting is persistent, add the following line to a file in the directory /etc/sysctl.d :
kernel.dmesg_restrict = 1
```

While this information is relevant, we might want to know more. This is where it's relevant to check the
Expand Down Expand Up @@ -194,11 +199,8 @@ metadata:
compliance.openshift.io/scan-name: rhcos4-e8-worker
compliance.openshift.io/suite: periodic-e8
machineconfiguration.openshift.io/role: worker
managedFields:
...
name: 75-rhcos4-e8-worker-sysctl-kernel-dmesg-restrict
resourceVersion: "136045"
selfLink: /apis/machineconfiguration.openshift.io/v1/machineconfigs/75-rhcos4-e8-worker-sysctl-kernel-dmesg-restrict
uid: 267bda7e-b170-4817-b9f5-89047e7888f5
spec:
config:
Expand Down
24 changes: 14 additions & 10 deletions doc/tutorials/workshop/content/exercises/07-content-setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ the content requires some Linux-specific packages such as `openscap-utils`.
If you are already running Linux and can install additional packages, the
setup is just a matter of running a couple of `yum/dnf` calls and cloning a
repo. You can head to the [SCAP developer
documentation](https://github.com/ComplianceAsCode/content/blob/master/docs/manual/developer_guide.adoc#building-complianceascode)
documentation](https://complianceascode.readthedocs.io/en/latest/)
for detailed instructions.

If you are running a different OS, like macOS or can't install packages on
Expand Down Expand Up @@ -107,8 +107,10 @@ user@compliance$ ./utils/build_ds_container.py
```
This command might take a fair amount of time, but eventually would finish with:
```
Success!
********
2023-08-31 15:30:02,170:INFO: Building content for ocp4, rhcos4
2023-08-31 15:31:03,195:INFO: Successfully built content for ocp4, rhcos4
2023-08-31 15:31:24,289:INFO: Build status: Running
...
Your image is available at: image-registry.openshift-image-registry.svc:5000/openshift-compliance/openscap-ocp4-ds:latest
```

Expand Down Expand Up @@ -137,24 +139,26 @@ new VSCode window that is connected to your host.

Open the compliance content files by clicking the Open icon (Top left on the sidebar)
and selecting "Open Folder". If you're using the VM setup, open the directory
`/home/user/content`. The CIS content is located in `ocp4/profiles/cis.profile`.
`/home/user/content`. The CIS content is defined in `controls/cis_ocp_1_4_0` and
referenced by a profile in `ocp4/profiles/cis.profile`.

You can even open a terminal in VSCode that proxies to the remote machine by selecting
"Terminal" which should open a shell in the remote VM.

ComplianceAsCode extensions
---------------------------
The ComplianceAsCode extensions written by Gabriel Becker allow you to
navigate between rules and remediations. The extension is called "Content
Navigator" and its ID is `ggbecker.content-navigator`. You should be able to
install it from the Extensions Marketplace as any other VSCode extension.
navigate between rules and remediations. The extension is called [Content
Navigator](content-navigator.net) and its ID is `ggbecker.content-navigator`.
You should be able to install it from the Extensions Marketplace as any other
VSCode extension.

Note - if you are using a remote connection to a VM, you need to install the
extension in the window that opens for the remote connection as well.

If you open the CIS profile at `ocp4/profiles/cis.profile`, you can test the
extension by e.g. right-clicking a rule name and selecting "Open Rule". All
the extension features also have keyboard shortcuts.
If you open the CIS profile at `controls/cis_ocp_1_4_0/section-1.yml`, you can
test the extension by e.g. right-clicking a rule name and selecting "Open Rule".
All the extension features also have keyboard shortcuts.

***

Expand Down
Loading

0 comments on commit c93d4e6

Please sign in to comment.