Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 4 commits into from
Dec 11, 2023
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/manual/developer/07_understanding_build_system.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## How OVAL is build
## How OVAL is Built

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## How OVAL is build
## How OVAL is built


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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per the style guide please have one sentence per line.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which XML file is being loaded into the object instance?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you elaborate more on the validation step?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is the "minimal OVAL document" stored?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which script performs this step?


### Python Build Scripts

Various Python utilities under `/build-scripts` contribute to this process;
Expand Down