Developers

Setup

You need Python 3 and Python Poetry installed. Clone this repository, then run this command in the root directory to create a virtual environment and install dependencies. This is a one-time setup step.

poetry install

Now activate the virtual environment in order to have access to the command line tools. You'll need to do this each time you open a new terminal to work on the project.

poetry shell

Install MyPy type stubs:

mypy --install-types

Workflow

Download ATT&CK Data

ATT&CK Sync needs to read the ATT&CK data in STIX format. Download all of the STIX files using this command:

download_attack_stix --stix20 --all -d data/attack

This will store all of the data in the data/attack subdirectory of this project, which is ignored by Git.

Important If you want to download a new ATT&CK release, you must upgrade the mitreattack-python library first, e.g.:

$ poetry update mitreattack-python
Updating dependencies
Resolving dependencies... (1.8s)

Writing lock file

Package operations: 0 installs, 1 update, 0 removals

  • Updating mitreattack-python (2.0.7 -> 2.0.10)

Then re-execute the download_attack_stix command above. It will only download version that it hasn't downloaded previously.

Build Website

To build the entire ATT&CK Sync site, run:

build-attack-sync

To build a single changelog (useful for development and debugging), use the following command and provide the versions you want to compare. For example, to compare v10.1 with v12.1, run:

python -m attack_sync.changelog_builder v10.1 v12.1

In order to run subsections of the diff, you can specify which domains and object types to include in the output with the -d and -t flags respectively. Both flags can be accept multiple values (separated by spaces), and the default is to include all values.

python -m attack_sync.changelog_builder v10.1 v12.1 -d enterprise-attack -t techniques software

View Website

To view the website locally, run the following command in the project root:

python -m http.server

Now you can open your browser to http://localhost:8000/public to view the site.

Upgrading ATT&CK

To add a new version of ATT&CK, perform these steps:

1. Bring in the latest version of the ATT&CK library, which contains the release info: poetry add --group dev mitreattack-python@latest
2. Add the version to versions in site_builder.py.
3. For major releases, update the ATT&CK badge in the README.

Debugging Tips

Log Level

During development and debugging, export the variable LOGURU_LEVEL in your environment to change log the level, e.g. export LOGURU_LEVEL=DEBUG in order to get more detailed logging.