or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-utilities.mdconfiguration.mdcore-validation.mdexception-handling.mdindex.mdresults-output.md
tile.json

tessl/pypi-stix2-validator

APIs and scripts for validating STIX 2.x documents against specification requirements and best practices.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/stix2-validator@3.2.x

To install, run

npx @tessl/cli install tessl/pypi-stix2-validator@3.2.0

index.mddocs/

STIX2-Validator

A comprehensive Python library for validating STIX (Structured Threat Information eXpression) 2.x JSON documents against specification requirements and best practices. The validator ensures conformance with both mandatory "MUST" requirements and recommended "SHOULD" best practices from the STIX 2.0 and 2.1 specifications.

Package Information

  • Package Name: stix2-validator
  • Language: Python
  • Installation: pip install stix2-validator

Core Imports

import stix2validator

Common validation functions:

from stix2validator import validate_file, validate_string, validate_instance, print_results

Configuration and utilities:

from stix2validator import ValidationOptions, parse_args

Exception handling:

from stix2validator import ValidationError, NoJSONFileFoundError

Exit codes and CLI utilities:

from stix2validator import codes
from stix2validator.codes import get_code, EXIT_SUCCESS, EXIT_FAILURE
from stix2validator.scripts.stix2_validator import main

Basic Usage

from stix2validator import validate_file, print_results

# Validate a STIX JSON file
results = validate_file("stix_document.json")
print_results(results)

# Check if validation passed
if results.is_valid:
    print("STIX document is valid!")
else:
    print("Validation errors found")
    for error in results.errors:
        print(f"Error: {error}")
from stix2validator import validate_string, ValidationOptions

# Validate STIX JSON from string with custom options
stix_json = '{"type": "indicator", "id": "indicator--12345678-1234-1234-1234-123456789012", ...}'

options = ValidationOptions(
    version="2.1",
    strict=True,
    verbose=True
)

results = validate_string(stix_json, options)
print(f"Valid: {results.is_valid}")

Architecture

The validator follows a layered architecture:

  • Validation Functions: Core entry points (validate_file, validate_string, etc.) that handle different input types
  • ValidationOptions: Configuration class for customizing validation behavior
  • Result Classes: Structured result objects (FileValidationResults, ObjectValidationResults) for validation outcomes
  • Schema Validation: JSON Schema-based validation for STIX object structure
  • Python Rule Validation: Custom Python functions for rules that cannot be expressed in JSON Schema
  • Version-Specific Modules: Separate validation logic for STIX 2.0 and 2.1 specifications

Capabilities

Core Validation Functions

Main validation entry points for different input types including files, strings, Python dictionaries, and parsed JSON objects. These functions form the foundation of STIX document validation.

def validate_file(fn, options=None): ...
def validate_string(string, options=None): ...
def validate_instance(instance, options=None): ...
def validate_parsed_json(obj_json, options=None): ...
def validate(in_, options=None): ...
def run_validation(options): ...

Core Validation

Configuration and Options

Comprehensive configuration system for customizing validation behavior, including version selection, strictness levels, custom schema directories, and selective enabling/disabling of validation checks.

class ValidationOptions: ...
def parse_args(cmd_args, is_script=False): ...

Configuration

Result Processing

Structured result classes and output formatting functions for handling validation outcomes, including error reporting, success indicators, and formatted console output with color coding.

class FileValidationResults: ...
class ObjectValidationResults: ...
def print_results(results): ...

Results and Output

Exception Handling

Comprehensive exception hierarchy for different validation error scenarios, enabling precise error handling and programmatic response to validation failures.

class ValidationError(Exception): ...
class SchemaError(ValidationError): ...
class NoJSONFileFoundError(OSError): ...

Exception Handling

Exit Codes and Status

Exit code utilities for command-line integration and programmatic validation result processing, providing standardized status codes for different validation outcomes.

def get_code(results): ...
EXIT_SUCCESS: int
EXIT_FAILURE: int
EXIT_SCHEMA_INVALID: int
EXIT_VALIDATION_ERROR: int

Exit codes module provides standardized status codes for validation results and CLI integration.

Command-Line Interface

Command-line script entry point and utilities for standalone STIX validation from the command line with comprehensive option support.

def main(): ...

The stix2_validator command-line script provides a complete CLI interface for STIX validation with all library features accessible via command-line arguments.

CLI Utilities

Types

from typing import Union, List

# Validation input types
FileInput = str  # File path
StringInput = str  # JSON string
InstanceInput = dict  # Python dictionary representing STIX object
ParsedJsonInput = Union[dict, list]  # Parsed JSON object or list

# Result types
FileValidationResult = FileValidationResults  # For validate_file()
ObjectValidationResult = ObjectValidationResults  # For validate_instance()
StreamValidationResult = Union[ObjectValidationResults, List[ObjectValidationResults]]  # For validate_string(), validate_parsed_json(), validate()
BatchValidationResult = List[FileValidationResults]  # For run_validation()

# Exit code constants
EXIT_SUCCESS = 0x0  # All documents valid
EXIT_FAILURE = 0x1  # Fatal system error  
EXIT_SCHEMA_INVALID = 0x2  # Schema validation failed
EXIT_VALIDATION_ERROR = 0x10  # Validation error occurred