Skip to content

Commit

Permalink
Reword and extend documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
jan-cerny committed Feb 6, 2024
1 parent 4a5f0a2 commit 97ca654
Showing 1 changed file with 20 additions and 6 deletions.
26 changes: 20 additions & 6 deletions docs/manual/developer/03_creating_content.md
Original file line number Diff line number Diff line change
Expand Up @@ -1072,23 +1072,37 @@ controls:
- other-policy:other-control
```

### Using controls to add references to rules
### Using Controls for Automated Reference Assignment to Rules

Naturally, control files map requirements of a given policy to individual rules.
That is a reverse mapping to what the `references` key in rules is used for.
Control files inherently establish the correspondence between the requirements of a specified policy and individual rules.
That represents a reverse mapping compared to the function of the `references` key in `rule.yml` files.
The `references` key in `rule.yml` maps the rule to a requirement of an external policy.
If a control file is used to map the policy requirements, then the references don't need to be specified in `rule.yml`.
The build system is able to assign the references to rules automatically at the build time.
This feature of the build system saves time and avoids data duplication, because the references are specified in a single place which is the control file, and they are not specified in `rule.yml` files.
Instead, the build system is able to assign the references to rules automatically at the build time.
This feature of the build system saves time and avoids data duplication, because the references are centralized in the control file, and they are not specified in `rule.yml` files.
To use the automated reference assignement, the `reference_type` key must be added to the control file.
The value of this key is the type of reference that will be assigned.
The value of this key represents the type of reference that will be assigned.

For example, to instruct the build system to use the control file to automatically assign `anssi` references to all rules listed in the control file, add the following line to the control file:

```
reference_type: anssi
```

The usage of `reference_type` key results in adding a reference to all rules in that control file across all products.
This is a useful behavior for the control files that represent a product agnostic policy, for example ANSSI.
However, some policies, for example CIS Benchmarks, are specific for a single product, so we represent them by separate control files, eg. `cis_rhel8.yml` and `cis_rhel9.yml`.
These files define the same `reference_type`.
To ensure the correct reference source for a given product we need to label the control file as product-specific.
Product-specific control files need to have the `product` key set.

For example, to instruct the build system to automatically assign `cis` references to all rules listed in the control file when building the `rhel9` product, include the following lines to the control file:

```
product: rhel9
reference_type: cis
```

### Using controls in profiles

Later, we can use the policy requirements in profile YAML. Let's say that we
Expand Down

0 comments on commit 97ca654

Please sign in to comment.