Convert User Docs

docs/index.rst

@@ -2,6 +2,15 @@
 ComplianceAsCode/content
 ========================
 
+.. toctree::
+    :maxdepth: 2
+    :glob:
+    :caption: User Guide
+    :name: User Guide
+
+    manual/user/*
+
+
 .. toctree::
     :maxdepth: 2
     :glob:

docs/manual/developer/01_introduction.md

@@ -88,7 +88,7 @@ Products may be subject to removal from the project if at **least one** of the f
 The following process shall be used to start the removal of the product:
 1. A GitHub issue is created proposing the removal of the product.
     The issue must contain the following:
-    1. The end date and time (in UTC) of the comment period 
+    1. The end date and time (in UTC) of the comment period
     1. A mention of the last contributor to the product, more than one is preferred
     1. The reason for removal (lack of contributions or product EOL)
 1. A comment period of **21 days** shall be observed.
@@ -101,6 +101,7 @@ The pull request removing the product should include the removal of
     1. the product from all `prodtype`
     1. any product specific checks or remediatons
     1. any product specific templates
+1. The removal must be documented in the [user guide](../user/30_content_notes.md#deprecated-content).
 
 All issues and pull requests for product removal must use the [product-removal](https://github.com/ComplianceAsCode/content/labels/product-removal) label.
 

docs/manual/developer_guide.adoc

@@ -1,6 +1,6 @@
 # ComplianceAsCode Developer Guide
 
-WARNING: This guide has been deprecated. Please check the latest link:https://complianceascode.readthedocs.io/[ComplianceAsCode Developer Documentation].
+WARNING: This guide has been deprecated. Please check the latest link:https://complianceascode.readthedocs.io/[ComplianceAsCode Documentation].
 
 To contribute to the new documentation (or to read it offline), check the
 files in the `developer/` folder. Commits into those documents will be

docs/manual/user/01_introduction.md

@@ -0,0 +1,8 @@
+# Introduction
+
+The ComplianceAsCode ([historical called the SCAP Security Guide](../developer/09_legacy_notice.md)) project delivers security guidance, baselines and associated validation mechanisms utilizing the Security Content Automation Protocol (SCAP). ComplianceAsCode provides content for Red Hat Enterprise Linux.
+In addition to hardening advice, ComplianceAsCode links back to compliance requirements in order to ease deployment activities, such as certification and accreditation.
+These include requirements in the U.S. Government (Federal, Defense, and Intelligence Community) as well as of the financial services and health care  industries.
+For example, high-level and widely-accepted policies such as NIST 800-53 provide prose stating that System Administrators must audit "privileged user actions," but do not define what "privileged actions" are.
+The ComplianceAsCode bridges the gap between generalized policy requirements and specific implementation guidance, in SCAP formats to support automation whenever possible.
+The project homepage is [https://www.open-scap.org/security-policies/scap-security-guide](https://www.open-scap.org/security-policies/scap-security-guide).

docs/manual/user/10_install.md

@@ -0,0 +1,37 @@
+# Installing
+
+By installing distribution packages, you will get the built content.
+For example, on Red Hat-based distributions, those will be files under the `/usr/share/xml/scap/ssg/content/` directory.
+What files will that be depends on the distribution, but for example on Fedora, you will get the Fedora datastream at `/usr/share/xml/scap/ssg/content/ssg-fedora-ds.xml`.
+
+
+## Installing from distribution packages
+
+### Red Hat Enterprise Linux 7
+
+```
+$ sudo yum -y install scap-security-guide
+```
+
+### Fedora / Red Hat Enterprise Linux 8+
+```
+$ sudo dnf -y install scap-security-guide
+```
+
+### Debian
+```
+$ sudo apt install ssg-debian  # for Debian guides
+$ sudo apt install ssg-debderived  # for Debian-based distributions (e.g. Ubuntu) guides
+$ sudo apt install ssg-nondebian  # for other distributions guides (RHEL, Fedora, etc.)
+$ sudo apt install ssg-applications  # for application-oriented guides (Firefox, JBoss, etc.)
+```
+
+## Installing content from upstream
+
+If you need to use upstream content rather than what is shipped in the distribution, you can download the nightly build, or build it yourself.
+
+The nightly builds are performed by [GitHub Actions](https://docs.github.com/en/actions) nightly. Below is a direct link to the latest build:
+
+* [https://nightly.link/ComplianceAsCode/content/workflows/nightly_build/master/Nightly%20Build.zip](https://nightly.link/ComplianceAsCode/content/workflows/nightly_build/master/Nightly%20Build.zip)
+
+If you wish to build the content yourself, please, refer to the [Developer Guide](../developer/02_building_complianceascode.md#building-complianceascode).

docs/manual/user/20_scanning.md

@@ -0,0 +1,192 @@
+# Scanning
+## Running a Scan with OpenSCAP
+
+#### Command Line Interface (CLI)
+This document outlines the usage of OpenSCAP, a command-line utility packaged within Fedora and Red Hat Enterprise Linux which allows users to load, scan, validate, edit, and export SCAP documents.
+
+See also [OpenSCAP User Manual](https://static.open-scap.org/openscap-1.3/oscap_user_manual.html) for instructions how to use OpenSCAP.
+Additional details regarding OpenSCAP can be found on the project homepage located at [open-scap.org](http://open-scap.org/).
+
+Five arguments to OpenSCAP are needed to perform a system scan against the upstream a profile:
+
+* `--profile`
+  * Mandatory, identifies which profile to scan against
+
+* `--results`
+  * Optional, indicates location to place ARF XML formatted results
+
+* `--report`
+  * Optional, indicates location to place HTML formatted results
+
+* datastream location
+  * Mandatory, identifies location of SCAP Source Datastream file
+
+Putting these arguments together, a properly formatted command would be:
+
+```
+$ sudo oscap xccdf eval --profile stig \
+--results /tmp/results.xml \
+--report /tmp/report.html \
+/usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml
+```
+
+While the scan is running, you will see output similar to the following on your screen:
+
+```
+Title   Install AIDE
+Rule    package_aide_installed
+Ident   CCE-83457-2
+Result  fail
+
+Title   Configure Periodic Execution of AIDE
+Rule    aide_periodic_cron_checking
+Ident   CCE-83437-4
+Result  notchecked
+
+Title   Verify File Permissions with RPM
+Rule    rpm_verify_permissions
+Ident   CCE-90840-0
+Result  fail
+
+Title   Verify File Hashes with RPM
+Rule    rpm_verify_hashes
+Ident   CCE-90841-8
+Result  pass
+```
+
+### Results Interpretation
+
+#### HTML Results
+
+Just open the `/tmp/report.html` file in your favorite browser.
+
+#### XML Results
+
+Looking at the `/tmp/results.xml` file, you will notice lines similar to those below:
+
+```xml
+    <rule-result idref="ensure_gpgcheck_globally_activated" time="2023-02-16T10:03:43" severity="high" weight="1.000000">
+      <result>pass</result>
+      <ident system="http://cce.mitre.org">CCE-83457-2</ident>
+      <check system="http://oval.mitre.org/XMLSchema/oval-definitions-5">
+        <check-content-ref name="oval:ssg:def:413" href="ssg-rhel9-oval.xml"/>
+      </check>
+    </rule-result>
+    ......
+    <rule-result idref="package_aide_installed" time="2023-02-16T10:03:43" severity="medium" weight="1.000000">
+      <result>pass</result>
+      <ident system="http://cce.mitre.org">CCE-90843-4</ident>
+      <fix xmlns:xhtml="http://www.w3.org/1999/xhtml" system="urn:xccdf:fix:script:sh">
+        yum -y install aide
+      </fix>
+      <check system="http://oval.mitre.org/XMLSchema/oval-definitions-5">
+        <check-content-ref name="oval:ssg:def:245" href="ssg-rhel9-oval.xml"/>
+      </check>
+    </rule-result>
+```
+
+The XML above can be parsed as follows:
+
+XCCDF Rule Elements
+
+|        XML Tag        | Meaning                                                                                                                                                |
+|:---------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------|
+|    `<rule-result>`    | Identifies which XCCDF rule the result reflects                                                                                                        |
+|      `<result>`       | Pass/Fail/Not Applicable                                                                                                                               |
+|        `<fix>`        | Remediation actions, in bash, which will configure the system to be in compliance with the XCCDF rule.                                                 |
+|   `<check system>`    | Identifies which version of OVAL the check was authored against.                                                                                       |
+| `<check-content-ref>` | Corresponding OVAL check name (`name`) and source OVAL file (`href`) this check came from. For general purpose users, this information can be ignored. |
+
+### Remediation
+
+#### Bash Scripts
+
+A Bash remediation script for each profile is shipped in `scap-security-guide` package.
+The scripts can be found in `/usr/share/scap-security-guide/bash/` or if you build the project from source in `./build/bash`.
+
+Moreover, ComplianceAsCode embeds bash remediation scripts into the SCAP content. This allows for SCAP compatible tools to extract these remediation scripts to aid in potential remediation of system misconfigurations.
+
+OpenSCAP, the CLI delivered with Fedora, Red Hat Enterprise Linux systems and other Linux distributions, contains the ability to transform XML results into an executable script.
+The syntax to generate a remediation script is:
+
+
+```
+$ oscap xccdf generate fix \
+--result-id xccdf_org.open-scap_testresult_{profile-name} \
+/root/ssg-results.xml
+```
+
+
+Replace `{profile-name}` with the profile the system was scanned against. For example, for `stig`:
+
+```
+$ oscap xccdf generate fix \
+--result-id xccdf_org.open-scap_testresult_stig \
+/root/ssg-results.xml
+```
+
+You will receive output similar to the following:
+
+```
+$ oscap xccdf generate fix \
+--result-id xccdf_org.open-scap_testresult_stig \
+/root/ssg-results.xml
+
+#!/bin/bash
+# OpenSCAP fix generator output for benchmark: DRAFT Guide
+# to the Secure Configuration of Red Hat Enterprise Linux 8
+
+# XCCDF rule: set_sysctl_net_ipv4_conf_default_rp_filter
+# CCE-26915-9
+#
+# Set runtime for net.ipv4.conf.default.rp_filter
+#
+sysctl -q -n -w net.ipv4.conf.default.rp_filter=1
+
+#
+# If net.ipv4.conf.default.rp_filter present in
+# /etc/sysctl.conf, change value to "1"
+# else, add "net.ipv4.conf.default.rp_filter = 1" to /etc/sysctl.conf
+#
+if grep --silent ^net.ipv4.conf.default.rp_filter /etc/sysctl.conf ; then sed -i \
+ 's/^net.ipv4.conf.default.rp_filter.*/net.ipv4.conf.default.rp_filter \
+ = 1/g' /etc/sysctl.conf
+else
+echo "" >> /etc/sysctl.conf
+echo "# Set net.ipv4.conf.default.rp_filter to 1 per \
+ security requirements" >> /etc/sysctl.conf
+echo "net.ipv4.conf.default.rp_filter = 1" >> /etc/sysctl.conf
+fi
+
+# XCCDF rule: uninstall_xinetd
+# CCE-27005-8
+if rpm -qa | grep -q xinetd; then
+yum -y remove xinetd
+fi
+
+# generated: 2013-07-05T13:56:30-04:00
+# END OF SCRIPT
+```
+
+This output could be redirected to a bash script, or built into your RHEL7 provisioning process (e.g. the %post section of a kickstart).
+
+#### Ansible Playbooks
+
+ComplianceAsCode embeds Ansible remediation scripts into the SCAP content.
+This allows for SCAP compatible tools to extract these remediation scripts to aid in potential remediation of system misconfigurations.
+
+You can create these playbooks by running:
+
+```
+$ oscap xccdf generate fix --profile stig --fix-type ansible /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml > ssg-rhel9-stig.yml
+```
+
+IMPORTANT: The minimum version of Ansible must be at the latest supported version.
+See [Red Hat Ansible Engine Life Cycle Page](https://access.redhat.com/support/policy/updates/ansible-engine) for information on the supported Ansible versions.
+
+## Other Scanners
+### Security Content Automation Protocol (SCAP) Compliance Checker (SCC)
+Funded by the Internal Revenue Service, the National Security Agency, and other United States government agencies Naval Information Warfare Center (NIWC) Atlantic has authored a SCAP Compliance Checker (SCC).
+The NIWC SCC tool is available to the general public.
+The NIWC SCC website is [www.niwcatlantic.navy.mil/scap](https://www.niwcatlantic.navy.mil/scap/).
+The SCC tool is available for download at [public.cyber.mil/stigs/scap](https://public.cyber.mil/stigs/scap/).

docs/manual/user/30_content_notes.md

@@ -0,0 +1,24 @@
+# Content Notes
+
+## Deprecated Content
+Below is list of products that have been removed from the project.
+
+| Product                                      | EOL Date           | Last Release                                                                       |
+|----------------------------------------------|--------------------|------------------------------------------------------------------------------------|
+| Debian 8                                     | June 30, 2020      | [content 0.1.52](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.52) |
+| Debian 9                                     | June 30, 2022      | [content 0.1.65](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.65) |
+| Java Runtime Environment                     | -                  | [content 0.1.64](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.64) |
+| JBoss EAP 5                                  | November 30, 2016  | [content 0.1.35](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.35) |
+| JBoss EAP 6                                  | June 30, 2019      | [content 0.1.53](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.53) |
+| JBoss Fuse 6                                 | January 1, 2022    | [content 0.1.64](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.64) |
+| McAfee VirusScan Enterprise for Linux (VESL) | December 31, 2021  | [content 0.1.65](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.65) |
+| Red Hat Enterprise Linux 5                   | March 31, 2017     | [content 0.1.34](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.34) |
+| Red Hat Enterprise Linux 6                   | June 1, 2022       | [content 0.1.52](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.52) |
+| Red Hat Enterprise Virtualization Manager 3  | September 30, 2018 | [content 0.1.38](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.38) |
+| Red Hat OpenShift Container Platform 3       | June 1, 2022       | [content 0.1.52](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.52) |
+| Red Hat OpenStack Platform 7                 | August 5, 2018     | [content 0.1.41](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.41) |
+| SUSE Enterprise Linux 11                     | March 31, 2019     | [content 0.1.52](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.52) |
+| Ubuntu 14.04                                 | April 30, 2019     | [content 0.1.52](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.52) |
+| Webmin                                       | -                  | [content 0.1.38](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.38) |
+| Wind River Linux 1019                        | -                  | [content 0.1.63](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.63) |
+| Wind River Linux 8                           | -                  | [content 0.1.63](https://github.com/ComplianceAsCode/content/releases/tag/v0.1.63) |