colander_data_converter.converters.threatr.models

class colander_data_converter.converters.threatr.models.Entity[source]

Bases: ThreatrType

Represents an entity in the Threatr data model.

Entities are the primary data objects in Threatr, representing observables, indicators, or other threat intelligence artifacts with associated metadata and classification levels.

Config:

  • str_strip_whitespace: bool = True

  • arbitrary_types_allowed: bool = True

Fields:
field id: Annotated[UUID, UuidVersion(uuid_version=4)] [Optional]

The unique identifier for the entity.

Constraints:

  • uuid_version = 4

field created_at: datetime = datetime.datetime(2025, 8, 10, 18, 48, 34, 561126, tzinfo=datetime.timezone.utc)

The timestamp when the entity was created.

field updated_at: datetime = datetime.datetime(2025, 8, 10, 18, 48, 34, 561151, tzinfo=datetime.timezone.utc)

The timestamp when the entity was last updated.

field name: str [Required]

The name of the entity.

Constraints:

  • min_length = 1

  • max_length = 512

field type: CommonEntityType [Required]

The specific type of the entity.

field super_type: CommonEntitySuperType [Required]

The super type classification of the entity.

field description: str | None = None

Optional description of the entity.

field pap: TlpPapLevel = WHITE

The PAP (Permissible Actions Protocol) level for the entity.

field source_url: str | None = None

Optional source URL for the entity.

field tlp: TlpPapLevel = WHITE

The TLP (Traffic Light Protocol) level for the entity.

field attributes: Dict[str, str | None] | None = None

Dictionary of additional attributes.

class colander_data_converter.converters.threatr.models.EntityRelation[source]

Bases: ThreatrType

Represents a relation between two entities in the Threatr data model.

EntityRelations define directed relationships between entities, supporting complex threat intelligence graphs and entity associations.

Config:

  • str_strip_whitespace: bool = True

  • arbitrary_types_allowed: bool = True

Fields:
field id: Annotated[UUID, UuidVersion(uuid_version=4)] [Optional]

The unique identifier for the entity relation.

Constraints:

  • uuid_version = 4

field created_at: datetime = datetime.datetime(2025, 8, 10, 18, 48, 34, 562305, tzinfo=datetime.timezone.utc)

The timestamp when the entity relation was created.

field updated_at: datetime = datetime.datetime(2025, 8, 10, 18, 48, 34, 562327, tzinfo=datetime.timezone.utc)

The timestamp when the entity relation was last updated.

field name: str [Required]

The name of the entity relation.

Constraints:

  • min_length = 1

  • max_length = 512

field description: str | None = None

Optional description of the relation.

field attributes: Dict[str, str | None] | None = None

Dictionary of additional attributes for the relation.

field obj_from: Entity | ObjectReference [Required]

The source entity or reference in the relation.

field obj_to: Entity | ObjectReference [Required]

The target entity or reference in the relation.

class colander_data_converter.converters.threatr.models.Event[source]

Bases: ThreatrType

Represents an event in the Threatr data model.

Events capture temporal occurrences related to threat intelligence, tracking when specific activities or observations took place.

Config:

  • str_strip_whitespace: bool = True

  • arbitrary_types_allowed: bool = True

Fields:
Validators:

  • _check_dates » all fields

field id: Annotated[UUID, UuidVersion(uuid_version=4)] [Optional]

The unique identifier for the event.

Constraints:

  • uuid_version = 4

Validated by:

  • _check_dates

field created_at: datetime = datetime.datetime(2025, 8, 10, 18, 48, 34, 563787, tzinfo=datetime.timezone.utc)

The timestamp when the event was created.

Validated by:

  • _check_dates

field updated_at: datetime = datetime.datetime(2025, 8, 10, 18, 48, 34, 563809, tzinfo=datetime.timezone.utc)

The timestamp when the event was last updated.

Validated by:

  • _check_dates

field name: str [Required]

The name of the event.

Constraints:

  • min_length = 1

  • max_length = 512

Validated by:

  • _check_dates

field description: str | None = None

Optional description of the event.

Validated by:

  • _check_dates

field attributes: Dict[str, str | None] | None = None

Dictionary of additional attributes for the event.

Validated by:

  • _check_dates

field first_seen: datetime = datetime.datetime(2025, 8, 10, 18, 48, 34, 563852, tzinfo=datetime.timezone.utc)

The timestamp when the event was first observed.

Validated by:

  • _check_dates

field last_seen: datetime = datetime.datetime(2025, 8, 10, 18, 48, 34, 563853, tzinfo=datetime.timezone.utc)

The timestamp when the event was last observed.

Validated by:

  • _check_dates

field count: Annotated[int, Gt(gt=0)] = 1

The number of times this event was observed.

Constraints:

  • gt = 0

Validated by:

  • _check_dates

field type: CommonEntityType [Required]

The type of the event.

Validated by:

  • _check_dates

field super_type: CommonEntitySuperType = CommonEntitySuperTypes.EVENT

The super type classification of the event.

Validated by:

  • _check_dates

field involved_entity: Entity | None | ObjectReference = None

Optional entity or reference involved in this event.

Validated by:

  • _check_dates

class colander_data_converter.converters.threatr.models.ThreatrFeed[source]

Bases: ThreatrType

Represents a feed of Threatr data, including entities, relations, and events.

ThreatrFeed serves as a container for complete threat intelligence datasets, organizing related entities, their relationships, and associated events into a cohesive data structure.

Config:

  • str_strip_whitespace: bool = True

  • arbitrary_types_allowed: bool = True

Fields:
field root_entity: Entity [Required]

The root entity of the feed, corresponding to the primary requested entity.

field entities: List[Entity] | None = []

List of entity objects in the feed.

field relations: List[EntityRelation] | None = []

List of entity relation objects in the feed.

field events: List[Event] | None = []

List of event objects in the feed.

static load(raw_object, strict=False)[source]

Loads a ThreatrFeed from a raw object dictionary, resolving references.

Parameters:

  • raw_object (Dict[str, Entity | Event | EntityRelation]) – The raw data to validate and load.

  • strict (bool) – If True, raises a ValueError when a UUID reference cannot be resolved. If False, unresolved references remain as UUIDs.

Returns:

The loaded and reference-resolved feed.

Return type:

ThreatrFeed

Important

Use strict=True to ensure all references in the feed are valid and resolvable.

resolve_references(strict=False)[source]

Resolves references within entities, relations, and events.

Iterates over each entity, relation, and event within the respective collections, calling their resolve_references method to update them with any referenced data.

Parameters:

strict – If True, raises a ValueError when a UUID reference cannot be resolved. If False, unresolved references remain as UUIDs.

Note

This method synchronizes internal state with external dependencies after loading.

Unlinks references from all entities, relations, and events within the feed.

This method iterates through each entity, event, and relation, invoking their unlink_references() methods to replace object references with UUIDs.

Note

This operation is useful for breaking dependencies or preparing data for serialization.

class colander_data_converter.converters.threatr.models.ThreatrRepository(*args, **kwargs)[source]

Bases: object

Singleton repository for managing and storing Entity, Event, and EntityRelation objects.

This class provides centralized storage and reference management for all model instances, supporting insertion, lookup, and reference resolution/unlinking. Uses the Singleton pattern to ensure a single global repository instance.

Warning

As a singleton, this repository persists for the entire application lifecycle. Use the clear() method to reset state when needed.

__init__()[source]

Initializes the repository with empty dictionaries for events, entities, and relations.

Note

Due to the Singleton pattern, this method is only called once per application run.

__lshift__(other)[source]

Inserts an object into the appropriate repository dictionary using the left shift operator.

This method overloads the << operator to provide a convenient way to register Entity, Event, and EntityRelation objects in their respective dictionaries. The object’s ID is used as the key, converted to string format for consistency.

Parameters:

other (Entity | Event | EntityRelation) – The object to insert into the repository.

__rshift__(other)[source]

Retrieves an object by its string or UUID identifier using the right shift operator.

This method overloads the >> operator to provide a convenient way to lookup Entity, Event, and EntityRelation objects from their respective dictionaries. The method searches through entities, relations, and events in that order, returning the first match found.

Parameters:

other (str | Annotated[UUID, UuidVersion(uuid_version=4)]) – The string or UUID identifier to look up in the repository.

Returns:

The found Entity, Event, or EntityRelation object, or the original identifier if no matching object is found.

Return type:

Entity | Event | EntityRelation | str | Annotated[UUID, UuidVersion(uuid_version=4)]

clear()[source]

Clears all stored entities, events, and relations from the repository.

Caution

This operation cannot be undone and will remove all data from the repository.

resolve_references(strict=False)[source]

Resolves all UUID references in relations and events to their corresponding objects.

This method iterates through all stored relations and events in the repository, calling their respective resolve_references methods to convert UUID references back to actual object instances. This is typically used after deserialization to restore object relationships.

Parameters:

strict – If True, raises a ValueError when a UUID reference cannot be resolved. If False, unresolved references remain as UUIDs. Defaults to False.

Raises:

ValueError – If strict is True and any UUID reference cannot be resolved to an existing object in the repository.

Important

Use strict=True to ensure data integrity when all references must be resolvable.

Unlinks all object references in relations and events by replacing them with UUIDs.

This method calls unlink_references() on all stored relations and events to convert object references back to UUID references for serialization purposes.

Note

This operation modifies the stored objects in-place.

entities: Dict[str, Entity]

Dictionary storing Entity objects by their string ID.

events: Dict[str, Event]

Dictionary storing Event objects by their string ID.

relations: Dict[str, EntityRelation]

Dictionary storing EntityRelation objects by their string ID.

class colander_data_converter.converters.threatr.models.ThreatrType[source]

Bases: BaseModel

Base model for Threatr objects, providing repository registration and reference management.

This class ensures that all subclasses are automatically registered in the ThreatrRepository and provides methods to unlink and resolve object references for serialization and deserialization workflows.

Important

All Threatr model classes must inherit from this base class to ensure proper repository integration and reference management.

Config:

  • str_strip_whitespace: bool = True

  • arbitrary_types_allowed: bool = True

model_post_init(_ThreatrType__context)[source]

Executes post-initialization logic for the model.

Ensures the repository registers the current subclass instance automatically after object creation.

Parameters:

__context – Additional context provided for post-initialization handling.

Note

This method is called automatically by Pydantic after model initialization.

Unlinks object references by replacing them with their respective UUIDs.

This method updates model fields annotated as ObjectReference or List[ObjectReference] by replacing object references with their UUIDs for serialization purposes.

Note

This operation modifies the object in-place and is typically used before serialization.

Raises:

AttributeError – If the class instance does not have the expected field or attribute.

resolve_references(strict=False)[source]

Resolves UUID references to their corresponding objects using the ThreatrRepository.

Fields annotated with ObjectReference or List[ObjectReference] are processed to fetch and replace their UUID references with actual object instances.

Parameters:

strict – If True, raises a ValueError when a UUID reference cannot be resolved. If False, unresolved references remain as UUIDs. Defaults to False.

Raises:

ValueError – If strict is True and a UUID reference cannot be resolved.

Important

Use strict=True to ensure all references are valid and resolvable.