From 956c39f51157427211aa5bb5325e286680d7a5b4 Mon Sep 17 00:00:00 2001 From: Watson Sato Date: Thu, 31 Aug 2023 18:02:09 +0200 Subject: [PATCH] Update Workshop instructions and outputs - Let's use resources from ComplianceAsCode - Fix typoes - Update link to upstream operator image - Update links to CaC/content documenation - Update output of build_ds_container.py --- config/catalog/catalog-source.yaml | 2 +- .../content/exercises/02-installation.md | 46 ++++---- .../exercises/03-creating-your-first-scan.md | 106 +++++++++++------- .../content/exercises/04-remediations.md | 14 ++- .../content/exercises/07-content-setup.md | 24 ++-- .../content/exercises/09-writing-rules.md | 5 +- 6 files changed, 112 insertions(+), 85 deletions(-) diff --git a/config/catalog/catalog-source.yaml b/config/catalog/catalog-source.yaml index 6c486f533..03e743968 100644 --- a/config/catalog/catalog-source.yaml +++ b/config/catalog/catalog-source.yaml @@ -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 diff --git a/doc/tutorials/workshop/content/exercises/02-installation.md b/doc/tutorials/workshop/content/exercises/02-installation.md index d4824934e..c94e95f25 100644 --- a/doc/tutorials/workshop/content/exercises/02-installation.md +++ b/doc/tutorials/workshop/content/exercises/02-installation.md @@ -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 ``` @@ -21,15 +21,15 @@ 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 @@ -37,9 +37,9 @@ 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 ``` @@ -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. @@ -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` diff --git a/doc/tutorials/workshop/content/exercises/03-creating-your-first-scan.md b/doc/tutorials/workshop/content/exercises/03-creating-your-first-scan.md index e8f1229c5..084e1e86c 100644 --- a/doc/tutorials/workshop/content/exercises/03-creating-your-first-scan.md +++ b/doc/tutorials/workshop/content/exercises/03-creating-your-first-scan.md @@ -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 ``` @@ -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 @@ -66,12 +76,17 @@ 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 @@ -79,22 +94,18 @@ 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 @@ -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 @@ -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:
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. +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 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. + 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 ``` @@ -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 ``` diff --git a/doc/tutorials/workshop/content/exercises/04-remediations.md b/doc/tutorials/workshop/content/exercises/04-remediations.md index 35525b950..947af4edc 100644 --- a/doc/tutorials/workshop/content/exercises/04-remediations.md +++ b/doc/tutorials/workshop/content/exercises/04-remediations.md @@ -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 @@ -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: diff --git a/doc/tutorials/workshop/content/exercises/07-content-setup.md b/doc/tutorials/workshop/content/exercises/07-content-setup.md index b0958dafd..9866d1460 100644 --- a/doc/tutorials/workshop/content/exercises/07-content-setup.md +++ b/doc/tutorials/workshop/content/exercises/07-content-setup.md @@ -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 @@ -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 ``` @@ -137,7 +139,8 @@ 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. @@ -145,16 +148,17 @@ You can even open a terminal in VSCode that proxies to the remote machine by sel 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. *** diff --git a/doc/tutorials/workshop/content/exercises/09-writing-rules.md b/doc/tutorials/workshop/content/exercises/09-writing-rules.md index 77fdc63fb..a8d26ab22 100644 --- a/doc/tutorials/workshop/content/exercises/09-writing-rules.md +++ b/doc/tutorials/workshop/content/exercises/09-writing-rules.md @@ -13,7 +13,7 @@ benchmark, or simply you have a custom scenario that you want to address. There is already documentation in place that will help you [write content and understand the structure of the project]( -https://github.com/ComplianceAsCode/content/blob/master/docs/manual/developer_guide.adoc#creating-content) +https://complianceascode.readthedocs.io/en/latest/manual/developer/03_creating_content.html) so let's focus instead on writing content for OpenShift. There is a handy tool in the `utils` directory that will help you create such @@ -51,6 +51,7 @@ Let's create a rule that simply checks that the `ConfigMap` exists with the appr value. ``` +$ source .pyenv.sh # Configure PYTHONPATH for CaC modules $ ./utils/add_platform_rule.py create \ --rule must_have_compliant_cm \ --name my-compliance-configmap --namespace openshift --type configmap \ @@ -100,7 +101,7 @@ template: This template will make the build system generate the appropriate OVAL check that OpenSCAP will take into use. You can read more about it in the [documentation -](https://github.com/ComplianceAsCode/content/blob/master/docs/manual/developer_guide.adoc#732-list-of-available-templates) +](https://complianceascode.readthedocs.io/en/latest/templates/template_reference.html) ## Testing our rule