stidantic 0.1.5

A Pydantic-based Python library for parsing, validating, and creating STIX 2.1 cyber threat intelligence data.

stidantic [WIP]

This is work in progress, compliant but untested.

A Pydantic-based Python library for parsing, validating, and creating STIX 2.1 cyber threat intelligence data.

Overview

stidantic provides a type-safe, Pythonic way to work with STIX 2.1 (Structured Threat Information Expression) objects.

This library leverages Pydantic to provide:

• 🔒 Strong type validation for all STIX objects
• 📝 IDE auto-completion and type hints
• ✅ Automatic validation of STIX specification constraints
• 🔄 Easy JSON serialization/deserialization
• ❄️ Immutable models with frozen Pydantic configurations
• 🎯 Discriminated unions for polymorphic STIX object handling

Installation

Requirements

• Python 3.12 or later (uses PEP 695 type statements)
• Pydantic >= 2.12

Quick Start

Parsing a STIX Bundle

from stidantic.bundle import StixBundle

# Load from JSON file
with open("threat_data.json", "r") as f:
    bundle = StixBundle.model_validate_json(f.read())

# Access objects
print(f"Bundle contains {len(bundle.objects)} objects")
for obj in bundle.objects:
    print(f"- {obj.type}: {obj.id}")

Creating STIX Objects

from datetime import datetime
from stidantic.sdo import Campaign
from stidantic.types import Identifier

campaign = Campaign(
    id=Identifier("campaign--8e2e2d2b-17d4-4cbf-938f-98ee46b3cd3f"),
    created=datetime.now(),
    modified=datetime.now(),
    name="Operation Stealth",
    description="A sophisticated campaign targeting financial institutions",
    objective="Financial gain through wire fraud"
)

# Export to JSON
json_output = campaign.model_dump_json(indent=2, exclude_none=True, by_alias=True)
print(json_output)

Handling property extensions

from stidantic.marking import MarkingDefinition
from stidantic.extensions.pap import PAPExtensionDefinition, PAPExtension

MarkingDefinition.register_new_extension(PAPExtensionDefinition, PAPExtension)
data = {
    "id": "marking-definition--c43594d1-4b11-4c59-93ab-1c9b14d53ce9",
    "type": "marking-definition",
    "spec_version": "2.1",
    "extensions": {
        "extension-definition--f8d78575-edfd-406e-8e84-6162a8450f5b": {
            "extension_type": "property-extension",
            "pap": "green",
        }
    },
    "created": "2022-10-01T00:00:00Z",
    "name": "PAP:GREEN",
}

pap_green = MarkingDefinition.model_validate(data)
if isinstance(pap_green.extensions[PAPExtensionDefinition.id], PAPExtension):
    print("Extension was parsed & validated by Pydantic.")

Implemented STIX Objects

STIX Domain Objects (SDOs)

• ✅ AttackPattern - Ways adversaries attempt to compromise targets
• ✅ Campaign - Grouping of adversarial behaviors over time
• ✅ Course of Action - Action taken to prevent or respond to an attack
• ✅ Grouping - Explicitly asserts that STIX Objects have a shared context
• ✅ Identity - Actual individuals, organizations, or groups
• ✅ Incident - A stub object representing a security incident
• ✅ Indicator - Pattern that can be used to detect suspicious or malicious activity
• ✅ Infrastructure - Systems, software services, and associated resources
• ✅ Intrusion Set - A grouped set of adversarial behaviors and resources
• ✅ Location - A geographic location
• ✅ Malware - A type of TTP that represents malicious code
• ✅ Malware Analysis - The results of a malware analysis
• ✅ Note - Analyst-created content and context
• ✅ Observed Data - Information about cyber security related entities
• ✅ Opinion - An assessment of the correctness of a STIX Object
• ✅ Report - Collections of threat intelligence
• ✅ Threat Actor - Actual individuals, groups, or organizations
• ✅ Tool - Legitimate software that can be used by threat actors
• ✅ Vulnerability - A mistake in software that can be used to compromise a system

STIX Cyber-observable Objects (SCOs)

• ✅ Artifact - Binary or file-like objects
• ✅ AutonomousSystem - Autonomous System (AS) information
• ✅ Directory - A directory on a file system
• ✅ Domain Name - A network domain name
• ✅ Email Address - An email address
• ✅ Email Message - An email message
• ✅ File - A computer file
• ✅ IPv4 Address - An IPv4 address
• ✅ IPv6 Address - An IPv6 address
• ✅ MAC Address - A Media Access Control (MAC) address
• ✅ Mutex - A mutual exclusion object
• ✅ Network Traffic - A network traffic flow
• ✅ Process - A running process
• ✅ Software - A software product
• ✅ URL - A Uniform Resource Locator (URL)
• ✅ User Account - A user account on a system
• ✅ Windows Registry Key - A key in the Windows registry
• ✅ X.509 Certificate - An X.509 certificate

STIX Relationship Objects (SROs)

• ✅ Relationship - Connections between STIX objects
• ✅ Sighting - Observations of threat intelligence in the wild

Meta Objects

• ✅ MarkingDefinition - Data markings (includes TLP)
• ✅ LanguageContent - Translations and internationalization
• ✅ ExtensionDefinition - Custom STIX extensions

Bundle

• ✅ StixBundle - Container for STIX objects

Extensions

• ✅ PAP - Permissible Actions Protocol (PAP) extension from Oasis

Roadmap

• Full STIX 2.1 Compliance
• Python packaging
• Extensive Testing
• Mind the datetime datatype serializer to follow the specification (convert to UTC).
• Implement auto deterministic UUIv5 generation for STIX Identifiers.
• Implement a Indicator to Observable export method (and the other way round ?).
• Add Generics validation for Identifier properties that must be of some type.
• Better STIX Extension Support: Develop a robust and user-friendly mechanism for defining, parsing, and validating custom STIX extensions.
• TAXII 2.1 Server: Build a TAXII 2.1 compliant server using FastAPI.
• OCA Standard Extensions: Implement STIX extensions from the Open Cybersecurity Alliance (OCA) and stix-common-objects repositories.
• Performance Tuning: Profile and optimize parsing and serialization.

Resources

• STIX 2.1 Specification
• STIX 2.1 Introduction
• Pydantic Documentation

License

stidantic is released under the MIT License.

Acknowledgments

This project implements the STIX 2.1 specification edited by Bret Jordan, Rich Piazza, and Trey Darley, published by the OASIS Cyber Threat Intelligence (CTI) Technical Committee.