Skip to content

Commit 8df1575

Browse files
macko1macko1
committed
Make comments more accessible for screen readers.
1 parent 9ea7785 commit 8df1575

1 file changed

Lines changed: 144 additions & 8 deletions

File tree

‎shared/templates/grub2_bootloader_argument/oval.template‎

Lines changed: 144 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
LOCATIONS WHERE KERNEL ARGS LIVE (per product):
99
================================================
1010

11+
[VISUAL TABLE: products vs. config file locations, aligned in columns.]
12+
1113
Product Flags Boot entries Persistent config Other
1214
--------------- ---------------------------------- ---------------------------------- ------------------------ ---------------------------
1315
RHEL 9+, Fedora `uses_boot_loader_entries` `/boot/loader/entries/*.conf` `/etc/default/grub` (`bootc`: `kargs.d/*.toml`)
@@ -21,6 +23,31 @@
2123
Ubuntu `uses_grub_cfg` `/boot/grub/grub.cfg` `/etc/default/grub` `/etc/default/grub.d/*.cfg`
2224
`uses_etc_default_grub_d` (args on `vmlinuz` lines)
2325

26+
LONG DESCRIPTION (text equivalent of the table):
27+
28+
RHEL 9+, Fedora:
29+
Flags: `uses_boot_loader_entries`
30+
Boot entries: `/boot/loader/entries/*.conf` (args on `options` line)
31+
Persistent config: `/etc/default/grub`
32+
Other: `bootc` systems use `/usr/lib/bootc/kargs.d/*.toml` instead
33+
34+
RHEL 8, OL8:
35+
Flags: `uses_boot_loader_entries`, `uses_kernelopts`
36+
Boot entries: `/boot/loader/entries/*.conf` (args on `options` line or via
37+
`$kernelopts` indirection from `/boot/grub2/grubenv`)
38+
Persistent config: `/etc/default/grub`
39+
40+
OL7:
41+
Flags: `uses_grub_cfg`
42+
Boot entries: `/boot/grub2/grub.cfg` (args on `vmlinuz` lines)
43+
Persistent config: `/etc/default/grub`
44+
45+
Ubuntu:
46+
Flags: `uses_grub_cfg`, `uses_etc_default_grub_d`
47+
Boot entries: `/boot/grub/grub.cfg` (args on `vmlinuz` lines)
48+
Persistent config: `/etc/default/grub`
49+
Other: `/etc/default/grub.d/*.cfg` (drop-in config files)
50+
2451
WHAT THIS TEMPLATE DOES:
2552
========================
2653

@@ -116,6 +143,9 @@
116143
(`IS bootc` / `NOT bootc`) ensure the wrong branch always fails.
117144
Products without `bootc` support emit only the normal `grub` branch.
118145

146+
[VISUAL TREE: indented AND/OR hierarchy showing the two branches (Image Mode vs.
147+
normal grub) and all sub-checks within the normal grub branch.]
148+
119149
definition (OR) -- passes if EITHER branch matches the system
120150
|
121151
+-- [Image Mode] AND (bootable_containers_supported)
@@ -146,13 +176,49 @@
146176
| (+ `grub.d` drop-in on Ubuntu)
147177
+-- `GRUB_DISABLE_RECOVERY=true`
148178

179+
LONG DESCRIPTION (text equivalent of the criteria tree):
180+
181+
The definition passes (compliant) if EITHER of two branches is true:
182+
183+
Branch 1 -- Image Mode (only emitted when `bootable_containers_supported`):
184+
Both must be true:
185+
- The system IS a `bootc` deployment.
186+
- `/usr/lib/bootc/kargs.d/*.toml` contains `arg=value`.
187+
188+
Branch 2 -- normal grub:
189+
All of the following must be true:
190+
- The system is NOT a `bootc` deployment (guard; only when `bootable_containers_supported`).
191+
- [RHEL 8 / OL8, `uses_kernelopts`]:
192+
EACH `/boot/loader/entries/*.conf` (excluding rescue) has `arg=value`
193+
on its `options` line, OR contains `$kernelopts`.
194+
AND EITHER no entry references `$kernelopts` (so `grubenv` is irrelevant),
195+
OR `{grub2_boot_path}/grubenv` contains `arg=value`.
196+
- [RHEL 9+ / Fedora, `uses_boot_loader_entries` without `uses_kernelopts`]:
197+
EACH `/boot/loader/entries/*.conf` (excluding rescue) has `arg=value`
198+
on its `options` line.
199+
- [OL7 / Ubuntu, `uses_grub_cfg`]:
200+
`{grub2_boot_path}/grub.cfg` has `arg=value` (BIOS path, or UEFI path if separate).
201+
- [all products]:
202+
EITHER `GRUB_CMDLINE_LINUX` in `/etc/default/grub` has `arg=value`
203+
(plus `grub.d` drop-in on Ubuntu),
204+
OR BOTH `GRUB_CMDLINE_LINUX_DEFAULT` has `arg=value`
205+
(plus `grub.d` drop-in on Ubuntu)
206+
AND `GRUB_DISABLE_RECOVERY=true`.
207+
208+
Only the sub-checks relevant to the product (controlled by `uses_*` flags) are emitted.
209+
Branches 1 and 2 are mutually exclusive at runtime due to the `IS bootc` / `NOT bootc` guards.
210+
149211
DATA FLOW:
150212
==========
151213

152214
Each object extracts the FULL line (or array) as `subexpression`.
153215
Each state uses `pattern match` to check if `arg=value` appears in that captured text.
154216
All `grub`-location tests share one state; `bootc` has its own (quotes around value).
155217

218+
[VISUAL DIAGRAM: 6 object boxes on the left (one per config file location) with
219+
arrows pointing to 3 state boxes on the right (shared grub state, bootc state,
220+
and kernelopts state). Shows which objects feed which states.]
221+
156222
OBJECTS STATES
157223
═══════ ══════
158224

@@ -211,16 +277,86 @@
211277
(uses_kernelopts) -- additional state used with `state_operator="OR"`:
212278
┌─ state_grub2_{ARG}_argument_is_kernelopts ─┐
213279
│ ^(?:.*\s)?\$kernelopts(?:\s.*)?$ │
214-
│ Matches `$kernelopts` as a word. │
215-
│ The RHEL 8 BLS test references BOTH │
216-
│ `state_argument` and this state with OR: │
217-
│ entry passes if it has arg=value OR │
218-
│ contains `$kernelopts`. │
219-
│ (Same flag as the `grubenv` object -- │
220-
│ both exist only when `$kernelopts` │
221-
│ indirection is in play.) │
280+
│ │
281+
│ Pattern match: is `$kernelopts` present │
282+
│ as a standalone word in the captured │
283+
│ `options` line from │
284+
│ `/boot/loader/entries/*.conf`? │
285+
│ │
286+
│ The RHEL 8 BLS test applies BOTH │
287+
│ `state_grub2_{ARG}_argument` and this │
288+
│ state with `state_operator="OR"`: │
289+
│ an entry passes if its `options` line │
290+
│ contains `{ARG_NAME_VALUE}` OR contains │
291+
│ `$kernelopts`. │
292+
│ │
293+
│ Same `uses_kernelopts` flag as the │
294+
│ `{grub2_boot_path}/grubenv` object -- │
295+
│ both exist only on RHEL 8 / OL8. │
222296
└─────────────────────────────────────────────┘
223297

298+
LONG DESCRIPTION (text equivalent of the diagram; same information, no box-drawing):
299+
──────────────────────────────────────────────────────────────────────────────────────
300+
301+
There are 6 objects (data collectors) and 3 states (pass/fail conditions).
302+
303+
OBJECTS -- each extracts a line of text from a config file:
304+
305+
A. `/boot/loader/entries/*.conf` (flag: `uses_boot_loader_entries`)
306+
OVAL element: `<ind:path>` + `<ind:filename operation="pattern match">`
307+
Pattern: `^options (.*)$` -- captures the kernel arg list after `options `.
308+
Filter: excludes filenames matching `*rescue.conf`.
309+
Tested against: `state_grub2_{ARG}_argument`.
310+
311+
B. `{grub2_boot_path}/grubenv` (flag: `uses_kernelopts`)
312+
OVAL element: `<ind:filepath>`
313+
Pattern: `^kernelopts=(.*)$` -- captures the arg list after `kernelopts=`.
314+
Tested against: `state_grub2_{ARG}_argument`.
315+
316+
C. `{grub2_boot_path}/grub.cfg` (flag: `uses_grub_cfg`)
317+
OVAL element: `<ind:filepath>`
318+
Pattern: `^.*/vmlinuz.*(root=.*)$` -- captures from `root=` to end of line.
319+
Tested against: `state_grub2_{ARG}_argument`.
320+
321+
D. `/etc/default/grub` (all products)
322+
OVAL element: `<ind:filepath>`
323+
Pattern: `^\s*GRUB_CMDLINE_LINUX="(.*)"$` -- captures contents between quotes.
324+
Same pattern repeated for `GRUB_CMDLINE_LINUX_DEFAULT`.
325+
Tested against: `state_grub2_{ARG}_argument`.
326+
327+
E. `/etc/default/grub.d/*.cfg` (flag: `uses_etc_default_grub_d` / Ubuntu)
328+
OVAL element: `<ind:filepath operation="pattern match">`
329+
Pattern: same as D.
330+
Same pattern repeated for `GRUB_CMDLINE_LINUX_DEFAULT`.
331+
Tested against: `state_grub2_{ARG}_argument`.
332+
333+
F. `/usr/lib/bootc/kargs.d/*.toml` (flag: `bootable_containers_supported`)
334+
OVAL element: `<ind:path>` + `<ind:filename operation="pattern match">`
335+
Pattern: `^kargs = \[([^\]]+)\]$` -- captures array contents between brackets.
336+
Tested against: `state_grub2_{ARG}_usr_lib_bootc_kargs_d`.
337+
338+
STATES -- each applies a regex to the captured text:
339+
340+
1. `state_grub2_{ARG}_argument` (shared by objects A through E)
341+
Regex: `^(?:.*\s)?{ARG_NAME_VALUE}(?:\s.*)?$`
342+
Question: is `{ARG_NAME_VALUE}` present as a standalone word (bounded by
343+
whitespace or start/end of string)?
344+
When `ARG_VARIABLE` is set, the regex is assembled at runtime: `oscap` reads
345+
the value from the `XCCDF` profile, a `local_variable` concatenates it into
346+
the regex pattern, and the state references it via `var_ref`.
347+
348+
2. `state_grub2_{ARG}_usr_lib_bootc_kargs_d` (used by object F only)
349+
Regex: `^.*"{ARG_NAME_VALUE}".*$`
350+
Question: is `"{ARG_NAME_VALUE}"` present anywhere (with surrounding quotes,
351+
as per `TOML` syntax)?
352+
353+
3. `state_grub2_{ARG}_argument_is_kernelopts` (flag: `uses_kernelopts`)
354+
Regex: `^(?:.*\s)?\$kernelopts(?:\s.*)?$`
355+
Question: is `$kernelopts` present as a standalone word?
356+
Used ONLY by the RHEL 8 BLS test, which applies both state 1 and state 3
357+
with `state_operator="OR"`: an entry passes if it contains `{ARG_NAME_VALUE}`
358+
OR contains `$kernelopts`.
359+
224360
REGEX SEMANTICS (what each `pattern` captures as `subexpression`):
225361
─────────────────────────────────────────────────────────────────
226362

0 commit comments

Comments
 (0)