Building ComplianceAsCode¶
Installing build dependencies¶
On Red Hat Enterprise Linux 7 make sure the packages cmake
, openscap-utils
,
PyYAML
, python-jinja2
and their dependencies are installed:
yum install cmake make openscap-utils PyYAML python-jinja2
On Red Hat Enterprise Linux 8 and Fedora the package list is the same but python2 packages need to be replaced with python3 ones:
yum install cmake make openscap-utils python3-pyyaml python3-jinja2
On Ubuntu and Debian, make sure the packages libopenscap8
,
libxml2-utils
, python3-jinja2
, python3-yaml
, xsltproc
and their dependencies are
installed:
apt-get install cmake make expat libopenscap8 libxml2-utils ninja-build python3-jinja2 python3-yaml xsltproc
IMPORTANT: Version 1.0.8
or later of openscap-utils
is required to build the content.
(optional) Install git if you want to clone the GitHub repository to get the source code:
# Fedora/RHEL
yum install git
# Ubuntu/Debian
apt-get install git
(optional) Install the ShellCheck
package to perform fix script static analysis:
# Fedora/RHEL
yum install ShellCheck
# Ubuntu/Debian
apt-get install shellcheck
(optional) Install yamllint
and ansible-lint
packages to perform Ansible
playbooks checks. These checks are not enabled by default in CTest, to enable
them add -DANSIBLE_CHECKS=ON
option to cmake
.
# Fedora/RHEL
yum install yamllint ansible-lint
# Ubuntu/Debian (to install ansible-lint on Debian you will probably need to
# enable Debian Backports repository)
apt-get install yamllint ansible-lint
(optional) Install the ninja
build system if you want to use it instead of
make
for faster builds:
# Fedora/RHEL
yum install ninja-build
# Ubuntu/Debian
apt-get install ninja-build
(optional) Install the json2html
package if you want to generate HTML report statistics:
pip install json2html
(optional) Install Sphinx packages if you want to generate HTML Documentation, from source directory run:
pip install -r docs/requirements.txt
Downloading the source code¶
Download and extract a tarball from the list of releases:
# change X.Y.Z for desired version
ssg_version="X.Y.Z"
wget "https://github.com/ComplianceAsCode/content/releases/download/v$ssg_version/scap-security-guide-$ssg_version.tar.bz2"
tar -xvjf ./scap-security-guide-$ssg_version.tar.bz2
cd ./scap-security-guide-$ssg_version/
Or clone the GitHub repository:
git clone https://github.com/ComplianceAsCode/content.git
cd content/
# (optional) select release version - change X.Y.Z for desired version
git checkout vX.Y.Z
# (optional) select latest development version
git checkout master
Building¶
To build all the security content:
cd build/
cmake ../
# To build all security content
make -j4
# To build security content for one specific product, for example for *Red Hat Enterprise Linux 7*
make -j4 rhel7
Or use the build_product
script from base directory that removes whatever is in the build
directory and builds specific product:
./build_product rhel7
(optional) To build only specific content for one specific product:
cd build/
cmake ../
make -j4 rhel7-content # SCAP XML files for RHEL7
make -j4 rhel7-guides # HTML guides for RHEL7
make -j4 rhel7-tables # HTML tables for RHEL7
make -j4 rhel7-profile-bash-scripts # remediation Bash scripts for all RHEL7 profiles
make -j4 rhel7-profile-playbooks # Ansible Playbooks for all RHEL7 profiles
make -j4 rhel7 # everything above for RHEL7
(optional) Configure options before building using a GUI tool:
cd build/
cmake-gui ../
make -j4
(optional) Use the ninja
build system (requires the ninja-build
package):
cd build/
cmake -G Ninja ../
ninja-build # depending on the distribution just "ninja" may also work
(optional) Generate statistics for products and profiles. Some of the statistics generated are: implemented OVAL, bash, ansible for rules, missing CCE, etc:
cd build/
cmake ../
make -j4 stats # display statistics in text format for all products
make -j4 profile-stats # display statistics in text format for all profiles in all products
You can also create statistics per product, to do that just prepend the product name (e.g.: rhel7-stats
) to the make target.
It is possible to generate HTML output by triggering similar command:
cd build/
cmake ../
make -j4 html-stats # generate statistics for all products, as a result <product>/product-statistics/statistics.html file is created.
make -j4 html-profile-stats # generate statistics for all profiles in all products, as a result <product>/profile-statistics/statistics.html file is created
If you want to go deeper into statistics, refer to Profile Statistics and Utilities section.
(optional) Generate HTML documentation of the project which includes developer documentation, supported Jinja Macros documentation and python modules documentation:
cd build/
cmake ../
make -j4 docs # check docs/index.html file
Building compliant SCAP 1.2 content¶
By default, the build system builds SCAP content with OVAL 5.11. This means that the SCAP 1.3 datastream conforms to SCAP standard version 1.3. But the SCAP 1.2 datastream is not fully conformant with SCAP standard version 1.2, as up to OVAL 5.10 version is allowed. As SCAP 1.3 allows up to OVAL 5.11 and SCAP 1.2 allows up to OVAL 5.10.
To build fully compliant SCAP 1.2 content:
If you use build_product
script, pass --oval510
option:
./build_product --oval510 <product-name>
If you use cmake
command, pass -DSSG_TARGET_OVAL_MINOR_VERSION:STRING=10
:
cd build/
cmake -DSSG_TARGET_OVAL_MINOR_VERSION:STRING=10 ../
make
And use the datastream with suffix -1.2.xml
.
Build outputs¶
When the build has completed, the output will be in the build folder.
That can be any folder you choose but if you followed the examples above
it will be the content/build
folder.
SCAP XML files¶
The SCAP XML files will be called ssg-${PRODUCT}-${TYPE}.xml
. For example
ssg-rhel7-ds.xml
is the SCAP 1.3 Red Hat Enterprise Linux 7 source datastream,
and ssg-rhel7-ds-1.2.xml
is the SCAP 1.2 source datastream.
We recommend using source datastream if you have a choice. The build system also generates separate XCCDF, OVAL, OCIL and CPE files:
$ ls -1 ssg-rhel7-*.xml
ssg-rhel7-cpe-dictionary.xml
ssg-rhel7-cpe-oval.xml
ssg-rhel7-ds.xml
ssg-rhel7-ds-1.2.xml
ssg-rhel7-ocil.xml
ssg-rhel7-oval.xml
ssg-rhel7-pcidss-xccdf-1.2.xml
ssg-rhel7-xccdf-1.2.xml
ssg-rhel7-xccdf.xml
These can be ingested by any SCAP-compatible scanning tool, to enable automated checking.
HTML Guides¶
The human readable HTML guide index files will be called
ssg-${PRODUCT}-guide-index.html
. For example ssg-rhel7-guide-index.html
.
This file will let the user browse all profiles available for that product.
The prose guide HTML contains practical, actionable information for auditors
and administrators. They are placed in the guides folder.
$ ls -1 guides/ssg-rhel7-*.html
guides/ssg-rhel7-guide-ospp42.html
guides/ssg-rhel7-guide-ospp.html
guides/ssg-rhel7-guide-pci-dss.html
...
HTML Reference Tables¶
Spreadsheet HTML tables - potentially useful as the basis for a Security Requirements Traceability Matrix (SRTM) document:
$ ls -1 tables/table-rhel7-*.html
...
tables/table-rhel7-nistrefs-ospp.html
tables/table-rhel7-nistrefs-stig.html
tables/table-rhel7-pcidssrefs.html
tables/table-rhel7-srgmap-flat.html
tables/table-rhel7-srgmap.html
tables/table-rhel7-stig.html
...
Ansible Playbooks¶
Profile Ansible Playbooks¶
These Playbooks contain the remediations for a profile.
$ ls -1 ansible/rhel7-playbook-*.yml
ansible/rhel7-playbook-C2S.yml
ansible/rhel7-playbook-ospp.yml
ansible/rhel7-playbook-pci-dss.yml
...
Rule Ansible Playbooks¶
These Playbooks contain just the remediation for a rule, in the context of a profile.
$ ls -1 ansible/rhel7-playbook-*.yml
$ ls -1 rhel7/playbooks/pci-dss/*.yml
rhel7/playbooks/pci-dss/account_disable_post_pw_expiration.yml
rhel7/playbooks/pci-dss/accounts_maximum_age_login_defs.yml
rhel7/playbooks/pci-dss/accounts_password_pam_dcredit.yml
rhel7/playbooks/pci-dss/accounts_password_pam_lcredit.yml
...
Profile Bash Scripts¶
These Bash Scripts contains the remediations for a profile.
$ ls -1 bash/rhel7-script-*.sh
bash/rhel7-script-C2S.sh
...
bash/rhel7-script-ospp.sh
bash/rhel7-script-pci-dss.sh
...
Testing¶
To ensure validity of built artifacts prior to installation, we recommend
running our test suite against the build output. This is done with CTest.
It is a good idea to execute quick tests first using the -L quick
option passed to ctest
.
cd content/
./build_product
cd build
ctest -L quick
ctest -LE quick -j4
Note: CTest does not run SSG Test Suite which provides simple system of test scenarios for testing profiles and rule remediations.
Installation¶
System-wide installation:
cd content/
cd build/
cmake ../
make -j4
sudo make install
(optional) Custom install location:
cd content/
cd build/
cmake ../
make -j4
sudo make DESTDIR=/opt/absolute/path/to/ssg/ install
(optional) System-wide installation using ninja:
cd content/
cd build/
cmake -G Ninja ../
ninja-build
ninja-build install
Extra Building Options¶
Building a package¶
To build a package for testing purposes:
cd build/
# disable any product you would not like to bundle in the package. For example:
cmake -DSSG_PRODUCT_FEDORA:BOOL=OFF../
# build the package.
make package
Currently, RPM and DEB packages are supported by this mechanism. We recommend only using it for testing. Please follow downstream workflows for production packages.
Building a ZIP file¶
To build a zip file with all generated source data streams and kickstarts:
cd build/
make zipfile
There is also target to build zip file containing contents specific for a vendor’s product.
cd build/
# To build content zipfiles of all vendors:
make vendor-zipfile
# To build Red Hat zipfiles:
make redhat-zipfile
Build the Docker container image¶
Find a suitable Dockerfile present in the Dockerfiles directory and build the image. This will take care of the build environment and all necessary setup.
docker build --no-cache --file Dockerfiles/ubuntu --tag oscap:$(date -u +%Y%m%d%H%M) --tag oscap:latest .
Build the content using the container image¶
To build all the content, run a container without any flags.
docker run --cap-drop=all --name oscap-content oscap:latest
Using docker cp
to copy all the generated content to the your host:
docker cp oscap-content:/home/oscap/content/build $(pwd)/container_build