# mitreattack-python turns the ATT&CK catalog into queryable Python objects

> mitreattack-python is a MITRE library for reading ATT&CK STIX 2.0 content in Python, with a MitreAttackData class for querying objects and their relationships, plus command line tools for diffing, exporting and converting the catalog. It is Apache-2.0 licensed, requires Python 3.11, and ships on PyPI.

**mitre-attack/mitreattack-python** — A python module for working with ATT&CK

- Repository: https://github.com/mitre-attack/mitreattack-python
- Website: https://mitreattack-python.readthedocs.io/
- Stars: 753 · Forks: 175
- Language: HTML
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/mitre-attack-mitreattack-python

## The catalog as an object graph, not a JSON file

mitreattack-python is described as a library of Python tools and utilities for working with ATT&CK data, and the main content of the package is the MitreAttackData class.

That class is used to read in and work with MITRE ATT&CK STIX 2.0 content, and it provides the ability to query the dataset for objects and their related objects. The distinction matters. The ATT&CK catalog is distributed as a STIX 2.0 bundle, which is a graph of SDOs and SROs with relationships between them, and a technique is not a record with fields but a node that relationships point at. Reading the JSON by hand means resolving those relationships yourself, and the library does that work for you.

The README places this in context by pointing at the rest of MITRE's work. The ATT&CK catalog itself is a curated knowledge base and model for cyber adversary behaviour, reflecting the various phases of an adversary's lifecycle and the platforms they are known to target, and the CTI repository holds the catalog expressed in STIX 2.0 JSON along with a USAGE document of examples for accessing and parsing the dataset in Python.

So the layering is: ATT&CK is the knowledge, STIX 2.0 is the format, the CTI repository is the data, and this library is the Python client for it.

## Installing is one pip command, but the dependency floor is real

The install is a single command:

```shell
pip install mitreattack-python
```

The manifest says more than the README does, and the manifest is the place to look before you install. The package requires Python 3.11 or later and below 4.0, with requires-python set to >=3.11,<4.0, and it is classified as operating system independent.

The dependency list is long but each entry has an obvious job. stix2>=3.0.1 is the STIX library itself, and requests is for fetching. The data analysis side is pandas>=2.1.1 and numpy>=1.26.1, with deepdiff>=6.6.0 for the diff tooling and openpyxl, xlsxwriter and Pillow for the Excel and image outputs. On the presentation side there is rich>=13.6.0, tabulate for tables, typer>=0.9.0 and click>=8.1.8 for command line interfaces, Markdown>=3.5 for generated documentation, and loguru for logging. drawsvg and colour handle diagram and terminal rendering, pooch and tqdm handle downloads and progress, and python-dateutil and typing-extensions round it out.

The stix2 pin is the one to check. STIX 2.0 parsing is done by a third party library, and if your project already depends on a different major version of stix2, that is a conflict you will hit at install time rather than later.

## Eight command line tools ship with the package

The manifest registers a set of console entry points, and they describe the scope of the package better than the README does.

```toml
[project.scripts]
attack-to-excel = 'mitreattack.attackToExcel.attackToExcel:main'
layerExporter_cli = 'mitreattack.navlayers.layerExporter_cli:main'
layerGenerator_cli = 'mitreattack.navlayers.layerGenerator_cli:main'
indexToMarkdown_cli = 'mitreattack.collections.index_to_markdown:main'
collectionToIndex_cli = 'mitreattack.collections.collection_to_index:main'
diff_stix = 'mitreattack.diffStix.changelog_helper:main'
attack-changelog = 'mitreattack.diffStix.attack_changelog:main'
download_attack_stix = 'mitreattack.download_stix:app'
```

Reading those tells you what the tool does beyond parsing. The layers pair exports and generates NAV layers, the collections pair converts an index to Markdown and a collection back to an index, the diff pair produces a changelog between STIX versions, and download_attack_stix fetches the catalog.

The changelog tooling is the part that earns its place in a security team workflow. ATT&CK changes continuously, new techniques appear and relationships are revised, and a detection written against an old version of the catalog needs to be checked against the new one. attack-changelog and diff_stix are how you find out what moved.

The package also has a mitreattack module directory, a navlayers submodule, a diffStix submodule and a collections submodule, which is the same division the entry points imply.

## The examples directory is the API documentation in practice

The examples directory lists dozens of scripts, and their names are a map of the questions a detection engineer actually asks of the catalog.

They come in three shapes. The get_all family enumerates the catalog by object type, with get_all_groups.py, get_all_software.py, get_all_campaigns.py, get_all_matrices.py, get_all_mitigations.py, get_all_assets.py and get_all_datacomponents.py. The _targeted_by_all_ and _using_all_ variants ask the inverse question, which groups use a given piece of software, which techniques use a given group, which campaigns are attributed to a group.

Then there are the analysis scripts, and they are the more interesting ones. attack-object-counter.py counts objects, get_all_assets_targeted_by_all_techniques.py maps assets to techniques, get_all_campaigns_attributing_to_all_groups.py and get_all_campaigns_using_all_techniques.py do the reverse mapping, and analytic_extractor.py is a general extraction helper.

And then there is the diff tooling in the examples: generate_multiple_attack_diffs.py and generate_excel_files.py, which is how you turn an ATT&CK version change into something a detection team can review in a spreadsheet.

The examples directory also has its own .env.example and a README, so the scripts are expected to be run rather than only read.

## uv, a justfile and pre-commit for the developers

The repository is set up around uv and a justfile rather than pip and tox, and that tells you what the contributor workflow looks like.

The justfile lists recipes for the whole loop. The default recipe lists all available commands. install runs uv sync with all extras and installs the pre-commit hooks, including a commit-msg hook. upgrade runs uv sync with --all-extras --upgrade.

```
test:
    uv run pytest

# Run the fast local test subset, excluding integration and slow tests
test-fast:
    uv run pytest -m "not integration and not slow"
```

There are parallel variants, test-fast-xdist and test-xdist, which take a workers argument and use the xdist plugin, plus coverage variants that add --cov=mitreattack.

The linting recipes separate the linter from the formatter. lint runs pre-commit on all files, ruff-check runs the ruff linter alone, and ruff-format-check and ruff-format run the ruff formatter. There are also two recipes for commit message checking with commitizen, one that asserts a conventional commit is accepted and one that asserts a non conventional one is rejected.

The pyproject dev extra lists check-wheel-contents, commitizen and pre-commit, and there is a uv.lock at the root, so the dependency versions are pinned for reproducible installs.

## What this library will not tell you

The scope is worth being clear about, because the name invites a wider reading than the library delivers.

This is a client for the ATT&CK knowledge base. It tells you what techniques exist, how they relate to groups, software, campaigns and mitigations, and how the catalog has changed between versions. It does not observe adversary activity, it does not score your defences, and it does not tell you whether an attack happened to you. ATT&CK itself is described in the README as useful for understanding security risk against known adversary behaviour, for planning security improvements, and for verifying defences work as expected, and the library is a way to get at that data from code rather than from the website.

The second limitation is versioning. The catalog is versioned and it changes, and the library's own tooling is built around that fact with the diff and changelog commands. That cuts both ways. It means you can diff two versions, and it also means code written against one version of the catalog can produce different results against another, so a detection pipeline needs to pin the version of the ATT&CK content it was built from.

The third is the STIX dependency. stix2>=3.0.1 is a third party parser with its own release cadence, and MITRE's library depends on it rather than implementing STIX parsing itself. That keeps the package small and correct as long as the two versions agree.

## Conclusion

mitreattack-python suits a detection engineer or threat intelligence analyst who needs to query the ATT&CK catalog programmatically, since the MitreAttackData class exposes the objects and the relationships between them instead of leaving you to walk a STIX bundle by hand. It is the wrong tool if you want a live feed of adversary activity, because the library reads the catalog rather than observing anything. Before adopting it, install it with pip install mitreattack-python, check that the stix2 version you already use does not conflict with the pinned stix2>=3.0.1, and read the diff tooling documentation, because the CLI entries for changelog and diff are the part most teams end up using first.

## FAQ

### How do I install mitreattack-python?

Install it with pip install mitreattack-python, or from source with uv sync --all-extras. The package requires Python 3.11 or later and below 4.0, and it depends on stix2>=3.0.1, which is worth checking against anything already in your own dependency set.

### What command line tools does mitreattack-python install?

Eight console scripts are registered, including attack-to-excel, layerExporter_cli, layerGenerator_cli, indexToMarkdown_cli, collectionToIndex_cli, diff_stix, attack-changelog and download_attack_stix. The diff and changelog entries are the ones for comparing two versions of the ATT&CK catalog.

### How do I run the mitreattack-python tests?

The justfile provides a test recipe running uv run pytest, a test-fast recipe that excludes integration and slow tests, parallel xdist variants that take a workers argument, and coverage variants that add --cov=mitreattack. Linting is separate, with a recipe for pre-commit across all files and dedicated ruff check and ruff format recipes.

## Sources

- [License: Apache-2.0](https://github.com/mitre-attack/mitreattack-python/blob/main/LICENSE)
- [mitre-attack/mitreattack-python on GitHub](https://github.com/mitre-attack/mitreattack-python)
- [Project website](https://mitreattack-python.readthedocs.io/)
- [README](https://github.com/mitre-attack/mitreattack-python/blob/main/README.md)
- [Releases](https://github.com/mitre-attack/mitreattack-python/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mitre-attack-mitreattack-python