Skip to content

feat(exporters): read the CCI mapping file a style names - #56

Merged
aaronlippold merged 2 commits into
nextfrom
feat/style-cci-mapping-file
Nov 17, 2026
Merged

aaronlippold merged 2 commits into
nextfrom
feat/style-cci-mapping-file

Conversation

@aaronlippold

Copy link
Copy Markdown
Member

Since the first release, the DISA style has named a CIS-to-CCI mapping file (ident.cci_lookup.mapping_file), the docs have shown it, and CCILookupService was built to load any mapping file. But the engine always used one shared service built with no file, so a style's mapping file was never read. This PR builds what was intended: the mapping file a style names is the one its CCI lookup reads. A style can now use its own mapping, for example one keyed by another CIS Controls version, or an organization's own.

Behaviour

  • Which file is read. The file named by a style's ident mapping in cci_lookup.mapping_file gives the CCIs. A style that names none reads the bundled src/cis_bench/data/cis-cci-mapping.json.
  • How a path resolves. A relative path is resolved against the folder of the style file that writes it, when that file loads and before it is merged, as extends is. compose-go resolves relative paths per file the same way. An absolute path is used as written.
  • Read once. cci_service_for(path) keeps one lookup per resolved path (functools.cache); get_cci_service() is the bundled file's.
  • Bad files are refused. A mapping file is validated against a pydantic model of its entries, matching the bundled file's shape, with extra keys such as reasoning kept. A file that doesn't exist, isn't JSON, or has entries of the wrong shape stops the load with an error naming the style and the mapping file.
  • Shipped styles. They name no mapping file. disa.yaml's mapping_file: "data/cis-cci-mapping.json" only seemed to work because it was never read; resolved against the styles folder, it points at a file that doesn't exist.

Docs

mapping-engine-guide.md, yaml-config-reference.md and xccdf-styles.md describe mapping_file, how a relative path resolves, and the default.

Verification

  • pytest tests/: 2715 passed. pytest tests/scripts: 53 passed. mypy, ruff check, ruff format --check and mkdocs build --strict are clean.
  • 28 XCCDF exports (9 cached benchmarks and 5 synthetic fixtures, DISA and CIS styles) are byte-identical to the exports before this branch, and cis-bench validate passes on all 28.
  • Live check: a DISA export of a cached benchmark, through a style naming a copy of the bundled mapping with safeguard 4.8's primary CCI changed to CCI-999999, carries CCI-999999 on all 43 Rules citing 4.8, and validates.

Since the first release the DISA style named ident.cci_lookup.mapping_file
and CCILookupService could load any mapping file, but the engine always
took one shared service built with no file, so a style could not use a
CIS-to-CCI mapping of its own.

The mapping file a style's ident mapping names is now the one its CCI
lookup reads. A relative path is resolved against the folder of the style
file that writes it, when that file loads and before it is merged (as
extends is; compose-go resolves relative paths per file the same way);
an absolute path is used as written. cci_service_for keeps one lookup per
resolved path (functools.cache); get_cci_service is the bundled file's.
A mapping file that cannot be read, or is not a list of safeguard
entries, stops the load with an error naming the style and the file.

The shipped styles name no mapping file: disa.yaml's line pointed at the
bundled file through a path that only worked because it was never read.
Exports are unchanged.

Signed-off-by: Aaron Lippold <lippold@gmail.com>
…s entries

The shape check covered only the outer list: an OFFICIAL entry whose
primary_cci was text passed it and raised AttributeError, with neither
the style nor the mapping file named. The entries are now described
once (_MappingEntry, _MappedCci, strict, extra keys such as reasoning
kept) and validated with pydantic; its ValidationError is a ValueError,
so the engine names the style and the mapping file. The reader of
OFFICIAL entries reads the models; what it gives is unchanged.

Signed-off-by: Aaron Lippold <lippold@gmail.com>
@aaronlippold
aaronlippold merged commit 2116156 into next Nov 17, 2026
7 checks passed
@aaronlippold
aaronlippold deleted the feat/style-cci-mapping-file branch November 17, 2026 03:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant