stidantic 0.1.0__py3-none-any.whl

stidantic/__init__.py

@@ -0,0 +1,23 @@
+"""stidantic - A Pydantic-based STIX 2.1 library."""
+
+__version__ = "0.1.0"
+__author__ = "nicocti"
+__all__ = [
+    "StixBundle",
+    "StixCore",
+    "StixCommon",
+    "StixDomain",
+    "StixRelationship",
+    "StixMeta",
+    "Identifier",
+]
+
+from stidantic.bundle import StixBundle
+from stidantic.types import (
+    Identifier,
+    StixCommon,
+    StixCore,
+    StixDomain,
+    StixMeta,
+    StixRelationship,
+)

stidantic/__init__.pyi

@@ -0,0 +1,14 @@
+"""Type stubs for stidantic."""
+
+from stidantic.bundle import StixBundle as StixBundle
+from stidantic.types import (
+    Identifier as Identifier,
+    StixCommon as StixCommon,
+    StixCore as StixCore,
+    StixDomain as StixDomain,
+    StixMeta as StixMeta,
+    StixRelationship as StixRelationship,
+)
+
+__version__: str
+__author__: str

stidantic/bundle.py

@@ -0,0 +1,29 @@
+from typing import Annotated
+from pydantic import Field
+from stidantic.types import StixCore, Identifier, StixCommon
+from stidantic.sdo import SDOs
+from stidantic.sco import SCOs
+from stidantic.sro import SROs
+from stidantic.language import LanguageContent
+from stidantic.marking import MarkingDefinition
+from stidantic.extension import ExtensionDefinition
+
+
+# 8. Stix Bundle
+class StixBundle(StixCore):
+    id: Identifier
+    type: str = "bundle"
+    objects: list[
+        Annotated[
+            (
+                SROs
+                | SDOs
+                | SCOs
+                | MarkingDefinition
+                | LanguageContent
+                | ExtensionDefinition
+            ),
+            Field(discriminator="type"),
+        ]
+        | StixCommon
+    ]

stidantic/extension.py

@@ -0,0 +1,115 @@
+from typing import Literal, Annotated, Self
+from pydantic import Field
+from pydantic.functional_validators import model_validator
+from stidantic.types import StixExtension, ExtensionType, StixProp
+
+
+# 7.3 Extension Definition
+class ExtensionDefinition(StixExtension):
+    """
+    The STIX Extension Definition object allows producers of threat intelligence to extend existing STIX objects or
+    to create entirely new STIX objects in a standardized way. This object contains detailed information about the
+    extension and any additional properties and or objects that it defines. This extension mechanism MUST NOT be used
+    to redefine existing standardized objects or properties.
+
+    If a producer does not include the STIX Extension Definition object with the STIX objects that use it,
+    consumers should refer to section 3.3 for information in resolving references.
+
+    There are three ways to extend STIX using STIX Extensions.
+        - Define one or more new STIX Object types.
+        - Define additional properties for an existing STIX Object type as a nested property extension. This is
+        typically done to represent a sub-component or module of one or more STIX Object types.
+        - Define additional properties for an existing STIX Object type at the object's top-level. This can be done to
+        represent properties that form an inherent part of the definition of an object type.
+
+    When defining a new STIX Object (e.g., SDO, SCO, or SRO) all common properties associated with that type of
+    object (SDO, SCO, SRO) MUST be included in the schema or definition of that new STIX Object type.
+    Extensions that create new STIX objects MUST follow all conformance requirements for that object type
+    (SDO, SCO, SRO) including all of the requirements for the common properties associated with that object type.
+
+    When defining a STIX extension using the nested property extension mechanism the extensions property MUST include
+    the extension definition's UUID that defines the extension definition object and the extension_type property
+    as defined in section 3.2.
+
+    IMPORTANT NOTE: Producers using top-level property extensions should be mindful that another producer could also
+    define a top-level property extension using the same property names but for different purposes causing name
+    conflicts when both extensions are used in the same environment. This standard does not define any name conflict
+    resolution for new STIX Objects or for top-level properties created by this extension mechanism. However,
+    producers SHOULD follow industry best practices such as using unique property names that are guaranteed to avoid
+    duplicates across all organizations to avoid naming conflicts.
+    IMPORTANT NOTE: Producers using STIX extensions should be mindful that future versions of the STIX specification
+    MAY define objects and or properties that conflict with existing non-standardized extensions. In these cases the
+    meaning as defined in the STIX specification will override any and all conflicting extensions.
+
+    Specific extensions, as with specific Custom Properties, MAY NOT be supported across implementations.
+    A consumer that receives STIX content containing a STIX extension that it does not understand MAY refuse to
+    process the content or MAY ignore that extension and continue processing the content.
+
+    The 3 uses of this extension facility MAY be combined into a single Extension Definition object when appropriate.
+
+    The following example highlights where this may be useful.
+
+    Hybrid Extension Example
+    An intelligence producer has a monitoring network of sensors that collect a variety of cybersecurity  telemetry
+    from each sensor where those sensors have unique data not currently defined in STIX 2.1.
+    The producer wishes to create an extension that other downstream consumers can receive both the high-level
+    summarization object but also the individual categorized telemetry from each sensor.
+    a)    A new SDO representing the statistical summarization object.
+    b)    A list of new properties to be added to the standard Observed Data object representing additional meta-data
+    information associated with the telemetry.
+    c)     A new SCO representing a new cyber observable data type.
+
+    In this case, the producer creates a single extension that contains the following extension types:
+    "extension_types": [ "new-sdo", "new-sco", "property-extension" ]
+
+    Therefore, producers MAY use the hybrid extension mechanism when they wish to define a single extension that
+    encompasses new SDO and/or sub-component or top-level property extension properties in a related extension.
+
+    Producers SHOULD NOT use the hybrid extension mechanism if the extensions are not related to each other.
+    If the extensions are independent features then a producer SHOULD consider creating separate extension definitions.
+    """
+
+    type: Literal["extension-definition"] = "extension-definition"  # pyright: ignore[reportIncompatibleVariableOverride]
+    # A name used for display purposes during execution, development, or debugging.
+    name: str
+    # A detailed explanation of what data the extension conveys and how it is intended to be used.
+    # While the description property is optional this property SHOULD be populated.
+    # Note that the schema property is the normative definition of the extension, and this property, if present,
+    # is for documentation purposes only.
+    description: str | None = None
+    # The normative definition of the extension, either as a URL or as plain text explaining the definition.
+    # A URL SHOULD point to a JSON schema or a location that contains information about the schema
+    json_schema: Annotated[str, Field(alias="schema")]
+    # The version of this extension. Producers of STIX extensions are encouraged to follow standard semantic
+    # versioning procedures where the version number follows the pattern, MAJOR.MINOR.PATCH. This will allow
+    # consumers to distinguish between the three different levels of compatibility typically identified by
+    # such versioning strings.
+    version: str
+    # This property specifies one or more extension types contained within this extension.
+    # When this property includes toplevel-property-extension then the extension_properties property
+    # SHOULD include one or more property names.
+    extension_types: list[ExtensionType]
+    # This property contains the list of new property names that are added to an object by an extension.
+    # This property MUST only be used when the extension_types property includes a value of toplevel-property-extension.
+    # In other words, when new properties are being added at the top-level of an existing object.
+    # The property names used in Extension STIX Object MUST be in ASCII and MUST only contain the characters a–z
+    # (lowercase ASCII), 0–9, and underscore (_).
+    # The name of a property of a Extension STIX Object MUST have a minimum length of 3 ASCII characters.
+    # The name of a property of a Extension STIX Object MUST be no longer than 250 ASCII characters in length.
+    extension_properties: list[StixProp] | None = None
+
+    @model_validator(mode="after")
+    def validate_extension_properties(self) -> Self:
+        """
+        extension_properties MUST only be used when the extension_types property includes a value of
+        toplevel-property-extension. In other words, when new properties are being added at the
+        top-level of an existing object.
+        """
+        if (
+            self.extension_properties
+            and ExtensionType.toplevel_property_extension not in self.extension_types
+        ):
+            raise ValueError(
+                "extension_types property can't be used without toplevel-property-extension in extension_types."
+            )
+        return self

stidantic/language.py

@@ -0,0 +1,35 @@
+from datetime import datetime
+from typing import Literal
+from stidantic.types import Identifier, StixLanguage
+
+
+# 7.1 Language Content
+class LanguageContent(StixLanguage):
+    type: Literal["language-content"] = "language-content"  # pyright: ignore[reportIncompatibleVariableOverride]
+    # The object_ref property identifies the id of the object that this Language Content applies to.
+    # It MUST be the identifier for a STIX Object.
+    object_ref: Identifier
+    # The object_modified property identifies the modified time of the object that this Language Content applies to.
+    # It MUST be an exact match for the modified time of the STIX Object being referenced.
+    object_modified: datetime | None = None
+    # The contents property contains the actual Language Content (translation).
+    # The keys in the dictionary MUST be RFC 5646 language codes for which language content is being provided [RFC5646].
+    # The values each consist of a dictionary that mirrors the properties in the target object
+    # (identified by object_ref and object_modified). For example, to provide a translation of the name property
+    # on the target object the key in the dictionary would be name.
+    # For each key in the nested dictionary:
+    # ●      If the original property is a string, the corresponding property in the language content object
+    # MUST contain a string with the content for that property in the language of the top-level key.
+    # ●      If the original property is a list, the corresponding property in the translation object must also be
+    # a list. Each item in this list recursively maps to the item at the same position in the list contained in the
+    # target object. The lists MUST have the same length.
+    # ●      In the event that translations are only provided for some list items, the untranslated list items MUST
+    # be represented by an empty string (""). This indicates to a consumer of the Language Content object that they
+    # should interpolate the translated list items in the Language Content object with the corresponding (untranslated)
+    # list items from the original object as indicated by the object_ref property.
+    # ●      If the original property is an object (including dictionaries), the corresponding location in the
+    # translation object must also be an object. Each key/value field in this object recursively maps to the object
+    # with the same key in the original.
+    # The translation object MAY contain only a subset of the translatable fields of the original. Keys that point to
+    # non-translatable properties in the target or to properties that do not exist in the target object MUST be ignored.
+    contents: dict[str, dict[str, str]]

stidantic/marking.py

@@ -0,0 +1,118 @@
+from typing import Literal, Self
+from enum import Enum
+from datetime import datetime, timezone
+
+from pydantic.functional_validators import model_validator
+from stidantic.types import (
+    StixCore,
+    StixMarking,
+    Identifier,
+)
+
+
+# 7.2.1.3 Statement Marking
+class StatementMarking(StixCore):
+    """
+    The Statement marking type defines the representation of a textual marking statement (e.g., copyright, terms of use,
+    etc.) in a definition. The value of the definition_type property MUST be statement when using this marking type.
+    Statement markings are generally not machine-readable, and this specification does not define any behavior or
+    actions based on their values.
+
+    Content may be marked with multiple statements of use. In other words, the same content can be marked both with a
+    statement saying "Copyright 2019" and a statement saying, "Terms of use are ..." and both statements apply.
+    """
+
+    # A Statement (e.g., copyright, terms of use) applied to the content marked by this marking definition.
+    statement: str
+
+
+# 7.2.1.4 TLP Marking
+class TLPMarking(StixCore):
+    """
+    The TLP marking type defines how you would represent a Traffic Light Protocol (TLP) marking in a definition
+    property. The value of the definition_type property MUST be tlp when using this marking type.
+    """
+
+    # The TLP level [TLP] of the content marked by this marking definition, as defined in this section.
+    tlp: str
+
+
+# 7.2.1 Marking Definition
+class MarkingDefinition(StixMarking):
+    """
+    The marking-definition object represents a specific marking. Data markings typically represent handling or
+    sharing requirements for data and are applied in the object_marking_refs and granular_markings properties on
+    STIX Objects, which reference a list of IDs for marking-definition objects.
+
+    Two marking definition types are defined in this specification: TLP, to capture TLP markings, and Statement,
+    to capture text marking statements. In addition, it is expected that the FIRST Information Exchange Policy (IEP)
+    will be included in a future version once a machine-usable specification for it has been defined.
+
+    Unlike other STIX Objects, Marking Definition objects cannot be versioned because it would allow for indirect
+    changes to the markings on a STIX Object. For example, if a Statement marking is changed from "Reuse Allowed" to
+    "Reuse Prohibited", all STIX Objects marked with that Statement marking would effectively have an updated marking
+    without being updated themselves. Instead, a new Statement marking with the new text should be created and the
+    marked objects updated to point to the new marking.
+    """
+
+    type: Literal["marking-definition"] = "marking-definition"  # pyright: ignore[reportIncompatibleVariableOverride]
+    # A name used to identify the Marking Definition.
+    name: str | None = None
+    # The definition_type property identifies the type of Marking Definition. The value of the definition_type property
+    # SHOULD be one of the types defined in the subsections below: statement or tlp (see sections 7.2.1.3 and 7.2.1.4).
+    # Any new marking definitions SHOULD be specified using the extension facility described in section 7.3.
+    # If the extensions property is not present, this property MUST be present.
+    definition_type: str | None = None
+    # The definition property contains the marking object itself (e.g., the TLP marking as defined in section 7.2.1.4,
+    # the Statement marking as defined in section 7.2.1.3).
+    # Any new marking definitions SHOULD be specified using the extension facility described in section 7.3.
+    # If the extensions property is not present, this property MUST be present.
+    definition: TLPMarking | StatementMarking | None = None
+
+    @model_validator(mode="after")
+    def definition_if_no_extensions(self) -> Self:
+        if not self.extensions and (not self.definition and not self.definition_type):
+            raise ValueError(
+                "If the extensions property is not present, definition_type and definition properties MUST be present."
+            )
+        return self
+
+
+STIX_ZERO_DATE = datetime(2017, 1, 20, 00, 00, 00, 00, tzinfo=timezone.utc)
+
+
+class TLP(Enum):
+    """
+    The following standard marking definitions MUST be used to reference or represent TLP markings.
+    Other instances of tlp-marking MUST NOT be used or created (the only instances of TLP marking definitions
+    permitted are those defined here).
+    """
+
+    white = MarkingDefinition(
+        id=Identifier("marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"),
+        definition_type="tlp",
+        definition=TLPMarking(tlp="white"),
+        name="TLP:WHITE",
+        created=STIX_ZERO_DATE,
+    )
+    green = MarkingDefinition(
+        id=Identifier("marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"),
+        definition_type="tlp",
+        definition=TLPMarking(tlp="green"),
+        name="TLP:GREEN",
+        created=STIX_ZERO_DATE,
+    )
+    amber = MarkingDefinition(
+        id=Identifier("marking-definition--f88d31f6-486f-44da-b317-01333bde0b82"),
+        definition_type="tlp",
+        definition=TLPMarking(tlp="amber"),
+        name="TLP:AMBER",
+        created=STIX_ZERO_DATE,
+    )
+    red = MarkingDefinition(
+        id=Identifier("marking-definition--5e57c739-391a-4eb3-b6be-7d15ca92d5ed"),
+        definition_type="tlp",
+        definition=TLPMarking(tlp="red"),
+        name="TLP:RED",
+        created=STIX_ZERO_DATE,
+    )

stidantic/sco.py

@@ -0,0 +1,91 @@
+from typing import Literal, Self
+from typing_extensions import Annotated
+from pydantic.functional_validators import model_validator
+from pydantic import Field
+from stidantic.types import StixObservable, StixBinary, StixUrl, Hashes
+from stidantic.vocab import EncryptionAlgorithm
+
+
+# 6.1 Artifact Object
+class Artifact(StixObservable):
+    """
+    The Artifact Object permits capturing an array of bytes (8-bits),
+    as a base64-encoded string string, or linking to a file-like payload.
+    """
+
+    type: Literal["artifact"] = "artifact"  # pyright: ignore[reportIncompatibleVariableOverride]
+    mime_type: str | None = None
+    payload_bin: StixBinary | None = None
+    url: StixUrl | None = None
+    hashes: Hashes | None = None
+    encryption_algorithm: EncryptionAlgorithm | None = None
+    decryption_key: str | None = None
+
+    @model_validator(mode="after")
+    def one_of(self) -> Self:
+        """
+        One of payload_bin or url MUST be provided.
+        """
+        if self.payload_bin or self.hashes:
+            return self
+        raise ValueError("Missing at least hashes or payload_bin property.")
+
+    @model_validator(mode="after")
+    def url_must_not_be_present_if_payload_bin_provided(self) -> Self:
+        """
+        URL property MUST NOT be present if payload_bin is provided.
+        """
+        if self.payload_bin and self.url:
+            raise ValueError(
+                "url property MUST NOT be present if payload_bin is provided."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def hashes_must_be_present_if_url_provided(self) -> Self:
+        """
+        Hashes property MUST be present when the url property is present.
+        """
+        if self.url and not self.hashes:
+            raise ValueError("hashes MUST be present if url is provided.")
+        return self
+
+    @model_validator(mode="after")
+    def decryption_key_must_not_be_present_if_encryption_algorithm_absent(self) -> Self:
+        """
+        decryption_key property MUST NOT be present when the encryption_algorithm property is absent.
+        """
+        if not self.encryption_algorithm and self.decryption_key:
+            raise ValueError(
+                "decryption_key MUST NOT be present when the encryption_algorithm property is absent."
+            )
+        return self
+
+    class Config:
+        json_schema_extra: dict[str, list[str]] = {
+            "id_contributing_properties": ["hashes", "payload_bin"]
+        }
+
+
+# 6.2 Autonomous System
+class AutonomousSystem(StixObservable):
+    """
+    The AS object represents the properties of an Autonomous Systems (AS).
+    """
+
+    type: Literal["autonomous-system"] = "autonomous-system"  # pyright: ignore[reportIncompatibleVariableOverride]
+    # Specifies the number assigned to the AS. Such assignments a
+    # re typically performed by a Regional Internet Registry (RIR).
+    number: int
+    # Specifies the name of the AS.
+    name: str | None = None
+    # Specifies the name of the Regional Internet Registry (RIR) that assigned the number to the AS.
+    rir: str | None = None
+
+    class Config:
+        json_schema_extra: dict[str, list[str]] = {
+            "id_contributing_properties": ["number"]
+        }
+
+
+SCOs = Annotated[(Artifact | AutonomousSystem), Field(discriminator="type")]

stidantic/sdo.py

@@ -0,0 +1,87 @@
+from typing import Literal, Annotated, Self
+from datetime import datetime
+from pydantic import Field
+from pydantic.functional_validators import model_validator
+from stidantic.types import StixDomain, KillChainPhase
+
+
+# 4.1 Attack Pattern
+class AttackPattern(StixDomain):
+    """
+    Attack Patterns are a type of TTP that describe ways that adversaries attempt to compromise targets.
+
+    Attack Patterns are used to help categorize attacks, generalize specific attacks to the patterns that they follow,
+    and provide detailed information about how attacks are performed. An example of an attack pattern is
+    "spear phishing": a common type of attack where an attacker sends a carefully crafted e-mail message
+    to a party with the intent of getting them to click a link or open an attachment to deliver malware.
+
+    Attack Patterns can also be more specific; spear phishing as practiced by a particular threat actor
+    (e.g., they might generally say that the target won a contest) can also be an Attack Pattern.
+    """
+
+    type: Literal["attack-pattern"] = "attack-pattern"  # pyright: ignore[reportIncompatibleVariableOverride]
+    # The name used to identify the Attack Pattern.
+    name: str
+    # A description that provides more details and context about the Attack Pattern,
+    # potentially including its purpose and its key characteristics.
+    description: str | None = None
+    # Alternative names used to identify this Attack Pattern.
+    aliases: list[str] | None = None
+    # The list of kill chain phases for which this attack pattern is used.
+    kill_chain_phases: list[KillChainPhase] | None = None
+
+
+# 4.2 Campaign
+class Campaign(StixDomain):
+    """
+    A Campaign is a grouping of adversarial behaviors that describes a set of malicious activities or attacks
+    (sometimes called waves) that occur over a period of time against a specific set of targets.
+    Campaigns usually have well defined objectives and may be part of an Intrusion Set.
+
+    Campaigns are often attributed to an intrusion set and threat actors. The threat actors may reuse known
+    infrastructure from the intrusion set or may set up new infrastructure specific for conducting that campaign.
+
+    Campaigns can be characterized by their objectives and the incidents they cause, people or resources they target,
+    and the resources (infrastructure, intelligence, Malware, Tools, etc.) they use.
+
+    For example, a Campaign could be used to describe a crime syndicate's attack using a specific variant of
+    malware and new C2 servers against the executives of ACME Bank during the summer of 2016 in order
+    to gain secret information about an upcoming merger with another bank.
+    """
+
+    type: Literal["campaign"] = "campaign"  # pyright: ignore[reportIncompatibleVariableOverride]
+    # A name used to identify the Campaign.
+    name: str
+    # A description that provides more details and context about the Campaign,
+    # potentially including its purpose and its key characteristics.
+    description: str | None = None
+    # Alternative names used to identify this Campaign.
+    aliases: list[str] | None = None
+    # The time that this Campaign was first seen.
+    # A summary property of data from sightings and other data that may or may not be available in STIX.
+    # If new sightings are received that are earlier than the first seen timestamp,
+    # the object may be updated to account for the new data.
+    first_seen: datetime | None = None
+    # The time that this Campaign was last seen.
+    # A summary property of data from sightings and other data that may or may not be available in STIX.
+    # If new sightings are received that are later than the last seen timestamp,
+    # the object may be updated to account for the new data.
+    last_seen: datetime | None = None
+    # The Campaign’s primary goal, objective, desired outcome, or intended effect
+    # — what the Threat Actor or Intrusion Set hopes to accomplish with this Campaign.
+    objective: str | None = None
+
+    @model_validator(mode="after")
+    def validate_first_last_interval(self) -> Self:
+        """
+        If this property and the first_seen property are both defined, then this property
+        MUST be greater than or equal to the timestamp in the first_seen property.
+        """
+        if self.first_seen and self.last_seen and self.first_seen > self.last_seen:
+            raise ValueError(
+                "the last_seen property MUST be greater than or equal to the timestamp in the first_seen property"
+            )
+        return self
+
+
+SDOs = Annotated[(AttackPattern | Campaign), Field(discriminator="type")]