Version: 2.4.0

STIX “Best Practices” Validation

The stix-validator library provides methods and data types to help perform STIX Best Practices validation.

Warning

The STIX Best Practices validation capabilities are under active development and do not cover all STIX Best Practices.

The following code examples demonstrate different ways you can utilize the STIX Best Practices validation capabilities in stix-validator.

Validating STIX Documents

The stix-validator sdv.validate_best_practices() method can be used to validate STIX XML files or file-like objects against STIX Best Practices.

import sdv

# Check the 'stix-content.xml' document for STIX Best Practices conformance
results = sdv.validate_best_practices('stix-content.xml')

# Print the result!
print results.is_valid

The sdv.validate_best_practices() method acts as a proxy to the STIXBestPracticeValidator class and is equivalent to the following:

from sdv.validators import STIXBestPracticeValidator

# Create the validator instance
validator = STIXBestPracticeValidator()

# Validate 'stix-content.xml` STIX document
results = validator.validate('stix-content.xml')

# Print the results!
print results.is_valid

The examples above pass the 'stix-content.xml' filename into sdv.validate_profile() and STIXProfileValidator.validate(), but these methods can also accept file-like objects (such as files on disk or StringIO instances), etree._Element instances, or etree._ElementTree instances. Neato!

Retrieving STIX Best Practice Validation Errors

The following sections explain how to retrieve STIX Best Practices validation errors from the BestPracticeValidationResults class.

The BestPracticeValidationResults Class

STIX Best Practices validation results are communicated via the BestPracticeValidationResults, BestPracticeWarningCollection, and BestPracticeWarning classes.

The sdv.validate_best_practices() and STIXBestPracticeValidator.validate() methods both return an instance of BestPracticeValidationResults.

To determine if a document was valid, users only need to inspect the is_valid property:

import sdv

# Check the 'stix-content.xml' document for STIX Best Practices conformance
results = sdv.validate_best_practices('stix-content.xml')

# Print the result!
print results.is_valid

If the is_valid property is False, users can inspect the errors property to retrieve specific validation errors, or iterate over the BestPracticeValidationResults class directly.

The errors property on BestPracticeValidationResults contains a list of BestPracticeWarningCollection instances, which hold details about the validation errors and methods for accessing those details.

BestPracticeWarnings and Collections

Every deviation from STIX Best Practices within an instance document is represented as an instance of BestPracticeWarning. These violations are categorized and collected within instances of BestPracticeWarningCollection instances, which are each assigned names, such as "Missing Titles", or "Duplicate IDs".

The errors property on BestPracticeValidationResults contains a list of BestPracticeWarningCollection instances, which hold details about the validation errors and methods for accessing those details.

import sdv

# Check the 'stix-content.xml' document for STIX Best Practices conformance
results = sdv.validate_best_practices('stix-content.xml')

# If 'stix-content.xml' is invalid, print each error
if not results.is_valid:
    for coll in results.errors:
        print_best_practice_collection(coll)  # User-defined print method

The example above iterates over the result.errors property, and calls a user-defined, print_best_practice_collection().

This function could be defined as the following:

def print_best_practice_collection(coll):
    """
    Prints BestPracticeWarningCollection info to stdout.
    """

    # Print the Best Practice Warning collection name
    print coll.name

    # Print the line and XML tag for each non-conformant node in the
    # warning collection.
    for warning in coll:
        print warning.line, warning.tag

Dictionaries and JSON

Users wanting to work with dictionaries or pass around JSON blobs can make use of the BestPracticeValidationResults.as_dict() and BestPracticeValidationResults.as_json() methods.

import sdv

# Check the 'stix-content.xml' document for STIX Best Practices conformance
results = sdv.validate_best_practices('stix-content.xml')

# Retrieve results as dictionary
result_dictionary = results.as_dict()  # returns {'result': True} if valid

# Retrieve results as JSON
result_json = results.as_json() # returns '{"result": true}' JSON if valid