tessl/pypi-stix2

Produce and consume STIX 2 JSON content for cyber threat intelligence

Overview

Eval results

Files

Object Creation and Parsing

Name: tessl/pypi-stix2
Author: tessl

Core functionality for creating STIX objects from scratch and parsing existing STIX JSON content into Python objects. Supports all STIX 2.0 and 2.1 specification objects with validation, automatic property generation, and custom content handling.

Capabilities

JSON Parsing

Parse STIX JSON data into Python objects with validation and spec version detection.

def parse(data, allow_custom=False, version=None):
    """
    Parse STIX JSON data into Python objects.
    
    Parameters:
    - data (str or dict): STIX JSON string or dictionary
    - allow_custom (bool): Allow custom STIX content (default: False)
    - version (str): STIX specification version ("2.0" or "2.1")
    
    Returns:
    STIX Python object corresponding to the JSON data
    
    Raises:
    ParseError: If JSON data is invalid or malformed
    CustomContentError: If custom content detected and not allowed
    """

Usage example:

from stix2 import parse

# Parse STIX JSON string
stix_json = '''
{
    "type": "malware",
    "spec_version": "2.1", 
    "id": "malware--162d917e-766f-4611-b5d6-652791454fca",
    "created": "2018-04-23T18:07:56.000Z",
    "modified": "2018-04-23T18:07:56.000Z",
    "name": "Poison Ivy",
    "malware_types": ["remote-access-trojan"]
}
'''

malware_obj = parse(stix_json)
print(malware_obj.name)  # "Poison Ivy"
print(malware_obj.malware_types)  # ["remote-access-trojan"]

# Parse dictionary
stix_dict = {
    "type": "indicator",
    "name": "File hash indicator",
    "indicator_types": ["malicious-activity"],
    "pattern_type": "stix",
    "pattern": "[file:hashes.md5 = 'abc123']"
}

indicator_obj = parse(stix_dict)

Observable Parsing

Parse STIX Cyber Observable Objects with reference validation.

def parse_observable(data, _valid_refs=None, allow_custom=False, version=None):
    """
    Parse STIX Cyber Observable Objects.
    
    Parameters:
    - data (str or dict): SCO JSON string or dictionary
    - _valid_refs (list): Valid object references for validation
    - allow_custom (bool): Allow custom observables (default: False) 
    - version (str): STIX specification version ("2.0" or "2.1")
    
    Returns:
    STIX Cyber Observable Object
    
    Raises:
    ParseError: If observable data is invalid
    InvalidObjRefError: If object references are invalid
    """

Usage example:

from stix2 import parse_observable

# Parse file observable
file_json = '''
{
    "type": "file",
    "hashes": {
        "MD5": "d41d8cd98f00b204e9800998ecf8427e",
        "SHA-1": "da39a3ee5e6b4b0d3255bfef95601890afd80709"
    },
    "name": "empty.txt",
    "size": 0
}
'''

file_obj = parse_observable(file_json)
print(file_obj.name)  # "empty.txt"
print(file_obj.hashes)  # {"MD5": "d41d8cd98f00b204e9800998ecf8427e", ...}

# Parse IP address observable
ip_dict = {
    "type": "ipv4-addr",
    "value": "192.168.1.1"
}

ip_obj = parse_observable(ip_dict)
print(ip_obj.value)  # "192.168.1.1"

Object Serialization

All STIX objects have built-in serialization methods for converting back to JSON.

# Available on all STIX objects
def serialize(self, pretty=False, ensure_ascii=True, encoding='utf-8'):
    """
    Serialize STIX object to JSON string.
    
    Parameters:
    - pretty (bool): Pretty-print JSON with indentation
    - ensure_ascii (bool): Escape non-ASCII characters
    - encoding (str): Character encoding for output
    
    Returns:
    str: JSON representation of the STIX object
    """

Usage example:

from stix2 import Indicator

indicator = Indicator(
    name="Malicious IP",
    indicator_types=["malicious-activity"],
    pattern_type="stix", 
    pattern="[ipv4-addr:value = '192.168.1.100']"
)

# Serialize to compact JSON
json_compact = indicator.serialize()

# Serialize to pretty-printed JSON
json_pretty = indicator.serialize(pretty=True)
print(json_pretty)

Dictionary Conversion

Internal utility for converting dictionaries to STIX objects.

def dict_to_stix2(stix_dict, allow_custom=False, version=None):
    """
    Convert dictionary to STIX object.
    
    Parameters:
    - stix_dict (dict): Dictionary representation of STIX object
    - allow_custom (bool): Allow custom content
    - version (str): STIX specification version
    
    Returns:
    STIX Python object
    """

Error Handling

ParseError

Raised when STIX JSON data cannot be parsed due to syntax errors, missing required properties, or invalid structure.

from stix2 import parse, ParseError

try:
    invalid_json = '{"type": "invalid-type"}'
    obj = parse(invalid_json)
except ParseError as e:
    print(f"Parse error: {e}")

CustomContentError

Raised when custom STIX content is detected but not allowed.

from stix2 import parse, CustomContentError

try:
    custom_json = '{"type": "x-custom-object", "name": "test"}'
    obj = parse(custom_json, allow_custom=False)
except CustomContentError as e:
    print(f"Custom content error: {e}")

Version Handling

The library supports both STIX 2.0 and 2.1 specifications:

# Parse as STIX 2.0
obj_v20 = parse(stix_json, version="2.0")

# Parse as STIX 2.1 (default)
obj_v21 = parse(stix_json, version="2.1")

# Auto-detect version from spec_version property
obj_auto = parse(stix_json)  # Uses spec_version from JSON

Install with Tessl CLI