diff --git a/docs/manual/developer/03_creating_content.md b/docs/manual/developer/03_creating_content.md index bcddf4851c8..07b0c1eb1f5 100644 --- a/docs/manual/developer/03_creating_content.md +++ b/docs/manual/developer/03_creating_content.md @@ -1072,16 +1072,16 @@ 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: @@ -1089,6 +1089,20 @@ For example, to instruct the build system to use the control file to automatical 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