ssg.templates module

Common functions for processing Templates in SSG

class ssg.templates.Builder(env_yaml, resolved_rules_dir, templates_dir, remediations_dir, checks_dir, platforms_dir, cpe_items_dir)

Bases: object

Class for building all templated content for a given product.

To generate content from templates, pass the env_yaml, path to the directory with resolved rule YAMLs, path to the directory that contains templates, path to the output directory for checks and a path to the output directory for remediations into the constructor. Then, call the method build() to perform a build.

env_yaml

Environment YAML configuration.

Type:

dict

resolved_rules_dir

Path to the directory with resolved rule YAMLs.

Type:

str

templates_dir

Path to the directory that contains templates.

Type:

str

remediations_dir

Path to the output directory for remediations.

Type:

str

checks_dir

Path to the output directory for checks.

Type:

str

platforms_dir

Path to the directory for platforms.

Type:

str

cpe_items_dir

Path to the directory for CPE items.

Type:

str

output_dirs

Dictionary of output directories for different languages.

Type:

dict

templates

Dictionary of loaded templates.

Type:

dict

product_cpes

Instance of ProductCPEs for managing CPE items.

Type:

ProductCPEs

build()

Builds all templated content for all languages and writes the output to the correct build directories.

This method performs the following steps: 1. Creates the necessary output directories. 2. Builds extra OVAL definitions. 3. Builds all rules. 4. Builds all platforms.

Returns:

None

Raises:

OSError – If there is an issue creating the output directories.

build_all_platforms()

Builds all platforms by iterating through the files in the platforms directory.

This method reads each platform file, constructs a Platform object from the YAML data, and then builds the platform using the build_platform method. The platforms are processed in sorted order based on their filenames.

Returns:

None

Raises:

• OSError – If there is an issue reading the platforms directory or files.

• ssg.build_yaml.PlatformError – If there is an issue constructing the Platform object.

build_all_rules()

Builds all rules from YAML files located in the resolved rules directory.

This method iterates over all files in the resolved rules directory, sorts them, and attempts to create a Rule object from each file. If a rule is marked as “documentation-incomplete” and the build is not in debug mode, it skips that rule. If a rule is templated, it calls the build_rule method to process it.

Returns:

None

Raises:

ssg.build_yaml.DocumentationNotComplete – If a rule’s documentation is incomplete and the build is not in debug mode.

build_cpe(cpe)

Builds and processes a CPE (Common Platform Enumeration) item.

This method generates language-specific templates for the given CPE item, processes them based on their template type, and then adds the CPE item to the product’s CPE list. Finally, it dumps the CPE item to a YAML file.

Parameters:

cpe (CPE) – The CPE item to be processed.

Returns:

None

build_extra_ovals()

Builds and processes extra OVAL definitions from a YAML declaration file.

This method reads a YAML file named “extra_ovals.yml” located in the templates directory. It iterates over the items in the YAML file, where each item represents an OVAL definition. For each OVAL definition, it creates a rule instance using the definition ID and template, builds the corresponding language-specific content, and writes the content to the appropriate location.

Returns:

None

Raises:

• FileNotFoundError – If the “extra_ovals.yml” file does not exist in the templates directory.

• ssg.yaml.YAMLError – If there is an error parsing the YAML file.

build_lang_for_templatable(templatable, lang)

Builds templated content of a given Templatable for a selected language.

Parameters:

• templatable (Templatable) – The object that contains the template to be filled.

• lang (str) – The language code for which the template should be filled.

Returns:

The filled template content for the specified language.

Return type:

str

build_platform(platform)

Builds templated content for a given platform, processing all CPEs/Symbols for all available languages.

The method writes the output to the appropriate build directories and updates the platform itself.

Parameters:

platform (Platform) – The platform object containing CPEs/Symbols to be processed.

The method performs the following steps: 1. Identifies languages affecting the platform by examining the symbols associated with the platform’s tests. 2. For each CPE that is templated, it builds the CPE and determines the languages that need to be generated. 3. Updates the platform’s conditional items based on the resolved languages and CPE items. 4. Dumps the platform’s data into a YAML file in the designated platforms directory.

build_rule(rule)

Builds templated content of a given Rule for all available languages, writing the output to the correct build directories.

Parameters:

rule (Rule) – The rule object containing the data to be templated.

Returns:

None

get_lang_contents_for_templatable(templatable, language)

Generate and return the content for a specified language for a given Templatable object.

Parameters:

• templatable (Templatable) – The Templatable object for which to generate content.

• language (Language) – The language for which to generate content.

Returns:

The generated content for the specified language.

Return type:

str

Raises:

RuntimeError – If there is an error generating the template language content.

get_resolved_langs_to_generate(templatable)

Determine the languages to generate for a given Templatable instance.

This method calculates the intersection of the languages supported by the template and the languages specified in the Templatable’s template configuration ‘backends’.

Parameters:

templatable (Templatable) – An instance of a Templatable object.

Returns:

A set of languages that are both supported by the template and specified in the

Templatable’s configuration.

Return type:

set

Raises:

ValueError – If the template used by the Templatable does not exist.

process_template_lang_file(template_name, template_vars, lang, local_env_yaml)

Processes a template for a given template name and language, and returns the rendered content.

Parameters:

• template_name (str) – The name of the template to process.

• template_vars (dict) – A dictionary of variables to be used in the template.

• lang (object) – An object representing the language, which should have a ‘name’ attribute.

• local_env_yaml (dict) – A dictionary of local environment variables to be merged with the global environment variables.

Returns:

The rendered content of the template.

Return type:

str

Raises:

ValueError – If the specified language is not available for the given template.

write_lang_contents_for_templatable(filled_template, lang, templatable)

Writes the filled template content to a file specific to the given language.

Parameters:

• filled_template (str) – The content to be written to the file.

• lang (Language) – The language object containing language-specific details.

• templatable (Templatable) – The templatable object containing the id_ attribute.

The output file name is generated by appending the language-specific file extension to the templatable’s id_. The file is then written to the appropriate output directory for the given language.

class ssg.templates.Template(templates_root_directory, name)

Bases: object

A class to represent a template for content generation.

templates_root_directory

The root directory where templates are stored.

Type:

str

name

The name of the template.

Type:

str

langs

A list to store supported languages.

Type:

list

template_path

The path to the template directory.

Type:

str

template_yaml_path

The path to the template’s YAML configuration file.

Type:

str

preprocessing_file_path

The path to the template’s preprocessing file.

Type:

str

classmethod load_template(templates_root_directory, name)

Load a template if it exists and looks like a template.

Parameters:

• cls – The class that this method belongs to.

• templates_root_directory (str) – The root directory where templates are stored.

• name (str) – The name of the template to load.

Returns:

An instance of the template if it exists and looks like a template, otherwise None.

preprocess(parameters, lang)

Preprocess the given parameters by applying template module preprocessing and converting parameter keys to uppercase.

Parameters:

• parameters (dict) – The parameters to preprocess.

• lang (str) – The language code.

Returns:

The preprocessed parameters with keys in uppercase.

Return type:

dict

class ssg.templates.TemplatingLang(name, file_extension, template_type, lang_specific_dir)

Bases: tuple

file_extension

Alias for field number 1

lang_specific_dir

Alias for field number 3

name

Alias for field number 0

template_type

Alias for field number 2

ssg.templates.load_module(module_name: str, module_path: str)

Loads a Python module from a given file path.

This function attempts to load a module using importlib.

Parameters:

• module_name (str) – The name to assign to the loaded module.

• module_path (str) – The file path to the module to be loaded.

Returns:

The loaded module object.

Return type:

module

Raises:

ValueError – If the module cannot be loaded due to an invalid spec or loader.