Version: 2.5.0

Getting Started

This page gives an introduction to stix-validator scripts. Please note that this page is being actively worked on and feedback is welcome! If you have a suggestion or something doesn’t look right, let us know: (stix@mitre.org).

Note that the GitHub repository is named stix-validator, but once installed, the library is imported using the import sdv statement.

Installation

To install stix-validator just run pip install stix-validator. If you have any issues, please refer to the instructions found on the Installation page.

Scripts

The stix-validator library comes with two scripts capable of performing the validation of STIX and CybOX documents: stix-validator.py and cybox-validator.py. These scripts can be found on your PATH after installing the stix-validator.

These instructions tell you how to validate STIX and CybOX content using the scripts bundled with stix-validator.

STIX Document Validator

The stix-validator.py script can be used to validate STIX content in a number of ways. The following sections describe the validation options and expected behavior of the stix-validator.py script.

Options

Running stix-validator.py -h displays the following:

$ stix-validator.py -h
usage: stix-validator.py [-h] [--stix-version STIX_VERSION]
                         [--schema-dir SCHEMA_DIR] [--use-schemaloc]
                         [--best-practices] [--profile PROFILE]
                         [--quiet] [--json-results]
                         [FILES [FILES ...]]

STIX Document Validator v2.4.0

positional arguments:
  FILES                 A whitespace separated list of STIX files or
                        directories of STIX files to validate.

optional arguments:
  -h, --help            show this help message and exit
  --stix-version STIX_VERSION
                        The version of STIX to validate against
  --schema-dir SCHEMA_DIR
                        Schema directory. If not provided, the STIX schemas
                        bundled with the stix-validator library will be used.
  --use-schemaloc       Use schemaLocation attribute to determine schema
                        locations.
  --best-practices      Check that the document follows authoring best
                        practices
  --profile PROFILE     Path to STIX profile in excel
  --quiet               Only print results and errors if they occur.
  --json-results        Print results as raw JSON. This also sets --quiet.

Profile Conversion

The profile-to-sch.py and profile-to-xslt.py scripts can be used to convert a valid STIX profile to ISO Schematron and XSLT respectively. This output is sent to stdout.

Schematron Conversion Options

Running profile-to-sch.py -h displays the following:

$ profile-to-sch.py -h
usage: profile-to-sch.py [-h] profile

STIX Profile to Schematron v2.4.0

positional arguments:
  profile               STIX profile filename to be converted to XSLT

optional arguments:
  -h, --help            Show this help message and exit

XSLT Conversion Options

Running profile-to-xslt.py -h displays the following:

$ profile-to-xslt.py -h
usage: profile-to-xslt.py [-h] profile

STIX Profile to XSLT v2.4.0

positional arguments:
  profile               STIX profile filename to be converted to XSLT

optional arguments:
  -h, --help            Show this help message and exit

Example Profile Conversion

The following code snippet demonstrates the conversion of a STIX profile document to Schematron.

$ profile-to-sch.py valid-stix-profile.xlsx

To save the conversion output, just redirect stdout to a file using the > operator. The following snippet shows how to convert a STIX profile and save the output to the file schematron-profile.sch.

$ profile-to-sch.py valid-stix-profile.xlsx > schematron-profile.sch

Example STIX Schema Validation

To perform xml schema validation, just pass in a path to the STIX filename, filenames, and/or directories containing STIX content.

$ stix-validator.py stix-content.xml another-stix-doc.xml

If these documents were valid, the stix-validator.py script would print something like the following:

[-] Performing xml schema validation on stix-content.xml
[-] Performing xml schema validation on another-stix-doc.xml
============================================================
[-] Results: stix-content.xml
[+] XML Schema: True
============================================================
[-] Results: another-stix-doc.xml
[+] XML Schema: True

CybOX Document Validator

The cybox-validator.py script can be used to perform XML Schema validation on one or more input CybOX documents. The following sections describe the validation options and expected behavior of the cybox-validator.py script.

Options

The cybox-validator.py script provides CybOX XML Schema validation capabilities to your command line.

$ cybox-validator.py -h
usage: cybox-validator.py [-h] [--cybox-version LANG_VERSION]
                          [--schema-dir SCHEMA_DIR] [--use-schemaloc]
                          [--quiet] [--json-results] [--recursive]
                          [FILES [FILES ...]]

CybOX Document Validator v2.4.0

positional arguments:
  FILES                 A whitespace separated list of CybOX files or
                        directories of CybOX files to validate.

optional arguments:
  -h, --help            show this help message and exit
  --cybox-version LANG_VERSION
                        The version of CybOX to validate against
  --schema-dir SCHEMA_DIR
                        Schema directory. If not provided, the CybOX schemas
                        bundled with the stix-validator library will be used.
  --use-schemaloc       Use schemaLocation attribute to determine schema
                        locations.
  --quiet               Only print results and errors if they occur.
  --json-results        Print results as raw JSON. This also sets --quiet.
  --recursive           Recursively descend into input directories.

Example CybOX Schema Validation

To perform xml schema validation, just pass in a path to the CybOX filename, filenames, and/or directories containing CybOX content.

$ cybox-validator.py cybox-content.xml another-cybox-doc.xml

If these documents were valid, the cybox-validator.py script would print something like the following:

[-] Performing xml schema validation on cybox-content.xml
[-] Performing xml schema validation on another-cybox-doc.xml
============================================================
[-] Results: cybox-content.xml
[+] XML Schema: True
============================================================
[-] Results: another-cybox-doc.xml
[+] XML Schema: True

Exit Codes

Exit status codes for the stix-validator bundled scripts are defined within sdv.codes module.

When invoking the stix-validator.py or cybox-validator.py scripts from another process, developers can inspect the exit code after execution to determine the results of the validation attempt. Exit status codes can be combined via bitmasks to convey multiple results (multiple files validated and/or multiple validation methods selected).

The following script demonstrates an example of invoking stix-validator.py from another Python script.

#!/usr/bin/env python

import subprocess
import sdv.codes as codes # STIX Document Validator exit codes

ARGS = [
    'stix-validator.py',
    '--best-practices',
    '--profile',
    'stix-profile.xlsx',
    'stix-document.xml'
]

# Run the stix-validator.py script as a subprocess. Redirect stdout.
results = subprocess.call(ARGS, stdout=subprocess.PIPE)

# Check exit status code(s)

if codes.EXIT_SUCCESS & results:
    print "Input document(s) were valid."

if codes.EXIT_SCHEMA_INVALID & results:
    print "One or more input files were schema-invalid."

if codes.EXIT_BEST_PRACTICE_INVALID & results:
    print "One or more input files were STIX Best Practices invalid."

if codes.EXIT_PROFILE_INVALID & results:
    print "One or more input files were STIX Profile invalid."

if codes.EXIT_VALIDATION_ERROR & results:
    print "A validation error occurred."

if codes.EXIT_FAILURE & results:
    print "An unknown, fatal error occurred."

Note

Invoking stix-validator.py or cybox-validator.py as a subprocess may not always be the best method for validating STIX documents from a Python script. The sdv module contains methods for performing STIX and CybOX validation!