Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/developer-guide/mapping-engine-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -423,7 +423,7 @@ target_element: "ident"
multiple: true
cci_lookup:
enabled: true
mapping_file: "data/cis-cci-mapping.json"
mapping_file: "my-cci-mapping.json" # optional: relative to this style file; the bundled mapping when left out
source_field: "cis_controls" # Look up CCIs from CIS Controls
extract: "all" # "all" or "primary"
deduplicate_nist: true # Write cited NIST controls as references unless a CCI restates them
Expand Down
4 changes: 4 additions & 0 deletions docs/technical-reference/xccdf-styles.md
Original file line number Diff line number Diff line change
Expand Up @@ -369,6 +369,10 @@ Avoid duplicating NIST control references when CCIs already provide that mapping

### The mapping file

The CCI lookup reads `src/cis_bench/data/cis-cci-mapping.json` unless the style's `ident`
mapping names another file with `cci_lookup.mapping_file` (relative to the style file that
writes it). A style's own file has the same shape as this one.

`src/cis_bench/data/cis-cci-mapping.json` maps each CIS Controls v8 safeguard (`cis_id`,
"4.8") to DISA CCIs: a `primary_cci` and up to three `supporting_ccis`, each with its
`cci`, `confidence`, `reasoning` and `nist_control` (the CCI's NIST SP 800-53 Rev 5 index
Expand Down
9 changes: 8 additions & 1 deletion docs/technical-reference/yaml-config-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -361,7 +361,7 @@ multiple: true # Create multiple <ident> elements
source_logic: "cci_lookup_with_deduplication"
cci_lookup:
enabled: true
mapping_file: "data/cis-cci-mapping.json"
mapping_file: "my-cci-mapping.json" # optional: relative to this style file
source_field: "cis_controls"
cis_controls_version: 8 # the CIS Controls version the mapping file is keyed by
extract: "all" # every CCI of the safeguard, primary first ("primary": only the first)
Expand All @@ -375,6 +375,13 @@ shipped `cis-cci-mapping.json` is keyed by v8). Only a rule's controls of that v
looked up: v7 reuses the same numbers for unrelated safeguards. A rule with no control of
that version gets `fallback_cci`. Without the key, every control is looked up.

`mapping_file` names the CIS-CCI mapping file the lookup reads, in the shape of the bundled
`src/cis_bench/data/cis-cci-mapping.json` (see [XCCDF styles](xccdf-styles.md#the-mapping-file)).
A relative path is relative to the style file that writes it, as `extends` is; an absolute
path is used as written. Without the key, the bundled file is read; the shipped styles name
none. A file that does not exist, or is not a list of safeguard entries, stops the export
with an error naming the style and the file.

The NIST controls no CCI on the rule covers are written as references by a field with
`source_logic: "nist_after_cci_deduplication"` (the DISA style's `reference`); each reference carries the `dc_elements` the field names (`dc:title`
"NIST SP 800-53" and `dc:identifier`). A `dublin_core` field with any other `source_logic`
Expand Down
3 changes: 2 additions & 1 deletion src/cis_bench/exporters/configs/styles/disa.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,8 @@ field_mappings:
source_logic: "cci_lookup_with_deduplication"
cci_lookup:
enabled: true
mapping_file: "data/cis-cci-mapping.json"
# mapping_file: the bundled CIS-CCI mapping (src/cis_bench/data/cis-cci-mapping.json)
# is read unless a style names its own, relative to that style's file
source_field: "cis_controls"
cis_controls_version: 8 # the mapping file is keyed by CIS Controls v8 only
extract: "all" # every CCI the mapping gives the safeguard, primary first; "primary" keeps only the first
Expand Down
56 changes: 50 additions & 6 deletions src/cis_bench/exporters/mapping_engine.py
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@
from cis_bench.exporters.style_config import (
check_mergeable,
extended_style,
file_name,
validate_style,
)
from cis_bench.models.benchmark import (
Expand All @@ -58,7 +59,7 @@

# Import XCCDF types for element creation (XCCDF 1.2 - for type hints only)
# Note: Engine dynamically loads version-specific types based on config
from cis_bench.utils.cci_lookup import get_cci_service
from cis_bench.utils.cci_lookup import CCILookupService, cci_service_for
from cis_bench.utils.xml_utils import ncname_slug

# Set up logger
Expand Down Expand Up @@ -240,7 +241,7 @@ def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any
return result

@staticmethod
def _chain(config_path: Path, loading_stack: list[Path]) -> list[tuple[str, dict[str, Any]]]:
def _chain(config_path: Path, loading_stack: list[Path]) -> list[tuple[Path, dict[str, Any]]]:
"""The files of a style's extends chain as written, root first. Only extends is read
to find a file's parent; nothing else is checked here.

Expand All @@ -265,15 +266,29 @@ def _chain(config_path: Path, loading_stack: list[Path]) -> list[tuple[str, dict
raise ValueError(f"{config_path.name}: not valid YAML: {error}") from error
if not isinstance(config_data, dict):
raise ValueError(f"{config_path.name}: a style is a mapping of sections")
earlier: list[tuple[str, dict[str, Any]]] = []
earlier: list[tuple[Path, dict[str, Any]]] = []
extends = extended_style(config_data)
if extends is not None:
extends_path = Path(extends)
# Resolve relative to current file's directory
if not extends_path.is_absolute():
extends_path = config_path.parent / extends_path
earlier = ConfigLoader._chain(extends_path, [*loading_stack, config_path])
return [*earlier, (config_path.name, config_data)]
return [*earlier, (config_path, config_data)]

@staticmethod
def _resolve_relative_paths(config_path: Path, config_data: dict[str, Any]) -> None:
"""Make a relative CCI mapping file a field mapping names (cci_lookup.mapping_file)
relative to the folder of the style file that writes it, before the file is merged,
as extends is; compose-go resolves relative paths per file the same way. A value
that is no file name is left for validation to report."""
for mapping in (config_data.get("field_mappings") or {}).values():
lookup = mapping.get("cci_lookup") if isinstance(mapping, dict) else None
if not isinstance(lookup, dict):
continue
name = file_name(lookup.get("mapping_file"))
if name is not None and not Path(name).is_absolute():
lookup["mapping_file"] = str((config_path.parent / name).resolve())

@staticmethod
def load(config_path: Path) -> MappingConfig:
Expand All @@ -298,8 +313,10 @@ def load(config_path: Path) -> MappingConfig:
FileNotFoundError: If config file not found
"""
config_data: dict[str, Any] = {}
for name, written in ConfigLoader._chain(config_path, []):
for path, written in ConfigLoader._chain(config_path, []):
name = path.name
check_mergeable(name, written)
ConfigLoader._resolve_relative_paths(path, written)
extends = {"extends": written["extends"]} if "extends" in written else {}
config_data = ConfigLoader._deep_merge(
config_data, {key: value for key, value in written.items() if key != "extends"}
Expand Down Expand Up @@ -473,7 +490,7 @@ def __init__(self, config_path: Path):
self._refuse_unknown_field_names()
self._refuse_unknown_transforms()
self._refuse_invalid_embedded_tags()
self.cci_service = get_cci_service()
self.cci_service = self._cci_service(config_path)

# Dynamically load XCCDF models based on config version
xccdf_version = self.config.metadata.get("xccdf_version", "1.2")
Expand Down Expand Up @@ -850,6 +867,33 @@ def create_embedded_xml_tags(
parts.append(etree.tostring(element, encoding="unicode"))
return "".join(parts)

def _cci_service(self, config_path: Path) -> CCILookupService:
"""The CCI lookup of the mapping file the style's ident mapping names
(cci_lookup.mapping_file, resolved against the style file that wrote it when the
style loaded), or of the bundled mapping file when it names none.

Raises:
ValueError: The mapping file is no file name, cannot be read, or is not a CCI
mapping file; the error names the style and the mapping file.
"""
ident = self.config.field_mappings.get("ident")
lookup = ident.get("cci_lookup") if isinstance(ident, dict) else None
written = lookup.get("mapping_file") if isinstance(lookup, dict) else None
if written is None:
return cci_service_for()
name = file_name(written)
if name is None:
raise ValueError(
f"{config_path.name}: ident.cci_lookup.mapping_file must name a file, "
f"not {written!r}"
)
try:
return cci_service_for(Path(name))
except (OSError, ValueError) as error:
raise ValueError(
f"{config_path.name}: ident.cci_lookup.mapping_file {name}: {error}"
) from error

def get_ccis_with_deduplication(self, rec: Recommendation) -> tuple[list[str], list[str]]:
"""Get CCIs and extra NIST controls using deduplication.

Expand Down
16 changes: 11 additions & 5 deletions src/cis_bench/exporters/style_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -440,21 +440,27 @@ def _unknown_key(location: tuple[int | str, ...]) -> str:
)


_EXTENDS: Final = TypeAdapter(_StyleFile)
_FILE_NAME: Final = TypeAdapter(_StyleFile)
_MERGEABLE: Final = TypeAdapter(dict[str, JsonValue])
# The tags pydantic puts in a JsonValue error's place, after each mapping or list it enters
_JSON_VALUE_TAGS: Final = frozenset({"dict", "list", "str", "int", "float", "bool", "none"})


def extended_style(data: Mapping[str, Any]) -> str | None:
"""The style file a style extends, as written; None when it names none, or names it in
a way the schema refuses (validate_style reports that)."""
def file_name(value: Any) -> str | None:
"""A file name a style writes (extends, a CCI mapping file), as written; None when the
value is no file name the schema accepts (validate_style reports that)."""
try:
return _EXTENDS.validate_python(data.get("extends"), strict=True)
return _FILE_NAME.validate_python(value, strict=True)
except ValidationError:
return None


def extended_style(data: Mapping[str, Any]) -> str | None:
"""The style file a style extends, as written; None when it names none, or names it in
a way the schema refuses (validate_style reports that)."""
return file_name(data.get("extends"))


def _as_written(key: Any) -> str:
"""A key as YAML wrote it: true, 1, null, 2026-01-01."""
return yaml.safe_dump(key, default_flow_style=True).splitlines()[0].removesuffix(" ...")
Expand Down
105 changes: 78 additions & 27 deletions src/cis_bench/utils/cci_lookup.py
Original file line number Diff line number Diff line change
@@ -1,23 +1,30 @@
"""CCI (Control Correlation Identifier) lookup service.

Maps CIS Controls safeguards to DoD CCIs through the bundled CIS-CCI mapping, and tells
which cited NIST controls a rule's CCIs already state, so only the others are written as
references.
Maps CIS Controls safeguards to DoD CCIs through a CIS-CCI mapping file (the bundled one
unless a style names its own), and tells which cited NIST controls a rule's CCIs already
state, so only the others are written as references.
"""

import functools
import json
import logging
import re
from dataclasses import dataclass
from gettext import ngettext
from pathlib import Path
from typing import Final

from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError

logger = logging.getLogger(__name__)

# A NIST SP 800-53 control and its enhancement at the start of an index: "CM-8" and "(3)" in
# "CM-8 (3) (a)"; sub-parts ("a 1", "(b)") and assessment suffixes (".1") are not part of it
_CONTROL_KEY_RE = re.compile(r"([A-Z]{2}-\d+)\s*(?:\((\d+)\))?")

# The mapping file shipped with the package, read when a style names none
BUNDLED_MAPPING: Final = Path(__file__).parent.parent / "data" / "cis-cci-mapping.json"


@dataclass
class CCIMapping:
Expand All @@ -28,37 +35,72 @@ class CCIMapping:
confidence: float | None = None


class _MappedCci(BaseModel):
"""A CCI of a mapping entry as the file writes it; the reader decides which are given."""

model_config = ConfigDict(extra="allow", strict=True) # reasoning and the like are kept

cci: str | None = None
nist_control: str | None = None
confidence: float | None = None


class _MappingEntry(BaseModel):
"""A safeguard's entry of a CIS-CCI mapping file."""

model_config = ConfigDict(extra="allow", strict=True) # cis_title and the like are kept

cis_id: str
mapping_status: str | None = None
primary_cci: _MappedCci | None = None
supporting_ccis: list[_MappedCci] = []


_MAPPING_FILE: Final = TypeAdapter(list[_MappingEntry])


class CCILookupService:
"""Service for looking up CCIs and managing NIST deduplication."""

def __init__(self, mapping_file: Path | None = None):
"""Initialize CCI lookup service.

Args:
mapping_file: Path to cis-cci-mapping.json (defaults to bundled file)
mapping_file: Path to a CIS-CCI mapping file (defaults to the bundled file)

Raises:
OSError: The file cannot be read.
ValueError: The file is not JSON, or not a list of safeguard entries in the
shape of the bundled file.
"""
if mapping_file is None:
# Use bundled mapping file
mapping_file = Path(__file__).parent.parent / "data" / "cis-cci-mapping.json"
mapping_file = BUNDLED_MAPPING

logger.debug(f"Initializing CCI lookup service with mapping file: {mapping_file}")

with open(mapping_file) as f:
mapping_data = json.load(f)
try:
entries = _MAPPING_FILE.validate_python(mapping_data)
except ValidationError as error:
raise ValueError(
f"{mapping_file}: a CCI mapping file is a list of safeguard entries in the shape "
f"of the bundled one: {error}"
) from error

logger.debug(
ngettext(
"Loaded {count} CCI mapping entry",
"Loaded {count} CCI mapping entries",
len(mapping_data),
).format(count=len(mapping_data))
len(entries),
).format(count=len(entries))
)

# Each safeguard's CCIs, read once through the one entry reader: only OFFICIAL
# entries give CCIs (INFERRED and UNMAPPED entries are kept in the file as
# research data and give none).
self._ccis_by_safeguard: dict[str, list[CCIMapping]] = {
entry["cis_id"]: self._official_ccis(entry) for entry in mapping_data
entry.cis_id: self._official_ccis(entry) for entry in entries
}
# Reverse index: CCI -> the NIST control it implements (DISA's Rev 5 index)
self._cci_to_nist: dict[str, str] = {
Expand All @@ -69,31 +111,32 @@ def __init__(self, mapping_file: Path | None = None):
}

@staticmethod
def _official_ccis(entry: dict) -> list[CCIMapping]:
def _official_ccis(entry: _MappingEntry) -> list[CCIMapping]:
"""An entry's CCIs, primary first, then its supporting CCIs; none unless the entry
is OFFICIAL.

Raises:
ValueError: An OFFICIAL entry without a primary CCI, or a CCI without its CCI
id or NIST control.
"""
if entry.get("mapping_status") != "OFFICIAL":
if entry.mapping_status != "OFFICIAL":
return []
cis_id = entry.get("cis_id")
primary = entry.get("primary_cci")
cis_id = entry.cis_id
primary = entry.primary_cci
if not primary:
raise ValueError(f"safeguard {cis_id}: an OFFICIAL entry needs a primary_cci")
ccis = []
for item in [primary, *entry.get("supporting_ccis", [])]:
if not item.get("cci") or not item.get("nist_control"):
for item in [primary, *entry.supporting_ccis]:
if not item.cci or not item.nist_control:
raise ValueError(
f"safeguard {cis_id}: every CCI needs its cci and nist_control: {item!r}"
f"safeguard {cis_id}: every CCI needs its cci and nist_control: "
f"{item.model_dump()!r}"
)
ccis.append(
CCIMapping(
cci=item["cci"],
nist_control=item["nist_control"],
confidence=item.get("confidence"),
cci=item.cci,
nist_control=item.nist_control,
confidence=item.confidence,
)
)
return ccis
Expand Down Expand Up @@ -201,14 +244,22 @@ def control_key(nist_control: str) -> str:
return f"{control}({enhancement})" if enhancement else control


# Singleton instance for easy access
_service_instance = None
@functools.cache
def _service(resolved: Path) -> CCILookupService:
return CCILookupService(resolved)


def cci_service_for(mapping_file: Path | None = None) -> CCILookupService:
"""The CCI lookup of a mapping file (the bundled one when None), read once per file per
process: two spellings of one path give the same lookup.

Raises:
OSError: The file cannot be read.
ValueError: The file is not a CCI mapping file.
"""
return _service((mapping_file or BUNDLED_MAPPING).resolve())


def get_cci_service() -> CCILookupService:
"""Get singleton CCI lookup service instance."""
global _service_instance
if _service_instance is None:
logger.debug("Creating singleton CCI lookup service instance")
_service_instance = CCILookupService()
return _service_instance
"""The CCI lookup of the bundled mapping file."""
return cci_service_for()
Loading
Loading