colander_data_converter.converters.stix2.utils

Utility functions for STIX2 to Colander conversion and vice versa.

colander_data_converter.converters.stix2.utils.extract_stix2_pattern_name(stix2_pattern)[source]

Extract the name from a STIX 2 pattern string.

This function parses STIX2 pattern expressions to extract the field name portion before the equality operator. It removes brackets and extracts the left side of the comparison.

Parameters:

stix2_pattern (str) – The STIX 2 pattern string to extract the name from

Returns:

The extracted name or None if no name is found

Return type:

Optional[str]

Note

The function handles various STIX2 pattern formats including nested hash references like file:hashes.'SHA-256'.

Examples

>>> pattern = "[ipv4-addr:value = '192.168.1.1']"
>>> extract_stix2_pattern_name(pattern)
'ipv4-addr:value'
>>> pattern = "[file:hashes.'SHA-256' = '123abc']"
>>> extract_stix2_pattern_name(pattern)
"file:hashes.'SHA-256'"
colander_data_converter.converters.stix2.utils.extract_uuid_from_stix2_id(stix2_id)[source]

Extract a UUID from a STIX2 ID.

This function parses a STIX2 identifier string to extract the UUID portion. STIX2 IDs follow the format {type}--{uuid}, where the UUID is the part after the double dash delimiter.

Parameters:

stix2_id (str) – The STIX2 ID to extract the UUID from

Returns:

The extracted UUID, or a new UUID if extraction fails

Return type:

UUID

Important

If the input format is invalid or UUID extraction fails, a new random UUID is generated and returned instead of raising an exception.

Examples

>>> # Valid STIX2 ID with UUID
>>> stix_id = "indicator--44af6c9f-4bbc-4984-a74b-1404d1ac07ea"
>>> uuid_obj = extract_uuid_from_stix2_id(stix_id)
>>> str(uuid_obj)
'44af6c9f-4bbc-4984-a74b-1404d1ac07ea'
>>> # Invalid STIX2 ID format (no delimiter)
>>> stix_id = "indicator-invalid-format"
>>> uuid_obj = extract_uuid_from_stix2_id(stix_id)
>>> isinstance(uuid_obj, UUID)  # Returns a new random UUID
True
>>> # Invalid UUID part
>>> stix_id = "indicator--not-a-valid-uuid"
>>> uuid_obj = extract_uuid_from_stix2_id(stix_id)
>>> isinstance(uuid_obj, UUID)  # Returns a new random UUID
True
colander_data_converter.converters.stix2.utils.get_nested_value(obj, path)[source]

Get a value from a nested dictionary using a dot-separated path.

This function safely navigates through nested dictionaries using a dot-separated path string. It returns the value at the specified path or None if any part of the path is missing or invalid.

Parameters:
  • obj (Dict[str, Any]) – The dictionary to get the value from

  • path (str) – The dot-separated path to the value

Returns:

The value at the specified path, or None if not found

Return type:

Any

Warning

This function returns None for missing paths rather than raising exceptions. Check for None return values when path existence is critical.

Examples

>>> data = {
...     "user": {
...         "profile": {
...             "name": "John",
...             "age": 30
...         },
...         "settings": {
...             "theme": "dark"
...         }
...     }
... }
>>> get_nested_value(data, "user.profile.name")
'John'
>>> get_nested_value(data, "user.settings.theme")
'dark'
colander_data_converter.converters.stix2.utils.set_nested_value(obj, path, value)[source]

Set a value in a nested dictionary using a dot-separated path.

This function creates nested dictionaries as needed to set a value at the specified dot-separated path. If intermediate dictionaries don’t exist, they are automatically created.

Parameters:
  • obj (Dict[str, Any]) – The dictionary to set the value in

  • path (str) – The dot-separated path to the value

  • value (Any) – The value to set

Note

The function modifies the input dictionary in-place and automatically creates any missing intermediate dictionary levels.

Examples

>>> data = {}
>>> set_nested_value(data, "user.profile.name", "John")
>>> data
{'user': {'profile': {'name': 'John'}}}
>>> # Update existing nested value
>>> data = {'user': {'settings': {'theme': 'light'}}}
>>> set_nested_value(data, "user.settings.theme", "dark")
>>> data
{'user': {'settings': {'theme': 'dark'}}}
>>> # Add new nested path to existing structure
>>> set_nested_value(data, "user.profile.age", 30)
>>> data
{'user': {'settings': {'theme': 'dark'}, 'profile': {'age': 30}}}
>>> # Empty path does nothing
>>> original = {'a': 1}
>>> set_nested_value(original, "", "value")
>>> original
{'a': 1}