stix2generator package

Subpackages

Submodules

stix2generator.exceptions module

exception stix2generator.exceptions.AutoRegistrationError(message, spec_name=None)[source]

Bases: Exception

Base class for errors with automatic creation and registration of Python classes as stix2 custom objects, which are derived from object generator specifications.

exception stix2generator.exceptions.AutoRegistrationInferenceError(message, spec_name=None)[source]

Bases: stix2generator.exceptions.AutoRegistrationError

For auto-registration to work, STIX object information must be inferred from an object generator specification. Instances of this class represent situations where the spec is such that inference can’t be performed (even if the spec itself is valid).

exception stix2generator.exceptions.CircularVariableDependenciesError(path)[source]

Bases: stix2generator.exceptions.LanguageError

Instances of this class represent circular dependencies among variables.

exception stix2generator.exceptions.CyclicSpecificationReferenceError(spec_name_cycle, spec_type=None, spec_name_stack=None)[source]

Bases: stix2generator.exceptions.ObjectGenerationError

Instances represent a reference cycle composed of specification names.

exception stix2generator.exceptions.EmptyListError[source]

Bases: stix2generator.exceptions.AutoRegistrationInferenceError

exception stix2generator.exceptions.GeneratableSTIXTypeNotFoundError(constraints, stix_version)[source]

Bases: stix2generator.exceptions.GenerationError

Instances of this class represent inability to find a generator spec registered with an object generator, which satisfies particular STIX-related criteria. For example, we might require any SDO or SCO type.

exception stix2generator.exceptions.GenerationError[source]

Bases: Exception

Base class for all object and graph generation (via the prototyping language) errors.

exception stix2generator.exceptions.HeterogenousListError(list_)[source]

Bases: stix2generator.exceptions.AutoRegistrationInferenceError

exception stix2generator.exceptions.IllegalSTIXObjectPropertyType(prop_type, spec_name=None)[source]

Bases: stix2generator.exceptions.AutoRegistrationInferenceError

An object generator property spec was for a JSON type which is unsupported for use as a stix2 property type.

exception stix2generator.exceptions.IllegalSTIXObjectSpecType(spec_type, spec_name=None)[source]

Bases: stix2generator.exceptions.AutoRegistrationInferenceError

Specifications for STIX objects must be of type “object”.

exception stix2generator.exceptions.InvalidPropertyGroupError(group_name, message, spec_type=None, spec_name_stack=None)[source]

Bases: stix2generator.exceptions.PresenceCoconstraintError

Instances represent an invalid property group, within a presence co-constraint definition.

exception stix2generator.exceptions.InvalidRefPropertyValueError(value)[source]

Bases: stix2generator.exceptions.PatternGenerationError

Instances represent an invalid value for a reference property. The value must be an ID from which we can extract an object type, which is used to continue an object path through the reference.

exception stix2generator.exceptions.LanguageError(message, parse_tree_meta=None)[source]

Bases: stix2generator.exceptions.GenerationError

Base class for exceptions thrown while processing the STIX prototyping language. Instances may have line/column attributes giving the location of the error, if known/applicable.

exception stix2generator.exceptions.ObjectGenerationError(message, spec_type=None, spec_name_stack=None)[source]

Bases: stix2generator.exceptions.GenerationError

Base class for object generation errors. Also used directly as a raised exception type, when there isn’t a more specific object generation error subclass that’s applicable. This is typically used for various types of problems with specifications.

This class is written (and used) in a different way, to make it easier to have good error messages. I think there is a relatively common problem in exception handling, that at the point where an exception object is created, not all contextual information is known. Python’s default behavior requires that a complete message be generated at the point the exception object is constructed. When you don’t have all the contextual information at that point, it’s just impossible to generate a good message. That makes it tempting to pass extra context junk into functions/methods which is only used to generate decent error messages. In simple cases, that may be fine, but in excess, it can clutter the API.

An approach to improving the situation is to allow an exception to have some extra info added as it propagates through stack frames where that info is known. I first came across this idea in Boost years ago, and I decided to try a similar design here. My idea is that exception handlers can specifically add specification type and name info, if known, as the exception propagates. Then I override how the message is formatted to incorporate this additional information.

exception stix2generator.exceptions.PatternGenerationError[source]

Bases: stix2generator.exceptions.GenerationError

Base class for errors related to random STIX pattern generation.

exception stix2generator.exceptions.PresenceCoconstraintError(message, spec_type=None, spec_name_stack=None)[source]

Bases: stix2generator.exceptions.ObjectGenerationError

Instances represent an invalid presence co-constraint.

exception stix2generator.exceptions.RedeclaredVariableError(var_name, parse_tree_meta=None)[source]

Bases: stix2generator.exceptions.VariableError

Instances of this class represent the declaration of a variable more than once.

exception stix2generator.exceptions.RegistryNotFoundError(stix_version)[source]

Bases: stix2generator.exceptions.GenerationError

Represents failure to find an object generator specification registry for the given STIX version.

exception stix2generator.exceptions.SemanticValueTypeMismatchError(semantic_name, actual_type, actual_value, spec_type, spec_name_stack=None)[source]

Bases: stix2generator.exceptions.ObjectGenerationError

Instances represent a mismatch between the type of value produced by a semantic implementation, and the declared type of a specification.

exception stix2generator.exceptions.SpecificationNotFoundError(spec_name, spec_type=None, spec_name_stack=None)[source]

Bases: stix2generator.exceptions.ObjectGenerationError

A specification referred to by name was not found in the registry.

exception stix2generator.exceptions.TypeMismatchError(expected_type, actual_type, spec_type=None, spec_name_stack=None)[source]

Bases: stix2generator.exceptions.ObjectGenerationError

Instances represent a spec type mismatch: a spec for a particular JSON type was required, but a spec for a different type was found instead.

exception stix2generator.exceptions.UndeclaredVariableError(var_name, parse_tree_meta=None)[source]

Bases: stix2generator.exceptions.VariableError

Instances of this class represent use of an undeclared variable.

exception stix2generator.exceptions.UndefinedPropertyError(prop_names, spec_type=None, spec_name_stack=None)[source]

Bases: stix2generator.exceptions.ObjectGenerationError

Instances represent a reference outside a co-constraint to a property which was not defined in an object specification. (Inside a co-constraint, a different co-constraint error type is used, to indicate a bad co-constraint.)

exception stix2generator.exceptions.UnhandledPropertyValueType(value)[source]

Bases: stix2generator.exceptions.PatternGenerationError

Instances represent an unhandled property value type from a stix2 object. The property value is used to create a constant in a STIX pattern, and we need to know what comparison expression operators are legal to use with it.

exception stix2generator.exceptions.UnrecognizedJSONTypeError(spec_type, spec_name_stack=None)[source]

Bases: stix2generator.exceptions.ObjectGenerationError

Represents an unrecognized spec type, e.g. in a spec’s “type” property.

exception stix2generator.exceptions.UnrecognizedSTIXTypeError(stix_type)[source]

Bases: stix2generator.exceptions.PatternGenerationError

Instances represent a STIX SCO type given as a comparison expression type constraint, which was unrecognized. A generator spec could not be found which generates objects of that type.

exception stix2generator.exceptions.UnsupportedObjectStructureError(object_type, path_elements)[source]

Bases: stix2generator.exceptions.PatternGenerationError

The AST for object paths can’t represent arbitrary path structure. E.g. it can’t represent a list of lists. Instances of this class represent a random path taken through a STIX object, where the path contains unsupported structure.

exception stix2generator.exceptions.ValueCoconstraintError(coconstraint, message, spec_type=None, spec_name_stack=None)[source]

Bases: stix2generator.exceptions.ObjectGenerationError

Instances represent an invalid value co-constraint.

exception stix2generator.exceptions.VariableError(message, var_name, parse_tree_meta=None)[source]

Bases: stix2generator.exceptions.LanguageError

Instances of this class represent errors regarding variable usage.

stix2generator.logging module

stix2generator.logging.config_logging(verbosity_count)[source]

Configure logging for commandline scripts. Library code should not configure logging.

Parameters

verbosity_count – The count of “-v”s on the commandline, or None

stix2generator.stixcustom module

stix2generator.stixcustom.stix2_auto_register_all_custom(specs, stix_version)[source]

Detect which of the given object generator specs are for “custom” objects, try to dynamically derive simple Python classes, and register them with the stix2 library as custom SDOs so that using those custom types with the prototyping language is possible.

Custom STIX object specs are detected as:

  • Spec name starts with a capital letter

  • Spec name is not in the builtin object generator spec registry for the given STIX version

Parameters

  • specs – A mapping from name -> object generator spec

  • stix_version – The STIX version to use: “2.0”, “2.1”, etc.

stix2generator.stixcustom.stix2_register_custom(spec, obj_type_name, stix_version)[source]

Dynamically derive a simple Python class for the given object generator spec, and register it as a custom SDO with the stix2 library under the given name.

Parameters

  • spec – An object generator spec for a STIX object, as a dict

  • obj_type_name – The desired STIX type name to register it as

  • stix_version – The STIX version to use: “2.0”, “2.1”, etc.

stix2generator.utils module

class stix2generator.utils.STIXTypeClass(value)[source]

Bases: enum.Enum

Represents different classes of STIX type.

SCO = 1
SDO = 0
SRO = 2
stix2generator.utils.find_references(obj)[source]

Find all ref prop names and their ID values from the given STIX object. This generator generates (ref_prop_name, ID) pairs for all reference properties. For _refs properties (which are list-valued), a separate pair is generated for each element of the list; these pairs will contain the same property name and a different list element.

Parameters

obj – A STIX object with a “type” property.

stix2generator.utils.find_references_assignable(obj)[source]

Find all ref prop names and their ID values from the given object in a way that allows modification of the reference (i.e. assignment of a new ID to the reference property). Generates 4-tuples

(parent, key, ID, reference property name)

where parent and key are such that the reference can be modified by assignment to the expression “parent[key]”. If the reference property is list-valued, parent will be the list and key will be an integer index; otherwise, parent will be a mapping and key will be a key from the mapping. ID is the value of parent[key] and is provided as a convenience so that callers can avoid doing an extra lookup to get it. The reference property name will be the same as key, if key is string-valued (a _ref property name). If parent is a list and key an integer, then the reference property name is the key which maps to that list (a _refs property name).

For list-valued _refs properties, a tuple is generated for each element of the list: key and ID will change, but parent and the reference property name will be the same.

Parameters

obj – A STIX object with a “type” property.

stix2generator.utils.is_object(obj_or_type, stix_version='2.1')[source]

Determine whether a type is the type of any STIX object. This includes all SDOs, SCOs, meta-objects, and bundle. If obj_or_type is an object, the object’s “type” property is checked.

Parameters

  • obj_or_type – A mapping with a “type” property, or a STIX type as a string

  • stix_version – A STIX version as a string

Returns

True if the (object) type is recognized as a STIX type with respect to the given STIX version; False if not

stix2generator.utils.is_sco(obj_or_type, stix_version='2.1')[source]

Determine whether the given object or type is an SCO.

Parameters

  • obj_or_type – A mapping with a “type” property, or a STIX type as a string

  • stix_version – A STIX version as a string

Returns

True if the object is an SCO or the type is an SCO type; False if not

stix2generator.utils.is_sdo(obj_or_type, stix_version='2.1')[source]

Determine whether the given object or type is an SDO.

Parameters

  • obj_or_type – A mapping with a “type” property, or a STIX type as a string

  • stix_version – A STIX version as a string

Returns

True if the object is an SDO or the type is an SDO type; False if not

stix2generator.utils.is_sro(obj_or_type, stix_version='2.1')[source]

Determine whether the given object or type is an SRO.

Parameters

  • obj_or_type – A mapping with a “type” property, or a STIX type as a string

  • stix_version – A STIX version as a string

Returns

True if the object is an SRO or the type is an SRO type; False if not

stix2generator.utils.is_stix_type(obj_or_type, *types, stix_version='2.1')[source]

Determine whether the given object or type satisfies the given constraints. ‘types’ must contain STIX types as strings, and/or the STIXTypeClass enum values. STIX types imply an exact match constraint; STIXTypeClass enum values imply a more general constraint, that the object or type be in that class of STIX type. These constraints are implicitly OR’d together.

Parameters

  • obj_or_type – A mapping with a “type” property, or a STIX type as a string

  • types – A sequence of STIX type strings or STIXTypeClass enum values

  • stix_version – A STIX version as a string

Returns

True if the object or type satisfies the constraints; False if not

stix2generator.utils.is_token(node, token_type=None)[source]

Determine whether the given parse tree node is a Token node, and optionally verify its type.

Parameters

  • node – The node to check

  • token_type – A token type, or None if it doesn’t matter

Returns

True if the node is a Token node of the proper type, False otherwise.

stix2generator.utils.is_tree(node, rule_name=None)[source]

Determine whether the given parse tree node is a Tree node, and optionally verify its type.

Parameters

  • node – The node to check

  • rule_name – A node type, or None if it doesn’t matter

Returns

True if the node is a Tree node of the proper type, False otherwise.

stix2generator.utils.make_bundle(stix_objs, stix_version)[source]

Creating a Bundle object of the given spec version, which contains the given STIX objects.

Parameters

  • stix_objs – The objects the bundle is to contain. Must be a value accepted by the Bundle constructor, e.g. a single or list of objects.

  • stix_version – A STIX version as a string

Returns

The Bundle object

stix2generator.utils.rand_iterable(it, len_it=None)[source]

Choose a uniformly random value from the given iterable. If len(it) is available, len_it may be None. Otherwise, len_it must be provided as the “length” of the given iterable (the number of values which will be produced).

random.choice() seems to require a sequence (needs indexed access), so it doesn’t work with things like sets.

Parameters

  • it – The iterable

  • len_it – The length of it, or None to obtain the length via len().

Returns

A random value from it

stix2generator.utils.random_generatable_stix_type(object_generator, *required_types, stix_version='2.1')[source]

Choose a STIX type at random which satisfies the given type constraints, and which the given object generator is able to generate. See is_stix_type() for more discussion on the type constraints.

Parameters

  • object_generator – An object generator

  • required_types – Type constraints, as a sequence of STIX type strings and/or STIXTypeClass enum values. If no types are given, it means no types are legal, so None will always be returned.

  • stix_version – A STIX version as a string

Returns

A STIX type if one could be found which satisfies the given constraints; None if one could not be found

stix2generator.utils.recurse_references(obj)[source]

Helper for find_references(). See that function for more information. Can also be used as a more generic reference finder, which requires no particular structure (e.g. a “type” property) and has no special casing for observed-data/objects.

Parameters

obj – An object. Can be any type, but values will only be produced from mappings.

stix2generator.utils.recurse_references_assignable(obj)[source]

Helper for find_references_assignable(). See that function for more information. Can also be used as a more generic reference finder, which requires no particular structure (e.g. a “type” property) and has no special casing for observed-data/objects.

Parameters

obj – An object. Can be any type, but values will only be produced from mappings.

Module contents

stix2generator.create_default_language_processor(object_generator_config=None, extra_specs=None, stix_version='2.1')[source]

Creates a language processor instance which uses the built-in object generator with the given settings.

Parameters

  • object_generator_config – Configuration information for the object generator, which will be used to generate any objects required by prototyping language this processor processes.

  • extra_specs – Any extra specifications which should be added to the built-in specs this generator will use, or None if there aren’t any. The extra specs are overlaid on the built-in specs, so built-in specs can be overridden this way. (dict)

  • stix_version – Which version of STIX to use.

Returns

A language processor instance

stix2generator.create_object_generator(object_generator_config=None, extra_specs=None, stix_version='2.1')[source]

Create an instance of the built-in object generator.

Parameters

  • object_generator_config – A Config object with generator settings, or None to use defaults.

  • extra_specs – Any extra specifications which should be added to the built-in specs this generator will use, or None if there aren’t any. The extra specs are overlaid on the built-in specs, so built-in specs can be overridden this way. (dict)

  • stix_version – The STIX version to use, as a string (“2.0”, “2.1”, etc).

Returns

The object generator

Raises

  • stix2generator.exceptions.RegistryNotFoundError – If there isn’t a built-in registry for the given STIX version

  • IOError – (python 2) If the registry JSON file couldn’t be opened or read

  • OSError – (python 3) If the registry JSON file couldn’t be opened or read (IOError is retained as an alias for backward compatibility).

stix2generator.create_stix_generator(object_generator_config=None, ref_graph_generator_config=None, stix_generator_config=None, extra_specs=None, stix_version='2.1')[source]