Creating Content¶
Directory Structure/Layout¶
Top Level Structure/Layout¶
Under the top level directory, there are directories and/or files for different products, shared content, documentation, READMEs, Licenses, build files/configuration, etc.
Important Top Level Directory Descriptions¶
Directory |
Description |
|
Contains security content for Linux operating systems. Contains rules, OVAL checks, Ansible tasks, Bash remediations, etc. |
|
Contains security content for applications such as OpenShift or OpenStack. Contains rules, OVAL checks, Ansible tasks, Bash remediations, etc. |
|
Contains templates which can generate, Jinja macros, Bash remediation functions. |
|
Contains the test suite for content validation and testing, contains also unit tests. |
|
Can be used to build the content using CMake. |
|
Scripts used by the build system. |
|
Contains the CMake build configuration files. |
|
Contains Dockerfiles to build content test suite container backends. |
|
Contains the User Guide and Developer Guide, manual page template, etc. |
|
Contains Python |
|
Miscellaneous scripts used for development but not used by the build system. |
The remaining directories such as fedora
, rhel7
, etc. are product
directories.
Important Top Level File Descriptions¶
File |
Description |
|
Top-level CMake build configuration file |
|
DO NOT MANUALLY EDIT script-generated file |
|
DO NOT MANUALLY EDIT script-generated file |
|
Disclaimer for usage of content |
|
CentOS7 Docker build file |
|
Content license |
|
Project README file |
Benchmark Structure/Layout¶
Benchmarks are directories that contain benchmark.yml
file. We have
multiple benchmarks in our project:
Name |
Location |
Linux OS |
|
Applications |
|
Java Runtime Environment |
|
Fuse 6 |
|
Firefox |
|
Chromium |
|
The Linux OS benchmark describes Linux Operating System in general.
This benchmark is used by multiple ComplianceAsCode products, eg.
rhel7
, fedora
, ubuntu1604
, sle15
etc. The benchmark is located
in /linux_os/guide
.
The products specify which benchmark they use as a source of content in
their product.yml
file using benchmark_root
key. For example,
rhel7
product specifies that it uses the Linux OS benchmark.
$ cat rhel7/product.yml
product: rhel7
full_name: Red Hat Enterprise Linux 7
type: platform
benchmark_root: "../linux_os/guide"
.....
Rules from multiple locations can be used for a single Benchmark. There
is an optional key additional_content_directories
for a list of paths
to some arbitrary Groups of Rules to be included in the benchmark. Note
that the additional directories cannot contain a benchmark file
(benchmark.yml
), otherwise it fails to build the content. Of all the
rules collected only the following would become a part of the benchmark:
rules that have the
prodtype
specified in correspondence with the benchmark;rules that have no
prodtype
metadata.
.....
benchmark_root: "../applications"
additional_content_directories:
- "../linux_os/guide/services"
- "../linux_os/guide/system"
.....
The Benchmarks are organized into directory structure. The directories
represent either groups or rules. The group directories contain
group.yml
and rule directories rule.yml
. The name of the group
directory is the group ID, without the prefix. Similarly, the name of
the rule directory if the rule ID, without the prefix.
For example, the Linux OS Benchmark is structured in this way:
.
├── benchmark.yml
├── intro
│ ├── general-principles
│ ├── group.yml
│ └── how-to-use
├── services
│ ├── apt
│ ├── avahi
│ ├── cron_and_at
│ ├── deprecated
│ ├── dhcp
│ ├── dns
│ ├── ftp
│ ├── group.yml
│ ├── http
│ ├── imap
│ ├── ldap
│ ├── mail
│ ├── nfs_and_rpc
│ .......
│ .......
└── system
├── accounts
├── auditing
├── bootloader-grub2
├── bootloader-grub-legacy
├── entropy
├── group.yml
├── logging
......
Product Structure/Layout¶
When creating a new product, use the guidelines below for the directory layout:
Do not use capital letters
If product versions are required, use major versions only. For example,
rhel7
,ubuntu16
, etc.If the content to be produced does not matter on versions, do not add version numbers. For example:
fedora
,firefox
, etc.In addition, use only a maxdepth of 3 directories.
See the README for more information about the changes needed.
Following these guidelines help with the usability and browsability of using and navigating the content.
For example:
$ tree -d rhel7
rhel7
├── kickstart
├── overlays
├── profiles
└── transforms
7 directories
Product Level Directory Descriptions¶
Directory |
Description |
|
|
|
|
|
|
|
|
Important
For any of the
Required
directories that may not yet add content, add a.gitkeep
file for any empty directories.
Profiles¶
Profiles define the set of rules and variables aligned to a compliance standard.
Structurally, a profile is a YAML file that represents a dictionary. A profile YAML file has one implied attribute:
id
: The primary identifier for the profile, to be referenced during evaluations. This is inferred from the file name.
A profile YAML file can, optionally, include metadata about the implemented policy and experts in the field, called Subject Matter Experts (SMEs). The SMEs usually are people familiar with the policy requirements or how it is applied.
metadata
: Dictionary for profile metadata.reference
: URL pointing to page or organization that publishes the policy.version
: Version of the policy implemented by the profile.SMEs
: List of people experienced with the profile, or how they are applied. The preferred method is the GitHub handle, but email is also accepted.
A profile should define these attributes:
title
: Human-readable title of the profile.description
: Human-readable HTML description, which provides broader context for non-experts than the rationale.extends
: Theid
of a profile to be extended. A profile can make incremental changes based on another profile, viaextends
attribute. The extendee can then, via theselections
attribute, select/unselect rules and change XCCDF Value selectors.selections
: List composed of items of these types:id`s of rules to be included in the profile, e.g. `accounts_tmout
, orid`s of rules to be excluded from the profile prefixed by an exclamation mark, e.g. `!accounts_tmout
, orchanges to XCCDF Value selectors, e.g.
var_accounts_tmout=10_min
, orrule refinements, e.g.
accounts_tmout.severity=high
.