# Content Customization

## So, you wanna be a developer?

Welcome! Making changes to the project requires posting a patch to the mailing list, so that it can be vetted. Once there, another commit-level project member must issue an acknowledgement (“ACK”) to accept it, and then it can be pushed - assuming another project member has not issued a NACK in protest first. The following instructions assume familiarity with git and git-send-email, but project members are happy to provide tips if you encounter any roadblocks.

To properly join the project you must first establish a few required accounts:

- Join the mailing list, it's how developers and users communicate.
- Create your FedoraHosted account. It formally registers you as a developer, and allows you to upload your public SSH key (required for commits).
- Once your FedoraHosted account is created, request membership to the SCAP Security Guide project.
- Lastly, review a few coding standards: How to Create a New Guidance Item in XCCDF and How to Create a New Compliance Check in OVAL

## Cloning the Source

If you've been given commit-level access, you will interface with the git repository over SSH. Change directory to where you'd like the source code to be placed (e.g. cd ~/MyProjects/) and run the following command: NOTE: For this workshop, use /var/www/html/

    $ cd /var/www/html/
    $ git clone ssh://USERNAME@git.fedorahosted.org/git/scap-security-guide.git

    If you have not been given commit access, use the standard HTTP interface:
    $ git clone git://git.fedorahosted.org/git/scap-security-guide.git

## Understanding the Code Tree

You've now cloned the projects source code. A new directory, scap-security-guide, was created where you ran the clone command. Change directory into it and perform a directory listing:

    $ cd scap-security-guide; ls -l

    total 56
    drwxrwxr-x. 8 dave dave 4096 Mar  5 13:02 docs
    drwxrwxr-x. 6 dave dave 4096 Mar  5 12:10 Fedora
    drwxrwxr-x. 4 dave dave 4096 Mar  5 12:10 JBossEAP5
    drwxrwxr-x. 4 dave dave 4096 Mar  5 12:10 JBossFuse6
    -rw-rw-r--. 1 dave dave  409 Mar  5 12:10 LICENSE
    -rw-rw-r--. 1 dave dave 6991 Mar  5 12:10 Makefile
    drwxrwxr-x. 7 dave dave 4096 Mar  5 12:10 OpenStack
    -rw-rw-r--. 1 dave dave  840 Mar  5 12:10 README
    drwxrwxr-x. 4 dave dave 4096 Mar  5 12:10 RHEL
    drwxrwxr-x. 7 dave dave 4096 Mar  5 12:10 RHEVM3
    -rw-rw-r--. 1 dave dave 7167 Mar  5 12:10 scap-security-guide.spec
    drwxrwxr-x. 5 dave dave 4096 Mar  5 12:10 shared

Top level directories have been created to contain the per-technology SCAP content. Thanks to the ongoing development work toward content for RHEL7, there is now a RHEL directory, with sub-directories for 6 and 7. Change directory into RHEL/6 and perform a directory listing:

    cd RHEL/6/ ; ls -l
    total 32
    drwxrwxr-x. 9 dave dave 4096 Mar  6 06:31 input
    -rw-rw-r--. 1 dave dave 1211 Mar  5 12:10 LICENSE
    -rw-rw-r--. 1 dave dave 7917 Mar  5 12:10 Makefile
    drwxrwxr-x. 3 dave dave 4096 Mar  5 12:10 output
    -rw-rw-r--. 1 dave dave 1616 Mar  5 12:10 README
    drwxrwxr-x. 2 dave dave 4096 Mar  5 12:10 transforms
    drwxrwxr-x. 2 dave dave 4096 Mar  5 12:10 utils

The directory usages are:

SSG Code Tree: RHEL6/

Directory | Usage
--- | ---
input/ | Source files that generate SCAP content, such as XCCDF and OVAL. Since a single large XML file is an impractical format for multiple authors to collaborate on editing SCAP content, efforts are made to keep logically related guidance and checking content in individual files.
output/ | Used as a storage area for items generated by the files in the inputs directory. It should be empty in the repository, and built on users' individual systems (and rely on its .gitignore file to keep such files out). The output directory contains transitional output (which may only exist in order to be further transformed) as well as final output.
transforms/ | Resources that enable the files inside the input directory (or output directory) to be combined and reformatted into valid SCAP formats or human-readable formats.

## Creating your first XCCDF rule

For this workshop we will create a rule which mandates installation of the SCAP Security Guide RPM, and we'll identify failure (the lack of installation) as a CAT I / SEV 1 finding.

The directory structure, and multiple XML files, can be a bit overwhelming at first. Change directory to input/system/ and perform a directory listing:

    $ cd input/system/; ls -l

    total 116
    drwxrwxr-x. 3 shawn shawn  4096 Mar 20 19:06 accounts
    -rw-rw-r--. 1 shawn shawn 64882 Mar 20 19:29 auditing.xml
    -rw-rw-r--. 1 shawn shawn 20365 Mar 14 20:51 logging.xml
    drwxrwxr-x. 2 shawn shawn  4096 Mar 14 20:51 network
    drwxrwxr-x. 2 shawn shawn  4096 Mar 21 06:47 permissions
    -rw-rw-r--. 1 shawn shawn 10760 Mar 14 20:51 selinux.xml
    drwxrwxr-x. 2 shawn shawn  4096 Mar 23 18:06 software
    -rw-rw-r--. 1 shawn shawn    62 Mar 14 20:51 system.xml

To aid with multi-author content creation, the SSG project creates compartmented XCCDF files. These individual files are merged together during our Make/compilation process (more on that later!).

In the directory listing above you'll notice auditing.xml, logging.xml, and a few directories. Since we're creating a rule that deals with software, change directory into software/ and perform a directory listing:

    $ cd software/; ls -l
    total 36
    -rw-rw-r--. 1 shawn shawn  7307 Mar 14 20:51 disk_partitioning.xml
    -rw-rw-r--. 1 shawn shawn 12458 Mar 17 18:57 integrity.xml
    -rw-rw-r--. 1 shawn shawn   274 Mar 14 20:51 software.xml
    -rw-rw-r--. 1 shawn shawn  5635 Mar 14 20:51 updating.xml

As the SSG project relates to security, lets create the new rule within the integrity.xml section. Load that file in your favorite text editor, then place yourself one line above EOF:

    $ vim integrity.xml
    {shift+g}
    -

Your screen should be similar to the following:

Using the template above, create a rule which:

- Has an XCCDF rule id of “package_scap-security-guide_installed” with a severity of “high”
- Has a human readable title of 'Install SCAP Security Guide”
- Outlines a method to install SSG. For example, “yum install scap-security-guide”
- States that “if SCAP Security Guide is not installed” this is a finding
- Includes the proper package name, scap-security-guide, in the package check macro
- Includes rationale on why the SSG project is awesome, and should be installed
- Corresponds to a (currently non-existent) OVAL rule named “package_scap-security-guide_installed”

Your completed template will look similar to:

As mentioned earlier, the output/ directory contains artifacts from the build. Using a web browser, view http://studentX/scap-security-guide/output/rhel6-guide.html. You'll notice your XCCDF Rule Title is now listed in the table of contents. Click on the “Install SCAP Security Guide” link, and you'll be brought to the newly created rule. Once updated, re-run the build:

    $ make clean; make content; make validate

Upon completion, refresh your web browser to see the updated content. This looks much better. At this point we have a valid, functioning, XCCDF rule! Now, onto OVAL content creation...

## OVAL Authoring

OVAL standardizes the assessment and reporting of machine state. It's very comprehensive, with capabilities to examine boot-time and run-time configuration. MITRE has documented OVAL's built-in functions at http://oval.mitre.org/language/version5.10.1/ovaldefinition/documentation/linux-definitions-schema.html

The SSG project maintains all OVAL code under shared/oval/ and RHEL/6/input/checks/, and provides template utilities in RHEL/6/input/checks/templates/. Change directories to templates/ and perform a directory listing:

    $ cd /var/www/html/scap-security-guide/RHEL6/input/checks/templates/; ls
    create_kernel_modules_disabled.py  packages_removed.csv
    create_package_installed.py        README
    create_package_removed.py          services_disabled.csv
    create_permission_checks.py        services_enabled.csv
    create_services_disabled.py        sysctl_values.csv
    create_services_enabled.py         template_kernel_module_disabled
    create_sysctl_checks.py            template_package_installed
    file_dir_permissions.csv           template_package_removed
    find_untemplated.py                template_permissions
    kernel_modules_disabled.csv        template_service_disabled
    Makefile                           template_service_enabled
    output                             template_sysctl
    packages_installed.csv

Before continuing to the next page, take a minute to review the README file. What is the process to create a template for checking if scap-security-guide is installed? As noted in the README file, several CSV files are located within the templates/ directory. To automate the OVAL content:

1. Add scap-security-guide to the listing in packages_installed.csv:

    $ echo “scap-security-guide” >> packages_installed.csv

2. Run “make templates”:

    $ make templates

3. This process generated output/package_scap-security-guide_installed.xml. Load this file in a text editor for human-review:

    $ vim output/package_scap-security-guide_installed.xml

The newly created template: OVAL contains many pre-defined functions. In this case, we make use of linux:rpminfo_test to check for the installation of scap-security-guide.

4. Run “make copy” to place package_scap-security-guide_installed.xml into the project:

    $ make copy

5. Done! You've now added an OVAL rule to check for the existence of scap-security-guide!

## Profiles

With our XCCDF rule and OVAL content created, we must now add the rule to an XCCDF profile. Let's add this as a STIG requirement, placing it into the stig-rhel6-server profile.

XCCDF profiles are retained within RHEL/6/input/profiles/. Change directory and perform a directory listing to see available profiles:

    $ cd /var/www/html/scap-security-guide/RHEL/6/input/profiles/; ls -l
    total 136
    -rw-rw-r--. 1 dave dave 16975 Mar  5 12:10 common.xml
    -rw-rw-r--. 1 dave dave 20758 Mar  5 12:10 CS2.xml
    -rw-rw-r--. 1 dave dave  1852 Mar  5 12:10 desktop.xml
    -rw-rw-r--. 1 dave dave 16163 Mar  5 12:10 fisma-medium-rhel6-server.xml
    -rw-rw-r--. 1 dave dave   800 Mar  5 12:10 ftp.xml
    -rw-rw-r--. 1 dave dave 21262 Mar  5 12:10 nist-CL-IL-AL.xml
    -rw-rw-r--. 1 dave dave  7507 Mar  5 12:10 rht-ccp.xml
    -rw-rw-r--. 1 dave dave   402 Mar  5 12:10 server.xml
    -rw-rw-r--. 1 dave dave  4736 Mar  5 12:10 stig-rhel6-server-upstream.xml
    -rw-rw-r--. 1 dave dave  3251 Mar  5 12:10 test.xml
    -rw-rw-r--. 1 dave dave 16983 Mar  5 12:10 usgcb-rhel6-server.xml

Since we're adding this rule to the STIG profile, load stig-rhel6-server.xml:

    $ vim stig-rhel6-server.xml

Upon loading the file, you will be presented with the XCCDF code behind the STIG profile:

## Patch Creation and Submission

Throughout this workshop, we've made several modifications to the SSG source code. Specifically:

- Creation of a new XCCDF rule, package_scap-security-guide_installed, which was placed into RHEL/6/input/system/software/integrity.xml.
- Creation of a new OVAL rule, package_scap-security-guide_installed.xml, which also involved updating the OVAL template file RHEL/6/input/checks/templates/packages_installed.csv.
- Modification of the STIG profile, located at RHEL/6/input/profiles/stig-rhel6-server.xml.

We must now prepare our changes for submission back to the community, in the form of a patch. Change directories to /var/www/html/scap-security-guide/ and run “git commit”:

    $ cd /var/www/html/scap-security-guide/; git commit
    # On branch master
    #
    # Changed but not updated:
    #   (use "git add [file]..." to update what will be committed)
    #   (use "git checkout -- [file]..." to discard changes in working directory)
    #
    #	modified:   RHEL/6/input/checks/templates/packages_installed.csv
    #	modified:   RHEL/6/input/profiles/stig-rhel6-server.xml
    #	modified:   RHEL/6/input/system/software/integrity.xml
    #
    # Untracked files:
    #   (use "git add [file]..." to include in what will be committed)
    #
    #	RHEL/6/input/checks/package_scap-security-guide_installed.xml
    no changes added to commit (use "git add" and/or "git commit -a")

From the output above, our patch must reflect changes to the “modified” files and include the net-new “untracked” file. To do so, run the following commands:

    $ git add RHEL/6/input/checks/package_scap-security-guide_installed.xml
    $ git commit RHEL/6/input/checks/templates/packages_installed.csv \ RHEL6/input/profiles/stig-rhel6-server.xml \
    RHEL/6/input/system/software/integrity.xml \
    RHEL/6/input/checks/package_scap-security-guide_installed.xml

The “git commit” command will bring you into a vi editor, prompting you to enter details of your patch. The first line, which is the default location of your cursor at this point, is where you create the patch title. At the EOF you place details of the patch.

Edit your patch content to reflect:

- Patch title of “Added package_scap-security-guide_installed.xml to stig-rhel6-server profile”
- Patch description of “Added package_scap-security-guide_installed.xml into STIG profile, which will now mandate the installation of the SSG”

Once complete, save and exit (:wq). Your local source tree has now identified and grouped your changes into a consolidated patch. Using the git utility, we must “export” these changes in the format of a patch file. To do so, run the following command:

    $ git format-patch origin

    0001-Added-package_scap-security-guide_installed.xml-to-s.patch

A newly created file, 0001-Added-package_scap-security-guide_installed.xml-to-s.patch, will be placed into your working directory. The final step is to EMail this patch to the SSG project mailing list. Upon acknowledgement/signoff, you will be able to “git push” your changes into the project.