stix2-utils 0.0.2__py3-none-any.whl

stix2_utils-0.0.2.dist-info/METADATA

@@ -0,0 +1,33 @@
+Metadata-Version: 2.3
+Name: stix2-utils
+Version: 0.0.2
+Summary: Utility library for validating stix2 entities and patterns
+Author: Daan Willems
+Author-email: Daan Willems <daan@daan.nl>
+Requires-Dist: pydantic
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/DaanWillems/stix2-utils
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# stix2-utils
+A utility library for validating STIX 2.1 objects. This library used pydantic to validate STIX 2.1 objects. Later on it will also support creating objects and validating indicator patterns.
+
+## Installation
+The stix2-utils library is hosted on PyPi. The most recent version can be installed with pip:
+
+```bash
+pip install stix2-utils
+```
+
+## Usage
+You can use the library to validate STIX 2.1 objects and receive human readable errors
+
+```python
+validator = STIX2Validator()
+validation_result = validator.validate_entity(stix_obj)
+
+print(validation_result.success)
+print(validation_result.errors)
+```

stix2_utils-0.0.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+stix2utils/__init__.py,sha256=G7mVWt3HImYrrIiOWZVZkMW2wIXY8FyH2R5fhzOuPoI,1444
+stix2utils/adapter.py,sha256=j9_UYnfxc-3dgQJ6AWtpVgz8xH2w8Vk1NYtrurrJnIA,1521
+stix2utils/common.py,sha256=qKq8Jfb9nY4JZ3SdlrrPn7ozK-Q1Yjlu0MMfVoNzdRQ,2150
+stix2utils/references.py,sha256=Ay1bcUnoumJ4FzadFguHBvWYAalSRCwtbmil1zQQBDs,2661
+stix2utils/sco_models.py,sha256=amzTH2LLo4pkAkLPn7daY0JBrkdWIvoCB9xnkA1GUOI,28610
+stix2utils/sdo_models.py,sha256=AijfmBPAv0zzWfojj1CYtbIlCQnxxwrnTJ8gaWN28WU,9046
+stix2utils/sro_models.py,sha256=1lUeDk_46OhzEkETURpsNDVrZtbth0izduAsGd8Jhqc,12427
+stix2utils/validator.py,sha256=IFeFBvppZNp4hr4B04e6BxSmN2icuzUC8CORy9YWUQU,944
+stix2_utils-0.0.2.dist-info/WHEEL,sha256=YR4QUxGCbsyoOnWBVTv-p1I4yc3seKGPev46mvmc8Cg,81
+stix2_utils-0.0.2.dist-info/METADATA,sha256=Zg3BVinUIjpNFUau7w7fj2EJlNAtH2B8pMdCf-L-1VQ,1015
+stix2_utils-0.0.2.dist-info/RECORD,,

stix2_utils-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.29
+Root-Is-Purelib: true
+Tag: py3-none-any

stix2utils/__init__.py

@@ -0,0 +1,85 @@
+from stix2utils.sco_models import (
+    URL,
+    Artifact,
+    AutonomousSystem,
+    Directory,
+    DomainName,
+    EmailAddress,
+    EmailMessage,
+    File,
+    IPv4Address,
+    IPv6Address,
+    MACAddress,
+    Mutex,
+    NetworkTraffic,
+    Process,
+    Software,
+    UserAccount,
+    WindowsRegistryKey,
+    X509Certificate,
+)
+from stix2utils.sdo_models import (
+    AttackPattern,
+    Campaign,
+    CourseOfAction,
+    Grouping,
+    Identity,
+    Indicator,
+    Infrastructure,
+    IntrusionSet,
+    Location,
+    Malware,
+    MalwareAnalysis,
+    Note,
+    ObservedData,
+    Opinion,
+    Report,
+    ThreatActor,
+    Tool,
+    Vulnerability,
+)
+from stix2utils.sro_models import Relationship, Sighting
+from stix2utils.validator import STIX2ValidationResult, STIX2Validator
+
+__all__ = [
+    STIX2Validator,
+    STIX2ValidationResult,
+    AttackPattern,
+    Campaign,
+    CourseOfAction,
+    Grouping,
+    Identity,
+    Indicator,
+    Infrastructure,
+    IntrusionSet,
+    Location,
+    Malware,
+    MalwareAnalysis,
+    Note,
+    ObservedData,
+    Opinion,
+    Report,
+    ThreatActor,
+    Tool,
+    Vulnerability,
+    Artifact,
+    AutonomousSystem,
+    Directory,
+    DomainName,
+    EmailAddress,
+    EmailMessage,
+    File,
+    IPv4Address,
+    IPv6Address,
+    MACAddress,
+    Mutex,
+    NetworkTraffic,
+    Process,
+    Software,
+    URL,
+    UserAccount,
+    WindowsRegistryKey,
+    X509Certificate,
+    Relationship,
+    Sighting,
+]

stix2utils/adapter.py

@@ -0,0 +1,89 @@
+from typing import Annotated
+
+from pydantic import Field, TypeAdapter
+
+from stix2utils.sco_models import (
+    URL,
+    Artifact,
+    AutonomousSystem,
+    Directory,
+    DomainName,
+    EmailAddress,
+    EmailMessage,
+    File,
+    IPv4Address,
+    IPv6Address,
+    MACAddress,
+    Mutex,
+    NetworkTraffic,
+    Process,
+    Software,
+    UserAccount,
+    WindowsRegistryKey,
+    X509Certificate,
+)
+from stix2utils.sdo_models import (
+    AttackPattern,
+    Campaign,
+    CourseOfAction,
+    Grouping,
+    Identity,
+    Indicator,
+    Infrastructure,
+    IntrusionSet,
+    Location,
+    Malware,
+    MalwareAnalysis,
+    Note,
+    ObservedData,
+    Opinion,
+    Report,
+    ThreatActor,
+    Tool,
+    Vulnerability,
+)
+from stix2utils.sro_models import Relationship, Sighting
+
+SDO_SCO_SRO = Annotated[
+    AttackPattern
+    | Campaign
+    | CourseOfAction
+    | Grouping
+    | Identity
+    | Indicator
+    | Infrastructure
+    | IntrusionSet
+    | Location
+    | Malware
+    | MalwareAnalysis
+    | Note
+    | ObservedData
+    | Opinion
+    | Report
+    | ThreatActor
+    | Tool
+    | Vulnerability
+    | Artifact
+    | AutonomousSystem
+    | Directory
+    | DomainName
+    | EmailAddress
+    | EmailMessage
+    | File
+    | IPv4Address
+    | IPv6Address
+    | MACAddress
+    | Mutex
+    | NetworkTraffic
+    | Process
+    | Software
+    | URL
+    | UserAccount
+    | WindowsRegistryKey
+    | X509Certificate
+    | Relationship
+    | Sighting,
+    Field(discriminator="type"),
+]
+
+stix_adapter = TypeAdapter(SDO_SCO_SRO)

stix2utils/common.py

@@ -0,0 +1,87 @@
+from enum import Enum
+from typing import Annotated
+
+from pydantic import Field
+
+# ---------------------------------------------------------------------------
+# Common base
+# ---------------------------------------------------------------------------
+
+_TIMESTAMP_RE = (
+    r"^\d{4}-\d{2}-\d{2}"  # YYYY-MM-DD
+    r"T\d{2}:\d{2}:\d{2}"  # THH:mm:ss
+    r"(?:\.\d+)?"  # optional .s+  (dot only if digits follow)
+    r"Z$"  # mandatory UTC designator
+)
+
+Timestamp = Annotated[str, Field(pattern=_TIMESTAMP_RE)]
+
+# hex type: even number of lowercase hex characters
+Hex = Annotated[str, Field(pattern=r"^(?:[0-9a-f]{2})+$")]
+
+# A hashes dictionary: keys are algorithm names, values are hash strings.
+# Keys should come from hash-algorithm-ov, dictionary keys 3-250 ASCII chars.
+Hashes = Annotated[dict[str, str], Field(min_length=1)]
+
+
+class HashAlgorithm(str, Enum):
+    MD5 = "MD5"
+    SHA_1 = "SHA-1"
+    SHA_256 = "SHA-256"
+    SHA_512 = "SHA-512"
+    SHA3_256 = "SHA3-256"
+    SHA3_512 = "SHA3-512"
+    SSDEEP = "SSDEEP"
+    TLSH = "TLSH"
+
+
+# ---------------------------------------------------------------------------
+# STIX object type universe
+# ---------------------------------------------------------------------------
+
+SDO_TYPES: frozenset[str] = frozenset(
+    {
+        "attack-pattern",
+        "campaign",
+        "course-of-action",
+        "grouping",
+        "identity",
+        "incident",
+        "indicator",
+        "infrastructure",
+        "intrusion-set",
+        "location",
+        "malware",
+        "malware-analysis",
+        "note",
+        "observed-data",
+        "opinion",
+        "report",
+        "threat-actor",
+        "tool",
+        "vulnerability",
+    }
+)
+
+SCO_TYPES: frozenset[str] = frozenset(
+    {
+        "artifact",
+        "autonomous-system",
+        "directory",
+        "domain-name",
+        "email-addr",
+        "email-message",
+        "file",
+        "ipv4-addr",
+        "ipv6-addr",
+        "mac-addr",
+        "mutex",
+        "network-traffic",
+        "process",
+        "software",
+        "url",
+        "user-account",
+        "windows-registry-key",
+        "x509-certificate",
+    }
+)

stix2utils/references.py

@@ -0,0 +1,47 @@
+from typing import Annotated, TypeAlias
+
+from pydantic import Field
+
+_UUID = r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+
+
+def _pattern(*types: str) -> str:
+    """Build the id-regex for one or more STIX id prefixes."""
+    prefix = types[0] if len(types) == 1 else "(?:" + "|".join(types) + ")"
+    return rf"^{prefix}--{_UUID}$"
+
+
+# Single-type references
+IdentityRef: TypeAlias = Annotated[str, Field(pattern=_pattern("identity"))]
+MarkingRef: TypeAlias = Annotated[str, Field(pattern=_pattern("marking-definition"))]
+SoftwareRef: TypeAlias = Annotated[str, Field(pattern=_pattern("software"))]
+ObservedDataRef: TypeAlias = Annotated[str, Field(pattern=_pattern("observed-data"))]
+
+# Multi-type references
+SampleRef: TypeAlias = Annotated[str, Field(pattern=_pattern("file", "artifact"))]  # malware / malware-analysis samples
+IdentityOrLocationRef: TypeAlias = Annotated[str, Field(pattern=_pattern("identity", "location"))]  # malware / malware-analysis samples
+InstalledSoftwareRef: TypeAlias = Annotated[str, Field(pattern=_pattern("software"))]
+
+# Open reference: any valid STIX object id (SDO / SCO / SRO / SMO)
+AnyRef: TypeAlias = Annotated[str, Field(pattern=_pattern("[a-z0-9-]+"))]
+
+
+# Single-type references
+ArtifactRef: TypeAlias = Annotated[str, Field(pattern=_pattern("artifact"))]
+AutonomousSystemRef: TypeAlias = Annotated[str, Field(pattern=_pattern("autonomous-system"))]
+DirectoryRef: TypeAlias = Annotated[str, Field(pattern=_pattern("directory"))]
+FileRef: TypeAlias = Annotated[str, Field(pattern=_pattern("file"))]
+MACAddrRef: TypeAlias = Annotated[str, Field(pattern=_pattern("mac-addr"))]
+NetworkTrafficRef: TypeAlias = Annotated[str, Field(pattern=_pattern("network-traffic"))]
+ProcessRef: TypeAlias = Annotated[str, Field(pattern=_pattern("process"))]
+UserAccountRef: TypeAlias = Annotated[str, Field(pattern=_pattern("user-account"))]
+
+# Multi-type references
+DirectoryContainsRef: TypeAlias = Annotated[str, Field(pattern=_pattern("file", "directory"))]
+DomainResolvesToRef: TypeAlias = Annotated[str, Field(pattern=_pattern("ipv4-addr", "ipv6-addr", "domain-name"))]
+IPResolvesToRef: TypeAlias = Annotated[str, Field(pattern=_pattern("mac-addr"))]
+IPBelongsToRef: TypeAlias = Annotated[str, Field(pattern=_pattern("autonomous-system"))]
+EmailAddrRef: TypeAlias = Annotated[str, Field(pattern=_pattern("email-addr"))]
+EmailFromRef: TypeAlias = Annotated[str, Field(pattern=_pattern("email-addr"))]
+MimeBodyRawRef: TypeAlias = Annotated[str, Field(pattern=_pattern("artifact", "file"))]
+NetworkSrcDstRef: TypeAlias = Annotated[str, Field(pattern=_pattern("ipv4-addr", "ipv6-addr", "mac-addr", "domain-name"))]