Registry / auth-security / stix2-patterns

stix2-patterns

library2.1.2pypypi✓ verified 26d ago

The `stix2-patterns` library provides a software tool for checking the syntax of Cyber Threat Intelligence (CTI) STIX Pattern expressions, used within STIX Indicators to describe conditions indicating cyber threat activity. It is currently at version 2.1.2 and actively maintained with regular updates addressing bug fixes and improvements.

auth-security data

pip install stix2-patterns

github ↗package ↗

INSTALL

IMPORT

SIG · STIX2-PATTERNS

stix2-patterns

auth-securitypythonv2.1.2

Install

1.9s avg

Import

86ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.092s · 19.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.9s · import 0.080s · 20MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

run_validator

✓ from stix2patterns.validator import run_validator

The primary way to use the library programmatically is via the `run_validator` function. It takes a STIX pattern string and returns a list of errors encountered during parsing. An empty list indicates a valid pattern.

from stix2patterns.validator import run_validator # A valid STIX 2.1 pattern pattern_valid = "[file-object:hashes.md5 = '79054025255fb1a26e4bc422aef54eb4']" errors_valid = run_validator(pattern_valid) if not errors_valid: print(f"Pattern '{pattern_valid}' is valid.") else: print(f"Pattern '{pattern_valid}' has errors: {errors_valid}") # An invalid STIX pattern pattern_invalid = "[file-object:hashes.md5 = 'bad_hash']" errors_invalid = run_validator(pattern_invalid) if not errors_invalid: print(f"Pattern '{pattern_invalid}' is valid.") else: print(f"Pattern '{pattern_invalid}' has errors: {errors_invalid}") # Example of STIX 2.0 pattern (might be considered invalid under 2.1 strictness, but syntax for this is okay) pattern_stix20 = "[file:hashes.'MD5' = 'd41d8cd98f00b204e9800998ecf8427e']" errors_stix20 = run_validator(pattern_stix20) if not errors_stix20: print(f"Pattern '{pattern_stix20}' is valid.") else: print(f"Pattern '{pattern_stix20}' has errors: {errors_stix20}")

Debug

Known issues

breakingPython 3.10 or newer is now required. Older versions of the library supported Python versions as low as 3.5 (for `stix2` core library) or older (pre-v1.0.0). Ensure your environment meets the `>=3.10` requirement.

fix

Upgrade your Python environment to 3.10 or later.

affects: >=2.0.0

breakingVersion 2.0.0 updated the underlying ANTLR grammar to ANTLR 4.9 (from 4.8 in v1.3.0). This change, along with the dependency on `antlr4-python3-runtime~=4.13.0`, might introduce subtle differences in how patterns are parsed or validated, potentially breaking previously valid complex patterns due to updated grammar rules or stricter enforcement.

fix

Review and re-test complex STIX patterns with the updated validator, especially those pushing the boundaries of the STIX Patterning Specification.

affects: >=2.0.0

gotchaAs of v2.0.0, the validator defaults to supporting STIX 2.1 patterns. While it can still parse many 2.0 patterns, subtle differences in the 2.1 specification may cause some 2.0-specific patterns to be flagged as invalid if not strictly compliant with 2.1 rules.

fix

Be aware of the STIX specification version you are targeting. The `cti-pattern-validator` repo's `stix2patterns.test` directories contain `spec_examples.txt` for both `v20` and `v21`, which can serve as a reference.

affects: >=2.0.0

gotchaThis library (`stix2-patterns`) is a *pattern validator*; it only checks the syntax of STIX patterns. It does *not* evaluate or match STIX patterns against actual STIX Observed Data. For pattern matching/evaluation functionality, you need a separate library like `cti-pattern-matcher` (or `stix2-matcher`).

fix

If you need to evaluate patterns against STIX data, use `pip install cti-pattern-matcher` in conjunction with `stix2-patterns`.

affects: All versions

Errors

Common errors & fixes

stix2patterns.exceptions.PatternSyntaxError

This error indicates that the provided STIX pattern string violates the STIX Patterning Language grammar rules.

fix

Review the STIX Patterning Language specification (e.g., STIX 2.1 Part 4: Patterns) to correct the syntax of your STIX pattern.

ModuleNotFoundError: No module named 'stix2_patterns'

The module name used in the import statement is incorrect; the installed package's main module is `stix2patterns`, not `stix2_patterns`.

fix

Use `stix2patterns` for imports, for example: `from stix2patterns.v21.pattern import Pattern` or `from stix2patterns.validator import validate`.

AttributeError: module 'stix2patterns' has no attribute 'validate'

The `validate` function is not directly available under the top-level `stix2patterns` module but resides within the `stix2patterns.validator` submodule.

fix

Import the `validate` function specifically from `stix2patterns.validator`: `from stix2patterns.validator import validate`.

TypeError: expected string or bytes-like object

The `stix2patterns` library functions, such as `Pattern()` or `parse()`, require the STIX pattern to be provided as a string.

fix

Ensure the input pattern is a string: `pattern_str = "[file:hashes.'MD5' = 'd41d8cd98f00b204e9800998ecf8427e']"; p = Pattern(pattern_str)`.

Upgrade

Version history

2.1.2latest on PyPI · released Feb 11, 2026

Audit

Dependencies

pythonrequiredRequired Python version for execution.

antlr4-python3-runtimerequiredUnderlying ANTLR parser runtime for grammar processing.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/oasis-open/cti-pattern-validator ↗

packagehttps://pypi.org/project/stix2-patterns/ ↗