ssg.controls module

Common functions for processing Controls in SSG

class ssg.controls.Control

Bases: SelectionHandler, XCCDFEntity

Represents a control entity with various attributes and methods to handle control-related operations.

KEYS

A dictionary defining the expected keys and their types.

Type:

dict

MANDATORY_KEYS

A set of keys that are mandatory for a control.

Type:

set

KEYS: Dict[str, Callable[[], Any | None]] = {'artifact_description': <class 'str'>, 'automated': <class 'str'>, 'check': <class 'str'>, 'controls': <class 'list'>, 'description': <class 'str'>, 'fixtext': <class 'str'>, 'id': <class 'str'>, 'levels': <class 'list'>, 'mitigation': <class 'str'>, 'notes': <class 'str'>, 'original_title': <class 'str'>, 'rationale': <class 'str'>, 'related_rules': <class 'list'>, 'rules': <class 'list'>, 'status': <function Control.<lambda>>, 'status_justification': <class 'str'>, 'tickets': <class 'list'>, 'title': <class 'str'>}

MANDATORY_KEYS: Set[str] = {'title'}

add_references(reference_type, rules)

Adds references to the specified rules based on the given reference type.

Parameters:

• reference_type (str) – The type of reference to add.

• rules (dict) – A dictionary of rules where the key is the rule id and the value is the rule object.

Raises:

ValueError – If there is a duplicate listing of a rule in the control.

classmethod from_control_dict(control_dict, env_yaml=None, default_level=None)

Create a control instance from a dictionary of control attributes.

Parameters:

• cls – The class itself.

• control_dict (dict) – A dictionary containing control attributes.

• env_yaml (optional) – Environment YAML configuration (default is None).

• default_level (list, optional) – Default level for the control (default is [“default”]).

Returns:

An instance of the control class populated with attributes from the control_dict.

Raises:

ValueError – If the ‘automated’ key has an invalid value or if ‘levels’ is not a list.

represent_as_dict()

Represents the Control object as a dictionary.

This method overrides the represent_as_dict method from the superclass. It adds the rules and controls attributes to the dictionary representation.

Returns:

A dictionary representation of the Control object, including

the rules and controls attributes.

Return type:

dict

class ssg.controls.ControlsManager(controls_dirs: List[str], env_yaml=None, existing_rules=None)

Bases: object

Manages the loading, processing, and saving of control policies.

controls_dirs

The directories where control policy files are located.

Type:

List[str]

env_yaml

The environment YAML file.

Type:

str, optional

existing_rules

Existing rules to check against.

Type:

dict, optional

policies

A dictionary of loaded policies.

Type:

dict

add_references(rules)

Add references to the policies and unify them under a single attribute.

This method first adds all control references into a separate attribute for each policy. Then, it unifies them under the references attribute. This allows multiple control files to add references of the same type while still tracking what references already existed in the rule.

Parameters:

rules (dict) – A dictionary containing the rules to which references will be added.

check_all_rules_exist()

Checks if all rules exist for each policy.

This method iterates through all policies and calls the check_all_rules_exist method on each policy, passing the existing rules as an argument. If existing_rules is None, the method returns immediately.

Returns:

None

get_all_controls(policy_id)

Retrieve all controls associated with a given policy.

Parameters:

policy_id (str) – The unique identifier of the policy.

Returns:

A list of control objects associated with the specified policy.

Return type:

list

get_all_controls_dict(policy_id: str) → Dict[str, Control]

Retrieve all controls for a given policy as a dictionary.

Parameters:

policy_id (str) – The unique identifier of the policy.

Returns:

A dictionary where the keys are control IDs and the values are lists

of controls.

Return type:

Dict[str, list]

get_all_controls_of_level(policy_id: str, level_id: str) → List[Control]

Retrieve all controls associated with a specific policy and level, including inherited levels.

This method fetches all controls for a given policy and filters them based on the specified level and its ancestor levels. Controls from higher levels can override variables defined in lower levels.

Parameters:

• policy_id (str) – The unique identifier of the policy.

• level_id (str) – The unique identifier of the level within the policy.

Returns:

A list of controls that are eligible for the specified level, with variables

from higher levels overriding those from lower levels.

Return type:

list

get_control(policy_id, control_id)

Retrieve a specific control from a policy.

Parameters:

• policy_id (str) – The unique identifier of the policy.

• control_id (str) – The unique identifier of the control within the policy.

Returns:

The control object associated with the given control_id within the specified policy.

Return type:

Control

Raises:

• PolicyNotFoundError – If the policy with the given policy_id does not exist.

• ControlNotFoundError – If the control with the given control_id does not exist within the policy.

load()

Load policies from YAML files in the controls directory.

This method checks if the controls directory exists. If it does, it loads all YAML files in the directory, creates Policy objects from them, and stores them in the self.policies dictionary using their IDs as keys. After loading all policies, it checks that all rules exist and resolves controls.

Returns:

None

load_compiled()

policies: Dict

remove_selections_not_known(known_rules)

Remove selections from policies that are not in the known rules.

This method iterates over all policies and removes any selections that are not present in the provided known rules set.

Parameters:

known_rules (iterable) – An iterable of known rule identifiers.

resolve_controls()

Resolves controls for each policy in the policies dictionary.

Iterates through each policy and its associated controls, calling the _resolve_control method for each control.

Returns:

None

save_everything(output_dir)

Saves all policies to the specified output directory in JSON format.

Parameters:

output_dir (str) – The directory where the policy files will be saved.

Returns:

None

exception ssg.controls.InvalidStatus

Bases: Exception

class ssg.controls.Level

Bases: XCCDFEntity

Represents a security control level entity.

id

The unique identifier for the level.

Type:

str

inherits_from

The identifier of the level from which this level inherits, if any.

Type:

str or None

Returns:

An instance of the Level class.

Return type:

Level

KEYS: Dict[str, Callable[[], Any | None]] = {'id': <function Level.<lambda>>, 'inherits_from': <function Level.<lambda>>}

classmethod from_level_dict(level_dict)

Create an instance of the class from a dictionary.

Parameters:

level_dict (dict) – A dictionary containing the level data. Must include the key “id”. May include the key “inherits_from”.

Returns:

An instance of the class with attributes set according to the dictionary.

class ssg.controls.Policy(filepath, env_yaml=None)

Bases: XCCDFEntity

Represents a security policy defined in an XCCDF file.

id

The identifier of the policy.

Type:

str

env_yaml

The environment YAML configuration.

Type:

dict

filepath

The file path to the policy definition.

Type:

str

controls_dir

The directory containing control definitions.

Type:

str

controls

A list of controls associated with the policy.

Type:

list

controls_by_id

A dictionary mapping control IDs to control objects.

Type:

dict

levels

A list of levels defined for the policy.

Type:

list

levels_by_id

A dictionary mapping level IDs to level objects.

Type:

dict

title

The title of the policy.

Type:

str

source

The source of the policy.

Type:

str

reference_type

The type of reference used in the policy.

Type:

str

product

A list of products associated with the policy.

Type:

list

add_references(rules)

Adds references to the controls based on the provided rules.

This method checks if the reference type is specified and if the current product matches the product specified in the environment YAML. It also verifies if the reference type is allowed based on the reference URIs defined in the environment YAML. If all checks pass, it adds references to the controls by calling the add_references method on each control.

Parameters:

rules (dict) – A dictionary containing the rules to be applied.

Raises:

ValueError – If the reference type is unknown.

check_all_rules_exist(existing_rules)

Checks if all rules in the controls exist in the given set of existing rules.

Parameters:

existing_rules (set) – A set of existing rule identifiers.

Raises:

ValueError – If any control contains rules that do not exist in the given set of existing rules.

check_levels_validity()

Validates the levels defined for each control in the policy.

This function iterates through all controls in the policy and ensures that the levels defined for each control are valid according to the policy’s defined levels. If the policy does not have any levels defined, it implicitly assumes that all controls should have the “default” level.

Raises:

ValueError – If a control has a level that is not defined in the policy’s allowed levels, an error message is raised indicating the invalid level, the control ID, the file path, and the allowed levels.

property default_level

Returns the default level.

If the instance has levels, it returns a list containing the id of the first level. Otherwise, it returns a list containing the string “default”.

Returns:

A list containing either the id of the first level or the string “default”.

Return type:

list

get_control(control_id)

Retrieve a control by its ID.

Parameters:

control_id (str) – The ID of the control to retrieve.

Returns:

The control object associated with the given ID.

Return type:

Control

Raises:

ValueError – If the control ID is not found in the policy.

get_level(level_id)

Retrieve a level by its ID.

Parameters:

level_id (str) – The ID of the level to retrieve.

Returns:

The level object corresponding to the given ID.

Return type:

Level

Raises:

ValueError – If the level ID is not found in the levels_by_id dictionary.

get_level_with_ancestors_sequence(level_id)

Retrieve a sequence of levels starting from the specified level and including all its ancestor levels.

This method uses an OrderedDict to maintain the order of levels and ensure compatibility with Python 2. It starts with the given level and recursively adds all ancestor levels, avoiding duplicates.

Parameters:

level_id (str) – The ID of the starting level.

Returns:

A list of levels starting from the specified level and including all its ancestors.

Return type:

list

load()

Loads and processes the YAML configuration file specified by self.filepath.

This method performs the following steps: 1. Opens and expands the YAML file. 2. Extracts and sets various attributes from the YAML contents, such as controls_dir,

id, policy, title, source, reference_type, and product.

3. Processes the levels section of the YAML file and populates the self.levels and self.levels_by_id attributes.

4. Loads the controls tree from the specified directory or directly from the YAML contents.

5. Saves the controls tree and checks the validity of the levels.

Raises:

KeyError – If required keys are missing in the YAML contents.

remove_selections_not_known(known_rules)

Remove selections and unselections that are not in the known rules.

This method updates the selected and unselected attributes of each control in self.controls by retaining only those elements that are present in the known_rules set.

Parameters:

known_rules (set) – A set of known rule identifiers.

represent_as_dict()

Represents the object as a dictionary.

Returns:

A dictionary representation of the policy object, containing the following keys:

• ”id”: The ID of the object.

• ”policy”: The policy associated with the object.

• ”title”: The title of the object.

• ”source”: The source of the object.

• ”definition_location”: The file path where the object is defined.

• ”controls”: A list of dictionaries representing the controls associated with the object.

• ”levels”: A list of dictionaries representing the levels associated with the object.

Return type:

dict

save_controls_tree(tree)

Saves the controls tree by parsing the given tree and appending each control to the controls list and controls_by_id dictionary.

Parameters:

tree (Any) – The tree structure containing controls to be parsed and saved.

class ssg.controls.Status(status)

Bases: object

The Status class represents various statuses that can be assigned to controls.

SUPPORTED

Indicates the control is supported for the relevant products but is not enabled by default.

Type:

str

PLANNED

Indicates that maintainers plan to work on the control in the near future.

Type:

str

PENDING

Indicates the control is not yet automated and there is no plan to work on it soon.

Type:

str

PARTIAL

Indicates the control is partially automated but requires additional work for full automation.

Type:

str

NOT_APPLICABLE

Indicates the control is not applicable for the products that are being evaluated or targeted by the policy.

Type:

str

MANUAL

Indicates the control requires manual intervention and is not expected to be automated.

Type:

str

INHERENTLY_MET

Indicates the control is inherently met. This means that the control is satisfied by the nature of the system or environment, without requiring additional configuration or actions.

Type:

str

DOES_NOT_MEET

Indicates the control does not meet requirements.

Type:

str

DOCUMENTATION

Indicates the control is related to documentation.

Type:

str

AUTOMATED

Indicates the control is fully automated.

Type:

str

AUTOMATED = 'automated'

DOCUMENTATION = 'documentation'

DOES_NOT_MEET = 'does not meet'

INHERENTLY_MET = 'inherently met'

MANUAL = 'manual'

NOT_APPLICABLE = 'not applicable'

PARTIAL = 'partial'

PENDING = 'pending'

PLANNED = 'planned'

SUPPORTED = 'supported'

classmethod from_control_info(ctrl, status)

Create a control status from the given control information.

Parameters:

• cls (Type) – The class type that this method is called on.

• ctrl (str) – The control identifier.

• status (str or None) – The status of the control.

Returns:

The status of the control if valid, otherwise cls.PENDING.

Return type:

str

Raises:

InvalidStatus – If the given status is not in the list of valid statuses.

classmethod get_status_list()

Retrieve a list of valid status constants.

Returns:

A list containing the valid status constants defined in the class.

Return type:

list