Skip to content

Latest commit

 

History

History
339 lines (247 loc) · 17.7 KB

lab1_introduction.adoc

File metadata and controls

339 lines (247 loc) · 17.7 KB
Raw

Lab Exercise 1: Say Hello to ComplianceAsCode

Table of Contents

Introduction

In this lab, you will become familiar with the ComplianceAsCode project. The purpose of this project is to help content authors create security policy content for various platforms. The ComplianceAsCode project enables content authors to efficiently develop and share security content.

Using the powerful build system, you can generate output in various formats such as Ansible® Playbooks or SCAP data streams that you can use to automate security auditing and hardening. The project contains many useful rules and checks that form various security policies and enables content authors to easily add new rules and checks.

You work with the project source repository at https://github.com/ComplianceAsCode/content.

In Red Hat® Enterprise Linux® (RHEL), the SCAP content generated from ComplianceAsCode data is shipped as the scap-security-guide RPM package.

Goals

  • Learn about the ComplianceAsCode project to understand what is where and what you can use the project for.

  • Learn how to build the content from the source and go through what gets built.

  • Understand how to find the source of a particular part of the built artifact.

  • Learn how to parameterize rules that use variables.

  • Learn where to find additional rule content, such as checks and remediations.

Preconfigured Lab Environment

  • The ComplianceAsCode repository was already cloned.

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

    • Generic build utilities: cmake and make

    • Utilities for generating SCAP content: openscap-scanner

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

Hands-on Lab

The ComplianceAsCode project consists of human-readable files that are compiled into standard-compliant files that are difficult to read and edit directly.

For your convenience, the environment is already set up, so the content is built and ready to be used. No worries, though—​you get to rebuild it later in the exercise.

To start the hands-on section, take the following steps:

  1. Go to: Lab 1 Environment

  2. Wait until all the steps being executed in the terminal are complete.

Viewing the HTML Guides for the ComplianceAsCode Project

The ComplianceAsCode project provides HTML guides that are a great resource for those interested in the rules that make up a policy. HTML guides are located in the respective build/guides of each lab exercise subdirectory.

In the ComplianceAsCode project, policies are referred to as security profiles. The HTML guide filenames have a ssg-<product>-guide-<profile>.html format, so the HTML guide for the RHEL 8 Protection Profile for General Purpose Operating Systems (OSPP profile) is ssg-rhel8-guide-ospp.html.

  1. On the lab environment, you navigate to the build/guides folder.

  2. Right click the ssg-rhel8-guide-ospp.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.

    navigateospp
    Figure 1. OSPP Profile Guide

  3. Viewing the HTML report in your browser.

    1. Rules are organized in a system of hierarchical groups. Take a look through this HTML guide to see the various rules of the RHEL 8 OSPP profile.

      html guide
      Figure 2. HTML guide showing all of the rules of the RHEL 8 Protection Profile for General Purpose Operating Systems (OSPP) profile

Updating a Rule Description to Find the Source of a Specific Rule

You will now take a closer look at a specific rule in the HTML guide of the RHEL 8 OSPP profile. For example, take a closer look at the Set Interactive Session Timeout rule entry.

  1. In the HTML guide of the RHEL 8 OSPP profile that you opened in Firefox, press Ctrl+F and search for session timeout.

    session timeout
    Figure 3. The Set Interactive Session Timeout rule in the RHEL 8 OSPP profile HTML guide

  2. Review the description just below the Set Interactive Session Timeout rule:

    Setting the TMOUT option in /etc/profile ensures that Setting the TMOUT option in /etc/profile ensures that all user sessions will terminate based on inactivity. The TMOUT setting in /etc/profile should read as follows:

TMOUT=600

    Note that the leading text is incorrectly repeated twice in this rule: Setting the TMOUT option in /etc/profile ensures that. This was done on purpose for you to fix, so you can understand how rule definitions are created and updated.

  3. Locate this duplicated rule-definition text.

    Rule definitions for Linux systems are under the linux_os/guide directory of the ComplianceAsCode project. Because there are about 1,000 rules, it is better to search all of the rules for the text, rather than trying to find a particular rule in the directory hierarchy by browsing it.

    Rule definitions are written as YAML files, which are particularly suited for storing key-value data. All rules are defined by the respective rule.yml file, and the parent directory is the respective rule’s ID. The ID of the rule in question is accounts_tmout. Given that, you can search for the directory.

  4. Press Ctrl+P and a pop up window will appear type accounts_tmout/rule.yml and the first file you will see is the one we are looking for.

  5. Open the file so you can remove the duplicate text that you saw earlier: Setting the TMOUT option in /etc/profile ensures that:

  6. Luckily, the rule’s description is right at the beginning of the rule.yml file. Remove the duplicate occurrence of Setting the <tt>TMOUT</tt> option in <tt>/etc/profile</tt> ensures that.

  7. Press Ctrl+S to save the file.

  8. Recompile the content to check whether your fix worked.

    The ComplianceAsCode/content project uses the CMake build system. The build itself is based on Python, the oscap tool, and XSLT transformations.

    1. Go to the terminal at the bottom of the environment

    2. Run ./build_product rhel8 to compile content for Red Hat® Enterprise Linux® 8:

      It is also possible to build content for other products. A product can be an operating system, such as RHEL 8, RHEL 7, or Fedora, or an application, such as Firefox or Java™.

      In general, you can run ./build_product <product> to build only the content for a product you are interested in. The <product> is the lowercase form of the product, so you run ./build_product rhel8 to build content for RHEL 8, ./build_product fedora to build content for Fedora, and so on.

      0 02 post build
      Figure 4. Completed build of security content for RHEL 8 in the Terminal window

  9. Refresh the tab with the guide ssg-rhel8-guide-ospp.html or right click the file in build/guides and select Open with Live Server.

  10. Review the fix. Expect to now see the fixed description, without the duplicate Setting the TMOUT option in /etc/profile ensures that text, if you scroll down to the Set Interactive Session Timeout rule.

Customizing a Parameterized Rule

In this lab exercise, you will learn about parameterized rules. Parameterization can be used to set timeout durations, password length, umask, and other settings. You will learn about parameterized rules by:

  • Observing where the value comes from

  • Changing the parameterized rule to see how it is applied

  • Observing what happens when the parameterized variable is omitted

  1. Customizing parameterized rule s.a. this accounts_tmout is very easy, as the rule does not have the timeout duration hard-coded—​it is parameterized by a variable. As the description for the Set Interactive Session Timeout rule indicates, the rule uses the var_accounts_tmout variable. This is defined in the var_accounts_tmout.var file. Just as you did in the previous step, you can search for the variable definition:

    1. Press Ctrl+P and search for var_accounts_tmout.

      Though the var_accounts_tmout.var file contains the variable description—​which is helpful—​you cannot be sure what the number 600 means. However, the contents of the file indicate that it is the same as 10 minutes, which is 600 seconds.

  2. The rule is parameterized per profile. This is because there can be multiple profiles in one data stream file, one rule can exist in multiple profiles, and it can be parameterized differently in different profiles.

    To see how the rule is connected to its variable, you have to review the respective profile definition, press Ctrl+P and open products/rhel8/profiles/ospp.profile. Then search for accounts_tmout with:

    1. In the editor, press Ctrl+F to search for accounts_tmout.

    2. Then press Enter to jump to the next occurrence.

          ...
    ### FMT_MOF_EXT.1 / AC-11(a)
    ### Set Screen Lock Timeout Period to 10 Minutes or Less
    - accounts_tmout
    - var_accounts_tmout=10_min
    ...

  3. Modify the var_accounts_tmout variable to 30_min.

    1. Press Ctrl+S to save the file.

    2. Rebuild the content from the terminal:

      1. ./build_product rhel8

        After the build finishes, refresh the tab with the guide ssg-rhel8-guide-ospp.html or right click the file in build/guides and select Open with Live Server. Expect the variable value to be updated to 1800.

  4. What happens if you omit the variable definition?

    1. Open the OSPP profile file in an editor.

    2. Again, press Ctrl+F to search for accounts_tmout.

    3. Comment out the line containing - var_accounts_tmout=30_min by inserting # just before the leading dash.

    4. After you are done, press Ctrl+S to save the file.

    5. Rebuild the content again:

      1. ./build_product rhel8

    6. After the build finishes, re-examine the variable definition—​maybe you can predict the result without looking! Open the variable definition in the editor and execute the following command:

      1. Again, press Ctrl+P and search for var_accounts_tmout. Open the variable file.

        In this YAML file, you have the options: key that defines mappings between the supplied and effective values. As the default: 600 line indicates, if you do not specify the timeout duration in a profile, it is going to be 600 seconds (10 minutes).

    7. Time to review the HTML guide - refresh the tab with the guide ssg-rhel8-guide-ospp.html or right click the file in build/guides and select Open with Live Server. The rule’s timeout indeed equals to 600.

Note
 The set of values a variable can have is discrete—​all values have to be defined in the variable file. Therefore, it is possible to specify var_accounts_tmout=20_min in the profile only after adding 20_min: 1200 to the options: key of the variable definition.

Associated Content

A rule needs more than a description to be of any use. Other functions are:

  • check whether the system complies with the rule definition, and

  • bring a noncompliant system into a compliant state.

For these reasons, a rule should contain a check and possibly also remediations. The additional content is placed in subdirectories of the rule, so explore your accounts_tmout rule.

You can browse the associated content if you list the contents of the directory. In the terminal, run the following commands:

  1. Press Ctrl+P and a pop up window will appear, type accounts_tmout/rule.yml and the first file you will see is the one we are looking for.

    accounts tmout folder
    Figure 5. accounts_tmout folder

The following sections describe the currently supported associated content types.

Macros

You have probably noticed strange snippets in the project’s code s.a. {{{ xccdf_value("var_accounts_tmout") }}} in the accounts_tmout rule yaml. Those are jinja2 macros with one minor syntax difference — there is an additional layer of curly brackets to regular jinja2 macros. That way, Ansible content that uses regular jinja2 doesn’t interfere with the build system.

Macros allow content authors to avoid writing complex directives s.a. variable substitution in rules or remediations, and they can also prevent copy-pasting of the code anywhere in the content. Rules, remediations, checks and other definition files are processed by jinja2, so one can define own local macros there, or one can used shared macros that are available. Macros are defined in various .jinja files, and they are documented online on the ComplianceAsCode readthedocs website.

Usage of macros in the content is shown in subsequent chapters.

Checks

Checks can be found under the oval directory. They are written in an standardized, declarative, XML-based language called OVAL (Open Vulnerability and Assessment Language). Writing checks in this language is considered cumbersome, but the ComplianceAsCode project helps content authors to write it more efficiently.

You do not get into the details of OVAL now—​just note that the OVAL content can be found in a rule’s oval subdirectory. The OVAL checks are described in Lab Exercise 5. If you are familiar with the language, you can take this opportunity to examine the oval subdirectory of the accounts_tmout rule’s directory containing the shared.xml file. The shared.xml file features a shorthand OVAL, which is much simpler than the full version of OVAL that you otherwise have to write.

Remediations

If the system is not set up according to the rule description, the scanner reports that the rule has failed, and the system administrator is supposed to fix it. The ComplianceAsCode content provides users with snippets that they can run to make the system compliant again or at least to provide administrators with hints about what they need to do.

Remediations are expected to work on the clean installation configuration—​if the administrator has made some changes in the meantime, remediations are not guaranteed to work.

The majority of rules present in profiles come with a Bash remediation, and a large number of them have Ansible remediation. Anaconda remediations are used to guide the user during system installation. Remediations in the form of a Puppet script are also supported.

Remediations can be found under bash, ansible, anaconda, and puppet directories and others.

For example, in the accounts_tmout rule there is a remediation in the form of a Bash script located in the bash subdirectory of the rule’s directory. See the contents of the bash directory—​there is a shared.sh file in it. The shared basename has a special meaning—​it indicates that the remediation can be used with any product. If the remediation is named rhel8.sh, it means that it is a RHEL8-only remediation and cannot be used to remediate other RHEL systems such as RHEL9 systems. This naming convention is relevant for all types of additional content.

Unlike checks, you can review remediations in the guide—​there is a clickable Remediation Shell Script link to do so. Bring back the browser window with the guide open, and see for yourself.

0 03 remediation
Figure 6. Bash remediation snippet in the HTML guide

  1. Now you improve the remediation script by adding a comment stating that the numerical value is "number of seconds." Edit the remediation file:

    1. Press Ctrl+P and search for accounts-session/accounts_tmout/bash/shared.sh.

      You can see that there are some extra lines, but the script corresponds to the content displayed in the HTML guide.

  2. The {{{ bash_instantiate_variables("var_accounts_tmout") }}} line is the one that gets transformed into the variable assignment statement. Put the explanatory comment just above it:

    # platform = multi_platform_all

# The timeout delay is defined by number of seconds
{{{ bash_instantiate_variables("var_accounts_tmout") }}}

# if 0, no occurrence of tmout found, if 1, occurrence found
tmout_found=0

for f in /etc/profile /etc/profile.d/*.sh; do
    if grep --silent '^\s*TMOUT' $f; then
        sed -i -E "s/^(\s*)TMOUT\s*=\s*(\w|\$)*(.*)$/declare -xr TMOUT=$var_accounts_tmout\3/g" $f
        tmout_found=1
    fi
done

if [ $tmout_found -eq 0 ]; then
        echo -e "\n# Set TMOUT to $var_accounts_tmout per security requirements" >> /etc/profile.d/tmout.sh
        echo "declare -xr TMOUT=$var_accounts_tmout" >> /etc/profile.d/tmout.sh
fi

  3. After you are done, press Ctrl+S to save the file.

  4. Rebuild the content from the terminal:

    1. ./build_product rhel8

  5. Once the build is done, refresh the tab with the guide ssg-rhel8-guide-ospp.html or right click the file in build/guides and select Open with Live Server. Expect the remediation to contain the newly added comment.

Congratulations, by completing the lab exercise, you became familiar with a comprehensive content creation tool and one of the largest open source compliance content repositories available.