Skip to content

Commit 6ee1110

Browse files
ggbeckerggbecker
committed
Add lab exercise 2.
1 parent d282b29 commit 6ee1110

19 files changed

+335
-1
lines changed

‎docs/workshop/README.adoc

+5
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
= Workshop
22

3+
This workshop contains many exercises that will get you familiar with OpenSCAP and ComplianceAsCode projects.
4+
5+
Go ahead and experiment them using an online free to use environment directly in your browser.
6+
37
== Table of Contents
48
* link:lab1_introduction.adoc[Lab Exercise 1: Say Hello to ComplianceAsCode^]
59
* link:lab2_openscap.adoc[Lab Exercise 2: Automated Security Scanning Using ComplianceAsCode^]
610
* link:lab3_profiles.adoc[Lab Exercise 3: Create Your Own Security Policy From Scratch^]
711
* link:lab4_ansible.adoc[Lab Exercise 4: Using Ansible in ComplianceAsCode^]
812
* link:lab5_oval.adoc[Lab Exercise 5: The Art of OVAL Checks^]
13+
* link:next_steps_with_complianceascode.adoc[Next Steps with ComplianceAsCode]

‎docs/workshop/images/download_datastream.png

101 KB
Loading

‎docs/workshop/images/lab1.1-scapreport.png

12 KB
Loading

‎docs/workshop/images/lab1.2-newprofileID.png

-624 Bytes
Loading

‎docs/workshop/images/lab1.2-savecustomization.png

1.98 KB
Loading

‎docs/workshop/images/lab1.2-scapworkbenchscan.png

-27.5 KB
Loading

‎docs/workshop/images/lab2_html_report_folder.png

66.7 KB
Loading

‎docs/workshop/images/load_content.png

9.18 KB
Loading

‎docs/workshop/images/scap_report_fail.png

-61.3 KB
Loading

‎docs/workshop/images/scap_report_pass.png

-45.6 KB
Loading

‎docs/workshop/images/scap_workbench_opened.png

36.8 KB
Loading

‎docs/workshop/images/scap_workbench_tailoring.png

-97.8 KB
Loading

‎docs/workshop/images/select_profile.png

82.1 KB
Loading

‎docs/workshop/lab2_openscap.adoc

+299
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
= Lab Exercise 2: Automated Security Scanning Using ComplianceAsCode
2+
:toc2:
3+
:linkattrs:
4+
:experimental:
5+
:imagesdir: images
6+
7+
== Introduction
8+
9+
As you already know from `Lab Exercise 1`, the `ComplianceAsCode` project provides security content that can be used for automated security scanning of your system.
10+
11+
The lab environment is provided with OpenSCAP Scanner, which is a security scanner that works with `ComplianceAsCode` content.
12+
The built content in `ComplianceAsCode` can be simply passed to OpenSCAP Scanner and the scan can be started right away.
13+
14+
OpenSCAP Scanner allows you to perform security compliance checks in a fully automated way.
15+
It is possible to run the scan using either the `oscap` command line tool or the SCAP Workbench graphical application.
16+
Several integrations for continuous scanning also exist, but in this lab exercise, you focus on one-off scanning.
17+
18+
.*Goals*
19+
20+
* Learn the basics of automated security scanning
21+
* Learn how to use `ComplianceAsCode` for automated security scanning
22+
* Learn how to do lightweight customization of a predefined security policy using a GUI tool
23+
* Explore the possibilities for remediations of failing rules
24+
25+
26+
.*Preconfigured Lab Environment*
27+
28+
* The `ComplianceAsCode` repository was cloned.
29+
* The dependencies required for the `ComplianceAsCode` content build were installed using `yum install`:
30+
** Generic build utilities: `cmake` and `make`
31+
** Utilities for generating SCAP content: `openscap-scanner`
32+
** Python dependencies for putting content together: `python3-pyyaml` and `python3-jinja2`
33+
* The following OpenSCAP ecosystem packages were installed using `yum install`:
34+
** The scanner: `openscap-scanner`
35+
// ** Utilities for scanning remote systems: `openscap-utils`
36+
// ** The GUI front end and datastream tool: `scap-workbench`
37+
38+
IMPORTANT: Content used in this lab has been altered to increase its educative potential, and is therefore different from the content in ComplianceAsCode upstream repository or the content in the scap-security-guide package shipped in Red Hat^(R)^ products for example.
39+
40+
== Hands-on Lab
41+
42+
The `ComplianceAsCode` project consists of human-readable files that are compiled into standard-compliant files that are difficult to read and edit directly.
43+
44+
For your convenience, the environment is already set up, so the content is built and ready to be used.
45+
No worries, though--you get to rebuild it later in the exercise.
46+
47+
To start the hands-on section, take the following steps:
48+
49+
. Go to: link:https://gitpod.io/#WORKSHOP=lab2_openscap/https://github.com/ggbecker/content/tree/gitpod-workshop[Lab 2 Environment]
50+
// . Go to: link:https://gitpod.io/#WORKSHOP=lab2_openscap/https://github.com/ComplianceAsCode/content[Lab 2 Environment]
51+
. Wait until all the steps being executed in the terminal are complete.
52+
53+
54+
== Introduction to OpenSCAP Command Line Tool
55+
56+
OpenSCAP provides a command line tool called `oscap` that can be used for automated security scanning.
57+
58+
. You can verify a successful installation of `oscap` by running the following commands:
59+
+
60+
----
61+
[... ]$ oscap --version
62+
63+
OpenSCAP command line tool (oscap) 1.3.6
64+
Copyright 2009--2021 Red Hat Inc., Durham, North Carolina.
65+
66+
==== Supported specifications ====
67+
SCAP Version: 1.3
68+
XCCDF Version: 1.2
69+
OVAL Version: 5.11.1
70+
CPE Version: 2.3
71+
CVSS Version: 2.0
72+
CVE Version: 2.0
73+
Asset Identification Version: 1.1
74+
Asset Reporting Format Version: 1.1
75+
CVRF Version: 1.1
76+
...
77+
----
78+
+
79+
Note that this command outputs the OpenSCAP version and versions of supported standards.
80+
81+
== Using `ComplianceAsCode` Content with OpenSCAP Command Line Tool
82+
83+
In this section, you find the security content for Ubuntu 20.04 from `ComplianceAsCode` source code and then you use the built content with the OpenSCAP command line tool to scan your machine.
84+
85+
. The content has been built, so you can take a look at the generated files in the `build` directory right away:
86+
+
87+
----
88+
[... ]$ cd build
89+
[... build]$ ls -1
90+
build_config.yml
91+
build.ninja
92+
CMakeCache.txt
93+
CMakeFiles
94+
cmake_install.cmake
95+
CPackConfig.cmake
96+
CPackSourceConfig.cmake
97+
CTestTestfile.cmake
98+
docs
99+
jinja2_cache
100+
rules.ninja
101+
ssg-ubuntu2004-cpe-dictionary.xml
102+
ssg-ubuntu2004-cpe-oval.xml
103+
ssg-ubuntu2004-ds-1.2.xml
104+
ssg-ubuntu2004-ds.xml
105+
ssg-ubuntu2004-ocil.xml
106+
ssg-ubuntu2004-oval.xml
107+
ssg-ubuntu2004-xccdf-1.2.xml
108+
ssg-ubuntu2004-xccdf.xml
109+
tests
110+
ubuntu2004
111+
----
112+
+
113+
There are multiple files produced by the build. The file that is going to be used with the OpenSCAP scanner is `ssg-ubuntu2004-ds.xml`. This file is called a SCAP Datastream.
114+
+
115+
. Check which compliance profiles are available for Ubuntu 20.04.
116+
+
117+
----
118+
[... build]$ oscap info ssg-ubuntu2004-ds.xml
119+
...
120+
Profiles:
121+
Title: CIS Ubuntu 20.04 Level 1 Server Benchmark
122+
Id: xccdf_org.ssgproject.content_profile_cis_level1_server
123+
Title: CIS Ubuntu 20.04 Level 1 Workstation Benchmark
124+
Id: xccdf_org.ssgproject.content_profile_cis_level1_workstation
125+
Title: CIS Ubuntu 20.04 Level 2 Server Benchmark
126+
Id: xccdf_org.ssgproject.content_profile_cis_level2_server
127+
Title: CIS Ubuntu 20.04 Level 2 Workstation Benchmark
128+
Id: xccdf_org.ssgproject.content_profile_cis_level2_workstation
129+
Title: Standard System Security Profile for Ubuntu 20.04
130+
Id: xccdf_org.ssgproject.content_profile_standard
131+
Title: Canonical Ubuntu 20.04 LTS Security Technical Implementation Guide (STIG) V1R1
132+
Id: xccdf_org.ssgproject.content_profile_stig
133+
...
134+
----
135+
+
136+
In the "Profiles:" section, you can see a list of profiles contained in the datastream.
137+
The datastream contains multiple profiles that cover different security baselines for different purposes.
138+
Each profile is identified by a profile ID.
139+
+
140+
The built `ComplianceAsCode` content is available as `scap-security-guide` package in Linux distributions (e.g. RHEL, Ubuntu, Suse, etc).
141+
Unlike the upstream repository that you work with now, the package contains only content that is officially tested and supported.
142+
Therefore, the `scap-security-guide` package in Linux distributions may contain less profiles that are available in the upstream repository.
143+
+
144+
. Perform your first baseline testing scan with the vanilla CIS Workstation Level 1 profile.
145+
+
146+
Note in the command below that you can skip the profile ID prefix to make the command simpler.
147+
The real ID is `xccdf_org.ssgproject.content_profile_cis_level1_workstation`.
148+
+
149+
The scanning command has to be executed by a privileged user using `sudo`, so the scanner can access parts of the system that are off-limits to common users.
150+
The simplest scanner invocation can look like this:
151+
+
152+
----
153+
sudo oscap xccdf eval --profile cis_level1_workstation ssg-ubuntu2004-ds.xml
154+
----
155+
+
156+
However, you also want to store the scan results so you can process them later.
157+
Therefore, you have to supply additional arguments:
158+
159+
* Use `--results-arf` to get a machine-readable results archive that includes results of the OVAL scan
160+
* Use `--report` to get a human-readable report (this can also be generated from ARF after the scan, as you see in the next optional step)
161+
+
162+
Now execute the following to run the scan and generate the HTML report as a side-effect:
163+
+
164+
----
165+
[... build]$ sudo oscap xccdf eval --profile cis_level1_workstation --results-arf /tmp/arf.xml --report lab2_report.html --oval-results ssg-ubuntu2004-ds.xml
166+
...
167+
----
168+
+
169+
[NOTE]
170+
====
171+
You can also generate the HTML report later by executing these commands:
172+
173+
----
174+
[... build]$ sudo rm -f lab2_report.html
175+
[... build]$ oscap xccdf generate report /tmp/arf.xml > lab2_report.html
176+
----
177+
====
178+
179+
. On the lab environment, you navigate to the `build` folder.
180+
181+
. Right click the `lab2_report.html` file and select `Open with Live Server` to preview the file. Note: Your browser may block the pop-up. You must allow it when asked.
182+
+
183+
.Lab 2 HTML Report
184+
image::lab2_html_report_folder.png[]
185+
+
186+
You see the compliance scan results for every security control in the CIS Workstation Level 1 security baseline profile in HTML format.
187+
+
188+
image:lab1.1-scapreport.png[]
189+
+
190+
Rules can have several types of results, but the most common ones are *pass* and *fail*, which indicate whether a particular security control has passed or failed the scan.
191+
Other results you frequently encounter are *notapplicable* for rules that have been skipped as not relevant to the scanned system, and *notchecked* for rules without an automated check.
192+
193+
. Click the rule title in the HTML report to bring up a pop-up dialog that allows you to examine why a particular rule failed or passed.
194+
+
195+
For example, if a rule is testing file permissions on a list of files, it specifies which files failed and what their permission bits are.
196+
+
197+
image::scap_report_pass.png[]
198+
+
199+
image::scap_report_fail.png[]
200+
201+
202+
== Customizing Existing SCAP Security Content Using SCAP Workbench
203+
204+
. This part can only be performed on you local machine if the SCAP Workbench is available to be installed, see instruction on how to install it on your Linux distribution.
205+
If you are unable to install SCAP-Workbench on your machine then you can skip to the next section
206+
.. link:https://www.open-scap.org/tools/scap-workbench/#download[Download SCAP Workbench].
207+
208+
. Download the `ssg-ubuntu2004-ds.xml` file to your own machine by clicking `Download...` on the file as shown in the following picture:
209+
+
210+
image:download_datastream.png[]
211+
212+
. Launch SCAP Workbench after installed.
213+
214+
. After Workbench starts, select `Other SCAP content` in the drop-down list and click `Load Content`. A file browser window appears.
215+
. Locate the download `ssg-ubuntu2004-ds.xml` file and click `Open` to open the security compliance content.
216+
+
217+
image:load_content.png[]
218+
+
219+
image::scap_workbench_opened.png[SCAP Workbench opened, profile selected]
220+
221+
. Customize the `CIS Ubuntu 20.04 Level 1 Workstation Benchmark` baseline.
222+
.. Select this profile from the `Profile` drop-down list.
223+
.. Click `Customize`.
224+
+
225+
image:select_profile.png[]
226+
227+
.. In the `Customize Profile` pop-up window, leave the name generated by default for `New Profile ID` and click `OK`.
228+
+
229+
image:lab1.2-newprofileID.png[600,600]
230+
231+
.. Now you can select and deselect rules according to your organization's needs, and change values such as minimum password length, to tailor the compliance profile.
232+
233+
// .. *IMPORTANT*: Search for `verify file hash` and deselect the following rules, these rules can take a long time to process and might cause problems on systems with limited resources:
234+
235+
// * *Verify File Hashes with RPM*
236+
// * *Verify and Correct File Permissions with RPM*
237+
238+
. After you are done customizing, click `OK` to save the profile.
239+
You have now created a new custom profile.
240+
+
241+
image::scap_workbench_tailoring.png[SCAP Workbench content customization]
242+
243+
. You can run a test scan if you have all the dependencies installed on your machine.
244+
But it will most likely end in `notapplicable` depending on your Linux Distribution.
245+
.. Click `Scan` and inspect the results.
246+
.. If there are errors thrown, you can just skip this test scan and move forward.
247+
+
248+
image:lab1.2-scapworkbenchscan.png[500,500]
249+
250+
[TIP]
251+
====
252+
You can save the customization to a tailoring file by selecting `File->Save Customization Only`.
253+
254+
image:lab1.2-savecustomization.png[300,300]
255+
====
256+
257+
== Security Remediations with OpenSCAP, Red Hat Ansible Automation, and Bash
258+
Putting the machine into compliance (for example, by changing its configuration) is called *remediation* in the SCAP terminology.
259+
Remediation changes the configuration of the machine, and it is possible to lock yourself out or disable important workloads!
260+
As a result, it is a best practice to test the remediation changes before deploying.
261+
262+
Go back to the Lab Environment in the browser.
263+
264+
. Generate an Ansible^(R)^ Playbook that puts your machine into compliance.
265+
.. Generate a playbook from the scan results.
266+
Use the `--fix-type ansible` option to request an Ansible Playbook with the fixes:
267+
+
268+
----
269+
[... build]$ oscap xccdf generate fix --fix-type ansible --result-id "" /tmp/arf.xml > playbook.yml
270+
----
271+
+
272+
You specified the empty `result-id` because `oscap` supports generation of fixes from a result file that has results from multiple scans. However, as there is only one result from a single scan, you do not have to specify the result ID explicitly.
273+
274+
. Check the output:
275+
+
276+
----
277+
[... build]$ open playbook.yml
278+
----
279+
280+
. Generate a Bash remediation script from the scan results.
281+
.. Run the following command, using `--fix-type bash` to request a bash script with the fixes:
282+
+
283+
----
284+
[... build]$ oscap xccdf generate fix --fix-type bash --result-id "" /tmp/arf.xml > bash-fix.sh
285+
----
286+
287+
. Check the output :
288+
+
289+
----
290+
[... build]$ open bash-fix.sh
291+
----
292+
293+
The Ansible Playbook can be used to configure a system to meet a compliant state. Using Ansible Playbooks is discussed in `Lab Exercise 4`.
294+
The Bash remediation script also can be used to change the configuration of the system.
295+
It is recommended that you review the contents of these scripts and test them in a testing environment first, as they have the potential to make unexpected or harmful changes.
296+
297+
<<top>>
298+
299+
link:README.adoc#table-of-contents[ Table of Contents ] | link:lab3_profiles.adoc[Lab exercise 3 - Create Your Own Security Policy From Scratch]

‎docs/workshop/lab3_profiles.adoc

+4
Original file line numberDiff line numberDiff line change
@@ -906,3 +906,7 @@ Finally, we execute the profile stability test from before -- as we have aimed t
906906
----
907907

908908
And indeed, the test passes, which proves that the control-based way of defining profiles is compatible with the literal profile definition in a profile file.
909+
910+
<<top>>
911+
912+
link:README.adoc#table-of-contents[ Table of Contents ] | link:lab4_ansible.adoc[Lab Exercise 4: Using Ansible in ComplianceAsCode]

‎docs/workshop/lab4_ansible.adoc

+4
Original file line numberDiff line numberDiff line change
@@ -419,3 +419,7 @@ rhel8-playbook-anssi_bp28_intermediary.yml rhel8-playbook-cis_workstation_l2.ym
419419
+
420420
At this point, you have per-rule Ansible Playbooks available, as well as per-profile ones.
421421
You can integrate these into your CI/CD pipelines and infrastructure management as needed.
422+
423+
<<top>>
424+
425+
link:README.adoc#table-of-contents[ Table of Contents ] | link:lab5_oval.adoc[Lab Exercise 5: The Art of OVAL Checks]

‎docs/workshop/lab5_oval.adoc

+4
Original file line numberDiff line numberDiff line change
@@ -824,3 +824,7 @@ INFO - Script supercompliant.pass.sh using profile xccdf_org.ssgproject.content_
824824
Everything passes, which means that your check can now handle a range of compliant values and it does not produce false positives when the `export` keyword is involved.
825825

826826
Congratulations--now you know how to use the `ComplianceAsCode` project to make OVAL creation less error-prone and how to make sure that OVAL checks are working according to expectations.
827+
828+
<<top>>
829+
830+
link:README.adoc#table-of-contents[ Table of Contents ] | link:next_steps_with_complianceascode.adoc[Next Steps with ComplianceAsCode]

‎docs/workshop/labs_setup.yml

+7-1
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,13 @@
9999
command: "./build_product rhel8"
100100
args:
101101
chdir: "{{ LAB_DIR }}"
102-
when: EXERCISE == TRACK_1_LABEL or EXERCISE == TRACK_2_LABEL or EXERCISE == TRACK_5_LABEL
102+
when: EXERCISE == TRACK_1_LABEL or EXERCISE == TRACK_5_LABEL
103+
104+
- name: "Build the ubuntu2004 content to be used in exercise 2"
105+
command: "./build_product ubuntu2004"
106+
args:
107+
chdir: "{{ LAB_DIR }}"
108+
when: EXERCISE == TRACK_2_LABEL
103109

104110
# - name: "Copy our Fedora OSPP profile to the target system"
105111
# copy:

‎docs/workshop/next_steps_with_complianceascode.adoc

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
= Next Steps
2+
3+
So you have finished all the lab exercises and now what:
4+
5+
Below you can find several links that will guide you to become more expert in ComplianceAsCode project
6+
7+
== Useful resources
8+
9+
* link:https://complianceascode.readthedocs.io/en/latest/[ComplianceAsCode Developer Guide^]
10+
* link:https://complianceascode.github.io/[ComplianceAsCode Blog^]
11+
* link:https://github.com/ComplianceAsCode/content/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22[Good first issues if you would like to contribute right away^]
12+
* link:https://content-navigator.net/[Useful VSCode extension for ComplianceAsCode project developed in-house^]

0 commit comments

Comments
 (0)