ssg.xml module

Common functions for processing XML in SSG

class ssg.xml.XMLBenchmark(root)[source]

Bases: XMLElement

Represents an XCCDF Benchmark read from an XML file.

root

The root element of the XML document.

Type:: Element

find_all_cpe_platforms(idref)[source]

Find all CPE platforms with the given idref.

Parameters:: idref (str) – The reference ID of the CPE platform to find.
Returns:: A list of XMLCPEPlatform objects that match the given idref.
Return type:: list

find_rule(rule_id)[source]

Find and return an XMLRule object for the given rule ID.

Parameters:: rule_id (str) – The ID of the rule to find.
Returns:: An XMLRule object if the rule is found, otherwise None.
Return type:: XMLRule

find_rules(rule_id)[source]

Find and return rules based on the given rule_id.

Parameters:

rule_id (str) – The ID of the rule to find. If None, all rules are returned.

Returns:

A list of XMLRule objects that match the given rule_id.: If rule_id is None, returns all rules.

Return type:

list

Raises:

ValueError – If no rules are found for the given rule_id.

class ssg.xml.XMLCPEPlatform(root)[source]

Bases: XMLElement

A class to represent an XML CPE Platform element.

root

The root element of the XML tree.

Type:: xml.etree.ElementTree.Element

find_all_check_fact_ref_elements()[source]

class ssg.xml.XMLComponent(root)[source]

Bases: XMLElement

Represents the element of the Datastream component that has relevant content.

This makes it easier to access contents pertaining to a SCAP component.

find_boolean_question(ocil_id)[source]

Finds and returns the text of a boolean question from an OCIL questionnaire.

Parameters:: ocil_id (str) – The ID of the OCIL questionnaire.
Returns:: The text of the boolean question.
Return type:: str
Raises:: ValueError – If the OCIL questionnaire, test action, or boolean question does not exist.

find_ocil_boolean_question(question_id)[source]

Find an OCIL boolean question by its ID.

Parameters:: question_id (str) – The ID of the boolean question to find.
Returns:: An instance of XMLOcilQuestion representing the found boolean question.
Return type:: XMLOcilQuestion
Raises:: AttributeError – If the question is not found or if the XML structure is incorrect.

find_ocil_questionnaire(def_id)[source]

Finds and returns an OCIL questionnaire by its definition ID.

Parameters:

def_id (str) – The definition ID of the OCIL questionnaire to find.

Returns:

An instance of XMLOcilQuestionnaire representing the found: questionnaire.

Return type:

XMLOcilQuestionnaire

Raises:

AttributeError – If the ‘ocil:questionnaires’ or ‘ocil:questionnaire’ elements are not found.

find_ocil_test_action(test_action_ref)[source]

Finds and returns an OCIL test action based on the provided reference ID.

Parameters:: test_action_ref (str) – The reference ID of the test action to find.
Returns:: An instance of XMLOcilTestAction representing the found test action.
Return type:: XMLOcilTestAction
Raises:: AttributeError – If the test action is not found in the XML structure.

find_oval_definition(def_id)[source]

Find and return an OVAL definition by its ID.

Parameters:: def_id (str) – The ID of the OVAL definition to find.
Returns:: An instance of XMLOvalDefinition representing the found definition.
Return type:: XMLOvalDefinition
Raises:: AttributeError – If the definitions or definition element is not found.

class ssg.xml.XMLContent(root)[source]

Bases: XMLElement

XMLContent is a class that represents a Data Stream or an XCCDF Benchmark read from an XML file.

check_engines

A list of tuples containing check engine names and their corresponding XML tags.

Type:: list

check_engines = [('OVAL', 'oval:oval_definitions'), ('OCIL', 'ocil:ocil')]

find_benchmark(id_)[source]

Finds and returns an XMLBenchmark object for the given benchmark ID.

This method searches for a benchmark with the specified ID within the XML structure. It first looks for “ds:component” elements and checks if any of them contain a “Benchmark” element with the given ID. If no “ds:component” elements are found, it checks if the root element is a benchmark itself.

Parameters:

id (str) – The ID of the benchmark to find.

Returns:

An XMLBenchmark object if a benchmark with the given ID is found,: otherwise None.

Return type:

XMLBenchmark

get_benchmarks()[source]

Extracts and yields XMLBenchmark objects from the XML tree.

This method searches for ‘ds:component’ elements in the XML tree. If no such elements are found, it checks if the root element is a benchmark and yields an XMLBenchmark object if true. Otherwise, it iterates over each ‘ds:component’ element and searches for ‘Benchmark’ elements within the component, yielding an XMLBenchmark object for each found benchmark.

Yields:: XMLBenchmark – An instance of XMLBenchmark for each found benchmark in the XML tree.

get_component_refs()[source]

Extracts and returns a dictionary of component references from the XML data.

This method searches for all “ds:component-ref” elements within “ds:checks” elements in the XML data stream. It retrieves the “href” attribute from the “xlink” namespace and the “id” attribute from each “ds:component-ref” element and stores them in a dictionary.

Returns:

A dictionary where the keys are the “href” attributes and the values are the: ”id” attributes of the “ds:component-ref” elements.

Return type:

dict

get_uris()[source]

Extracts URIs and their corresponding names from the XML data.

This method searches through the XML structure defined in self.root for data streams, checklists, and catalogs to find URI elements. It then extracts the ‘uri’ and ‘name’ attributes from each URI element and stores them in a dictionary.

Returns:

A dictionary where the keys are URI strings and the values are the corresponding: names.

Return type:

dict

is_benchmark()[source]

Determines if the root tag of the XML document is a Benchmark tag.

This method checks if the root tag of the XML document matches the Benchmark tag for either the “xccdf-1.2” or “xccdf-1.1” namespace. If the root tag matches the “xccdf-1.2” namespace, it returns True. If the root tag matches the “xccdf-1.1” namespace, it sets the content_xccdf_ns attribute to “xccdf-1.1” and returns True.

Returns:

True if the root tag is a Benchmark tag for either “xccdf-1.2” or “xccdf-1.1”: namespace, False otherwise.

Return type:

bool

class ssg.xml.XMLElement(root)[source]

Bases: object

Represents a generic element read from an XML file.

ns

A dictionary mapping namespace prefixes to their respective URIs.

Type:: dict

root

The root element of the XML structure.

Type:: Element

content_xccdf_ns

The XCCDF version namespace determined from the XML.

Type:: str

get_attr(attr)[source]

Retrieve the value of an attribute from the root element.

Parameters:: attr (str) – The name of the attribute to retrieve.
Returns:: The value of the attribute if it exists, otherwise None.
Return type:: str or None

get_namespace()[source]

Extracts and returns the XML namespace from the root tag of the XML document.

Returns:: The namespace URI extracted from the root tag.
Return type:: str
Raises:: AttributeError – If the root tag does not contain a namespace.

ns = {'catalog': 'urn:oasis:names:tc:entity:xmlns:xml:catalog', 'cpe-lang': 'http://cpe.mitre.org/language/2.0', 'ds': 'http://scap.nist.gov/schema/scap/source/1.2', 'ocil': 'http://scap.nist.gov/schema/ocil/2.0', 'oval': 'http://oval.mitre.org/XMLSchema/oval-definitions-5', 'xccdf-1.1': 'http://checklists.nist.gov/xccdf/1.1', 'xccdf-1.2': 'http://checklists.nist.gov/xccdf/1.2', 'xlink': 'http://www.w3.org/1999/xlink'}

class ssg.xml.XMLOcilQuestion(root)[source]

Bases: XMLComponent

A class to represent an OCIL question in XML format.

root

The root element of the XML structure.

Type:: Element

ns

The namespace dictionary for XML parsing.

Type:: dict

get_question_test_element()[source]

Retrieves the ‘question_text’ element from the XML tree.

This method searches for the ‘question_text’ element within the XML tree using the specified namespace.

Returns:: The ‘question_text’ element if found, otherwise None.
Return type:: Element

class ssg.xml.XMLOcilQuestionnaire(root)[source]

Bases: XMLComponent

A class to represent an OCIL Questionnaire in XML format.

root

The root element of the XML structure.

Type:: Element

ns

A dictionary of XML namespaces.

Type:: dict

get_test_action_ref_element()[source]

Retrieves the test action reference element from the XML.

This method searches for the ‘ocil:test_action_ref’ element within the ‘ocil:actions’ section of the XML document using the specified namespace.

Returns:: The found ‘ocil:test_action_ref’ element, or None if not found.
Return type:: Element

class ssg.xml.XMLOcilTestAction(root)[source]

Bases: XMLComponent

A class to represent an OCIL Test Action in XML format.

root

The root element of the XML structure.

Type:: Element

class ssg.xml.XMLOvalDefinition(root)[source]

Bases: XMLComponent

A class to represent an OVAL definition in XML format.

root

The root element of the XML document.

Type:: xml.etree.ElementTree.Element

ns

A dictionary of XML namespaces.

Type:: dict

get_criteria_element()[source]

Retrieves the first ‘oval:criteria’ element from the XML document.

Returns:: The first ‘oval:criteria’ element found in the XML document, or None if no such element is found.
Return type:: xml.etree.ElementTree.Element

get_elements()[source]

Extracts and returns a list of elements from the criteria element.

The method iterates over the children of the criteria element and identifies the tag of each child. Depending on the tag, it extracts relevant attributes and appends them to the elements list as tuples.

Returns:

A list of tuples where each tuple contains the element type and its associated: attribute value. The possible element types and their attributes are: - (“criteria”, operator) - (“criterion”, test_id) - (“extend_definition”, extend_def_id)

Return type:

list

class ssg.xml.XMLRule(root)[source]

Bases: XMLElement

Represents an XCCDF Rule read from an XML file.

root

The root element of the XML tree.

Type:: Element

content_xccdf_ns

The namespace for XCCDF content.

Type:: str

ns

The namespace dictionary for XML parsing.

Type:: dict

get_all_platform_elements()[source]

Retrieve all platform elements from the XML document.

This method searches for all elements with the tag ‘platform’ within the XML document’s root, using the specified namespace.

Returns:: A list of all found platform elements.
Return type:: list

get_check_content_ref_element(check_element)[source]

Retrieves the ‘check-content-ref’ element from the given check element.

Parameters:: check_element (Element) – The XML element representing the check.
Returns:: The ‘check-content-ref’ sub-element if found, otherwise None.
Return type:: Element

get_check_element(check_system_uri)[source]

Retrieve a check element from the XML tree based on the given check system URI.

Parameters:: check_system_uri (str) – The URI of the check system to find.
Returns:: The XML element corresponding to the check system URI, or None if not found.
Return type:: Element

get_element_text(el)[source]

Extracts and returns the text content of an XML element.

If the element’s tag (without namespace) is “description”, it uses a specialized method to get the description text. Otherwise, it concatenates all text within the element.

Parameters:: el (xml.etree.ElementTree.Element) – The XML element from which to extract text.
Returns:: The text content of the XML element.
Return type:: str

get_fix_element(fix_uri)[source]

Retrieve the ‘fix’ element from the XML tree based on the provided fix URI.

Parameters:: fix_uri (str) – The URI of the fix to be retrieved.
Returns:: The XML element corresponding to the fix URI, or None if not found.
Return type:: Element

get_version_element()[source]

Retrieve the version element from the XML document.

This method searches for the version element within the XML document using the specified namespace.

Returns:: The version element if found, otherwise None.
Return type:: Element

join_text_elements()[source]

Collects and concatenates text from relevant subelements of the root element.

This function iterates over the subelements of the root element, collects their text, and concatenates it into a single string. It skips certain elements that are not relevant for comparison, such as “fix” elements and “reference” elements with specific attributes. For each collected text, it injects a line indicating the tag of the element from which the text was collected to facilitate tracking.

Returns:

A concatenated string of text from relevant subelements, with injected lines: indicating the source element tags.

Return type:

str

ssg.xml.add_xhtml_namespace(data)[source]

Given an XML blob, adds the XHTML namespace to all relevant tags.

This function performs two main transformations: 1. It transforms <tt> tags into <code> tags. 2. It adds the XHTML prefix to specified elements.

Parameters:: data (str) – The XML data as a string.
Returns:: The modified XML data with XHTML namespaces added.
Return type:: str

ssg.xml.determine_xccdf_tree_namespace(tree)[source]

Determines the XCCDF namespace of the given XML tree.

Parameters:: tree (xml.etree.ElementTree.ElementTree) – The XML tree to examine.
Returns:: The XCCDF namespace URI.
Return type:: str
Raises:: ValueError – If the root element of the tree is not recognized as a Benchmark element from either XCCDF 1.1 or XCCDF 1.2 namespaces.

ssg.xml.get_element_namespace(self)[source]

Extracts the namespace from the root element’s tag.

The method uses a regular expression to search for a namespace pattern in the root element’s tag. The namespace is expected to be enclosed in curly braces at the beginning of the tag.

Returns:: The namespace extracted from the root element’s tag.
Return type:: str
Raises:: AttributeError – If the root element’s tag does not match the expected pattern.

ssg.xml.get_element_tag_without_ns(xml_tag)[source]

Extracts the tag name from an XML element, removing any namespace.

Parameters:: xml_tag (str) – The XML tag with namespace.
Returns:: The XML tag without the namespace.
Return type:: str
Raises:: AttributeError – If the input string does not match the expected pattern.

ssg.xml.get_namespaces_from(file)[source]

Extracts and returns a dictionary of XML namespaces from the given file.

Parameters:

file (str or file-like object) – The path to the XML file or a file-like object containing XML data.

Returns:

A dictionary where the keys are namespace prefixes and the values are namespace URIs.: Returns an empty dictionary if an error occurs during parsing.

Return type:

dict

Return dictionary of namespaces in file. Return empty dictionary in case of error.

ssg.xml.map_elements_to_their_ids(tree, xpath_expr)[source]

Given an ElementTree and an XPath expression, iterate through matching elements and create 1:1 id->element mapping.

Parameters:

tree (ElementTree) – The XML tree to search within.
xpath_expr (str) – The XPath expression to match elements.

Raises:

AssertionError – If a matching element doesn’t have the id attribute.

Returns:

A dictionary mapping element IDs to their corresponding elements.

Return type:

dict

ssg.xml.open_xml(filename)[source]

Open and parse an XML file.

This function registers all possible namespaces and then parses the XML file specified by the given filename, returning the resulting XML tree.

Parameters:: filename (str) – The path to the XML file to be parsed.
Returns:: The parsed XML tree.
Return type:: xml.etree.ElementTree.ElementTree
Raises:: xml.etree.ElementTree.ParseError – If there is an error parsing the XML file.

ssg.xml.oval_generated_header(product_name, schema_version, ssg_version)[source]

Generates an OVAL header for a given product.

Parameters:

product_name (str) – The name of the product.
schema_version (str) – The version of the OVAL schema.
ssg_version (str) – The version of the SCAP Security Guide (SSG).

Returns:

A string containing the OVAL header with the provided product name, schema version,: SSG version, Python version, and the current timestamp.

Return type:

str

ssg.xml.parse_file(filename)[source]

Parses an XML file and returns the root element of the ElementTree.

Parameters:: filename (str) – The path to the XML file to be parsed.
Returns:: The root element of the parsed XML tree.
Return type:: xml.etree.ElementTree.Element

ssg.xml.register_namespaces(ns=None)[source]

Register all possible namespaces.

This function registers XML namespaces for use with the ElementTree module. If no namespaces are provided, it defaults to using the PREFIX_TO_NS dictionary.

Parameters:: ns (dict, optional) – A dictionary mapping prefixes to namespace URIs. If None, the function uses the PREFIX_TO_NS dictionary.
Raises:: Exception – Catches all exceptions, which may occur if using an old version of Python. This is non-essential and will be silently ignored.