STIX 2.x Validator

Common errors

• jsonschema.exceptions.ValidationError: 'properties' is a required property

  cause A STIX object or a custom extension schema is missing a required property according to the STIX specification or its own schema definition.
  fix Carefully review the STIX object against the relevant STIX specification (e.g., STIX 2.1) to ensure all mandatory properties are present and correctly formatted. For custom schemas, verify the schema definition itself.

• ImportError: cannot import name 'Validator' from 'stix2validator'

  cause Attempting to import `Validator` from an incorrect module path, or `stix2-validator` is not installed or installed in a different environment.
  fix Ensure the library is installed with `pip install stix2-validator` and that the import statement is exactly `from stix2validator import Validator`. Check your Python environment if using virtual environments.

• AttributeError: 'list' object has no attribute 'get'

  cause Attempting to validate a list of STIX objects directly with `validator.validate()`. The `validate` method expects a single STIX object (dictionary) or a STIX bundle (which is also a dictionary).
  fix If you have a list of STIX objects, iterate through the list and validate each object individually. If it's meant to be a STIX Bundle, ensure it's structured as a dictionary with 'type': 'bundle' and an 'objects' list.

Warnings

• breaking Python 3.5 and 3.6 are no longer supported. Version 3.0.0 dropped support for Python 3.5, and version 3.1.0 dropped support for Python 3.6.
  Fix: Upgrade your Python environment to 3.7 or newer to use stix2-validator versions 3.0.0+.
• breaking The `network-traffic.http-request-ext.request_header` property must now be a list of strings. Previously, it could be a singular string, which is no longer compliant.
  Fix: Ensure that `request_header` values within network-traffic extension objects are provided as a list of strings, even if only one header is present (e.g., `['Host: example.com']`).
• gotcha When validating STIX documents against older specification versions, or documents that mix object `spec_version` values, the validator might default to the latest specification rules. Explicitly configure `stix_version` if you encounter unexpected errors for older STIX documents.
  Fix: When initializing `Validator` or calling `validate()`, specify the `stix_version` parameter (e.g., `Validator(stix_version='2.0')` or `validator.validate(obj, stix_version='2.0')`) to ensure validation against the correct STIX specification version.
• deprecated Older versions of `jsonschema` used by `stix2-validator` might log deprecation warnings related to `jsonschema.draft202012_format_checker` due to changes in `jsonschema` itself.
  Fix: Upgrade `stix2-validator` to version 3.1.3 or newer, which includes fixes to address these `jsonschema` deprecation warnings by updating internal schema references.

Install

• pip install stix2-validator Install latest version

Imports

• Validator

  from stix2validator import Validator

Quickstart

This quickstart demonstrates how to initialize the `Validator` and use it to validate a STIX object represented as a Python dictionary. It shows both standard and verbose validation output. To validate a STIX document from a file, load its JSON content into a dictionary first.

from stix2validator import Validator
import json

# Example STIX 2.1 Indicator object for validation
stix_object = {
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a79f0462-8789-4b67-8c0c-52643a2d1d07",
    "created": "2024-01-01T12:00:00.000Z",
    "modified": "2024-01-01T12:00:00.000Z",
    "pattern": "[file:hashes.MD5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    "pattern_type": "stix",
    "valid_from": "2024-01-01T12:00:00.000Z"
}

# Initialize the validator
validator = Validator()

# Validate a STIX dictionary (e.g., loaded from JSON)
results = validator.validate(stix_object)

if not results:
    print("STIX object is valid.")
else:
    print("STIX object has validation issues:")
    for result in results:
        print(f"  - {result}")

# For more detailed output, instantiate with verbose=True
verbose_validator = Validator(verbose=True)
verbose_results = verbose_validator.validate(stix_object)
if verbose_results:
    print("\nVerbose validation results:")
    for result in verbose_results:
        print(f"  - {result}")