colander_data_converter.formats.stix2 package

colander_data_converter.formats.stix2.models module

class colander_data_converter.formats.stix2.models.Stix2Converter[source]

Bases: object

Converter for STIX2 data to Colander data and vice versa. Uses the mapping file to convert between formats.

static colander_to_stix2(colander_feed: ColanderFeed) → Dict[str, Any][source]

Converts Colander data to STIX2 data using the mapping file.

Parameters:: colander_feed (ColanderFeed) – The Colander data to convert.
Returns:: The converted STIX2 data.
Return type:: Dict[str, Any]

static stix2_to_colander(stix2_data: Dict[str, Any]) → ColanderFeed[source]

Converts STIX2 data to Colander data using the mapping file.

Parameters:: stix2_data (Dict[str, Any]) – The STIX2 data to convert.
Returns:: The converted Colander data.
Return type:: ColanderFeed

class colander_data_converter.formats.stix2.models.Stix2Repository(*args, **kwargs)[source]

Bases: object

Singleton repository for managing and storing STIX2 objects.

This class provides centralized storage and reference management for all STIX2 objects, supporting conversion to and from Colander data.

add_object(stix2_object: Dict[str, Any]) → None[source]

Adds a STIX2 object to the repository.

Parameters:: stix2_object (Dict[str, Any]) – The STIX2 object to add.

clear() → None[source]: Clears all STIX2 objects from the repository.

get_object(object_id: str) → Dict[str, Any] | None[source]

Retrieves a STIX2 object from the repository by its ID.

Parameters:: object_id (str) – The ID of the STIX2 object to retrieve.
Returns:: The STIX2 object if found, None otherwise.
Return type:: Optional[Dict[str, Any]]

stix2_objects: Dict[str, Dict[str, Any]]

colander_data_converter.formats.stix2.mapping module

class colander_data_converter.formats.stix2.mapping.Stix2MappingLoader[source]

Bases: object

Loads and provides access to the STIX2 to Colander mapping data.

get_colander_to_stix2_field_mapping(entity_type: str) → Dict[str, str][source]

Get the field mapping from Colander to STIX2 for a specific entity type.

Parameters:: entity_type (str) – The entity type.
Returns:: The field mapping from Colander to STIX2.
Return type:: Dict[str, str]

get_entity_subtype_mapping(entity_type: str, entity_subtype: str) → Dict[str, Any][source]

Get the mapping data for a specific Colander entity type.

Parameters:

entity_type (str) – The entity type (e.g., “actor”, “device”).
entity_subtype (str) – The Colander entity subtype (e.g. “ipv4”).

Returns:

The mapping data for the entity type.

Return type:

Dict[str, Any]

get_entity_type_for_stix2(stix2_type: str) → Tuple[str | None, List[str] | None][source]

Get the Colander entity type for a STIX2 type (e.g. “indicator”, “threat-actor”).

Parameters:: stix2_type (str) – The STIX2 type.
Returns:: The corresponding Colander type and the list of subtype candidates, or None if not found.
Return type:: Tuple[Optional[str], Optional[List[str]]]

get_entity_type_mapping(entity_type: str) → Dict[str, Any][source]

Get the mapping data for a specific Colander entity type.

Parameters:: entity_type (str) – The entity type (e.g., “actor”, “device”).
Returns:: The mapping data for the entity type.
Return type:: Dict[str, Any]

get_field_relationship_type(field_name: str) → str[source]

Get the STIX2 relationship type for a field name.

Parameters:: field_name (str) – The field name.
Returns:: The STIX2 relationship type, or “related-to” if not found.
Return type:: str

get_malware_types_for_threat(threat_type: str) → List[str][source]

Get the malware types for a specific threat type.

Parameters:: threat_type (str) – The threat type.
Returns:: The malware types.
Return type:: List[str]

get_observable_pattern(observable_type: str) → Dict[str, Any][source]

Get the pattern data for a specific observable type.

Parameters:: observable_type (str) – The observable type (e.g., “ipv4”, “domain”).
Returns:: The pattern data for the observable type.
Return type:: Dict[str, Any]

get_pattern_template(observable_type: str) → str[source]

Get the pattern template for a specific observable type.

Parameters:: observable_type (str) – The observable type.
Returns:: The pattern template.
Return type:: str

get_pattern_type(observable_type: str) → str[source]

Get the pattern type for a specific observable type.

Parameters:: observable_type (str) – The observable type.
Returns:: The pattern type.
Return type:: str

get_relation_mapping(relation_type: str) → Dict[str, Any][source]

Get the mapping data for a specific relation type.

Parameters:: relation_type (str) – The relation type (e.g., “uses”, “targets”).
Returns:: The mapping data for the relation type.
Return type:: Dict[str, Any]

get_source_types_for_relation(relation_type: str) → List[str][source]

Get the valid source entity types for a relation type.

Parameters:: relation_type (str) – The relation type.
Returns:: The valid source entity types.
Return type:: List[str]

get_stix2_to_colander_field_mapping(entity_type: str) → Dict[str, str][source]

Get the field mapping from STIX2 to Colander for a specific entity type.

Parameters:: entity_type (str) – The entity type.
Returns:: The field mapping from STIX2 to Colander.
Return type:: Dict[str, str]

get_stix2_type_for_entity(entity_type: str, entity_subtype: str) → str[source]

Get the STIX2 type for a Colander entity type.

Parameters:

entity_type (str) – The Colander entity type (e.g., “actor”, “device”).
entity_subtype (str) – The Colander entity subtype (e.g. “ipv4”).

Returns:

The corresponding STIX2 type.

Return type:

str

get_stix2_type_for_threat(threat_type: str) → str[source]

Get the STIX2 type for a specific threat type.

Parameters:: threat_type (str) – The threat type.
Returns:: The STIX2 type.
Return type:: str

get_supported_colander_types() → List[str][source]

get_supported_stix2_types() → List[str][source]

get_target_types_for_relation(relation_type: str) → List[str][source]

Get the valid target entity types for a relation type.

Parameters:: relation_type (str) – The relation type.
Returns:: The valid target entity types.
Return type:: List[str]

get_threat_mapping(threat_type: str) → Dict[str, Any][source]

Get the mapping data for a specific threat type.

Parameters:: threat_type (str) – The threat type (e.g., “ransomware”, “trojan”).
Returns:: The mapping data for the threat type.
Return type:: Dict[str, Any]

colander_data_converter.formats.stix2.converter module

class colander_data_converter.formats.stix2.converter.ColanderToStix2Mapper[source]

Bases: Stix2Mapper

Maps Colander data to STIX2 data using the mapping file.

convert(colander_feed: ColanderFeed) → Dict[str, Any][source]

Convert Colander data to STIX2 data.

Parameters:: colander_feed (ColanderFeed) – The Colander data to convert.
Returns:: The converted STIX2 data.
Return type:: Dict[str, Any]

Convert a Colander entity to a STIX2 object.

Parameters:: entity – The Colander entity to convert.
Returns:: The converted STIX2 object, or None if the entity type is not supported.
Return type:: Optional[Dict[str, Any]]

convert_colander_relation(relation: EntityRelation) → Dict[str, Any] | None[source]

Convert a Colander EntityRelation to a STIX2 relationship object.

Parameters:: relation (EntityRelation) – The Colander EntityRelation to convert.
Returns:: The converted STIX2 relationship object, or None if the relation cannot be converted.
Return type:: Optional[Dict[str, Any]]

class colander_data_converter.formats.stix2.converter.Stix2Mapper[source]

Bases: object

Base class for mapping between STIX2 and Colander data using the mapping file.

class colander_data_converter.formats.stix2.converter.Stix2ToColanderMapper[source]

Bases: Stix2Mapper

Maps STIX2 data to Colander data using the mapping file.

convert(stix2_data: Dict[str, Any]) → ColanderFeed[source]

Convert STIX2 data to Colander data.

Parameters:: stix2_data (Dict[str, Any]) – The STIX2 data to convert.
Returns:: The converted Colander data.
Return type:: ColanderFeed

Convert a STIX2 object to a Colander entity.

Parameters:: stix2_object (Dict[str, Any]) – The STIX2 object to convert.
Returns:: The converted Colander entity, or None if the object type is not supported.
Return type:: Optional[Union[Actor, Device, Artifact, Observable, Threat, Event, DetectionRule, DataFragment, EntityRelation]]

colander_data_converter.formats.stix2.utils module

Utility functions for STIX2 to Colander conversion and vice versa.

colander_data_converter.formats.stix2.utils.extract_stix2_pattern_name(stix2_pattern: str) → str | None[source]

Extracts the name from a STIX 2 pattern string.

Parameters:: stix2_pattern (str) – The STIX 2 pattern string to extract the name from (e.g. “[ipv4-addr:value = ‘{value}’]”).
Returns:: The extracted name or None if no name is found (e.g. “ipv4-addr:value”).
Return type:: Optional[str]

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.formats.stix2.utils.extract_uuid_from_stix2_id(stix2_id: str) → UUID[source]

Extract a UUID from a STIX2 ID.

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

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.formats.stix2.utils.get_nested_value(obj: Dict[str, Any], path: str) → Any[source]

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

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

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.formats.stix2.utils.set_nested_value(obj: Dict[str, Any], path: str, value: Any) → None[source]

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

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.

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}