stix2-utils 0.0.2__tar.gz

stix2_utils-0.0.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,20 @@
+# 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/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["uv_build >= 0.11.23, <0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "stix2-utils"
+version = "0.0.2"
+requires-python = ">= 3.13"
+description = "Utility library for validating stix2 entities and patterns"
+readme = "README.md"
+authors = [
+    { name = "Daan Willems", email = "daan@daan.nl" }
+]
+dependencies = [
+    "pydantic"
+]
+[project.optional-dependencies]
+dev = [
+    "pytest"
+]
+
+[project.urls]
+Homepage = "https://github.com/DaanWillems/stix2-utils"
+
+[tool.uv.build-backend]
+module-root = ""
+module-name = "stix2utils"
+
+[tool.coverage.run]
+omit = [
+]
+
+[tool.coverage.report]
+skip_empty = true
+
+[tool.semantic_release.branches.main]
+match = "(main|master)"
+prerelease = "false"
+
+[tool.setuptools.packages]
+find = { }
+
+[tool.pytest.ini_options]
+pythonpath = "."
+env = [
+    "ENV = test",
+]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+ignore_errors = true
+
+[tool.ruff]
+exclude = [
+]
+line-length = 140
+indent-width = 4
+
+[tool.ruff.format]
+line-ending = "lf"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/fixtures/**.py" = ["PT022"]  # Inversed teardown, ignore for this specific case only
+"tests/*" = [
+    "ANN",      # Non annotations are fine in tests.
+    "S101",     # We actually want 'assert' in tests.
+    "S106",     # Dummy strings as passswords are fine in tests.
+]
+
+
+[tool.ruff.lint]
+ignore = ["ANN002", "ANN003", "FIX002", "COM812", "UP040"]
+select = ["E", "F", "W", "ANN", "I", "N", "UP", "YTT", "S", "BLE", "FBT", "B", "A", "COM", "C4", "T10", "EM", "EXE", "ISC", "ICN", "LOG", "G", "INP", "PIE", "T20", "PYI", "PT", "RSE", "RET", "SLF", "SIM", "TID", "TCH", "INT", "ARG", "PTH", "TD", "FIX", "ERA", "R", "TRY", "FLY", "PERF", "FURB", "RUF"]
+
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-base-classes = ["pydantic.BaseModel"]

stix2_utils-0.0.2/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,
+]

stix2_utils-0.0.2/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)

stix2_utils-0.0.2/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",
+    }
+)

stix2_utils-0.0.2/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"))]