STIX 2 Python Library

3.0.2 · active · verified Sun Apr 12

The stix2 Python library provides APIs for serializing and de-serializing STIX 2 JSON content, enabling users to produce, consume, and process cyber threat intelligence. It supports multiple versions of the STIX 2 Technical Specification, currently STIX 2.1. The library, currently at version 3.0.2, is actively maintained by the OASIS Cyber Threat Intelligence (CTI) Technical Committee, with releases typically driven by STIX specification updates and bug fixes.

Warnings

breaking The `stix2` library now requires Python 3.10 or higher. Older Python versions are no longer supported.
Fix: Upgrade your Python environment to 3.10 or newer. Ensure your `pyproject.toml` or `setup.py` reflects this requirement.
breaking Implicit imports (e.g., `import stix2; stix2.Indicator()`) can lead to breaking changes across major releases of `stix2` as the default STIX specification version supported by the library may be updated.
Fix: Explicitly import specific STIX object types (e.g., `from stix2 import Indicator`) or specify the STIX version using versioned modules (e.g., `from stix2 import v21; obj = v21.Indicator()`).
deprecated Custom properties in STIX 2.0 were deprecated in STIX 2.1 in favor of the `property-extension` mechanism. While the library supports parsing old custom properties for backward compatibility, new content should use extensions.
Fix: For new custom content, define and use STIX Extensions instead of directly adding custom properties. Refer to the `stix2` documentation on custom content and extensions.
gotcha STIX objects created with the `stix2` library are immutable by design. All properties must be provided during object instantiation and cannot be changed afterward.
Fix: To 'modify' an object, create a new object instance with the desired changes, often leveraging the `new_version()` method for versioning STIX objects appropriately.
gotcha ID generation differs between STIX Domain Objects (SDOs) and STIX Relationship Objects (SROs) which use random v4 UUIDs, and STIX Cyber Observable Objects (SCOs) which use deterministic v5 UUIDs. Changing ID-contributing properties for an SCO will result in a new ID.
Fix: Be aware of the ID generation behavior when creating and versioning objects, especially SCOs. If an SCO's ID-contributing properties change, it's considered a new object, not a minor version update.
breaking The `six` compatibility library dependency was dropped in `stix2` v3.0.0. This might affect applications relying on `six` for Python 2/3 compatibility within their `stix2` integration.
Fix: Ensure your codebase is fully Python 3 compatible and no longer relies on `six` for `stix2`-related operations. This change supports the library's Python 3.10+ requirement.

Install

pip install stix2 Install latest version

Imports

Indicator
```
from stix2 import Indicator
```
Implicit imports can break across major releases as the default STIX version supported by the library may change. It's recommended to import specific classes or explicitly reference versioned modules (e.g., `stix2.v21.Indicator`).
parse
```
from stix2 import parse
```
serialize
```
from stix2 import serialize
```

v21 (for explicit versioning)

from stix2 import v21
obj = v21.Indicator()

Quickstart

This quickstart demonstrates how to create a STIX Indicator object, serialize it to pretty-printed JSON, and parse a STIX JSON string back into a Python object. It uses the `Indicator` class for object creation and `serialize` and `parse` functions for data interchange.

from stix2 import Indicator, parse, serialize
from datetime import datetime, timezone

# Create a STIX Indicator object
indicator = Indicator(
    name="File hash for malware variant",
    indicator_types=["malicious-activity"],
    pattern_type="stix",
    pattern="[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    valid_from=datetime.now(timezone.utc)
)

# Serialize the STIX object to JSON
serialized_indicator = serialize(indicator, pretty=True)
print("\nSerialized Indicator:")
print(serialized_indicator)

# Parse a STIX JSON string back into a Python object
json_string = '''{
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--dbcbd659-c927-4f9a-994f-0a2632274394",
    "created": "2017-09-26T23:33:39.829Z",
    "modified": "2017-09-26T23:33:39.829Z",
    "name": "Another malware hash",
    "indicator_types": ["malicious-activity"],
    "pattern_type": "stix",
    "pattern_version": "2.1",
    "pattern": "[file:hashes.md5 = 'abcdef1234567890abcdef1234567890']",
    "valid_from": "2017-09-26T23:33:39.829952Z"
}'''
parsed_indicator = parse(json_string)
print("\nParsed Indicator Name:", parsed_indicator.name)

view raw JSON →