ssg.build_yaml module

Common functions for building YAML in SSG. Also contains definitions of basic classes like Rule, Group, Value and Platform.

class ssg.build_yaml.Benchmark(id_)

Bases: XCCDFEntity

Represents an XCCDF Benchmark entity with various attributes and methods to manipulate and represent the benchmark data.

KEYS

Dictionary of keys with default values.

Type:

dict

MANDATORY_KEYS

Set of mandatory keys for the benchmark.

Type:

set

GENERIC_FILENAME

Default filename for the benchmark.

Type:

str

GENERIC_FILENAME = 'benchmark.yml'

KEYS: Dict[str, Callable[[], Any | None]] = {'cpes': <function Benchmark.<lambda>>, 'definition_location': <function XCCDFEntity.<lambda>>, 'description': <function Benchmark.<lambda>>, 'front_matter': <function Benchmark.<lambda>>, 'groups': <function Benchmark.<lambda>>, 'id_': <function XCCDFEntity.<lambda>>, 'notice_description': <function Benchmark.<lambda>>, 'notice_id': <function Benchmark.<lambda>>, 'platforms': <function Benchmark.<lambda>>, 'product_cpe_names': <function Benchmark.<lambda>>, 'profiles': <function Benchmark.<lambda>>, 'rear_matter': <function Benchmark.<lambda>>, 'rules': <function Benchmark.<lambda>>, 'status': <function Benchmark.<lambda>>, 'title': <function XCCDFEntity.<lambda>>, 'values': <function Benchmark.<lambda>>, 'version': <function Benchmark.<lambda>>}

MANDATORY_KEYS: Set[str] = {'description', 'front_matter', 'rear_matter', 'status', 'title'}

add_group(group, env_yaml=None, product_cpes=None)

Adds a group to the groups dictionary.

Parameters:

• group (Group) – The group object to be added. Must have an ‘id_’ attribute.

• env_yaml (dict, optional) – Additional environment YAML data. Default is None.

• product_cpes (dict, optional) – Additional product CPEs data. Default is None.

Returns:

None

add_profiles_from_dir(dir_, env_yaml, product_cpes)

Adds profiles from the specified directory to the current instance.

This method scans the given directory for files with the ‘.profile’ extension, attempts to create ProfileWithInlinePolicies objects from them, and appends them to the instance’s profiles list.

Parameters:

• dir (str) – The directory to scan for profile files.

• env_yaml (dict) – The environment YAML data used for profile creation.

• product_cpes (list) – The list of product CPEs used for profile creation.

Returns:

None

Raises:

RuntimeError – If there is an error building a profile from a file.

Notes

• Files that do not have the ‘.profile’ extension are skipped.

• If a profile file is incomplete or an error occurs during its creation, it is skipped.

add_rule(rule)

Adds a rule to the rules dictionary.

Parameters:

rule (Rule) – The rule to be added. If None, the method returns without adding anything.

Returns:

None

add_value(value)

Adds a value to the values dictionary if the value is not None.

Parameters:

value (object) – The value to be added. It is expected to have an ‘id_’ attribute.

Returns:

None

drop_rules_not_included_in_a_profile()

Removes rules from groups that are not included in any profile.

This method retrieves the set of rules that are selected in all profiles and removes any rules from each group that are not listed in this set.

Returns:

None

classmethod from_yaml(yaml_file, env_yaml=None, product_cpes=None)

Creates a Benchmark instance from a YAML file.

Parameters:

• yaml_file (str) – Path to the YAML file.

• env_yaml (dict, optional) – Environment-specific YAML data. Defaults to None.

• product_cpes (ProductCPEs, optional) – Product CPEs instance. Defaults to None.

Returns:

An instance of the Benchmark class populated with data from the YAML file.

Return type:

Benchmark

get_benchmark_xml_for_profiles(env_yaml, profiles, rule_and_variables_dict, include_contributors=True)

Generates the benchmark XML for the given profiles.

Parameters:

• env_yaml (dict) – The environment YAML configuration.

• profiles (list) – A list of profile objects.

• rule_and_variables_dict (dict) – A dictionary containing rules and variables.

Returns:

A tuple containing:

• profiles_ids (list): A list of profile IDs.

• xml_element (Element): The XML element representing the benchmark.

Return type:

tuple

get_components_not_included_in_a_profiles(profiles, rules_and_variables_dict)

Identify and return the sets of rules, groups, and variables that are not included in any of the given profiles.

Parameters:

• profiles (list) – A list of profiles to check against.

• rules_and_variables_dict (dict) – A dictionary containing rules and their associated variables.

Returns:

A tuple containing three sets:

• rules (set): A set of rules not included in any of the profiles.

• groups (set): A set of groups not included in any of the profiles.

• variables (set): A set of variables not included in any of the profiles.

Return type:

tuple

get_not_used_cpe_platforms(profiles)

Get the CPE platforms that are not used in the given profiles.

Parameters:

profiles (list) – A list of profiles to check for used CPE platforms.

Returns:

A set of CPE platforms that are not used in the given profiles.

Return type:

set

get_rules_selected_in_all_profiles(profiles=None)

Get the set of rules that are selected in all given profiles.

Parameters:

profiles (list, optional) – A list of profile objects. If None, the method will use the instance’s profiles attribute.

Returns:

A set of rules that are selected in all provided profiles.

Return type:

set

get_used_cpe_platforms(profiles)

Retrieves the CPE platforms used by the selected rules in the given profiles.

Parameters:

profiles (list) – A list of profiles to check for selected rules.

Returns:

A list of CPE platforms associated with the selected rules.

Return type:

list

static get_variables_of_rules(profiles, rule_ids, rules_and_variables_dict)

Collects and returns a set of variables associated with the given rules and profiles.

Parameters:

• profiles (list) – A list of profile objects, each containing a dictionary of variables.

• rule_ids (list) – A list of rule identifiers.

• rules_and_variables_dict (dict) – A dictionary mapping rule identifiers to sets of variables.

Returns:

A set of variables associated with the specified rules and profiles.

Return type:

set

load_entities(rules_by_id, values_by_id, groups_by_id)

Load entities into the current object from provided dictionaries if they are not already set.

Parameters:

• rules_by_id (dict) – A dictionary containing rule entities indexed by their IDs.

• values_by_id (dict) – A dictionary containing value entities indexed by their IDs.

• groups_by_id (dict) – A dictionary containing group entities indexed by their IDs.

This method updates the rules, values, and groups attributes of the current object. If an entity in these attributes is not already set (i.e., its value is falsy), it will be loaded from the corresponding provided dictionary.

classmethod process_input_dict(input_contents, env_yaml, product_cpes)

Processes the input dictionary by transforming specific keys and extracting required data.

Parameters:

• cls (type) – The class that calls this method.

• input_contents (dict) – The dictionary containing the input data to be processed.

• env_yaml (dict) – The environment YAML data.

• product_cpes (list) – The list of product CPEs.

Returns:

The processed data dictionary with transformed and extracted information.

Return type:

dict

Raises:

KeyError – If any required key is missing in the input dictionaries.

represent_as_dict()

Converts the instance attributes to a dictionary representation, modifying specific keys for compatibility.

Returns:

A dictionary representation of the instance with modified keys.

Return type:

dict

to_file(file_name, env_yaml=None)

Serializes the XML representation of the object to a file.

Parameters:

• file_name (str) – The name of the file to which the XML data will be written.

• env_yaml (dict, optional) – An optional parameter that can be used to customize the XML generation.

Returns:

None

to_xccdf()

Converts the current object to XCCDF format.

This method is intended to be extended to generate a valid XCCDF instead of SSG SHORTHAND.

Returns:

None

Raises:

NotImplementedError – This method is not yet implemented.

to_xml_element(env_yaml=None, product_cpes=None, components_to_not_include=None, include_contributors=True)

Converts the current object to an XML element.

Parameters:

• env_yaml (dict, optional) – Environment YAML data. Defaults to None.

• product_cpes (list, optional) – List of product CPEs. Defaults to None.

• components_to_not_include (dict, optional) – Components to exclude from the XML. Defaults to None.

• include_contributors (bool, optional) – Whether to include contributors in the XML. Defaults to True.

Returns:

The root XML element representing the object.

Return type:

xml.etree.ElementTree.Element

unselect_empty_groups()

Unselects empty groups from each profile in the profiles list.

This method iterates through each profile in the profiles list and calls the unselect_empty_groups method on each profile, passing the current instance as an argument.

Returns:

None

class ssg.build_yaml.BuildLoader(profiles_dir, env_yaml, product_cpes, sce_metadata_path=None)

Bases: DirectoryLoader

BuildLoader is a class that extends DirectoryLoader to handle the loading and processing of build-related YAML files, including profiles, environment configurations, product CPEs, and SCE metadata.

sce_metadata

Metadata for SCE, loaded from a JSON file.

Type:

dict

components_dir

Absolute path to the components directory.

Type:

str

rule_to_components

Mapping of rules to their respective components.

Type:

dict

export_group_to_file(filename)

Exports the loaded group to a specified file.

Parameters:

filename (str) – The name of the file to which the group will be exported.

Returns:

True if the export was successful, False otherwise.

Return type:

bool

load_components()

Loads the components from the specified components directory and maps rules to components.

This method checks if the “components_root” key is present in the environment YAML. If not, it returns None. If the key is present, it constructs the absolute path to the components directory using the “product_dir” and “components_root” values from the environment YAML. It then loads the components from this directory and creates a mapping of rules to components.

Returns:

None

class ssg.build_yaml.DirectoryLoader(profiles_dir, env_yaml, product_cpes)

Bases: object

A class to load and process security content from a directory structure.

profiles_dir

Directory containing profiles.

Type:

str

env_yaml

Environment YAML configuration.

Type:

dict

product_cpes

Product CPEs.

Type:

object

benchmark_file

Path to the benchmark file.

Type:

str

group_file

Path to the group file.

Type:

str

loaded_group

Loaded group object.

Type:

object

rule_files

List of rule file paths.

Type:

list

value_files

List of value file paths.

Type:

list

subdirectories

List of subdirectory paths.

Type:

list

all_values

Dictionary of all loaded values.

Type:

dict

all_rules

Dictionary of all loaded rules.

Type:

dict

all_groups

Dictionary of all loaded groups.

Type:

dict

parent_group

Parent group object.

Type:

object

load_benchmark_or_group(guide_directory)

Loads a given benchmark or group from the specified benchmark_file or group_file, in the context of guide_directory, profiles_dir and env_yaml.

Parameters:

guide_directory (str) – The directory containing the guide files.

Returns:

The loaded group or benchmark.

Return type:

Group or Benchmark

Raises:

ValueError – If both a .benchmark file and a .group file are found in the same directory.

process_directory_tree(start_dir, extra_group_dirs=None)

Processes the directory tree starting from the given directory.

This method collects items to load from the start directory, optionally adds extra group directories to the list of subdirectories, and then processes and recurses through the directory tree.

Parameters:

• start_dir (str) – The starting directory to process.

• extra_group_dirs (list, optional) – A list of additional directories to include in the processing. Defaults to None.

Returns:

None

process_directory_trees(directories)

Processes a list of directory trees.

Parameters:

directories (list) – A list of directory paths. The first directory in the list is considered the start directory, and the remaining directories are considered extra group directories.

Returns:

The result of processing the start directory and extra group directories.

save_all_entities(base_dir)

Saves all entities (rules, groups, values, platforms, and cpe_items) to the specified base directory.

This method creates subdirectories within the base directory for each type of entity and saves the entities if they exist. The subdirectories created are:

• rules

• groups

• values

• platforms

• cpe_items

The entities are saved using the save_entities method.

Parameters:

base_dir (str) – The base directory where the entities will be saved.

Returns:

None

save_entities(entities, destdir)

Save a list of entities to YAML files in the specified directory.

Parameters:

• entities (list) – A list of entities to be saved. Each entity must have an ‘id_’ attribute and a ‘dump_yaml’ method.

• destdir (str) – The destination directory where the YAML files will be saved.

Returns:

None

class ssg.build_yaml.Group(id_)

Bases: XCCDFEntity

Represents an XCCDF Group entity, which is a collection of rules, values, and sub-groups that can be processed and converted into various formats such as YAML and XML.

GENERIC_FILENAME

The default filename for the group.

Type:

str

KEYS

A dictionary of keys and their default values for the group.

Type:

dict

MANDATORY_KEYS

A set of keys that are mandatory for the group.

Type:

set

GENERIC_FILENAME = 'group.yml'

KEYS: Dict[str, Callable[[], Any | None]] = {'conflicts': <function Group.<lambda>>, 'cpe_platform_names': <function Group.<lambda>>, 'definition_location': <function XCCDFEntity.<lambda>>, 'description': <function Group.<lambda>>, 'groups': <function Group.<lambda>>, 'id_': <function XCCDFEntity.<lambda>>, 'inherited_platforms': <function Group.<lambda>>, 'platform': <function Group.<lambda>>, 'platforms': <function Group.<lambda>>, 'requires': <function Group.<lambda>>, 'rules': <function Group.<lambda>>, 'title': <function XCCDFEntity.<lambda>>, 'values': <function Group.<lambda>>, 'warnings': <function Group.<lambda>>}

MANDATORY_KEYS: Set[str] = {'description', 'front_matter', 'rear_matter', 'status', 'title'}

add_group(group, env_yaml=None, product_cpes=None)

Adds a group to the current object.

Parameters:

• group (str) – The group to be added.

• env_yaml (dict, optional) – Environment YAML data. Defaults to None.

• product_cpes (list, optional) – List of product CPEs. Defaults to None.

Returns:

None

add_rule(rule, env_yaml=None, product_cpes=None)

Adds a rule to the current object and processes its inherited platforms.

Parameters:

• rule (Rule) – The rule object to be added.

• env_yaml (dict, optional) – Environment-specific YAML data. Defaults to None.

• product_cpes (dict, optional) – Product-specific CPEs. Defaults to None.

Returns:

None

add_value(value)

Adds a value to the values dictionary if the value is not None.

Parameters:

value – An object with an ‘id_’ attribute that will be used as the key in the values dictionary.

Returns:

None

contains_rules(rule_ids)

Check if the specified rule IDs are present in the rules.

Parameters:

rule_ids (list) – A list of rule IDs to check for presence.

Returns:

True if all specified rule IDs are present, False otherwise.

Return type:

bool

contains_variables(variable_ids)

Check if the given variable IDs are present in the values.

Parameters:

variable_ids (list) – A list of variable IDs to check for presence.

Returns:

True if all the given variable IDs are present in the values, False otherwise.

Return type:

bool

get_not_included_components(rule_ids_list, variables_ids_list)

Identify and return the sets of rules, variables, and groups that are not included in the provided lists of rule IDs and variable IDs.

Parameters:

• rule_ids_list (list) – A list of rule IDs to check against.

• variables_ids_list (list) – A list of variable IDs to check against.

Returns:

A tuple containing three sets: - rules (set): A set of rule IDs that are not in the provided rule_ids_list. - groups (set): A set of group IDs that are not included based on the provided lists. - variables (set): A set of variable IDs that are not in the provided variables_ids_list.

Return type:

tuple

get_used_cpe_platforms(rule_ids_list)

Get the set of CPE platforms used by the given list of rule IDs.

This method collects CPE platform names from the specified rules and their inherited rules. It also includes CPE platforms from sub-groups of the given rules.

Parameters:

rule_ids_list (list) – A list of rule IDs to retrieve CPE platforms for.

Returns:

A set of CPE platform names used by the specified rules.

Return type:

set

load_entities(rules_by_id, values_by_id, groups_by_id)

Load entities into the current object’s rules, values, and groups attributes.

This method updates the current object’s rules, values, and groups attributes with the corresponding entities from the provided dictionaries (rules_by_id, values_by_id, groups_by_id). If an entity is not present in the current object’s attributes, it will be added from the provided dictionaries.

Parameters:

• rules_by_id (dict) – A dictionary containing rule entities indexed by their IDs.

• values_by_id (dict) – A dictionary containing value entities indexed by their IDs.

• groups_by_id (dict) – A dictionary containing group entities indexed by their IDs.

Returns:

None

Raises:

KeyError – If a group ID in the current object’s groups attribute is not found in the groups_by_id dictionary, the group will be removed from the current object’s groups attribute.

classmethod process_input_dict(input_contents, env_yaml, product_cpes=None)

Processes the input dictionary and updates it with additional data.

Parameters:

• cls (type) – The class type that calls this method.

• input_contents (dict) – The input dictionary containing initial data.

• env_yaml (dict) – The environment YAML data.

• product_cpes (dict, optional) – The product CPEs, defaults to None.

Returns:

The processed data dictionary with updated rules, groups, values, and platforms.

Return type:

dict

remove_rules_with_ids_not_listed(rule_ids_list)

Remove rules from the current object whose IDs are not listed in the provided rule_ids_list.

This method updates the rules attribute by filtering out rules whose IDs are not in the provided list. It also recursively applies the same filtering to all groups within the current object.

Parameters:

rule_ids_list (list) – A list of rule IDs to retain.

Returns:

None

represent_as_dict()

Represents the object as a dictionary.

This method overrides the represent_as_dict method from the superclass. It adds the rules, groups, and values attributes to the dictionary representation if they are present.

Returns:

A dictionary representation of the object with sorted keys for

rules, groups, and values if they are not empty.

Return type:

dict

to_xml_element(env_yaml=None, components_to_not_include=None)

Converts the current object to an XML element.

Parameters:

• env_yaml (dict, optional) – Environment YAML data. Defaults to None.

• components_to_not_include (dict, optional) – Components to exclude from the XML. Defaults to None. The dictionary can contain the following keys: - “rules”: A set of rule IDs to exclude. - “groups”: A set of group IDs to exclude. - “variables”: A set of variable IDs to exclude.

Returns:

The XML element representing the current object, or None if the object is in the groups_to_not_include set.

Return type:

xml.etree.ElementTree.Element

class ssg.build_yaml.LinearLoader(env_yaml, resolved_path)

Bases: object

LinearLoader is responsible for loading and managing various security content entities such as rules, profiles, groups, values, platforms, fixes, and CPE items from a specified directory structure. It also provides methods to export this content to XML format.

resolved_rules_dir

Directory path for resolved rules.

Type:

str

rules

Dictionary to store loaded rules.

Type:

dict

resolved_profiles_dir

Directory path for resolved profiles.

Type:

str

profiles

Dictionary to store loaded profiles.

Type:

dict

resolved_groups_dir

Directory path for resolved groups.

Type:

str

groups

Dictionary to store loaded groups.

Type:

dict

resolved_values_dir

Directory path for resolved values.

Type:

str

values

Dictionary to store loaded values.

Type:

dict

resolved_platforms_dir

Directory path for resolved platforms.

Type:

str

platforms

Dictionary to store loaded platforms.

Type:

dict

fixes_dir

Directory path for fixes.

Type:

str

fixes

Dictionary to store loaded fixes.

Type:

dict

resolved_cpe_items_dir

Directory path for resolved CPE items.

Type:

str

cpe_items

Dictionary to store loaded CPE items.

Type:

dict

benchmark

Loaded benchmark object.

Type:

Benchmark

env_yaml

Environment YAML configuration.

Type:

dict

product_cpes

Product CPEs object.

Type:

ProductCPEs

off_ocil

Flag to indicate if OCIL should be turned off.

Type:

bool

add_fixes_to_rules()

Adds fixes to the rules in the rules dictionary.

Iterates over the items in the fixes dictionary and adds the corresponding fixes to the rules in the rules dictionary.

Returns:

None

Raises:

KeyError – If a rule_id in fixes does not exist in rules.

export_benchmark_to_file(filename)

Exports the benchmark data to a specified file.

This method registers the necessary namespaces and then writes the benchmark data to the given filename using the environment YAML configuration.

Parameters:

filename (str) – The path to the file where the benchmark data will be exported.

Returns:

True if the export was successful, False otherwise.

Return type:

bool

export_benchmark_to_xml(rule_and_variables_dict, ignore_single_rule_profiles)

Exports the benchmark data to an XML format.

Parameters:

• rule_and_variables_dict (dict) – A dictionary containing rules and variables.

• ignore_single_rule_profiles (bool) – All profiles that contain “single_rule_profile: true” will be skipping.

Returns:

The benchmark data in XML format.

Return type:

str

export_ocil_to_file(filename)

Exports the OCIL data to an XML file.

This method converts the OCIL data to an XML format and writes it to the specified file. If the conversion to XML results in a None root, the method returns without writing to the file.

Parameters:

filename (str) – The path to the file where the XML data will be written.

Returns:

None

export_ocil_to_xml(benchmark=None)

Exports OCIL content to an XML format.

Parameters:

benchmark (optional) – The benchmark object containing rules to be exported. If not provided, the instance’s benchmark attribute is used.

Returns:

The root element of the generated OCIL XML tree.

Returns None if OCIL is turned off or no rules are found.

Return type:

xml.etree.ElementTree.Element

find_first_groups_ids(start_dir)

Finds the IDs of the first-level groups in the specified directory.

This method searches for all “group.yml” files located in the immediate subdirectories of the given start directory and extracts the names of these subdirectories as group IDs.

Parameters:

start_dir (str) – The directory to start searching from.

Returns:

A list of group IDs (names of subdirectories containing “group.yml”).

Return type:

list

get_benchmark_xml()

Converts the benchmark data to an XML element.

Returns:

The XML representation of the benchmark data.

Return type:

xml.etree.ElementTree.Element

get_benchmark_xml_by_profile(rule_and_variables_dict)

Generates benchmark XML for each profile in the benchmark.

This method iterates over all profiles in the benchmark and generates the corresponding benchmark XML for each profile using the provided rule and variables dictionary.

Parameters:

rule_and_variables_dict (dict) – A dictionary containing rules and variables to be used for generating the benchmark XML.

Yields:

tuple – A tuple containing the profile ID (str) and the corresponding benchmark XML (str).

Raises:

Exception – If the benchmark is not loaded before calling this method.

load_benchmark(directory)

Loads the benchmark data from the specified directory.

This method performs the following steps: 1. Loads the benchmark from a YAML file located in the given directory. 2. Adds profiles from the resolved profiles directory. 3. Adds groups to the benchmark based on the first group IDs found in the directory. 4. Drops rules that are not included in any profile. 5. Unselects empty groups from the benchmark.

Parameters:

directory (str) – The directory from which to load the benchmark data.

Returns:

None

Raises:

KeyError – If a group ID is not found in the compiled and loaded groups.

load_compiled_content()

Loads and compiles various content entities from specified directories into the appropriate attributes.

This method performs the following steps: 1. Loads CPEs from the directory tree specified by self.resolved_cpe_items_dir and

updates self.product_cpes.

2. Loads compiled remediations from the directory specified by self.fixes_dir and assigns them to self.fixes.

3. Loads rule entities from YAML files in the directory specified by self.resolved_rules_dir and updates self.rules.

4. Loads group entities from YAML files in the directory specified by self.resolved_groups_dir and updates self.groups.

5. Loads value entities from YAML files in the directory specified by self.resolved_values_dir and updates self.values.

6. Loads platform entities from YAML files in the directory specified by self.resolved_platforms_dir and updates self.platforms.

7. Assigns the loaded platforms to self.product_cpes.platforms.

8. For each group in self.groups, loads associated rules, values, and sub-groups.

Returns:

None

Raises:

• FileNotFoundError – If any of the specified directories or files do not exist.

• ValueError – If there is an issue with the content of the YAML files.

load_entities_by_id(filenames, destination, cls)

Loads entities from a list of JSON files and stores them in a destination dictionary by their ID.

Parameters:

• filenames (list of str) – List of file paths to JSON files.

• destination (dict) – Dictionary to store the loaded entities, keyed by their ID.

• cls (type) – Class type that has a from_yaml method to create an instance from a JSON file.

Returns:

None

class ssg.build_yaml.Platform(id_)

Bases: XCCDFEntity

Represents a platform entity in the XCCDF standard.

KEYS

Dictionary of keys with default lambda functions.

Type:

dict

MANDATORY_KEYS

List of mandatory keys for the platform.

Type:

list

prefix

Prefix for the platform.

Type:

str

ns

Namespace for the platform.

Type:

str

KEYS: Dict[str, Callable[[], Any | None]] = {'ansible_conditional': <function Platform.<lambda>>, 'bash_conditional': <function Platform.<lambda>>, 'definition_location': <function XCCDFEntity.<lambda>>, 'id_': <function XCCDFEntity.<lambda>>, 'name': <function Platform.<lambda>>, 'original_expression': <function Platform.<lambda>>, 'title': <function XCCDFEntity.<lambda>>, 'xml_content': <function Platform.<lambda>>}

MANDATORY_KEYS: Set[str] = {'ansible_conditional', 'bash_conditional', 'name', 'original_expression', 'xml_content'}

classmethod from_compiled_json(json_file_path, env_yaml=None, product_cpes=None)

classmethod from_text(expression, product_cpes)

Creates a platform object from a given text expression and product CPEs.

Parameters:

• cls – The class itself.

• expression (str) – The text expression to parse.

• product_cpes (ProductCPEs) – The product CPEs to use for parsing and resolving CPE items.

Returns:

A platform object with the parsed and enriched CPE information,

or None if product_cpes is empty.

Return type:

platform (Platform)

classmethod from_yaml(yaml_file, env_yaml=None, product_cpes=None)

Creates a Platform object from a YAML file.

Parameters:

• yaml_file (str) – Path to the YAML file.

• env_yaml (dict, optional) – Environment YAML data. Defaults to None.

• product_cpes (ProductCPEs, optional) – Product CPEs object for restoring the original test object. Defaults to None.

Returns:

A Platform object created from the YAML file.

Return type:

Platform

get_fact_refs()

Retrieve fact references from the test symbols.

Returns:

A list of symbols from the test object.

Return type:

list

get_remediation_conditional(language)

Returns the remediation conditional based on the specified language.

Parameters:

language (str) – The remediation language. Supported values are “bash” and “ansible”.

Returns:

The corresponding remediation conditional for the specified language.

Return type:

str

Raises:

AttributeError – If an invalid remediation language is specified.

get_xml()

Generates an XML string representation of the platform.

This method creates an XML element for the platform with the appropriate namespace and sets its ‘id’ attribute to the platform’s name. If the platform contains only a single CPE name, it creates a logical test element with an ‘AND’ operator and ‘false’ negate attribute to adhere to the CPE specification. The logical test element or the test element is then appended to the platform element.

Returns:

A string representation of the XML for the platform.

Return type:

str

ns = 'http://cpe.mitre.org/language/2.0'

prefix = 'cpe-lang'

to_xml_element()

Converts the stored XML content into an XML element.

Returns:

The root element of the parsed XML content.

Return type:

xml.etree.ElementTree.Element

update_conditional_from_cpe_items(language, product_cpes)

Updates the conditional statements for the specified language based on CPE items.

This method enriches the test object with CPE information and then generates the appropriate conditional statements for the specified language.

Parameters:

• language (str) – The language for which to generate the conditional statements. Supported values are “bash” and “ansible”.

• product_cpes (list) – A list of CPE items to enrich the test object with.

Returns:

None

Raises:

RuntimeError – If the specified language is not supported.

class ssg.build_yaml.Rule(id_)

Bases: XCCDFEntity, Templatable

Represents an XCCDF Rule entity with various attributes and methods for handling rule data, validation, and conversion.

KEYS

Default values for various rule attributes.

Type:

dict

MANDATORY_KEYS

Set of mandatory keys for a rule.

Type:

set

GENERIC_FILENAME

Default filename for a rule.

Type:

str

ID_LABEL

Label for rule ID.

Type:

str

PRODUCT_REFERENCES

Tuple of product-specific reference types.

Type:

tuple

GENERIC_FILENAME = 'rule.yml'

ID_LABEL = 'rule_id'

KEYS: Dict[str, Callable[[], Any | None]] = {'bash_conditional': <function Rule.<lambda>>, 'check_type': <function Rule.<lambda>>, 'checktext': <function Rule.<lambda>>, 'components': <function Rule.<lambda>>, 'conflicts': <function Rule.<lambda>>, 'control_references': <function Rule.<lambda>>, 'cpe_platform_names': <function Rule.<lambda>>, 'definition_location': <function XCCDFEntity.<lambda>>, 'description': <function Rule.<lambda>>, 'expression': <function Rule.<lambda>>, 'failure_reason': <function Rule.<lambda>>, 'fixes': <function Rule.<lambda>>, 'fixtext': <function Rule.<lambda>>, 'id_': <function XCCDFEntity.<lambda>>, 'identifiers': <function Rule.<lambda>>, 'inherited_cpe_platform_names': <function Rule.<lambda>>, 'inherited_platforms': <function Rule.<lambda>>, 'inputs': <function Rule.<lambda>>, 'ocil': <function Rule.<lambda>>, 'ocil_clause': <function Rule.<lambda>>, 'oval_external_content': <function Rule.<lambda>>, 'platform': <function Rule.<lambda>>, 'platforms': <function Rule.<lambda>>, 'policy_specific_content': <function Rule.<lambda>>, 'rationale': <function Rule.<lambda>>, 'references': <function Rule.<lambda>>, 'requires': <function Rule.<lambda>>, 'sce_metadata': <function Rule.<lambda>>, 'severity': <function Rule.<lambda>>, 'srg_requirement': <function Rule.<lambda>>, 'template': <function Templatable.<lambda>>, 'title': <function XCCDFEntity.<lambda>>, 'vuldiscussion': <function Rule.<lambda>>, 'warnings': <function Rule.<lambda>>}

MANDATORY_KEYS: Set[str] = {'description', 'rationale', 'severity', 'title'}

PRODUCT_REFERENCES = ('stigid', 'cis')

add_control_reference(ref_type, ref_value)

Adds a control reference to the rule.

Parameters:

• ref_type (str) – The type of the control reference.

• ref_value (str) – The value of the control reference.

Returns:

None

Raises:

ValueError – If the rule already contains the specified reference type and value.

add_fixes(fixes)

Adds a list of fixes to the current instance.

Parameters:

fixes (list) – A list of fixes to be added.

Returns:

None

add_stig_references(stig_references)

Adds STIG references to the object’s references.

This method looks up STIG references based on the STIG IDs present in the object’s references. If any matching references are found, they are added to the object’s references under the key “stigref”.

Parameters:

stig_references (dict) – A dictionary mapping STIG IDs to their corresponding references.

Returns:

None

find_policy_specific_content(rule_root)

Finds and returns a set of policy-specific YAML files within a given rule directory.

Parameters:

rule_root (str) – The root directory of the rule to search for policy-specific content.

Returns:

A set of file paths to the policy-specific YAML files found within the rule

directory.

Return type:

set

classmethod from_yaml(yaml_file, env_yaml=None, product_cpes=None, sce_metadata=None)

Creates a Rule object from a YAML file.

Parameters:

• yaml_file (str) – Path to the YAML file containing the rule definition.

• env_yaml (dict, optional) – Environment-specific YAML data. Defaults to None.

• product_cpes (list, optional) – List of product CPEs. Defaults to None.

• sce_metadata (dict, optional) – SCE metadata dictionary. Defaults to None.

Returns:

An instance of the Rule class populated with data from the YAML file.

Return type:

Rule

Notes

• Converts platforms from list to set.

• Splits references from comma-separated strings to lists.

• Ensures rule.platform is included in rule.platforms.

• Loads policy-specific content if not already defined.

• Adds SCE metadata if available.

• Validates identifiers and references.

get_template_context(env_yaml)

Generates the template context for the given environment YAML.

This method overrides the parent class’s get_template_context method to include additional context specific to this class.

Parameters:

env_yaml (dict) – The environment YAML data.

Returns:

The template context with additional identifiers if available.

Return type:

dict

load_policy_specific_content(rule_filename, env_yaml)

Loads policy-specific content for a given rule.

This method finds and reads policy-specific content files related to the provided rule filename and environment YAML. The content is then stored in the instance variable policy_specific_content.

Parameters:

• rule_filename (str) – The filename of the rule for which to load policy-specific content.

• env_yaml (dict) – The environment YAML data.

Returns:

None

make_refs_and_identifiers_product_specific(product)

Adjusts the rule’s references and identifiers to be product-specific.

This method modifies the rule’s references and identifiers by appending a product-specific suffix to them. It ensures that general references do not contain product-specific identifiers and raises an error if such identifiers are found.

Parameters:

product (str) – The product identifier to be appended to references and identifiers.

Returns:

None

Raises:

ValueError – If an unexpected reference identifier without a product qualifier is found, or if there is an error processing the references or identifiers.

merge_control_references()

Merges control references into the main references dictionary.

This method iterates over the control references and adds them to the main references dictionary. If a reference type already exists in the main references, the control references of that type are appended to the existing list. If the reference type does not exist, it is added to the main references dictionary.

Returns:

None

normalize(product)

Normalize the given product by making references and identifiers product-specific and applying product-specific templates.

Parameters:

product (str) – The product to be normalized.

Returns:

None

Raises:

RuntimeError – If an error occurs during normalization, an exception is raised with a message indicating the rule and the error message.

read_policy_specific_content(env_yaml, files)

Reads policy-specific content from a list of files and returns a dictionary of keys.

Parameters:

• env_yaml (dict) – A dictionary containing environment-specific YAML data.

• files (list) – A list of file paths to read the policy-specific content from.

Returns:

A dictionary where the keys are policy identifiers and the values are the

corresponding YAML data.

Return type:

dict

read_policy_specific_content_file(env_yaml, filename)

Reads and processes a policy-specific content file.

Parameters:

• env_yaml (dict) – The environment variables and macros for YAML expansion.

• filename (str) – The path to the policy-specific content file.

Returns:

The processed YAML data from the content file.

Return type:

dict

to_ocil()

Converts the rule to OCIL format.

This method generates an OCIL questionnaire, boolean question test action, and boolean question for the rule. It ensures that the rule has the necessary OCIL and OCIL clause information, and processes the OCIL content to remove HTML and XML tags where necessary.

Returns:

A tuple containing the OCIL questionnaire, boolean question test action, and

boolean question elements.

Return type:

tuple

Raises:

ValueError – If the rule does not have OCIL or OCIL clause information.

to_xml_element(env_yaml=None)

Converts the rule object to an XML element.

Parameters:

env_yaml (dict, optional) – A dictionary containing environment-specific YAML data. If provided, it will be used to fetch reference URIs. Defaults to None.

Returns:

An XML element representing the rule.

Return type:

xml.etree.ElementTree.Element

triage_policy_specific_content(product_name, filenames)

Organizes filenames by policy based on the product name and specific criteria.

Parameters:

• product_name (str) – The name of the product.

• filenames (list) – A list of filenames to be triaged.

Returns:

A dictionary where the keys are policy names and the values are filenames that

match the criteria for storage.

Return type:

dict

validate_identifiers(yaml_file)

Validates the identifiers in the given YAML file.

Parameters:

yaml_file (str) – The path to the YAML file being validated.

Returns:

None

Raises:

ValueError – If the identifiers section is empty, if any identifier or value is not a string, if any identifier value is empty, if a CCE identifier format is invalid, or if a CCE identifier value is not a valid checksum.

validate_references(yaml_file)

Validates the references section of a YAML file.

Parameters:

yaml_file (str) – The path to the YAML file being validated.

Returns:

None

Raises:

• ValueError – If the references section is empty.

• ValueError – If any reference type is not a string.

• ValueError – If any reference value is empty.

• ValueError – If any reference contains leading or trailing whitespace.

class ssg.build_yaml.Value(id_)

Bases: XCCDFEntity

Represents an XCCDF Value entity.

KEYS

A dictionary of default values for various attributes.

Type:

dict

MANDATORY_KEYS

A set of keys that are mandatory for the Value entity.

Type:

set

KEYS: Dict[str, Callable[[], Any | None]] = {'definition_location': <function XCCDFEntity.<lambda>>, 'description': <function Value.<lambda>>, 'id_': <function XCCDFEntity.<lambda>>, 'interactive': <function Value.<lambda>>, 'operator': <function Value.<lambda>>, 'options': <function Value.<lambda>>, 'title': <function XCCDFEntity.<lambda>>, 'type': <function Value.<lambda>>, 'warnings': <function Value.<lambda>>}

MANDATORY_KEYS: Set[str] = {'description', 'title', 'type'}

classmethod from_yaml(yaml_file, env_yaml=None, product_cpes=None)

Create an instance of the class from a YAML file.

Parameters:

• yaml_file (str) – Path to the YAML file.

• env_yaml (str, optional) – Path to an environment YAML file. Defaults to None.

• product_cpes (str, optional) – Product CPEs information. Defaults to None.

Returns:

An instance of the class created from the YAML file.

Return type:

Value

classmethod process_input_dict(input_contents, env_yaml, product_cpes=None)

Processes the input dictionary for a given environment YAML and optional product CPEs.

Parameters:

• input_contents (dict) – The input dictionary containing various parameters.

• env_yaml (dict) – The environment YAML configuration.

• product_cpes (optional) – Product CPEs, if any.

Returns:

Processed data dictionary with validated and possibly modified contents.

Return type:

dict

Raises:

ValueError – If the operator in the input data is not one of the expected possible operators.

to_xml_element()

Converts the current object to an XML element.

This method creates an XML element representing the current object using the XCCDF 1.2 namespace. It sets attributes and child elements based on the object’s properties.

Returns:

The XML element representing the object.

Return type:

xml.etree.ElementTree.Element

ssg.build_yaml.add_benchmark_metadata(element, include_contributors)

Adds benchmark metadata to an XML element.

This function appends metadata information to the provided XML element, including publisher, creator, contributors, and source information.

Parameters:

• element (xml.etree.ElementTree.Element) – The XML element to which the metadata will be added.

• include_contributors (bool) – A flag indicating whether to include contributors in the metadata.

Returns:

None

ssg.build_yaml.add_nondata_subelements(element, subelement, attribute, attr_data)

Add multiple iterations of a subelement that contains an attribute but no data.

This function creates subelements under a given XML element. Each subelement will have a specified attribute set to a value from the provided list of attribute data.

Parameters:

• element (xml.etree.ElementTree.Element) – The parent XML element to which subelements will be added.

• subelement (str) – The tag name of the subelements to be created.

• attribute (str) – The name of the attribute to be set on each subelement.

• attr_data (list) – A list of values to be assigned to the specified attribute of each subelement.

ssg.build_yaml.add_platform_if_not_defined(platform, product_cpes)

Adds a platform to the product_cpes if it is not already defined.

Parameters:

• platform (Platform) – The platform to be added.

• product_cpes (ProductCPEs) – The product CPEs object containing platforms.

Returns:

The existing platform if it was already defined, otherwise the newly added platform.

Return type:

Platform

ssg.build_yaml.add_reference_elements(element, references, ref_uri_dict)

Adds reference elements to an XML element based on provided references and their corresponding URIs.

Parameters:

• element (xml.etree.ElementTree.Element) – The XML element to which reference elements will be added.

• references (dict) – A dictionary where keys are reference types (e.g., ‘srg’) and values are lists of reference values.

• ref_uri_dict (dict) – A dictionary mapping reference types to their corresponding URIs.

Returns:

None

Raises:

ValueError – If an SRG reference does not have a defined URI or if an unknown reference type is encountered.

ssg.build_yaml.add_reference_title_elements(benchmark_el, env_yaml)

Adds reference title elements to the given benchmark element.

This function creates and appends reference elements to the provided benchmark element. The references are sourced from the env_yaml if provided, otherwise from the default SSG_REF_URIS.

Parameters:

• benchmark_el (xml.etree.ElementTree.Element) – The benchmark element to which reference elements will be added.

• env_yaml (dict) – A dictionary containing reference URIs. If None, the default SSG_REF_URIS will be used.

Returns:

None

ssg.build_yaml.add_warning_elements(element, warnings)

Adds warning elements to the given XML element.

This function iterates over a list of warning dictionaries and adds each warning as a sub-element to the provided XML element. Each dictionary in the warnings list should contain a single key-value pair, where the key represents the warning category and the value represents the warning text.

Parameters:

• element (xml.etree.ElementTree.Element) – The XML element to which the warning elements will be added.

• warnings (list of dict) – A list of dictionaries, each containing a single key-value pair representing the warning category and text.

Returns:

None

ssg.build_yaml.check_warnings(xccdf_structure)

Checks the warnings in the given xccdf_structure.

This function iterates through the warnings in the xccdf_structure and ensures that each warning dictionary contains exactly one key/value pair. If a warning dictionary contains more than one key/value pair, a ValueError is raised with an appropriate message.

Parameters:

xccdf_structure (object) – An object that contains a list of warning dictionaries under the attribute ‘warnings’.

Returns:

None

Raises:

ValueError – If any warning dictionary contains more than one key/value pair.

ssg.build_yaml.noop_rule_filterfunc(rule)

ssg.build_yaml.reorder_according_to_ordering(unordered, ordering, regex=None)

Reorders a list of items according to a specified ordering.

Parameters:

• unordered (list) – The list of unordered items.

• ordering (list) – The list of items specifying the desired order.

• regex (str, optional) – A regex pattern to filter items to be ordered. If None, a pattern is created from the ordering list.

Returns:

A list of items ordered according to the ordering list, followed by any remaining

items sorted alphabetically.

Return type:

list

ssg.build_yaml.restore_original_test_object(platform, product_cpes)

ssg.build_yaml.rule_filter_from_def(filterdef)

Creates a filter function based on the provided filter definition.

Parameters:

filterdef (str or None) – A string containing a Python expression that will be used to filter rules. If None or an empty string is provided, a no-operation filter function is returned.

Returns:

A function that takes a rule object and evaluates the filter definition against

the rule’s attributes. If the filter definition is None or an empty string, a no-operation filter function is returned.

Return type:

function

Note

The filter function uses eval to evaluate the filter definition. For security reasons, only the rule’s attributes are exposed to the evaluation context, and Python built-ins are not available.