Add documentation of the steps that OVAL content goes through during the build #11336

Honny1 · 2023-12-04T12:59:44Z

This PR documents the steps the OVAL content goes through during the build.

…during build

openshift-ci · 2023-12-04T12:59:55Z

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

github-actions · 2023-12-04T13:01:04Z

Start a new ephemeral environment with changes proposed in this pull request:

Fedora Environment

Oracle Linux 8 Environment

Mab879

Thanks for the docs addition, however I do have a couple of comments.

Mab879 · 2023-12-04T13:08:26Z

docs/manual/developer/07_understanding_build_system.md

@@ -86,6 +86,13 @@ of occurrence:
 - Generate content for derived products (such as CentOS and Scientific Linux).
 - Generate HTML tables, Bash scripts, Ansible Playbooks and other secondary artifacts.

+## How OVAL is build


Suggested change

## How OVAL is build

## How OVAL is Built

Title case per the style guide and consider change the tense for clarity.

Mab879 · 2023-12-04T13:16:58Z

docs/manual/developer/07_understanding_build_system.md

@@ -86,6 +86,13 @@ of occurrence:
 - Generate content for derived products (such as CentOS and Scientific Linux).
 - Generate HTML tables, Bash scripts, Ansible Playbooks and other secondary artifacts.

+## How OVAL is build
+
+Creating OVAL checks is done in two steps. First, all available OVAL checks are combined into a one unlinked OVAL document. The OVAL shorthands are loaded into the OVAL Document object and, in the case of template shorthand, extended using jinja macros before loading. If the shorthand is already loaded into the OVAL Document object, it is skipped. Shorthands are loaded in the order that benchmark checks are loaded first, followed by shared directory checks.


Per the style guide please have one sentence per line.

jan-cerny

I expect this to be more verbose and detailed.

You have recognized two major steps of the process. But, I would like to see to split them into more granular substeps.

As you describe a sequence of steps, I think a form of numbered list can be used to describe the process of processing OVALs. You can use a list with nested lists.

I have add some helpful questions below that will help you with extending the text.

jan-cerny · 2023-12-04T13:17:51Z

docs/manual/developer/07_understanding_build_system.md

@@ -86,6 +86,13 @@ of occurrence:
 - Generate content for derived products (such as CentOS and Scientific Linux).
 - Generate HTML tables, Bash scripts, Ansible Playbooks and other secondary artifacts.

+## How OVAL is build


Suggested change

## How OVAL is build

## How OVAL is built

jan-cerny · 2023-12-04T13:20:23Z

docs/manual/developer/07_understanding_build_system.md

@@ -86,6 +86,13 @@ of occurrence:
 - Generate content for derived products (such as CentOS and Scientific Linux).
 - Generate HTML tables, Bash scripts, Ansible Playbooks and other secondary artifacts.

+## How OVAL is build
+
+Creating OVAL checks is done in two steps. First, all available OVAL checks are combined into a one unlinked OVAL document. The OVAL shorthands are loaded into the OVAL Document object and, in the case of template shorthand, extended using jinja macros before loading. If the shorthand is already loaded into the OVAL Document object, it is skipped. Shorthands are loaded in the order that benchmark checks are loaded first, followed by shared directory checks.


This is against the style guide. There should be one sentence per line.

jan-cerny · 2023-12-04T13:21:21Z

docs/manual/developer/07_understanding_build_system.md

@@ -86,6 +86,13 @@ of occurrence:
 - Generate content for derived products (such as CentOS and Scientific Linux).
 - Generate HTML tables, Bash scripts, Ansible Playbooks and other secondary artifacts.

+## How OVAL is build
+
+Creating OVAL checks is done in two steps. First, all available OVAL checks are combined into a one unlinked OVAL document. The OVAL shorthands are loaded into the OVAL Document object and, in the case of template shorthand, extended using jinja macros before loading. If the shorthand is already loaded into the OVAL Document object, it is skipped. Shorthands are loaded in the order that benchmark checks are loaded first, followed by shared directory checks.


I want information about which scripts perform each of these actions.

jan-cerny · 2023-12-04T13:22:30Z

docs/manual/developer/07_understanding_build_system.md

+Creating OVAL checks is done in two steps. First, all available OVAL checks are combined into a one unlinked OVAL document. The OVAL shorthands are loaded into the OVAL Document object and, in the case of template shorthand, extended using jinja macros before loading. If the shorthand is already loaded into the OVAL Document object, it is skipped. Shorthands are loaded in the order that benchmark checks are loaded first, followed by shared directory checks.
+
+The second step is to link the generated document from the previous step with the XCCDF document.
+The unlinked OVAL document is loaded into the OVAL Document object while the XML file is being loaded into the object instance. Validation of the OVAL document is performed during and after loading (for example, whether all the checks listed in the XCCDF are present in the OVAL document). After validation of the OVAL document, the IDs are converted to valid OVAL IDs. The OVAL document is then saved as an XML file. During saving, a minimal OVAL document is generated for each rule as an artifact. The last step is to link the file to the XCCDF document.


Which XML file is being loaded into the object instance?

Can you elaborate more on the validation step?

Where is the "minimal OVAL document" stored?

What does it take "to link the file to the XCCDF"? What is difference between linked and unlinked document?

Which script performs this step?

Honny1 · 2023-12-07T17:08:57Z

I fixed the style and rewrote the description of the steps the OVAL content goes through during build.

jan-cerny · 2023-12-08T09:37:28Z

/packit retest failed

jan-cerny · 2023-12-08T09:38:15Z

docs/manual/developer/07_understanding_build_system.md

+
+### 1. Combination of OVALs
+
+In the first step, all available and applicable for platform OVAL checks are builded into a single unlinked OVAL document stored in the `build/${PRODUCT}/oval-unlinked.xml` directory.


Suggested change

In the first step, all available and applicable for platform OVAL checks are builded into a single unlinked OVAL document stored in the `build/${PRODUCT}/oval-unlinked.xml` directory.

In the first step, all available and applicable OVAL checks are built into a single unlinked OVAL document stored in the `build/${PRODUCT}/oval-unlinked.xml` directory.

jan-cerny · 2023-12-08T09:39:08Z

docs/manual/developer/07_understanding_build_system.md

+
+In the first step, all available and applicable for platform OVAL checks are builded into a single unlinked OVAL document stored in the `build/${PRODUCT}/oval-unlinked.xml` directory.
+The `oval-unlinked.xml` document is generated using the `combine_ovals.py` script.
+The OVAL shortcuts are loaded into the OVAL Document object in the order that the benchmark checks are loaded first, followed by the shared directory checks.


What are shortcuts? It's a new term here

jan-cerny · 2023-12-08T09:40:01Z

docs/manual/developer/07_understanding_build_system.md

+
+Steps of loading the OVAL shorthand:
+
+1. The OVAL Shorthand file is loaded as a string, and in the case of templated Shorthand, it is expanded using Jinja macros before loading.


Shouldn't it be the opposite?

Suggested change

1. The OVAL Shorthand file is loaded as a string, and in the case of templated Shorthand, it is expanded using Jinja macros before loading.

1. The OVAL Shorthand file is loaded as a string, and in the case of not templated Shorthand, it is expanded using Jinja macros before loading.

jan-cerny · 2023-12-08T09:40:55Z

docs/manual/developer/07_understanding_build_system.md

+2. The OVAL Shorthand string is processed by the OVAL Document object.
+   1. The OVAL Shorthand string is loaded into the OVAL Shorthand object.
+   2. the OVAL Shorthand object is validated
+      It is checked:


Suggested change

It is checked:

The following properties are checked:

jan-cerny · 2023-12-08T09:43:01Z

docs/manual/developer/07_understanding_build_system.md

+4. The OVAL definition referenced by the XCCDF is checked to be defined in the OVAL document.
+5. Verify if `<xccdf:Value>` `type` to corresponding OVAL variable `datatype` export matching [constraint](http://csrc.nist.gov/publications/nistpubs/800-126-rev2/SP800-126r2.pdf#page=30&zoom=auto,69,313) is met.
+   Also correct the `type` attribute of those `<xccdf:Value>` elements where necessary in order the produced content to meet this constraint.
+6. verify that the referenced CCE identifiers are correct


Suggested change

6. verify that the referenced CCE identifiers are correct

6. Verify that the referenced CCE identifiers are correct.

jan-cerny · 2023-12-08T09:43:12Z

docs/manual/developer/07_understanding_build_system.md

+5. Verify if `<xccdf:Value>` `type` to corresponding OVAL variable `datatype` export matching [constraint](http://csrc.nist.gov/publications/nistpubs/800-126-rev2/SP800-126r2.pdf#page=30&zoom=auto,69,313) is met.
+   Also correct the `type` attribute of those `<xccdf:Value>` elements where necessary in order the produced content to meet this constraint.
+6. verify that the referenced CCE identifiers are correct
+7. translate the identifiers in the OVAL Document object using `IDTranslator`.


Suggested change

7. translate the identifiers in the OVAL Document object using `IDTranslator`.

7. Translate the identifiers in the OVAL Document object using `IDTranslator`.

jan-cerny · 2023-12-08T09:43:23Z

docs/manual/developer/07_understanding_build_system.md

+6. verify that the referenced CCE identifiers are correct
+7. translate the identifiers in the OVAL Document object using `IDTranslator`.
+8. The OVAL Document object is stored as an XML file `build/ssg-${PRODUCT}-oval.xml`.
+9. for each XCCDF rule, a minimal OVAL Documents document is generated as an artifact


Suggested change

9. for each XCCDF rule, a minimal OVAL Documents document is generated as an artifact

9. For each XCCDF rule, a minimal OVAL Documents document is generated as an artifact.

jan-cerny · 2023-12-08T09:43:43Z

docs/manual/developer/07_understanding_build_system.md

+10. The last step is to link the XCCDF document
+    - For each reference of OVAL check in XCCDF, a link to the check content and a check export element is added.


Suggested change

10. The last step is to link the XCCDF document

- For each reference of OVAL check in XCCDF, a link to the check content and a check export element is added.

10. For each reference of OVAL check in XCCDF, a link to the `check-content` and a `check-export` element is added.

jan-cerny · 2023-12-08T09:46:36Z

docs/manual/developer/07_understanding_build_system.md

+### 2. Linking OVAL Document
+
+The second step is performed when building an XCCDF document using the `build_xccdf.py` script.
+In this step, the `oval-unlinked.xml` document from the previous step is linked to the XCCDF document being built.


It would be great to explain that in this context the term "linking" means alignment of IDs between rules and checks.

jan-cerny · 2023-12-08T09:47:05Z

docs/manual/developer/07_understanding_build_system.md

+1. The OVAL Shorthand file is loaded as a string, and in the case of templated Shorthand, it is expanded using Jinja macros before loading.
+2. The OVAL Shorthand string is processed by the OVAL Document object.
+   1. The OVAL Shorthand string is loaded into the OVAL Shorthand object.
+   2. the OVAL Shorthand object is validated


Suggested change

2. the OVAL Shorthand object is validated

2. The OVAL Shorthand object is validated.

Honny1 · 2023-12-10T18:51:30Z

@jan-cerny I've incorporated your comments.

codeclimate · 2023-12-10T18:59:59Z

Code Climate has analyzed commit 6efad1c and detected 0 issues on this pull request.

The test coverage on the diff in this pull request is 100.0% (50% is the threshold).

This pull request will bring the total coverage in the repository to 58.5%.

View more on Code Climate.

jan-cerny · 2023-12-11T09:37:27Z

/packit retest-failed

jan-cerny

This is a well-written, understandable and concise.

jan-cerny · 2023-12-11T10:10:38Z

The testing farm problem on Fedora 39 is an infrastructure problem. This PR changes only the documentation, so I think the PR is harmless.

Add documentation of the actual steps that OVAL content goes through …

02d5c1b

…during build

openshift-ci bot added the do-not-merge/work-in-progress Used by openshift-ci bot. label Dec 4, 2023

Honny1 added Documentation Update in project documentation. OVAL OVAL update. Related to the systems assessments. Infrastructure Our content build system labels Dec 4, 2023

Honny1 marked this pull request as ready for review December 4, 2023 13:02

openshift-ci bot removed the do-not-merge/work-in-progress Used by openshift-ci bot. label Dec 4, 2023

Mab879 requested changes Dec 4, 2023

View reviewed changes

jan-cerny reviewed Dec 4, 2023

View reviewed changes

jan-cerny added this to the 0.1.72 milestone Dec 4, 2023

jan-cerny self-assigned this Dec 4, 2023

Honny1 added 2 commits December 4, 2023 15:03

Fix style guide

5eb589a

Move section to bottom of document

6be3900

Honny1 requested review from Mab879 and jan-cerny December 7, 2023 12:01

jan-cerny reviewed Dec 8, 2023

View reviewed changes

Correction of step descriptions

6efad1c

Honny1 force-pushed the docs-build-of-content branch from f91b141 to 6efad1c Compare December 10, 2023 18:47

jan-cerny approved these changes Dec 11, 2023

View reviewed changes

jan-cerny merged commit f4b0412 into ComplianceAsCode:master Dec 11, 2023
32 of 33 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation of the steps that OVAL content goes through during the build #11336

Add documentation of the steps that OVAL content goes through during the build #11336

Honny1 commented Dec 4, 2023

openshift-ci bot commented Dec 4, 2023

github-actions bot commented Dec 4, 2023

Mab879 left a comment

Mab879 Dec 4, 2023

Mab879 Dec 4, 2023

jan-cerny left a comment

jan-cerny Dec 4, 2023

jan-cerny Dec 4, 2023

jan-cerny Dec 4, 2023

jan-cerny Dec 4, 2023

jan-cerny Dec 4, 2023

jan-cerny Dec 4, 2023

jan-cerny Dec 4, 2023

jan-cerny Dec 4, 2023

Honny1 commented Dec 7, 2023

jan-cerny commented Dec 8, 2023

jan-cerny Dec 8, 2023

jan-cerny Dec 8, 2023

jan-cerny Dec 8, 2023

jan-cerny Dec 8, 2023

jan-cerny Dec 8, 2023

jan-cerny Dec 8, 2023

jan-cerny Dec 8, 2023

jan-cerny Dec 8, 2023

jan-cerny Dec 8, 2023

jan-cerny Dec 8, 2023

Honny1 commented Dec 10, 2023

codeclimate bot commented Dec 10, 2023

jan-cerny commented Dec 11, 2023

jan-cerny left a comment

jan-cerny commented Dec 11, 2023


		### 1. Combination of OVALs

		In the first step, all available and applicable for platform OVAL checks are builded into a single unlinked OVAL document stored in the `build/${PRODUCT}/oval-unlinked.xml` directory.


		Steps of loading the OVAL shorthand:

		1. The OVAL Shorthand file is loaded as a string, and in the case of templated Shorthand, it is expanded using Jinja macros before loading.

	6. verify that the referenced CCE identifiers are correct
	6. Verify that the referenced CCE identifiers are correct.

	7. translate the identifiers in the OVAL Document object using `IDTranslator`.
	7. Translate the identifiers in the OVAL Document object using `IDTranslator`.

	9. for each XCCDF rule, a minimal OVAL Documents document is generated as an artifact
	9. For each XCCDF rule, a minimal OVAL Documents document is generated as an artifact.

		10. The last step is to link the XCCDF document
		- For each reference of OVAL check in XCCDF, a link to the check content and a check export element is added.

	10. The last step is to link the XCCDF document
	- For each reference of OVAL check in XCCDF, a link to the check content and a check export element is added.
	10. For each reference of OVAL check in XCCDF, a link to the `check-content` and a `check-export` element is added.

	2. the OVAL Shorthand object is validated
	2. The OVAL Shorthand object is validated.

Add documentation of the steps that OVAL content goes through during the build #11336

Add documentation of the steps that OVAL content goes through during the build #11336

Conversation

Honny1 commented Dec 4, 2023

openshift-ci bot commented Dec 4, 2023

github-actions bot commented Dec 4, 2023

Mab879 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jan-cerny left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Honny1 commented Dec 7, 2023

jan-cerny commented Dec 8, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Honny1 commented Dec 10, 2023

codeclimate bot commented Dec 10, 2023

jan-cerny commented Dec 11, 2023

jan-cerny left a comment

Choose a reason for hiding this comment

jan-cerny commented Dec 11, 2023