{"id":4783,"library":"stix2-patterns","title":"STIX 2 Patterns Validator","description":"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.","status":"active","version":"2.1.2","language":"en","source_language":"en","source_url":"https://github.com/oasis-open/cti-pattern-validator","tags":["stix","cti","security","threat intelligence","pattern validation","cybersecurity"],"install":[{"cmd":"pip install stix2-patterns","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required Python version for execution.","package":"python","version":">=3.10"},{"reason":"Underlying ANTLR parser runtime for grammar processing.","package":"antlr4-python3-runtime","version":"~=4.13.0"}],"imports":[{"symbol":"run_validator","correct":"from stix2patterns.validator import run_validator"}],"quickstart":{"code":"from stix2patterns.validator import run_validator\n\n# A valid STIX 2.1 pattern\npattern_valid = \"[file-object:hashes.md5 = '79054025255fb1a26e4bc422aef54eb4']\"\nerrors_valid = run_validator(pattern_valid)\nif not errors_valid:\n    print(f\"Pattern '{pattern_valid}' is valid.\")\nelse:\n    print(f\"Pattern '{pattern_valid}' has errors: {errors_valid}\")\n\n# An invalid STIX pattern\npattern_invalid = \"[file-object:hashes.md5 = 'bad_hash']\"\nerrors_invalid = run_validator(pattern_invalid)\nif not errors_invalid:\n    print(f\"Pattern '{pattern_invalid}' is valid.\")\nelse:\n    print(f\"Pattern '{pattern_invalid}' has errors: {errors_invalid}\")\n\n# Example of STIX 2.0 pattern (might be considered invalid under 2.1 strictness, but syntax for this is okay)\npattern_stix20 = \"[file:hashes.'MD5' = 'd41d8cd98f00b204e9800998ecf8427e']\"\nerrors_stix20 = run_validator(pattern_stix20)\nif not errors_stix20:\n    print(f\"Pattern '{pattern_stix20}' is valid.\")\nelse:\n    print(f\"Pattern '{pattern_stix20}' has errors: {errors_stix20}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or later.","message":"Python 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Review and re-test complex STIX patterns with the updated validator, especially those pushing the boundaries of the STIX Patterning Specification.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"As 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"If you need to evaluate patterns against STIX data, use `pip install cti-pattern-matcher` in conjunction with `stix2-patterns`.","message":"This 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`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}