Signed-off-by: David Smith<[email protected]>
---
.../en-US/Content_Customization.xml | 191 +++++++++++---------
1 files changed, 101 insertions(+), 90 deletions(-)
diff --git a/docs/SCAP_and_STIG_Workshop/en-US/Content_Customization.xml
b/docs/SCAP_and_STIG_Workshop/en-US/Content_Customization.xml
index 771e281..2a22405 100644
--- a/docs/SCAP_and_STIG_Workshop/en-US/Content_Customization.xml
+++ b/docs/SCAP_and_STIG_Workshop/en-US/Content_Customization.xml
@@ -8,7 +8,7 @@
<para/>
<section>
<title>So, you wanna be a developer?</title>
- <para>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 acknowledgement (“ACKâ€) to accept it, and then it can be pushed.
Assuming another project member has not issued a NACK in protest first, that is! The
following instructions assume familiarity with git and git-send-email, but project members
are happy to provide tips if you encounter any roadblocks.</para>
+ <para>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.</para>
<para>To properly join the project you must first establish a
few required accounts:
<simplelist>
<member>Join the <ulink
url="https://fedorahosted.org/mailman/listinfo/scap-security-guide";>mailing list</ulink>, it's
how developers and users communicate.</member>
@@ -25,10 +25,10 @@
NOTE: For this workshop, use/var/www/html/
<screen>
$ cd/var/www/html/
-$ git clonessh://git.fedorahosted.org/git/scap-security-guide.git
+$ git clonessh://[email protected]/git/scap-security-guide.git
If you have not been given commit access, use the standard HTTP interface:
-$ git clonessh://git.fedorahosted.org/git/scap-security-guide.git
+$ git clone git://git.fedorahosted.org/git/scap-security-guide.git
</screen>
</para>
</section>
@@ -38,29 +38,32 @@ $ git
clonessh://git.fedorahosted.org/git/scap-security-guide.git
<screen>
$ cd scap-security-guide; ls -l
-total 36
-drwxrwxr-x. 4 shawn shawn 4096 Mar 14 20:51 JBossEAP5
--rw-rw-r--. 1 shawn shawn 409 Mar 14 20:51 LICENSE
--rw-rw-r--. 1 shawn shawn 2945 Mar 17 18:58 Makefile
-drwxrwxr-x. 8 shawn shawn 4096 Mar 17 14:03 OpenStack
--rw-rw-r--. 1 shawn shawn 840 Mar 14 20:51 README
-drwxrwxr-x. 8 shawn shawn 4096 Mar 23 14:34 RHEL6
-drwxrwxr-x. 8 shawn shawn 4096 Mar 17 14:03 RHEVM3
-drwxrwxr-x. 4 shawn shawn 4096 Mar 23 11:32 rpmbuild
--rw-rw-r--. 1 shawn shawn 3229 Mar 14 20:51 scap-security-guide.spec
-
+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
+</screen>
-Top level directories have been created to contain the per-technology SCAP content. Change directory into RHEL6 and perform a directory listing:
-$ cd RHEL6; ls -l
-total 40
-drwxrwxr-x. 2 shawn shawn 4096 Mar 23 17:35 dist
-drwxrwxr-x. 9 shawn shawn 4096 Mar 21 18:57 input
--rw-rw-r--. 1 shawn shawn 10277 Mar 14 20:51 Makefile
-drwxrwxr-x. 2 shawn shawn 4096 Mar 23 17:35 output
--rw-rw-r--. 1 shawn shawn 1616 Mar 14 20:51 README
-drwxrwxr-x. 2 shawn shawn 4096 Mar 17 18:57 references
-drwxrwxr-x. 2 shawn shawn 4096 Mar 17 14:03 transforms
-drwxrwxr-x. 2 shawn shawn 4096 Mar 14 20:51 utils
+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:
+<screen>
+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
</screen>
</para>
<para>
@@ -77,10 +80,6 @@ The directory usages are:
</thead>
<tbody>
<row>
- <entry>dist/</entry>
- <entry>The build process generates finalized content here, which then
are included into SSG RPMs.</entry>
- </row>
- <row>
<entry>input/</entry>
<entry>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.</entry>
</row>
@@ -89,10 +88,6 @@ The directory usages are:
<entry>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.</entry>
</row>
<row>
- <entry>references/</entry>
- <entry>Contain documents which are specified as references from within the SCAP
content, or documents that are "seeds," viz. documents whose prose will be translated into
SCAP formats, as well as other examples of SCAP content.</entry>
- </row>
- <row>
<entry>transforms/</entry>
<entry>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.</entry>
</row>
@@ -148,8 +143,8 @@ The template for SSG XCCDF rules is below. Insert the
following template into in
<ocil clause="">
<package-check-macro package="" />
</ocil>
- <rational>
- </rational>
+ <rationale>
+ </rationale>
<oval id="" />
</Rule> -->
</screen>
@@ -161,17 +156,17 @@ The template for SSG XCCDF rules is below. Insert the
following template into in
<member>Outlines a method to install SSG. For
example, “yum install scap-security-guideâ€</member>
<member>States that “if SCAP Security Guide is not
installed†this is a finding</member>
<member>Includes the proper package name,
scap-security-guide, in the package check macro</member>
- <member>Includes rational on why the SSG project is
awesome, and should be installed</member>
+ <member>Includes rationale on why the SSG project is
awesome, and should be installed</member>
<member>Corresponds to a (currently non-existent)
OVAL rule named “package_scap-security-guide_installedâ€</member>
</simplelist>
</para>
<para>Your completed template will look similar to:
<screen>
<!-- FIXME
-Done! Hopefully that wasn't to painful. If you're curious on where the
“package-check-macro†comes from, check out RHEL6/transforms/shorthand2xccdf.xslt
and search for lines that begin with “<xsl:template match="â€
+Done! Hopefully that wasn't too painful. If you're curious on where the
“package-check-macro†comes from, check out RHEL/6/transforms/shorthand2xccdf.xslt
and search for lines that begin with “<xsl:template match="â€
The shorthand2xccdf.xslt file contains many short-hand macros that are
available, which inserts template text into final XCCDF output. Unfortunately,
in a two hour workshop, we don't have enough time to properly cover all
embedded XSLT transformations within the SSG. Feel free to direct questions to
the public mailing list!
Now that the XCCDF language is written, let's see how it looks in the HTML
guide. For this we will need to run a quick SSG compilation:
-$ cd /var/www/html/scap-security-guide/RHEL6
+$ cd /var/www/html/scap-security-guide/RHEL/6
$ make content
To ensure your XCCDF is still SCAP compliant, run a quick “make validateâ€:
@@ -182,9 +177,7 @@ oscap oval validate-xml output/ssg-rhel6-cpe-oval.xml
-->
</screen>
</para>
- <para>As mentioned earlier, the output/ directory contains
artifacts from the build. Using a web browser,
viewhttp://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:
+ <para>As mentioned earlier, the output/ directory contains
artifacts from the build. Using a web browser,
viewhttp://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.
<!-- FIXME
@@ -196,16 +189,21 @@ The <description> tag has the ability to handle XHTML
arguments. Let's wrap our
Once updated, re-run the build:
+<screen>
$ make clean; make content; make validate
+</screen>
-Upon completion, refresh your web browser to see the updated content:
+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.
-5.5 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 here:
-http://oval.mitre.org/language/version5.10.1/ovaldefinition/documentation/linux-definitions-schema.html
-The SSG project maintains all OVAL code under RHEL6/input/checks/, and
provides a template utilities in RHEL6/input/checks/templates/. Change
directories to templates/ and perform a directory listing:
+Now, onto OVAL content creation...</para>
+
+ </section>
+ <section>
+ <title>OVAL Authoring</title>
+ <para>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
athttp://oval.mitre.org/language/version5.10.1/ovaldefinition/documentation/linux-definitions-schema.html</para>
+ <para>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:
+ <screen>
$ 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
@@ -220,49 +218,65 @@ 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:
+ </screen>
+ </para>
+ <para>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:</para>
+ <para>
1. Add scap-security-guide to the listing in packages_installed.csv:
+ <screen>
$ echo “scap-security-guide†>> packages_installed.csv
-
+ </screen>
+ </para>
+ <para>
2. Run “make templatesâ€:
+ <screen>
$ make templates
-
+ </screen>
+ </para>
+ <para>
3. This process generated output/package_scap-security-guide_installed.xml.
Load this file in a text editor for human-review:
+ <screen>
$ vim output/package_scap-security-guide_installed.xml
-
+ </screen>
+ </para>
+ <para>
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.
-
-
+ </para>
+ <para>
4. Run “make copy†to place package_scap-security-guide_installed.xml
into the project:
+ <screen>
$ make copy
-
+ </screen>
+ </para>
+ <para>
5. Done! You've now added an OVAL rule to check for the existence of
scap-security-guide!
-
</para>
</section>
<section>
<title>Profiles</title>
<para>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.</para>
- <para>XCCDF profiles are retained within RHEL6/input/profiles/.
Change directory and perform a directory listing to see available profiles:
+ <para>XCCDF profiles are retained within
RHEL/6/input/profiles/. Change directory and perform a directory listing to see
available profiles:
<screen>
-$ cd/var/www/html/scap-security-guide/RHEL6/input/profiles/; ls -l
-total 96
--rw-rw-r--. 1 shawn shawn 16798 Mar 14 20:51 common.xml
--rw-rw-r--. 1 shawn shawn 1957 Mar 14 20:51 desktop.xml
--rw-rw-r--. 1 shawn shawn 800 Mar 14 20:51ftp.xml
--rw-rw-r--. 1 shawn shawn 2527 Mar 14 20:51 manual_audits.xml
--rw-rw-r--. 1 shawn shawn 1902 Mar 14 20:51 manual_remediation.xml
--rw-rw-r--. 1 shawn shawn 21629 Mar 14 20:51 nist-CL-IL-AL.xml
--rw-rw-r--. 1 shawn shawn 448 Mar 14 20:51 server.xml
--rw-rw-r--. 1 shawn shawn 4166 Mar 20 18:59 stig-rhel6-server.xml
--rw-rw-r--. 1 shawn shawn 3108 Mar 14 20:51 test.xml
--rw-rw-r--. 1 shawn shawn 17127 Mar 14 20:51 usgcb-rhel6-server.xml
-
+$ 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:10ftp.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
+ </screen>
+ </para>
+ <para>
Since we're adding this rule to the STIG profile, load stig-rhel6-server.xml:
+ <screen>
$ vim stig-rhel6-server.xml
</screen>
</para>
@@ -297,11 +311,11 @@ If added correctly, you will have inserted a line that
matches the following:
</section>
<section>
<title>Patch Creation and Submission</title>
- <para>Through this workshop we've made several modifications to
the SSG source code. Specifically:
+ <para>Throughout this workshop, we've made several
modifications to the SSG source code. Specifically:
<simplelist>
- <member>Creation of a new XCCDF rule,
package_scap-security-guide_installed, which was placed into
RHEL6/input/system/software/integrity.xml.</member>
- <member>Creation of a new OVAL rule,
package_scap-security-guide_installed.xml, which also involved updating the OVAL template
file RHEL6/input/checks/templates/packages_installed.csv.</member>
- <member>Modification of the STIG profile, located at
RHEL6/input/profiles/stig-rhel6-server.xml.</member>
+ <member>Creation of a new XCCDF rule,
package_scap-security-guide_installed, which was placed into
RHEL/6/input/system/software/integrity.xml.</member>
+ <member>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.</member>
+ <member>Modification of the STIG profile, located at
RHEL/6/input/profiles/stig-rhel6-server.xml.</member>
</simplelist>
</para>
<para>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â€:
@@ -313,41 +327,38 @@ $ cd/var/www/html/scap-security-guide/; git commit
# (use "git add [file]..." to update what will be committed)
# (use "git checkout -- [file]..." to discard changes in working directory)
#
-# modified: RHEL6/input/checks/templates/packages_installed.csv
-# modified: RHEL6/input/profiles/stig-rhel6-server.xml
-# modified: RHEL6/input/system/software/integrity.xml
+# 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)
#
-# RHEL6/input/checks/package_scap-security-guide_installed.xml
+# RHEL/6/input/checks/package_scap-security-guide_installed.xml
no changes added to commit (use "git add" and/or "git commit -a")
</screen>
</para>
<para>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:
<screen>
-$ git add RHEL6/input/checks/package_scap-security-guide_installed.xml
-$ git commit RHEL6/input/checks/templates/packages_installed.csv \
RHEL6/input/profiles/stig-rhel6-server.xml \
-RHEL6/input/system/software/integrity.xml \
-RHEL6/input/checks/package_scap-security-guide_installed.xml
+$ 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
</screen>
</para>
- <para>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 to create the patch title. At the EOF you place
details of the patch.</para>
+ <para>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.</para>
<para>Edit your patch content to reflect:
<simplelist>
<member>Patch title of “Added
package_scap-security-guide_installed.xml to stig-rhel6-server profileâ€</member>
<member>Patch description of “Added
package_scap-security-guide_installed.xml into STIG profile, which will now mandate the
installation of the SSGâ€</member>
</simplelist>
</para>
- <para>When done, your window will resemble the following:
-<screen>
-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:
+ <para>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:
+ <screen>
$ git format-patch origin
0001-Added-package_scap-security-guide_installed.xml-to-s.patch
-</screen>
+ </screen>
</para>
<para>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.</para>
-- 1.7.1
