repository·main·Indexed 20 days ago
https://github.com/mitre-attack/mitreattack-pythonA Python library of tools and utilities for working with MITRE ATT&CK data, primarily handling STIX 2.0 content. It includes the MitreAttackData library, tools for converting STIX data to Excel spreadsheets or Pandas DataFrames via the attackToExcel module, and utilities for managing ATT&CK collections. Additionally, it provides the navlayers core for programmatically creating and configuring MITRE ATT&CK Navigator layers, including management of techniques, gradients, legends, and layout settings.
The mitreattack.collections module provides tools for managing ATT&CK collections, which are sets of STIX objects grouped for convenience.
Available scripts:
index_to_markdown.py: Converts a collection index to Markdown.collection_to_index.py: Summarizes collections into an index file.stix_to_collection.py: Converts raw STIX bundles into bundles containing a collection object.The navlayers package provides modules and scripts for working with ATT&CK Navigator layers. These layers are annotations overlaid on the ATT&CK Matrix. The package supports the ATT&CK Navigator Layer file format version 4.3 and can automatically upgrade legacy version 3.0 and 4.X layers to version 4.3.
Key functional areas include:
layer, technique, metadata).layerops to combine multiple layers.to_excel) or SVG (to_svg) formats.overview_generator, usage_generator, sum_generator).layerExporter_cli.py) and generating (layerGenerator_cli.py) layers.The mitreattack-python library provides a collection of Python tools and utilities specifically designed for working with MITRE ATT&CK content.
The library is organized into several key areas:
navlayers: Navigation layer utilities.attackToExcel: Tools for exporting ATT&CK data to Excel formats.collections: Utilities for managing collections of ATT&CK objects.diffStix: Tools for performing diffs on STIX data.attackToExcel module provides utilities to convert MITRE ATT&CK STIX data into Excel spreadsheets. Additionally, it allows you to access the dataset as Pandas DataFrames, which is useful for performing data analysis on the ATT&CK framework.The navlayers module provides a collection of utilities for working with ATT&CK Navigator layers. It allows you to import, export, and manipulate layers programmatically.
Key capabilities include:
For detailed implementation details and specific API references, refer to the source documentation in the mitreattack/navlayers directory.
The collections module provides a set of utilities designed for working with ATT&CK Collections and Collection Indexes.
Key capabilities include:
For detailed implementation details and specific API references, refer to the mitreattack.collections package documentation.
The Layers Core subcomponent manages Layer objects. A Layer acts as the main handle and container for a _LayerObj instance. The _LayerObj is the raw layer object that contains several sub-objects representing the different components of an ATT&CK Navigator layer.
Note: This implementation assumes familiarity with the ATT&CK Navigator layer format.
demo (Layer instance) <------------------------------------------------> The container for a layer object
|---> demo.layer (_LayerObj instance)--------------------------------> The raw layer object itself
|---> demo.layer.version (Versions instance)-----------------> A versions object
|---> demo.layer.filters (Filter instance)-------------------> A filter object
|---> demo.layer.layout (Layout instance)--------------------> A layout object
|---> demo.layer.techniques (List of Technique instances)----> A collection of technique objects
|---> demo.layer.gradient (Gradient instance)----------------> A gradient object
|---> demo.layer.legendItems (List of LegendItem instances)----> A collection of legend item objects
|---> demo.layer.metadata (List of Metadata instances)-------> A collection of metadata objectsMitreAttackData library is the primary component of this package. It is designed to read and manipulate MITRE ATT&CK STIX 2.0 content. It allows you to query the dataset for specific objects and retrieve their related objects.The MitreAttackData methods use the StixObjectFactory to determine the return type of retrieved objects. Depending on the object type, the factory will either:
stix2 Custom Object (for ATT&CK-specific types like Tactics or Matrices).This allows you to interact with both standard and custom MITRE ATT&CK objects using a consistent API, accessing attributes directly from the returned object.
The LayerOps class allows you to automate the combination of multiple ATT&CK Navigator layers using user-defined lambda functions. This is useful for merging scores, comments, or metadata across different layers.
LayerOps instance by passing lambda functions for the fields you want to combine (e.g., score, comment, name, colors, metadata, desc)..process() method, passing in a list or a dictionary of Layer objects. The method applies your lambdas to the provided data to produce a new, combined Layer object.score, comment, enabled, colors, metadata, name, desc: Each accepts a lambda function that defines how to combine the values from the input layers.default_values (optional): A dictionary of default values to use if a technique is missing a field in the combined layers.x.process(data, default_values=None)
data: Must be a list of Layer objects or a dict of {key: Layer} pairs.default_values (optional): Overrides the default values provided during initialization for this specific operation.from mitreattack.navlayers.manipulators.layerops import LayerOps
from mitreattack.navlayers.core.layer import Layer
# Setup layers
demo = Layer()
demo.from_file("layer1.json")
demo2 = Layer()
demo2.from_file("layer2.json")
# Example 1: Average scores across a list of layers
lo = LayerOps(score=lambda x: sum(x) / len(x),
name=lambda x: x[1],
desc=lambda x: "This is a list example")
out_layer = lo.process([demo, demo2])
out_layer.to_file("averaged_layer.json")
# Example 2: Combine scores using a dictionary of layers
lo2 = LayerOps(score=lambda x: sum([x[y] for y in x]) / len([x[y] for y in x]),
colors=lambda x: x['b'],
desc=lambda x: "This is a dict example")
out_layer3 = lo2.process({'a': demo, 'b': demo2})The generated Excel files follow a specific structure:
citations sheet is provided to look up in-text citations.The MitreAttackData library provides methods to fetch specific ATT&CK objects using various identifiers such as STIX IDs, ATT&CK IDs, names, or aliases.
Common retrieval patterns include:
# Refer to the following example scripts for specific implementations:
# get_object_by_stix_id.py
# get_object_by_attack_id.py
# get_objects_by_name.py
# get_groups_by_alias.py
# get_software_by_alias.py
# get_campaigns_by_alias.py