stidantic 0.1.3__py3-none-any.whl

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/extensions/pap.py

@@ -0,0 +1,66 @@
+from enum import Enum
+from typing import Literal
+from datetime import datetime, timezone
+
+from stidantic.extension import ExtensionDefinition
+from stidantic.types import (
+    Extension,
+    ExtensionType,
+    Identifier,
+)
+from stidantic.marking import MarkingDefinition
+
+
+STIX_PAP_EXT_CREATION_DATE = datetime(2022, 11, 28, 00, 00, 00, 00, tzinfo=timezone.utc)
+CISA = Identifier("identity--b3bca3c2-1f3d-4b54-b44f-dac42c3a8f01")
+
+PAPExtensionDefinition = ExtensionDefinition(
+    id=Identifier(
+        "extension-definition--f8d78575-edfd-406e-8e84-6162a8450f5b",
+    ),
+    name="pap",
+    version="1.0.0",
+    created=STIX_PAP_EXT_CREATION_DATE,
+    modified=STIX_PAP_EXT_CREATION_DATE,
+    created_by_ref=CISA,
+    json_schema="https://github.com/oasis-open/cti-stix-common-objects/blob/main/extension-definition-specifications/pap-marking-definition-f8d/extension-definition--f8d78575-edfd-406e-8e84-6162a8450f5b.json",
+    extension_types=[ExtensionType.property_extension],
+)
+
+
+class PAPExtension(Extension):
+    extension_type: ExtensionType | None = ExtensionType.property_extension
+    pap: Literal["white", "clear", "green", "red", "amber"]
+
+
+class PAP(Enum):
+    white = MarkingDefinition(
+        id=Identifier("marking-definition--a3bea94c-b469-41dc-9cfe-d6e7daba7730"),
+        name="PAP:WHITE",
+        created=datetime(2022, 10, 1, 00, 00, 00, 00, tzinfo=timezone.utc),
+        extensions={PAPExtensionDefinition.id: PAPExtension(pap="white")},
+    )
+    clear = MarkingDefinition(
+        id=Identifier("marking-definition--ad15a0cd-55b6-4588-a14c-a66105329b92"),
+        name="PAP:CLEAR",
+        created=datetime(2022, 10, 1, 00, 00, 00, 00, tzinfo=timezone.utc),
+        extensions={PAPExtensionDefinition.id: PAPExtension(pap="clear")},
+    )
+    green = MarkingDefinition(
+        id=Identifier("marking-definition--c43594d1-4b11-4c59-93ab-1c9b14d53ce9"),
+        name="PAP:GREEN",
+        created=datetime(2022, 10, 9, 00, 00, 00, 00, tzinfo=timezone.utc),
+        extensions={PAPExtensionDefinition.id: PAPExtension(pap="green")},
+    )
+    red = MarkingDefinition(
+        id=Identifier("marking-definition--740d36e5-7714-4c30-961a-3ae632ceee0e"),
+        name="PAP:RED",
+        created=datetime(2022, 10, 6, 00, 00, 00, 00, tzinfo=timezone.utc),
+        extensions={PAPExtensionDefinition.id: PAPExtension(pap="red")},
+    )
+    amber = MarkingDefinition(
+        id=Identifier("marking-definition--60f8932b-e51e-4458-b265-a2e8be9a80ab"),
+        name="PAP:AMBER",
+        created=datetime(2022, 10, 2, 00, 00, 00, 00, tzinfo=timezone.utc),
+        extensions={PAPExtensionDefinition.id: PAPExtension(pap="amber")},
+    )

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,
+    )