Skip to content

Latest commit

 

History

History
614 lines (483 loc) · 25.2 KB

lab3_profiles.adoc

File metadata and controls

614 lines (483 loc) · 25.2 KB

Lab Exercise 3: Create Your Own Security Policy From Scratch

Table of Contents

3.1 Introduction

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.

Goals

  • 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

Preconfigured Lab Environment

  • The ComplianceAsCode repository was cloned to the lab3_profiles directory.

  • The following dependencies required for the ComplianceAsCode content build were installed using yum install:

    • Generic build utilities: cmake and make

    • Utilities for generating SCAP content: openscap-scanner

    • The Python dependencies for putting content together: python3-pyyaml and python3-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.

3.2 Creating a New Empty Profile

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.

3.2.1 Navigating the Profiles Directory

  1. 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 .profile files in the profiles directory. You can get some inspiration from them.

3.2.2 Creating the New Profile

  1. Create a new travel.profile file in the profiles directory and open it in the editor:

    [... profiles]$ nano travel.profile

  2. 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

  3. When you are finished editing, press Ctrl+X, then enter y to save and exit.

  4. Go back to the project’s root directory.

    [... profiles]$ cd /home/lab-user/labs/lab3_profiles
    Note

    profile is 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:

    1. documentation_complete: true means that your profile is not in a draft state, so the build system picks it up.

    2. title is a short profile title.

    3. description consists of a few paragraphs that describe the purpose of the profile.

    4. selections is a list of rules and variables that make up the profile. It cannot be an empty list, so for now you add the sshd_enable_strictmodes rule. You learn how to find and add other rules later in this lab exercise.

3.2.3 Rebuilding and Reviewing the Content

  1. 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.

  2. Check the resulting HTML guide to see your new profile.

    1. This is the same thing you did in the first lab—​click Activities and then the "file cabinet" icon to open the file browser:

      100

    2. Just to make sure, click the Home icon in the upper left portion of the file explorer window.

    3. Navigate to the location of the exercise by double-clicking labs, followed by double-clicking the lab3_profiles, build, and guides folders.

      700

    4. Finally, double-click the ssg-rhel8-guide-travel.html file. A Firefox window opens and you can see the guide for your "Travel" profile, which contains just the single sshd_enable_strictmodes rule:

      HTML Guide
      Figure 1. The header of the HTML Guide generated by OpenSCAP during the build

3.3 Adding Rules to the Profile

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.

3.3.1 Finding the Relevant Rule

Rules are represented by directories in ComplianceAsCode. Each rule directory contains a file called rule.yml, which contains a rule description and metadata.

  1. In this case, you are looking to see if you have a rule.yml file in your repository that contains “SSH root login.” You can use git grep for 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'

  2. If you want, you can verify that this is the right rule by opening the rule.yml file 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 ... ]

  3. 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.yml file is located. In this case, the rule ID is sshd_disable_root_login.

3.3.2 Including the Rule in the New Profile

  1. Add the rule ID to the selections list in your "Travel" profile.

    [... lab3_profiles]$ nano rhel8/profiles/travel.profile

  2. Add sshd_disable_root_login as a new item in selections list. The selections list is a list of rules that the profile consists of.

    Please make sure that you use spaces for indentation.

  3. After you are finished editing, press Ctrl+X, then enter y to save and exit.

    Expect your travel.profile file 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

3.3.3 Verifying the Result

  1. To review the result, you need to rebuild the content:

    [... lab3_profiles]$ ./build_product rhel8

    The sshd_disable_root_login rule is included in your profile by the build system.

  2. Check the resulting HTML guide.

    1. Switch to the graphical console in the web browser on your laptop.

    2. Click Activities, and then the "file cabinet" icon to bring up the file browser. Expect to be in the labs/lab3_profiles/build/guides directory 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.

    3. Double-click the ssg-rhel8-guide-travel.html file. A Firefox window opens and you can see your "Travel" profile, which contains two rules.

3.4 Adding Customizable Rules to the Profile and Customizing Them

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.

3.4.1 Adding Another Rule to the List

This is similar to the previous section.

  1. 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 is accounts_tmout because the rule ID is the name of the directory where the rule is located.

  2. Add the rule ID to the selections list in your "Travel" profile.

    [... lab3_profiles]$ nano rhel8/profiles/travel.profile

  3. Add accounts_tmout as 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.

  4. 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.

  5. After you are finished looking, press Ctrl+X to bring up the "save and exit" option. If you are asked about saving any changes, you probably do not want that, so enter n.

    From the rule contents you can clearly see that it is parametrized by the var_accounts_tmout variable. Note that the var_accounts_tmout variable is used in the description instead of an exact value. In the HTML guide, you later see that var_accounts_tmout has been assigned a value. The value is also automatically substituted into OVAL checks, Ansible® Playbooks, and the remediation scripts.

3.4.2 Examining the Parametrization

  1. 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

  2. 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: 600

    options: is defined as a YAML dictionary that maps keys to values. In ComplianceAsCode, 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 the options dictionary if none of the values suits your needs. Later, you add a new pair—​variable name and selector—​into the profile and you use the 5_min selector to choose 300 seconds.

  3. After you are finished looking, press Ctrl+X to bring up the "save and exit" option. If you are asked about saving any changes, you probably do not want that, so enter n.

3.4.3 Completing the Parametrization

  1. To finalize the rule’s parametrization, the variable and the selector have to be added to the selections list in your travel profile.

    [... lab3_profiles]$ nano rhel8/profiles/travel.profile

    As with the rule IDs, the variable values also belong to the selections list in the profile. However, the entry for a variable has the format variable=selector. So in this case, the format of the list entry is var_accounts_tmout=5_min.

  2. Make sure your travel.profile file 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_min

    Please make sure that you use spaces for indentation.

  3. After you are finished editing, press Ctrl+X, then enter y to save and exit.

3.4.4 Reviewing the Result

  1. To review the result, rebuild the content again:

    [... lab3_profiles]$ ./build_product rhel8

    The accounts_tmout rule gets included into your profile by the build system.

  2. Check the resulting HTML guide.

    1. 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.

    2. The Travel profile now contains three rules. Scroll down to the Account Inactivity Timeout rule and note that 300 seconds is substituted there.

3.5 Scanning the System Against the New Profile

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.

  1. Run an OpenSCAP scan using the built content.

    oscap is the command line tool that you use to scan the machine. You need to give oscap the 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.

    1. Use sudo to 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

  2. Check the scan results.

    In your terminal you see all three rules, and all of them were evaluated:

    Terminal
    Figure 2. The oscap output from evaluating the "Travel" profile

  3. Review the details in the HTML report. The report is located in the /home/lab-user/labs/lab3_profiles directory, so you can locate it using the file explorer as you did in the previous exercises:

    1. Open the file explorer by clicking Activities, and then the "file cabinet" icon.

    2. Once it opens, click Home at the top left corner of the browser’s window.

    3. Then, double-click the labs and lab3_profiles folders.

    4. Double-click the report.html file to open it in the browser.

      The structure of the HTML report is similar to the HTML guide, but it contains the evaluation results.

    5. 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.

    6. 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 no TMOUT entry in /etc/profile. To fix this problem, you need to insert TMOUT=300 into /etc/profile and then run the scan again.

      Report
      Figure 3. Details of the rule evaluation displayed in the HTML report

3.6 Creating a New Rule from Scratch

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.

3.6.1 Creating the rule definition file

You will now create the rule.yml file for your new rule.

  1. Find a group directory that best fits your new rule.

    The rules are located in the linux_os directory. Rules in the ComplianceAsCode project 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:

    1. You are in the linux_os/guide directory, which has intro, system, and services directories.

    2. You definitely do not want to configure a service setting, so explore system.

    3. There are more subdirectories under system, and as you want a new software package installed, it makes sense to explore the software directory.

    4. Here, you create the directory for your rule.

  2. Create a new rule directory in a group directory.

    The name of the directory is the rule ID. In this case, package_hexchat_installed is a suitable ID. You create the directory using mkdir and use the -p switch 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

  3. Create rule.yml in the rule directory.

    A description of the rule is stored. Each rule needs to have it. rule.yml is a simple YAML file.

    [... lab3_profiles]$ nano linux_os/guide/system/software/package_hexchat_installed/rule.yml

  4. Add the following content to the rule.yml file:

    Tip
    		 You can select the text in the laptop’s browser, copy it to the clipboard using Ctrl+C, and paste it to the nano editor using Ctrl+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

  5. When you have finished editing, press Ctrl+X, then enter y to save and exit.

    Note

    1. documentation_complete: true again indicates that the rule is picked up by the build system whenever it is applicable.

    2. title is the rule title, which is displayed on the command line and in SCAP Workbench.

    3. description is a section that describes the check.

    4. rationale needs to contain a justification for why the rule exists.

    5. severity can be either low, medium, or high.

  6. Add the rule ID to the profile selections.

    1. 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

    2. When adding the package_hexchat_installed item, 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

    3. When you have finished editing, press Ctrl+X, then enter y to save and exit.

3.6.2 Use templates to generate checks automatically

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.

  1. Open the list of templates in your web browser.

  2. 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_installed template. 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

  3. Open the rule.yml file for the package_hexchat_installed rule .

    [... lab3_profiles]$ nano linux_os/guide/system/software/package_hexchat_installed/rule.yml

  4. 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: hexchat

    Notice that you used one of the two possible parameters; pkgname.

  5. When you have finished editing, press Ctrl+X, then enter y to save and exit.

  6. Build the content.

    [... lab3_profiles]$ ./build_product rhel8

  7. 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.html file in the /home/lab-user/lab3_profiles/build/guides directory as you already did earlier in this exercise.

    500
    Figure 4. The Firefox Refresh Page button

    Either way, you see your "Travel" profile with four rules, including the newly added rule.

    New 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.