Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
90 lines (64 loc) · 4.09 KB

CONTRIBUTING.md

File metadata and controls

90 lines (64 loc) · 4.09 KB

Contributors

Reporting Issues

If you encounter an issue with the mitreattack-python library, please let us know by filing a GitHub issue. When doing so, please make sure you provide the following information:

  • Describe (in as much detail as possible) what occurred and what you were expecting to occur. Any information you can provide, such as stack traces or errors, is very helpful.
  • Describe the steps necessary to replicate the issue.
  • Indicate your OS and Python versions.

Suggested New Features

If you have an idea for a new feature for mitreattack-python, please let us know by filing a GitHub issue. When doing so, please make sure you provide the following information:

  • Explain the functionality you are proposing, and its use case — what would it be useful for or allow you to do?
  • List what existing ATT&CK tools or resources map to the proposed functionality.
  • If applicable, provide examples of other requests for the proposed functionality.

Developing

We welcome pull requests! To set up a local development environment:

Prerequisites

  • Python 3.11+
  • uv — fast Python package manager
  • just — command runner (optional, but recommended)

Setup

# Clone the repository
git clone https://github.com/mitre-attack/mitreattack-python
cd mitreattack-python

# Install all dependencies (including dev and docs extras)
just install
# or without just:
uv sync --all-extras

# (Optional) Install pre-commit hooks for local linting and commit message validation
just setup-hooks
# or without just:
uv run pre-commit install
uv run pre-commit install --hook-type commit-msg

Common Commands

Run just with no arguments to see all available commands. Here are the most common ones:

just lint          # Run pre-commit hooks (ruff format) on all files
just test          # Run the full test suite, matching CI expectations
just test-fast     # Run the fast local subset, excluding integration and slow tests
just test-xdist    # Run tests in parallel
just test-cov      # Run tests with coverage report
just test-cov-xdist  # Run tests with coverage in parallel
just build         # Build the package

Use just test-fast while iterating locally on changes that do not need full STIX-backed export or other slow integration coverage. Tests or setup steps that normally take longer than 10 seconds should be marked slow, so they are skipped by just test-fast. Before opening a PR, run just test; GitHub Actions also runs the full suite with coverage.

Tests that need real ATT&CK STIX data should use the shared STIX fixtures instead of downloading or preparing bundles directly. Parallel test runs warm the shared STIX cache before workers start; if a new xdist-backed test needs an additional ATT&CK release, update the cache warmup list in tests/conftest.py.

To run STIX-backed tests against specific local bundles, pass the bundle paths to pytest:

uv run pytest \
  --stix-enterprise /path/to/enterprise-attack.json \
  --stix-mobile /path/to/mobile-attack.json \
  --stix-ics /path/to/ics-attack.json

To have pytest download a specific ATT&CK release instead, use:

uv run pytest --attack-version 16.1 --stix-version 2.1

Pull Requests

When making a pull request, please make sure to:

  • Include a summary of what the changes are intended to do and the testing performed to validate them (ideally in the form of new pytests in the tests/ collection, though this is not strictly required).
  • Use a Conventional Commits formatted PR title (e.g., feat: add new export format, fix: handle missing data sources). PRs are squash-merged, so the PR title becomes the merge commit message — individual commit messages within the PR do not need to follow any convention.
  • All pytest tests in tests/ must pass, and ruff linting/formatting checks must be clean.