Imagine that your company has approved an internal security policy that enforces certain configurations for laptops being used outside the company site.
Your task is to implement an automated way of checking the laptop configuration.
In this lab exercise, you learn how to solve the task using ComplianceAsCode.
-
Learn how to represent your company security policy as a security profile in
ComplianceAsCode -
Learn how to operate with basic building blocks (rules) of
ComplianceAsCode -
Learn how to choose between hundreds of existing rules and add them into a profile
-
Learn how to customize the rules for your needs by using variables
-
Learn how to create a new rule
-
Learn how to scan your system against the profile you created
-
The
ComplianceAsCoderepository was cloned to thelab3_profilesdirectory. -
The following dependencies required for the
ComplianceAsCodecontent build were installed usingyum install:-
Generic build utilities:
cmakeandmake -
Utilities for generating SCAP content:
openscap-scanner -
The Python dependencies for putting content together:
python3-pyyamlandpython3-jinja2
-
|
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® products. |
The basic building block of a security policy in ComplianceAsCode is a rule.
The rule represents a single configuration setting—for example,
"Password length is at least 8 characters" or "Logging is enabled."
A set of rules is called a profile.
A profile represents a specific security policy.
In ComplianceAsCode, there are multiple profiles.
There are profiles for different products.
The term "product" means operating systems or applications—for example,
Red Hat® Enterprise Linux® 8 or Red Hat OpenShift® Container Platform 3.
The products are represented by directories in the root of the ComplianceAsCode repository—for example,
rhel7, rhel8, or ocp3 directories.
Each product has a different set of profiles because some security policies are relevant only for certain operating systems or applications.
The profiles are located in the profiles directory in the product directory.
The profiles are represented by a simple YAML (YAML Ain’t Markup Language) file, such as
ospp.profile, which defines a profile.
In this lab, you create a new “Travel” profile for Red Hat® Enterprise Linux® 8. The profile represents your company’s new security policy for laptops.
-
Go to the profiles directory for Red Hat® Enterprise Linux® 8:
[... ~]$ cd /home/lab-user/labs/lab3_profiles [... lab3_profiles]$ cd rhel8/profiles [... profiles]$ ls cjis.profile cui.profile hipaa.profile ospp.profile pci-dss.profile rht-ccp.profile standard.profile
As you can see, there are already some
.profilefiles in theprofilesdirectory. You can get some inspiration from them.
-
Create a new
travel.profilefile in theprofilesdirectory and open it in the editor:[... profiles]$ nano travel.profile
-
Next, create the basic structure and fill in the profile title and description as specified in this listing. You can copy and paste the following text to the editor—just keep in mind that when pasting to the console, you have to use
Ctrl+Shift+V.documentation_complete: true title: Travel profile for corporate laptops description: This profile represents settings that are required by company security policy for employee laptops. selections: - sshd_enable_strictmodes -
When you are finished editing, press
Ctrl+X, then enteryto save and exit. -
Go back to the project’s root directory.
[... profiles]$ cd /home/lab-user/labs/lab3_profiles
Noteprofileis a file in YAML format. Expect it to be fine if you copy and paste the content from the previous listing. When creating a new YAML file from scratch, the most common mistake tends to be incorrect indentation. Make sure you use spaces, not tabs. Also check that there is no trailing whitespace.The profile consists of four items that are required:
-
documentation_complete: truemeans that your profile is not in a draft state, so the build system picks it up. -
titleis a short profile title. -
descriptionconsists of a few paragraphs that describe the purpose of the profile. -
selectionsis a list of rules and variables that make up the profile. It cannot be an empty list, so for now you add thesshd_enable_strictmodesrule. You learn how to find and add other rules later in this lab exercise.
-
-
Rebuild the content:
[... lab3_profiles]$ ./build_product rhel8 ...
This command rebuilds content for all of the product profiles in Red Hat® Enterprise Linux® 8, including your new “Travel” profile. The command builds the human-readable HTML guide that can be displayed in a web browser and the machine-readable SCAP files that can be consumed by OpenSCAP.
-
Check the resulting HTML guide to see your new profile.
-
This is the same thing you did in the first lab—click
Activitiesand then the "file cabinet" icon to open the file browser:
-
Just to make sure, click the
Homeicon in the upper left portion of the file explorer window. -
Navigate to the location of the exercise by double-clicking
labs, followed by double-clicking thelab3_profiles,build, andguidesfolders.
-
Finally, double-click the
ssg-rhel8-guide-travel.htmlfile. A Firefox window opens and you can see the guide for your "Travel" profile, which contains just the singlesshd_enable_strictmodesrule:
Figure 1. The header of the HTML Guide generated by OpenSCAP during the build
-
Next, imagine that one of the requirements of your company policy is that the root user cannot log in to the machine via SSH.
ComplianceAsCode already contains a rule implementing this requirement.
You only need to add this rule to your “Travel” profile.
Rules are represented by directories in ComplianceAsCode.
Each rule directory contains a file called rule.yml, which contains a rule description and metadata.
-
In this case, you are looking to see if you have a
rule.ymlfile in your repository that contains “SSH root login.” You can usegit grepfor this:[... lab3_profiles]$ git grep -i "SSH root login" "*rule.yml" linux_os/guide/services/ssh/ssh_server/sshd_disable_root_login/rule.yml:title: 'Disable SSH Root Login'
-
If you want, you can verify that this is the right rule by opening the
rule.ymlfile and reading the description section.[... lab3_profiles]$ nano linux_os/guide/services/ssh/ssh_server/sshd_disable_root_login/rule.yml
It looks like this:
documentation_complete: true title: 'Disable SSH Root Login' description: |- The root user should never be allowed to login to a system directly over a network. To disable root login via SSH, add or correct the following line [ ... snip ... ] -
In order to add the rule to your new "Travel" profile, you need to determine the ID of the rule you found. The rule ID is the name of the directory where the
rule.ymlfile is located. In this case, the rule ID issshd_disable_root_login.
-
Add the rule ID to the selections list in your "Travel" profile.
[... lab3_profiles]$ nano rhel8/profiles/travel.profile
-
Add
sshd_disable_root_loginas a new item inselectionslist. Theselectionslist is a list of rules that the profile consists of.Please make sure that you use spaces for indentation.
-
After you are finished editing, press
Ctrl+X, then enteryto save and exit.Expect your
travel.profilefile to look like this:documentation_complete: true title: Travel profile for corporate laptops description: This profile represents settings which are required by company security policy for employee laptops. selections: - sshd_enable_strictmodes - sshd_disable_root_login
-
To review the result, you need to rebuild the content:
[... lab3_profiles]$ ./build_product rhel8
The
sshd_disable_root_loginrule is included in your profile by the build system. -
Check the resulting HTML guide.
-
Switch to the graphical console in the web browser on your laptop.
-
Click
Activities, and then the "file cabinet" icon to bring up the file browser. Expect to be in thelabs/lab3_profiles/build/guidesdirectory from the previous step. If that is not the case, refer to the end of the 3.2.3 Rebuilding and Reviewing the Content section for the steps to get there. -
Double-click the
ssg-rhel8-guide-travel.htmlfile. A Firefox window opens and you can see your "Travel" profile, which contains two rules.
-
Imagine that one of the requirements set in your company policy is that the user sessions must timeout if the user is inactive for more than 5 minutes.
ComplianceAsCode already contains an implementation of this requirement in the form of a rule.
You now need to add this rule to your “Travel” profile.
However, the rule in ComplianceAsCode is generic—or, in other words, customizable.
It can check for an arbitrary period of user inactivity.
You need to set the specific value of 5 minutes in the profile.
This is similar to the previous section.
-
First, use command line tools to search for the correct rule file:
[... lab3_profiles]$ git grep -i "Interactive Session Timeout" "*rule.yml" linux_os/guide/system/accounts/accounts-session/accounts_tmout/rule.yml:title: 'Set Interactive Session Timeout'
As you already know from the first lab exercise, the rule is located in
linux_os/guide/system/accounts/accounts-session/accounts_tmout/rule.yml. It is easy to spot that the rule ID isaccounts_tmoutbecause the rule ID is the name of the directory where the rule is located. -
Add the rule ID to the selections list in your "Travel" profile.
[... lab3_profiles]$ nano rhel8/profiles/travel.profile
-
Add
accounts_tmoutas a new item in the selections list.Make sure your indentation is consistent and use spaces, not tabs. Also make sure there is no trailing whitespace.
-
Check the rule contents to find out whether there is a variable involved:
[... lab3_profiles]$ nano linux_os/guide/system/accounts/accounts-session/accounts_tmout/rule.yml
You do not need to make any changes.
-
After you are finished looking, press
Ctrl+Xto bring up the "save and exit" option. If you are asked about saving any changes, you probably do not want that, so entern.From the rule contents you can clearly see that it is parametrized by the
var_accounts_tmoutvariable. Note that thevar_accounts_tmoutvariable is used in the description instead of an exact value. In the HTML guide, you later see thatvar_accounts_tmouthas been assigned a value. The value is also automatically substituted into OVAL checks, Ansible® Playbooks, and the remediation scripts.
-
In order to learn more about the parametrization, find and review the variable definition file.
[... lab3_profiles]$ find . -name 'var_accounts_tmout*' linux_os/guide/system/accounts/accounts-session/var_accounts_tmout.var [... lab3_profiles]$ nano linux_os/guide/system/accounts/accounts-session/var_accounts_tmout.var
-
The variable has multiple options, which you can see in the options list:
options: 30_min: 1800 10_min: 600 15_min: 900 5_min: 300 default: 600options:is defined as a YAML dictionary that maps keys to values. InComplianceAsCode, the YAML dictionary keys are used as selectors and the YAML dictionary values are concrete values that are used in the checks. You use the selector to choose the value in the profile. You can add a new key and value to theoptionsdictionary if none of the values suits your needs. Later, you add a new pair—variable name and selector—into the profile and you use the5_minselector to choose 300 seconds. -
After you are finished looking, press
Ctrl+Xto bring up the "save and exit" option. If you are asked about saving any changes, you probably do not want that, so entern.
-
To finalize the rule’s parametrization, the variable and the selector have to be added to the selections list in your
travelprofile.[... lab3_profiles]$ nano rhel8/profiles/travel.profile
As with the rule IDs, the variable values also belong to the
selectionslist in the profile. However, the entry for a variable has the formatvariable=selector. So in this case, the format of the list entry isvar_accounts_tmout=5_min. -
Make sure your
travel.profilefile looks like the following listing:documentation_complete: true title: Travel profile for corporate laptops description: This profile represents settings which are required by company security policy for employee laptops. selections: - security_patches_up_to_date - sshd_disable_root_login - accounts_tmout - var_accounts_tmout=5_minPlease make sure that you use spaces for indentation.
-
After you are finished editing, press
Ctrl+X, then enteryto save and exit.
-
To review the result, rebuild the content again:
[... lab3_profiles]$ ./build_product rhel8
The
accounts_tmoutrule gets included into your profile by the build system. -
Check the resulting HTML guide.
-
The file browser already has the corresponding guide loaded, so you just need to refresh it to review the changes. Click the "Refresh" icon in the top left corner of the browser window.
-
The Travel profile now contains three rules. Scroll down to the Account Inactivity Timeout rule and note that
300 secondsis substituted there.
-
In this section, you use the new profile that you just created to scan your machine using OpenSCAP.
You have examined only the HTML guide so far, but for automated scanning, you use a datastream instead.
A datastream is an XML file that contains all of the data (rules, checks, remediations, and metadata) in a single file.
The datastream that contains your new profile was also built during the content build.
It is called ssg-rhel8-ds.xml and is located in the build directory.
-
Run an OpenSCAP scan using the built content.
oscapis the command line tool that you use to scan the machine. You need to giveoscapthe name of the profile (travel) and the path to the built datastream (ssg-rhel8-ds.xml) as arguments. You also add arguments to turn on full reporting, which generates XML and HTML results that you can review later.-
Use
sudoto run the command as the privileged user, to scan the parts of the system that common users are not able to access.[... lab3_profiles]$ sudo oscap xccdf eval --results results.xml --oval-results --report report.html --profile travel build/ssg-rhel8-ds.xml
-
-
Check the scan results.
In your terminal you see all three rules, and all of them were evaluated:
Figure 2. Theoscapoutput from evaluating the "Travel" profile -
Review the details in the HTML report. The report is located in the
/home/lab-user/labs/lab3_profilesdirectory, so you can locate it using the file explorer as you did in the previous exercises:-
Open the file explorer by clicking
Activities, and then the "file cabinet" icon. -
Once it opens, click
Homeat the top left corner of the browser’s window. -
Then, double-click the
labsandlab3_profilesfolders. -
Double-click the
report.htmlfile to open it in the browser.The structure of the HTML report is similar to the HTML guide, but it contains the evaluation results.
-
After clicking the rule title, you can see the detailed rule results.
In the detailed rule results for the Set Interactive Session Timeout rule, you can review the rule description to see which requirement was not met by the scanned system.
-
Review the OVAL details section to examine the reason why this rule failed. It states that items were missing, which means that objects described by the table shown below the message do not exist on the scanned system. In this specific example, there was no string to match the pattern in
/etc/profile, which means there is noTMOUTentry in/etc/profile. To fix this problem, you need to insertTMOUT=300into/etc/profileand then run the scan again.
Figure 3. Details of the rule evaluation displayed in the HTML report
-
Imagine that one of the requirements in your corporate policy is that users have to install the Hexchat application when their laptops are used during travel outside the company site because Hexchat is the preferred way to communicate with the company IT support center.
You want to add a check to your new profile that checks if Hexchat is installed.
ComplianceAsCode does not have a rule ready for installing this application yet.
That means you need to add a new rule for that.
You will now create the rule.yml file for your new rule.
-
Find a group directory that best fits your new rule.
The rules are located in the
linux_osdirectory. Rules in theComplianceAsCodeproject are organized into groups, which are represented by directories. It is up to you to decide which group the new rule belongs to. You can browse the directory tree to find a suitable group:-
You are in the
linux_os/guidedirectory, which hasintro,system, andservicesdirectories. -
You definitely do not want to configure a service setting, so explore
system. -
There are more subdirectories under
system, and as you want a new software package installed, it makes sense to explore thesoftwaredirectory. -
Here, you create the directory for your rule.
-
-
Create a new rule directory in a group directory.
The name of the directory is the rule ID. In this case,
package_hexchat_installedis a suitable ID. You create the directory usingmkdirand use the-pswitch to make sure that the directory is created along with its parents if needed.[... lab3_profiles]$ cd /home/lab-user/labs/lab3_profiles [... lab3_profiles]$ mkdir -p linux_os/guide/system/software/package_hexchat_installed
-
Create
rule.ymlin the rule directory.A description of the rule is stored. Each rule needs to have it.
rule.ymlis a simple YAML file.[... lab3_profiles]$ nano linux_os/guide/system/software/package_hexchat_installed/rule.yml
-
Add the following content to the
rule.ymlfile:TipYou can select the text in the laptop’s browser, copy it to the clipboard using Ctrl+C, and paste it to thenanoeditor usingCtrl+Shift+V.documentation_complete: true title: Install Hexchat Application description: As of company policy, the traveling laptops have to have the Hexchat application installed. rationale: The Hexchat application enables IRC communication with the corporate IT support centre. severity: medium
-
When you have finished editing, press
Ctrl+X, then enteryto save and exit.Note-
documentation_complete: trueagain indicates that the rule is picked up by the build system whenever it is applicable. -
titleis the rule title, which is displayed on the command line and in SCAP Workbench. -
descriptionis a section that describes the check. -
rationaleneeds to contain a justification for why the rule exists. -
severitycan be eitherlow,medium, orhigh.
-
-
Add the rule ID to the profile selections.
-
As described in the previous section, you need to add the ID of your new rule (
package_hexchat_installed) to the selections list in your profile (travel.profile). You do it by editing the travel profile file:[... lab3_profiles]$ nano rhel8/profiles/travel.profile
-
When adding the
package_hexchat_installeditem, please make sure that you use spaces, not tabs for indentation:documentation_complete: true title: Travel profile for corporate laptops description: This profile represents settings which are required by company security policy for employee laptops. selections: - sshd_enable_strictmodes - sshd_disable_root_login - accounts_tmout - var_accounts_tmout=5_min - package_hexchat_installed -
When you have finished editing, press
Ctrl+X, then enteryto save and exit.
-
You have successfully defined the rule and added it to the profile. However, the rule currently has no check nor remediation. That means OpenSCAP can’t check if the Hexchat package is installed. Writing OVAL checks is a process out of scope of this chapter and it is described in a separate lab. However, in some cases you can use the already created templates. You can try to search by keyword in list of templates to find out if some template suits your case. In this case it does.
Templates are a great way of simplifying development of new rules and avoiding unnecessarily large amount of duplicated code.
There are sets of rules which perform very similar checks and can be remediated in a similar way.
This applies for example to checks that a certain package is installed, that a certain Systemd service is disabled, etc.
Using templates is recommended whenever possible to avoid code duplication and possible inconsistencies.
Another benefit of templates is ease of creation of new rules.
As demonstrated below, you don’t have to know how to write OVAL checks or Bash remediations to create a fully working rule.
The template will create this for you automatically.
You only need to append a special block at the end of the particular rule.yml file.
-
Open the list of templates in your web browser.
-
You can quickly glance through the list of templates. Notice that every template is accompanied by a description and one or more parameters. Finally, search for the
package_installedtemplate. Notice that the template has two parameters:- pkgname
-
name of the RPM or DEB package, eg. tmux
- evr
-
Optional parameter. It can be used to check if the package is of a specific version or newer. Provide epoch, version, release in epoch:version-release format, eg. 0:2.17-55.0.4.el7_0.3. Used only in OVAL checks. The OVAL state uses operation "greater than or equal" to compare the collected package
-
Open the
rule.ymlfile for thepackage_hexchat_installedrule .[... lab3_profiles]$ nano linux_os/guide/system/software/package_hexchat_installed/rule.yml
-
Add the special block at the end of the file, so it looks like this:
documentation_complete: true title: Install Hexchat Application description: As of company policy, the traveling laptops have to have the Hexchat application installed. rationale: The Hexchat application enables IRC communication with the corporate IT support centre. severity: medium template: name: package_installed vars: pkgname: hexchatNotice that you used one of the two possible parameters;
pkgname. -
When you have finished editing, press
Ctrl+X, then enteryto save and exit. -
Build the content.
[... lab3_profiles]$ ./build_product rhel8
-
Check the resulting HTML guide. Expect to still have it as a tab in your browser, which you can refresh by clicking the refresh button in the browser window. Alternatively, you can locate the
ssg-rhel8-guide-travel.htmlfile in the/home/lab-user/lab3_profiles/build/guidesdirectory as you already did earlier in this exercise.
Figure 4. The Firefox Refresh Page buttonEither way, you see your "Travel" profile with four rules, including the newly added rule.
Figure 5. New "Install Hexchat Application" rule displayed in the HTML guide
For more details about the rule.yml format, please refer to contributor’s section of the developer guide.
For more information about the templating system, including the list of currently available templates, refer to the Templating section of the developer guide.