stidantic 0.1.3__py3-none-any.whl → 0.2.1__py3-none-any.whl

stidantic/sdo.py

@@ -1,12 +1,18 @@
-from datetime import datetime
-from typing import Any, Literal, Annotated, Self
-from typing_extensions import deprecated
-from annotated_types import Ge, Gt, Le
+from typing import Annotated, Any, Literal, Self
 
-from pydantic import Field
+from annotated_types import Ge, Le
+from pydantic import AfterValidator, Field
 from pydantic.functional_validators import model_validator
+from typing_extensions import deprecated
 
-from stidantic.types import Identifier, StixDomain, KillChainPhase, ExternalReference
+from stidantic.types import (
+    ExternalReference,
+    Identifier,
+    KillChainPhase,
+    StixDomain,
+    StixTimestamp,
+)
+from stidantic.validators import identifier_of_type
 from stidantic.vocab import OpinionEnum
 
 
@@ -66,12 +72,12 @@ class Campaign(StixDomain):
     # 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
+    first_seen: StixTimestamp | 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
+    last_seen: StixTimestamp | 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
@@ -113,7 +119,7 @@ class CourseOfAction(StixDomain):
     # potentially including its purpose and its key characteristics.
     description: str | None = None
     # A reserved property that serves as a placeholder for future inclusion of machine automatable courses of action.
-    # action: str | None = None
+    # action: str | None = None  # noqa: ERA001
 
 
 # 4.4 Grouping
@@ -236,12 +242,12 @@ class Indicator(StixDomain):
     # this object’s creation.
     pattern_version: str | None = None
     # The time from which this Indicator is considered a valid indicator of the behaviors it is related or represents.
-    valid_from: datetime
+    valid_from: StixTimestamp
     # The time at which this Indicator should no longer be considered a valid indicator of the behaviors it is
     # related to or represents.
     # If the valid_until property is omitted, then there is no constraint on the latest time for which the
     # Indicator is valid.
-    valid_until: datetime | None = None
+    valid_until: StixTimestamp | None = None
     # The kill chain phase(s) to which this Indicator corresponds.
     kill_chain_phases: list[KillChainPhase] | None = None
 
@@ -251,9 +257,7 @@ class Indicator(StixDomain):
         The valid_until property MUST be greater than the timestamp in the valid_from property.
         """
         if self.valid_from and self.valid_until and self.valid_from > self.valid_until:
-            raise ValueError(
-                "The valid_until property MUST be greater than the timestamp in the valid_from property"
-            )
+            raise ValueError("The valid_until property MUST be greater than the timestamp in the valid_from property")
         return self
 
 
@@ -282,9 +286,9 @@ class Infrastructure(StixDomain):
     # The list of Kill Chain Phases for which this Infrastructure is used.
     kill_chain_phases: list[KillChainPhase] | None = None
     # The time that this Infrastructure was first seen performing malicious activities.
-    first_seen: datetime | None = None
+    first_seen: StixTimestamp | None = None
     # The time that this Infrastructure was last seen performing malicious activities.
-    last_seen: datetime | None = None
+    last_seen: StixTimestamp | None = None
 
     @model_validator(mode="after")
     def validate_last_seen_after_first_seen(self) -> Self:
@@ -329,12 +333,12 @@ class IntrusionSet(StixDomain):
     # 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
+    first_seen: StixTimestamp | None = None
     # The time that this Intrusion Set was last seen.
     # This property is a summary property of data from sightings and other data that may or may not be available.
     # 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
+    last_seen: StixTimestamp | None = None
     # The high-level goals of this Intrusion Set, namely, what are they trying to do.
     # For example, they may be motivated by personal gain, but their goal is to steal credit card numbers.
     # To do this, they may execute specific Campaigns that have detailed objectives like compromising point of sale
@@ -423,14 +427,8 @@ class Location(StixDomain):
         - country
         - latitude and longitude
         """
-        if (
-            not self.region
-            and not self.country
-            and not (self.latitude and self.longitude)
-        ):
-            raise ValueError(
-                "At least one of region, country, or both latitude and longitude MUST be provided"
-            )
+        if not self.region and not self.country and not (self.latitude and self.longitude):
+            raise ValueError("At least one of region, country, or both latitude and longitude MUST be provided")
 
         if self.latitude and not self.longitude:
             raise ValueError("If latitude is present, longitude MUST be present")
@@ -439,9 +437,7 @@ class Location(StixDomain):
             raise ValueError("If longitude is present, latitude MUST be present")
 
         if self.precision and (not self.latitude or not self.longitude):
-            raise ValueError(
-                "If precision is present, latitude and longitude MUST be present"
-            )
+            raise ValueError("If precision is present, latitude and longitude MUST be present")
 
         return self
 
@@ -479,15 +475,15 @@ class Malware(StixDomain):
     # This property is 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
+    first_seen: StixTimestamp | None = None
     # The time that the malware family or malware instance was last seen.
     # This property is 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
+    last_seen: StixTimestamp | None = None
     # The operating systems that the malware family or malware instance is executable on.
     # This applies to virtualized operating systems as well as those running on bare metal.
-    operating_system_refs: list[Identifier] | None = None
+    operating_system_refs: list[Annotated[Identifier, AfterValidator(identifier_of_type("software"))]] | None = None
     # The processor architectures (e.g., x86, ARM, etc.) that the malware instance or family is executable on.
     # The values for this property SHOULD come from the processor-architecture-ov open vocabulary.
     architecture_execution_envs: list[str] | None = None
@@ -499,7 +495,7 @@ class Malware(StixDomain):
     capabilities: list[str] | None = None
     # The sample_refs property specifies a list of identifiers of the SCO file or artifact objects associated with
     # this malware instance(s) or family.
-    sample_refs: list[Identifier] | None = None
+    sample_refs: list[Annotated[Identifier, AfterValidator(identifier_of_type("file", "artifact"))]] | None = None
 
     @model_validator(mode="after")
     def validate_last_seen_after_first_seen(self) -> Self:
@@ -541,16 +537,13 @@ class MalwareAnalysis(StixDomain):
     # used for the dynamic analysis of the malware instance or family. If this value is not included in conjunction
     # with the operating_system_ref property, this means that the dynamic analysis may have been performed on bare
     # metal (i.e. without virtualization) or the information was redacted.
-    # The value of this property MUST be the identifier for a SCO software object.
-    host_vm_ref: Identifier | None = None
+    host_vm_ref: Annotated[Identifier, AfterValidator(identifier_of_type("software"))] | None = None
     # The operating system used for the dynamic analysis of the malware instance or family. This applies to
     # virtualized operating systems as well as those running on bare metal.
-    # The value of this property MUST be the identifier for a SCO software object.
-    operating_system_ref: Identifier | None = None
+    operating_system_ref: Annotated[Identifier, AfterValidator(identifier_of_type("software"))] | None = None
     # Any non-standard software installed on the operating system (specified through the operating-system value)
     # used for the dynamic analysis of the malware instance or family.
-    # The value of this property MUST be the identifier for a SCO software object.
-    installed_software_refs: list[Identifier] | None = None
+    installed_software_refs: list[Annotated[Identifier, AfterValidator(identifier_of_type("software"))]] | None = None
     # The named configuration of additional product configuration parameters for this analysis run. For example, when
     # a product is configured to do full depth analysis of Window™ PE files. This configuration may have a named
     # version and that named version can be captured in this property. This will ensure additional runs can be
@@ -565,11 +558,11 @@ class MalwareAnalysis(StixDomain):
     analysis_definition_version: str | None = None
     # The date and time that the malware was first submitted for scanning or analysis. This value will stay constant
     # while the scanned date can change. For example, when Malware was submitted to a virus analysis tool.
-    submitted: datetime | None = None
+    submitted: StixTimestamp | None = None
     # The date and time that the malware analysis was initiated.
-    analysis_started: datetime | None = None
+    analysis_started: StixTimestamp | None = None
     # The date and time that the malware analysis ended.
-    analysis_ended: datetime | None = None
+    analysis_ended: StixTimestamp | None = None
     # The classification result or name assigned to the malware instance by the scanner tool.
     result_name: str | None = None
     # The classification result as determined by the scanner or tool analysis process.
@@ -583,7 +576,15 @@ class MalwareAnalysis(StixDomain):
     # Analysis objects when the Malware sample_refs property does not contain the SCO that is included in the
     # Malware Analysis sample_ref property. Note, this property can also contain a reference to an SCO which is not
     # associated with Malware (i.e., some SCO which was scanned and found to be benign.)
-    sample_ref: Identifier | None = None
+    sample_ref: (
+        list[
+            Annotated[
+                Identifier,
+                AfterValidator(identifier_of_type("file", "artifact", "network-traffic")),
+            ]
+        ]
+        | None
+    ) = None
 
     @model_validator(mode="after")
     def at_least_one_of(self) -> Self:
@@ -657,15 +658,15 @@ class ObservedData(StixDomain):
 
     type: Literal["observed-data"] = "observed-data"  # pyright: ignore[reportIncompatibleVariableOverride]
     # The beginning of the time window during which the data was seen.
-    first_observed: datetime
+    first_observed: StixTimestamp
     # The end of the time window during which the data was seen.
-    last_observed: datetime
+    last_observed: StixTimestamp
     # The number of times that each Cyber-observable object represented in the objects or object_refs property was
     # seen. If present, this MUST be an integer between 1 and 999,999,999 inclusive.
     # If the number_observed property is greater than 1, the data contained in the objects or object_refs property was
     # seen multiple times. In these cases, object creators MAY omit properties of the SCO (such as timestamps) that are
     # specific to a single instance of that observed data.
-    number_observed: Annotated[int, Gt(1), Gt(999999999)]
+    number_observed: Annotated[int, Ge(1), Le(999999999)]
     # A dictionary of SCO representing the observation. The dictionary MUST contain at least one object.
     # The cyber observable content MAY include multiple objects if those objects are related as part of a single
     # observation. Multiple objects not related to each other via cyber observable Relationships MUST NOT be contained
@@ -683,11 +684,7 @@ class ObservedData(StixDomain):
         """
         The last_observed property MUST be greater than or equal to the timestamp in the first_observed property.
         """
-        if (
-            self.first_observed
-            and self.last_observed
-            and self.first_observed > self.last_observed
-        ):
+        if self.first_observed and self.last_observed and self.first_observed > self.last_observed:
             raise ValueError(
                 "The last_observed property MUST be greater than or equal to the the first_observed property"
             )
@@ -700,9 +697,7 @@ class ObservedData(StixDomain):
         but both MUST NOT be present at the same time.
         """
         if self.objects is not None and self.object_refs is not None:
-            raise ValueError(
-                "The objects and object_refs properties MUST NOT be present at the same time"
-            )
+            raise ValueError("The objects and object_refs properties MUST NOT be present at the same time")
         if self.objects is None and self.object_refs is None:
             raise ValueError("Either objects or object_refs MUST be provided")
         return self
@@ -770,7 +765,7 @@ class Report(StixDomain):
     # The date that this Report object was officially published by the creator of this report.
     # The publication date (public release, legal release, etc.) may be different than the date the report was
     # created or shared internally (the date in the created property).
-    published: datetime
+    published: StixTimestamp
     # Specifies the STIX Objects that are referred to by this Report.
     object_refs: list[Identifier]
 
@@ -804,12 +799,12 @@ class ThreatActor(StixDomain):
     # This property is 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
+    first_seen: StixTimestamp | None = None
     # The time that this Threat Actor was last seen.
     # This property is 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
+    last_seen: StixTimestamp | None = None
     # A list of roles the Threat Actor plays.
     # The values for this property SHOULD come from the threat-actor-role-ov open vocabulary.
     roles: list[str] | None = None

stidantic/serializers.py

@@ -0,0 +1,16 @@
+from datetime import UTC, datetime
+
+
+def ser_datetime(value: datetime) -> str:
+    """
+    The timestamp property MUST be a valid RFC 3339-formatted timestamp [RFC3339] using the format
+    YYYY-MM-DDTHH:mm:ss[.s+]Z where the "s+" represents 1 or more sub-second values.
+    The brackets denote that sub-second precision is optional, and that if no digits are provided,
+    the decimal place MUST NOT be present.
+    The timestamp MUST be represented in the UTC timezone and MUST use the "Z" designation to indicate this.
+    NOTE: when using precisions greater than nanoseconds there may be implications for interoperability as they may be
+    truncated when stored as a UNIX timestamp or floating point number due to the precision of those formats.
+    """
+    if value.microsecond == 0:
+        return value.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    return value.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%S.%fZ")

stidantic/sro.py

@@ -1,9 +1,11 @@
-from typing import Literal, Self, Annotated
-from datetime import datetime
-from pydantic import Field
+from typing import Annotated, Literal, Self
+
+from pydantic import AfterValidator, Field
 from pydantic.functional_validators import model_validator
 from pydantic.types import PositiveInt
-from stidantic.types import StixRelationship, Identifier, StixType
+
+from stidantic.types import Identifier, StixRelationship, StixTimestamp, StixType
+from stidantic.validators import identifier_of_type
 
 
 # 5.1 Relationship
@@ -51,13 +53,13 @@ class Relationship(StixRelationship):
     # time at which relationship will be asserted to be true.
     # If it is not specified, then the earliest time at which the relationship between the objects exists
     # is not defined.
-    start_time: datetime | None = None
+    start_time: StixTimestamp | None = None
     # The latest time at which the Relationship between the objects exists. If this property is a future timestamp,
     # at the time the stop_time property is defined, then this represents an estimate by the producer of the
     # intelligence of the latest time at which relationship will be asserted to be true.
     # If stop_time is not specified, then the latest time at which the relationship between
     # the objects exists is either not known, not disclosed, or has no defined stop time.
-    stop_time: datetime | None = None
+    stop_time: StixTimestamp | None = None
 
     @model_validator(mode="after")
     def validate_start_stop_interval(self) -> Self:
@@ -110,9 +112,9 @@ class Sighting(StixRelationship):
     # A description that provides more details and context about the Sighting.
     description: str | None = None
     # The beginning of the time window during which the SDO referenced by the sighting_of_ref property was sighted.
-    first_seen: datetime | None = None
+    first_seen: StixTimestamp | None = None
     # The end of the time window during which the SDO referenced by the sighting_of_ref property was sighted.
-    last_seen: datetime | None = None
+    last_seen: StixTimestamp | None = None
     # If present, this MUST be an integer between 0 and 999,999,999 inclusive and represents the number of times the
     # SDO referenced by the sighting_of_ref property was sighted.
     # Observed Data has a similar property called number_observed, which refers to the number of times the data was
@@ -129,19 +131,20 @@ class Sighting(StixRelationship):
     # A list of ID references to the Observed Data objects that contain the raw cyber data for this Sighting.
     # For example, a Sighting of an Indicator with an IP address could include the Observed Data for the
     # network connection that the Indicator was used to detect.
-    # This property MUST reference only Observed Data SDOs.
-    observed_data_refs: list[Identifier] | None = None
+    observed_data_refs: list[Annotated[Identifier, AfterValidator(identifier_of_type("observed-data"))]] | None = None
     # A list of ID references to the Identity or Location objects describing the entities or types of entities
     # that saw the sighting.
     # Omitting the where_sighted_refs property does not imply that the sighting was seen by the object creator.
     # To indicate that the sighting was seen by the object creator, an Identity representing the object creator
     # should be listed in where_sighted_refs.
-    # This property MUST reference only Identity or Location SDOs.
-    where_sighted_refs: list[Identifier] | None = None
+    where_sighted_refs: (
+        list[Annotated[Identifier, AfterValidator(identifier_of_type("identity", "location"))]] | None
+    ) = None
     # The summary property indicates whether the Sighting should be considered summary data.
     # Summary data is an aggregation of previous Sightings reports and should not be considered primary source data.
     # Default value is false.
-    summary: bool | None = False
+    # WARN: Spec says it's a string, but description describes a boolean which defaults to false...
+    summary: bool | str | None = None
 
     @model_validator(mode="after")
     def validate_first_last_interval(self) -> Self: