diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..b4a659fc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,24 @@ +--- +name: Bug report +about: Create a report to help us improve +title: "[BUG]" +labels: bug +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**To Reproduce** +Steps to reproduce the behavior: +1. +2. +3. +4. + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..72b1f490 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for improving the ATT&CK Workbench Frontend +title: "[REQUEST]" +labels: enhancement +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..92a079d1 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,19 @@ +## Description of what has changed + +### All Submissions: + +* [ ] Have you followed the guidelines in our Contributing document? +* [ ] Have you checked to ensure there aren't other open [Pull Requests](https://github.com/mitre-attack/attack-data-model/pulls) for the same update/change? + + + +### New Feature Submissions: + +1. [ ] Does your submission pass tests? +2. [ ] Have you lint your code locally prior to submission? + +### Changes to Core Features: + +* [ ] Have you added an explanation of what your changes do and why you'd like us to include them? +* [ ] Have you written new tests for your core changes, as applicable? +* [ ] Have you successfully ran tests with your changes locally? diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..e9e77e6f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,5 @@ +# Contributing to MITRE ATT&CK® Data Model + +Thank you for your interest in contributing to the MITRE ATT&CK® Data Model! We welcome contributions from the community to help improve and expand this TypeScript library. + +Please see our contributor guide for more information: https://mitre-attack.github.io/attack-data-model/docs/contributing/ diff --git a/docs/COMPATIBILITY.md b/docs/COMPATIBILITY.md deleted file mode 100644 index d6d2a12f..00000000 --- a/docs/COMPATIBILITY.md +++ /dev/null @@ -1,71 +0,0 @@ -# Compatibility - -This document tracks the compatibility between versions of the ATT&CK® Data Model (ADM) TypeScript API (`@mitre-attack/attack-data-model`), the ATT&CK® Specification, and versions of the MITRE ATT&CK® dataset (`mitre-attack/attack-stix-data`). - -## Supported Versions Compatibility Matrix1 - -| ADM Version ([`@mitre-attack/attack-data-model`](npmjs.com/package/@mitre-attack/attack-data-model)) | ATT&CK Specification Version ([`ATTACK_SPEC_VERSION`](https://github.com/mitre-attack/attack-data-model/blob/main/ATTACK_SPEC_VERSION)) | STIX Version ([`spec_version`](https://oasis-open.github.io/cti-documentation/resources#stix-21-specification)) | Supported ATT&CK Releases ([`mitre-attack/attack-stix-data`](https://github.com/mitre-attack/attack-stix-data/)) | -|-------------------------------------------------|------------------------------------------------------|-------------------------------|-------------------------------------------------------------| -| 1.x, 2.x, 3.x | 3.2.0 | 2.1 | >=15.x, <=17.x | -| 4.x | 3.3.0 | 2.1 | >=15.x, <=18.x | -| 5.x (future release) | 4.0.0 | 2.1 | >=18.x | - -1Other versions of ATT&CK or the ATT&CK Specification may work with the specified ADM release, but are not officially supported. -## Compatibility Details - -- **ATT&CK Specification v3.3.0**: - - **New SDOs**: - - MITRE Detection Strategies (`x-mitre-detection-strategy`) [[schema](../src/schemas/sdo/detection-strategy.schema.ts)] - - MITRE Analytics (`x-mitre-analytic`) [[schema](../src/schemas/sdo/analytic.schema.ts)] - - **Schema Changes**: - - Added `x_mitre_log_sources` field to MITRE Data Components for tracking security telemetry across platforms - - **Deprecations**: - - MITRE Data Sources (`x-mitre-data-sources`) [[schema](../src/schemas/sdo/data-source.schema.ts)] (removal in v4.0.0) - - `x-mitre-data-component` --[detects]--> `attack-pattern` SROs (replaced by Detection Strategy framework) - - **Content Support**: - - ATT&CK Release v18.x and later - -## Using Other Versions - -While the ADM may function with other versions of the ATT&CK dataset or ATT&CK Specification, the following considerations apply: - -- **Older ATT&CK Releases**: May lack properties or objects that the ADM expects based on the latest ATT&CK Specification, potentially causing validation errors or missing data when parsing. -- **Newer ATT&CK Releases**: May introduce new objects or properties not recognized by the current ADM version, leading to incomplete data mapping or parsing failures. -- **Different ATT&CK Specification Versions**: Using a different specification version may result in discrepancies between the expected and actual data model, affecting validation and data integrity. - -## Recommendations - -- **Stay Updated**: Always use the ADM version that corresponds to the ATT&CK Specification and dataset version you are working with. -- **Check `ATTACK_SPEC_VERSION`**: Refer to the `ATTACK_SPEC_VERSION` file in the repository to identify the ATT&CK Specification version the ADM is pinned to. -- **Testing**: If you need to use unsupported versions, thoroughly test your application to ensure data integrity. -- **Feedback**: If you require support for additional ATT&CK versions or specifications, consider opening an issue or contributing to the project. - -## Future Compatibility Plans - -We plan to: - -- **Regular Updates**: Release new ADM versions shortly after new ATT&CK Specifications or ATT&CK dataset versions are published. -- **Backward Compatibility**: Where feasible, maintain backward compatibility with previous ATT&CK Specifications and releases. -- **Deprecation Notices**: Provide deprecation warnings in documentation and release notes when dropping support for older versions. - -## Contributing to Compatibility - -Community contributions are welcome to help expand compatibility: - -- **Issue Reporting**: Report any compatibility issues you encounter with specific ATT&CK versions or specifications. -- **Pull Requests**: Submit pull requests to add support for additional ATT&CK versions or to improve compatibility. - -## Contact and Support - -For questions or support regarding compatibility: - -- **GitHub Issues**: [Open an issue](https://github.com/mitre-attack/attack-data-model/issues) on the repository. -- **Email**: Contact the maintainers at [attack@mitre.org](mailto:attack@mitre.org). - ---- - -© 2020-2025 The MITRE Corporation. - -This project makes use of ATT&CK®. - -[ATT&CK Terms of Use](https://attack.mitre.org/resources/terms-of-use/) \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md deleted file mode 100644 index c1f69758..00000000 --- a/docs/CONTRIBUTING.md +++ /dev/null @@ -1,200 +0,0 @@ -# Contributing to MITRE ATT&CK® Data Model - -Thank you for your interest in contributing to the MITRE ATT&CK® Data Model! We welcome contributions from the community to help improve and expand this TypeScript library. - -## How to Contribute - -We don't have a formal process or Standard Operating Procedure (SOP) for accepting changes. However, there are several ways you can contribute: - -1. **Open Issues**: If you encounter bugs or have feature requests, please open an issue using the templates provided below. -2. **Submit Pull Requests**: Feel free to fork the repository, make changes, and submit a pull request. We will review your changes as necessary. - -## Issue Templates - -### Bug Report - -When reporting a bug, please use the following template: - -``` -## Expected Behavior - - -## Actual Behavior - - -## Steps to Reproduce the Problem - - 1. - 2. - 3. - -## Possible Solution - -``` - -### Feature Request - -For feature requests, please use this template: - -``` -### Is your feature request related to a problem? -Please provide a clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -### Describe the solution you'd like -A clear and concise description of what you want to happen. - -### Describe alternatives you've considered -A clear and concise description of any alternative solutions or features you've considered. - -### Additional context -Add any other context or screenshots about the feature request here. -``` - -## Pull Request Guidelines - -When submitting a pull request: - -1. Fork the repository and create your branch from `main`. -2. Ensure your code adheres to the existing style of the project to maintain consistency. -3. Include comments in your code where necessary. -4. Update the README.md with details of changes to the interface, if applicable. -5. Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/). -6. Include a description of your changes and why they're necessary. - -## Developer Setup - -### Requirements - -- [Node.js](https://nodejs.org/) v18.20 - -### Install dependences - -```bash -npm install -``` - -## Developer Workflow - -To maintain code quality and consistency, we use **ESLint**, **Prettier**, and **Husky** as part of the development workflow. These tools are installed and configured by the [Developer Setup](#developer-setup) steps above. Below is an overview of how each tool is configured and how it affects the contribution process: - -### ESLint and Prettier Configuration - -- **ESLint**: ESLint is used to enforce code quality rules and catch potential errors in JavaScript and TypeScript. It checks for both syntax issues and best practices. -- **Prettier**: Prettier is used for code formatting to ensure a consistent code style across the entire codebase. Prettier takes care of formatting such as indentation, quotes, and line length. - -We use **eslint-config-prettier** to disable any formatting rules in ESLint that might conflict with Prettier. This setup ensures that **ESLint** focuses on code quality while **Prettier** takes care of formatting. - -### How They Differ -- **ESLint**: Focuses on finding problematic patterns and enforcing best practices in the code. For example, it catches unused variables, enforces type safety in TypeScript, and flags potential bugs. -- **Prettier**: Focuses solely on formatting code (e.g., indentation, semicolons, line wrapping) without caring about the logic of the code. - -### Husky and Git Hooks - -- **Husky**: We use Husky to add Git hooks that automate certain tasks before commits and pushes. -- **Pre-Commit Hook**: Husky runs `npm run format` before every commit. This command runs both Prettier and ESLint in fix mode to ensure all code is properly formatted and adheres to linting rules before it is committed. -- **Pre-Push Hook**: Husky also runs `npm run test` before pushing to the repository. This ensures that all tests pass before the code is pushed, preventing broken code from entering the remote branches. -- **Commit-Msg Hook**: Husky also runs `npx --no-install commitlint --edit` before accepting a commit. This ensures that all commit messages adhere to the conventional commit format, thereby keeping semantic-release happy. - -These hooks help enforce code quality and consistency across all contributions, making it easier to maintain the project over time. - -## Versioning and Release Process - -We use semantic-release to manage all aspects of the release process. It automatically determines the next version number, creates git tags, generates release notes, and publishes the package to the GitHub Package Registry for npm artifacts. - -### Semantic Release Configuration - -We use the default semantic-release configuration, which includes the following plugins (in order of execution): - -1. "@semantic-release/commit-analyzer" -2. "@semantic-release/release-notes-generator" -3. "@semantic-release/npm" -4. "@semantic-release/github" - -These plugins are part of semantic-release and do not need to be installed separately. - -### Release Workflow and Distribution Channels - -Our release workflow follows semantic-release's default configuration, which uses different branches for different types of releases and distribution channels: - -- Main release channel (`@latest`): - - Branches: `master`, `main` - - This is the default channel for stable releases. - -- Next release channel (`@next`): - - Branches: `next`, `next-major` - - Used for upcoming feature releases or major version changes. - -- Maintenance release channels: - - Branch pattern: `+([0-9])?(.{+([0-9]),x}).x` - - Example: `2.x` or `2.1.x` - - Used for maintenance releases of older versions. - -- Pre-release channels: - - Branches: `beta` (`@beta` channel), `alpha` (`@alpha` channel) - - Used for pre-release versions. - -### How It Works - -1. **Commit Messages**: When you make changes, use [Conventional Commits](https://www.conventionalcommits.org/) syntax for your commit messages. This helps semantic-release determine the type of changes and the appropriate version increment. - - Examples: - - `feat: add new attack technique` (triggers a minor version bump) - - `fix: correct typo in technique description` (triggers a patch version bump) - - `feat!: rename primary data structure` (triggers a major version bump) - -2. **Husky**: We use Husky to enforce compliance with Conventional Commits syntax. It runs a commit message linter before each commit to ensure your messages follow the correct format. - -3. **Branching**: Choose the appropriate branch for your work: - - For regular features and fixes, work on `main`. - - For major changes or experimental features, use `next` or `next-major`. - - For bug fixes to older versions, use the appropriate maintenance branch (e.g., `2.x`). - - For pre-release features, use `beta` or `alpha`. - -4. **Pull Requests**: When your changes are ready, create a pull request to the appropriate branch. - -5. **Merging**: Once approved and merged, semantic-release takes over: - - It analyzes the commit messages since the last release. - - Determines the new version number based on the changes. - - Creates a new git tag for the release. - - Generates release notes. - - Publishes the package to npm with the appropriate dist-tag. - -### Examples - -1. Regular feature addition: - - Work on `main` branch - - Commit with message: `feat: add MITRE ATT&CK v10 techniques` - - After merge, semantic-release might create version `1.1.0` on the `@latest` channel - -2. Critical bug fix: - - Work on `main` branch - - Commit with message: `fix: resolve data corruption in technique lookup` - - After merge, semantic-release might create version `1.1.1` on the `@latest` channel - -3. Major breaking change: - - Work on `next-major` branch - - Commit with message: `feat!: restructure data model for performance improvements` - - After merge, semantic-release might create version `2.0.0-next.1` on the `@next` channel - -4. Maintenance fix for older version: - - Work on `1.x` branch - - Commit with message: `fix: address compatibility issue with Node.js 14` - - After merge, semantic-release might create version `1.2.1` on a `@release-1.x` channel - -### Version Management - -The `version` property in `package.json` is not actively tracked. To make it clear to contributors that the version is not kept up to date, we use the value `0.0.0-semantically-released`. For more information on this approach, please refer to the semantic-release [FAQ](https://github.com/semantic-release/semantic-release/blob/master/docs/support/FAQ.md#making-commits-during-the-release-process-adds-significant-complexity). - -### Further Reading - -For more detailed information on specific release scenarios, please refer to the following example workflows maintained by semantic-release: - -- [Publishing on distribution channels](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/release-workflow/distribution-channels.md) -- [Publishing maintenance releases](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/release-workflow/maintenance-releases.md) -- [Publishing pre-releases](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/release-workflow/pre-releases.md) - -## Questions? - -If you have any questions about contributing, please open an issue and we'll be happy to help! - -Thank you for your contributions to make the MITRE ATT&CK® Data Model better for everyone! \ No newline at end of file diff --git a/docusaurus/docs/contributing/dev-setup.mdx b/docusaurus/docs/contributing/dev-setup.mdx index 0b035eb0..803ff9a4 100644 --- a/docusaurus/docs/contributing/dev-setup.mdx +++ b/docusaurus/docs/contributing/dev-setup.mdx @@ -2,6 +2,10 @@ Follow these steps to get the ADM codebase running on your local machine. +## Requirements + +- [Node.js](https://nodejs.org/) v18.20 + ## Clone and install ```bash diff --git a/docusaurus/docs/contributing/index.mdx b/docusaurus/docs/contributing/index.mdx index 32f3b110..d988b057 100644 --- a/docusaurus/docs/contributing/index.mdx +++ b/docusaurus/docs/contributing/index.mdx @@ -2,13 +2,149 @@ import DocCardList from '@theme/DocCardList'; # Contributing -**Step-by-step technical instructions for contributors** - This section explains how to contribute to the ATT&CK Data Model repository. -It complements the high-level `CONTRIBUTING.md` in the root of the repository by focusing on specific developer tasks. +This includes the general contribution guidelines in addition to step-by-step technical instructions for specific developer tasks. ## Topics +## How to Contribute + +We don't have a formal process or Standard Operating Procedure (SOP) for accepting changes. However, there are several ways you can contribute: + +1. **Open Issues**: If you encounter bugs or have feature requests, please open an issue using the templates provided below. +2. **Submit Pull Requests**: Feel free to fork the repository, make changes, and submit a pull request. We will review your changes as necessary. + +## Pull Request Guidelines + +When submitting a pull request: + +1. Fork the repository and create your branch from `main`. +2. Ensure your code adheres to the existing style of the project to maintain consistency. +3. Include comments in your code where necessary. +4. Update the README.md with details of changes to the interface, if applicable. +5. Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/). +6. Include a description of your changes and why they're necessary. + +## Developer Workflow + +To maintain code quality and consistency, we use **ESLint**, **Prettier**, and **Husky** as part of the development workflow. Below is an overview of how each tool is configured and how it affects the contribution process: + +### ESLint and Prettier Configuration + +- **ESLint**: ESLint is used to enforce code quality rules and catch potential errors in JavaScript and TypeScript. It checks for both syntax issues and best practices. +- **Prettier**: Prettier is used for code formatting to ensure a consistent code style across the entire codebase. Prettier takes care of formatting such as indentation, quotes, and line length. + +We use **eslint-config-prettier** to disable any formatting rules in ESLint that might conflict with Prettier. This setup ensures that **ESLint** focuses on code quality while **Prettier** takes care of formatting. + +### How They Differ +- **ESLint**: Focuses on finding problematic patterns and enforcing best practices in the code. For example, it catches unused variables, enforces type safety in TypeScript, and flags potential bugs. +- **Prettier**: Focuses solely on formatting code (e.g., indentation, semicolons, line wrapping) without caring about the logic of the code. + +### Husky and Git Hooks + +- **Husky**: We use Husky to add Git hooks that automate certain tasks before commits and pushes. +- **Pre-Commit Hook**: Husky runs `npm run format` before every commit. This command runs both Prettier and ESLint in fix mode to ensure all code is properly formatted and adheres to linting rules before it is committed. +- **Pre-Push Hook**: Husky also runs `npm run test` before pushing to the repository. This ensures that all tests pass before the code is pushed, preventing broken code from entering the remote branches. +- **Commit-Msg Hook**: Husky also runs `npx --no-install commitlint --edit` before accepting a commit. This ensures that all commit messages adhere to the conventional commit format, thereby keeping semantic-release happy. + +These hooks help enforce code quality and consistency across all contributions, making it easier to maintain the project over time. + +## Versioning and Release Process + +We use semantic-release to manage all aspects of the release process. It automatically determines the next version number, creates git tags, generates release notes, and publishes the package to the GitHub Package Registry for npm artifacts. + +### Semantic Release Configuration + +We use the default semantic-release configuration, which includes the following plugins (in order of execution): + +1. "@semantic-release/commit-analyzer" +2. "@semantic-release/release-notes-generator" +3. "@semantic-release/npm" +4. "@semantic-release/github" + +These plugins are part of semantic-release and do not need to be installed separately. + +### Release Workflow and Distribution Channels + +Our release workflow follows semantic-release's default configuration, which uses different branches for different types of releases and distribution channels: + +- Main release channel (`@latest`): + - Branches: `master`, `main` + - This is the default channel for stable releases. + +- Next release channel (`@next`): + - Branches: `next`, `next-major` + - Used for upcoming feature releases or major version changes. + +- Maintenance release channels: + - Branch pattern: `+([0-9])?(.{+([0-9]),x}).x` + - Example: `2.x` or `2.1.x` + - Used for maintenance releases of older versions. + +- Pre-release channels: + - Branches: `beta` (`@beta` channel), `alpha` (`@alpha` channel) + - Used for pre-release versions. + +### How It Works + +1. **Commit Messages**: When you make changes, use [Conventional Commits](https://www.conventionalcommits.org/) syntax for your commit messages. This helps semantic-release determine the type of changes and the appropriate version increment. + + Examples: + - `feat: add new attack technique` (triggers a minor version bump) + - `fix: correct typo in technique description` (triggers a patch version bump) + - `feat!: rename primary data structure` (triggers a major version bump) + +2. **Husky**: We use Husky to enforce compliance with Conventional Commits syntax. It runs a commit message linter before each commit to ensure your messages follow the correct format. + +3. **Branching**: Choose the appropriate branch for your work: + - For regular features and fixes, work on `main`. + - For major changes or experimental features, use `next` or `next-major`. + - For bug fixes to older versions, use the appropriate maintenance branch (e.g., `2.x`). + - For pre-release features, use `beta` or `alpha`. + +4. **Pull Requests**: When your changes are ready, create a pull request to the appropriate branch. + +5. **Merging**: Once approved and merged, semantic-release takes over: + - It analyzes the commit messages since the last release. + - Determines the new version number based on the changes. + - Creates a new git tag for the release. + - Generates release notes. + - Publishes the package to npm with the appropriate dist-tag. + +### Examples + +1. Regular feature addition: + - Work on `main` branch + - Commit with message: `feat: add MITRE ATT&CK v10 techniques` + - After merge, semantic-release might create version `1.1.0` on the `@latest` channel + +2. Critical bug fix: + - Work on `main` branch + - Commit with message: `fix: resolve data corruption in technique lookup` + - After merge, semantic-release might create version `1.1.1` on the `@latest` channel + +3. Major breaking change: + - Work on `next-major` branch + - Commit with message: `feat!: restructure data model for performance improvements` + - After merge, semantic-release might create version `2.0.0-next.1` on the `@next` channel + +4. Maintenance fix for older version: + - Work on `1.x` branch + - Commit with message: `fix: address compatibility issue with Node.js 14` + - After merge, semantic-release might create version `1.2.1` on a `@release-1.x` channel + +### Version Management + +The `version` property in `package.json` is not actively tracked. To make it clear to contributors that the version is not kept up to date, we use the value `0.0.0-semantically-released`. For more information on this approach, please refer to the semantic-release [FAQ](https://github.com/semantic-release/semantic-release/blob/master/docs/support/FAQ.md#making-commits-during-the-release-process-adds-significant-complexity). + +### Further Reading + +For more detailed information on specific release scenarios, please refer to the following example workflows maintained by semantic-release: + +- [Publishing on distribution channels](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/release-workflow/distribution-channels.md) +- [Publishing maintenance releases](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/release-workflow/maintenance-releases.md) +- [Publishing pre-releases](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/release-workflow/pre-releases.md) + --- diff --git a/docusaurus/docs/principles/compatibility.mdx b/docusaurus/docs/principles/compatibility.mdx index eea1f735..04770372 100644 --- a/docusaurus/docs/principles/compatibility.mdx +++ b/docusaurus/docs/principles/compatibility.mdx @@ -4,238 +4,61 @@ import WorkInProgressNotice from '@site/src/components/WorkInProgressNotice'; -**Understanding version relationships and compatibility across the ATT&CK ecosystem** +This page tracks the compatibility between versions of the ATT&CK® Data Model (ADM) TypeScript API (`@mitre-attack/attack-data-model`), the ATT&CK® Specification, and versions of the MITRE ATT&CK® dataset (`mitre-attack/attack-stix-data`). -The ATT&CK Data Model operates within a complex ecosystem of interconnected version dependencies. Understanding these relationships helps you make informed decisions about version selection, upgrade timing, and compatibility management for your applications. +## Supported Versions Compatibility Matrix1 -## The Compatibility Challenge +| ADM Version ([`@mitre-attack/attack-data-model`](npmjs.com/package/@mitre-attack/attack-data-model)) | ATT&CK Specification Version ([`ATTACK_SPEC_VERSION`](https://github.com/mitre-attack/attack-data-model/blob/main/ATTACK_SPEC_VERSION)) | STIX Version ([`spec_version`](https://oasis-open.github.io/cti-documentation/resources#stix-21-specification)) | Supported ATT&CK Releases ([`mitre-attack/attack-stix-data`](https://github.com/mitre-attack/attack-stix-data/)) | +|-------------------------------------------------|------------------------------------------------------|-------------------------------|-------------------------------------------------------------| +| `1.x`, `2.x`, `3.x` | `3.2.0` | `2.1` | `>=15.x`, `<=17.x` | +| `4.x` | `3.3.0` | `2.1` | `>=15.x`, `<=18.x` | +| `5.x` (Future Release) | `4.0.0` | `2.1` | `>=18.x` | -ATT&CK's ecosystem involves multiple independent components that evolve at different rates: +1Other versions of ATT&CK or the ATT&CK Specification may work with the specified ADM release, but are not officially supported. +## Compatibility Details -- **ATT&CK Data Model Library** (`@mitre-attack/attack-data-model`) - This TypeScript library -- **ATT&CK Specification** - Defines object schemas and validation rules -- **STIX Specification** - Core STIX standard that ATT&CK extends -- **ATT&CK Dataset Releases** - The actual threat intelligence data from MITRE +- **ATT&CK Specification v3.3.0**: + - **New SDOs**: + - MITRE Detection Strategies (`x-mitre-detection-strategy`) [[schema](../src/schemas/sdo/detection-strategy.schema.ts)] + - MITRE Analytics (`x-mitre-analytic`) [[schema](../src/schemas/sdo/analytic.schema.ts)] + - **Schema Changes**: + - Added `x_mitre_log_sources` field to MITRE Data Components for tracking security telemetry across platforms + - **Deprecations**: + - MITRE Data Sources (`x-mitre-data-sources`) [[schema](../src/schemas/sdo/data-source.schema.ts)] (removal in v4.0.0) + - `x-mitre-data-component` --[detects]--> `attack-pattern` SROs (replaced by Detection Strategy framework) + - **Content Support**: + - ATT&CK Release v18.x and later -Each component has its own versioning scheme and release cycle, creating a compatibility matrix that must be carefully managed. +## Using Other Versions -## Supported Versions Compatibility Matrix +While the ADM may function with other versions of the ATT&CK dataset or ATT&CK Specification, the following considerations apply: -| ADM Version | ATT&CK Specification | STIX Version | Supported ATT&CK Releases | -|-------------|---------------------|--------------|---------------------------| -| 1.x, 2.x, 3.x | 3.2.0 | 2.1 | ≥15.x, ≤17.x | -| 4.x | 3.3.0 | 2.1 | ≥15.x, ≤18.x | -| 5.x *(future)* | 4.0.0 | 2.1 | ≥18.x | +- **Older ATT&CK Releases**: May lack properties or objects that the ADM expects based on the latest ATT&CK Specification, potentially causing validation errors or missing data when parsing. +- **Newer ATT&CK Releases**: May introduce new objects or properties not recognized by the current ADM version, leading to incomplete data mapping or parsing failures. +- **Different ATT&CK Specification Versions**: Using a different specification version may result in discrepancies between the expected and actual data model, affecting validation and data integrity. -*Note: Other versions may work but are not officially supported or tested.* +## Recommendations -## Understanding Version Dependencies +- **Stay Updated**: Always use the ADM version that corresponds to the ATT&CK Specification and dataset version you are working with. +- **Check `ATTACK_SPEC_VERSION`**: Refer to the `ATTACK_SPEC_VERSION` file in the repository to identify the ATT&CK Specification version the ADM is pinned to. +- **Testing**: If you need to use unsupported versions, thoroughly test your application to ensure data integrity. +- **Feedback**: If you require support for additional ATT&CK versions or specifications, consider opening an issue or contributing to the project. -### ATT&CK Specification Evolution +## Future Compatibility Plans -**Version 3.3.0 introduced significant changes:** +We plan to: -- **New Object Types**: Detection Strategies, Analytics, and Log Sources -- **Deprecations**: Legacy Data Source detection relationships -- **Enhanced Features**: Campaign temporal tracking and asset relationship modeling +- **Regular Updates**: Release new ADM versions shortly after new ATT&CK Specifications or ATT&CK dataset versions are published. +- **Backward Compatibility**: Where feasible, maintain backward compatibility with previous ATT&CK Specifications and releases. +- **Deprecation Notices**: Provide deprecation warnings in documentation and release notes when dropping support for older versions. -**Version 4.0.0 (planned)** will include breaking changes: -- Removal of deprecated data source `detects` relationships -- Potential schema changes affecting validation logic - -### Compatibility Implications - -#### Using Older ATT&CK Releases - -- May lack properties or objects expected by newer ADM versions -- Can cause validation errors or incomplete data mapping -- Generally safe for read-only analytical workflows - -#### Using Newer ATT&CK Releases - -- May introduce objects or properties not recognized by older ADM versions -- Risk of parsing failures or missing data -- Requires ADM updates for full feature support - -#### Specification Mismatches - -- Different specification versions may have incompatible validation rules -- Object schemas may differ, affecting data integrity -- Relationship types and constraints may change - -## Practical Compatibility Strategies - -### Development Environment Management - -```typescript -// Check compatibility at runtime -function validateCompatibility(attackDataModel: AttackDataModel) { - const specVersion = attackDataModel.getSpecificationVersion(); - const supportedVersions = ['3.2.0', '3.3.0']; - - if (!supportedVersions.includes(specVersion)) { - console.warn(`Specification version ${specVersion} may not be fully supported`); - } -} -``` - -### Version Pinning for Stability - -```typescript -// Pin specific versions for predictable behavior -const dataSource = new DataSource({ - source: 'attack', - domain: 'enterprise-attack', - version: '15.1', // Pin to tested version - parsingMode: 'strict' -}); -``` - -### Graceful Degradation - -```typescript -// Handle version differences gracefully -function getDetectionData(technique: Technique) { - // Try modern detection strategy approach (3.3.0+) - if (technique.getDetectionStrategies) { - const strategies = technique.getDetectionStrategies(); - if (strategies.length > 0) { - return strategies; - } - } - - // Fall back to legacy data component approach - if (technique.getDetectedBy) { - return technique.getDetectedBy(); - } - - // Final fallback to detection text - return [{ description: technique.x_mitre_detection || 'No detection information available' }]; -} -``` - -## Version Migration Planning - -### Planning Specification Upgrades - -1. **Assessment Phase** - - Review changelog for breaking changes - - Identify affected code paths in your application - - Plan testing strategy for new features - -2. **Testing Phase** - - Test with representative data samples - - Validate existing functionality continues working - - Verify new features work as expected - -3. **Rollout Phase** - - Implement gradual rollout with monitoring - - Maintain rollback capability - - Update documentation and training materials - -### Handling Breaking Changes - -Breaking changes typically involve: - -- **Object Schema Changes**: New required fields or validation rules -- **Relationship Changes**: Modified relationship types or constraints -- **Deprecated Features**: Removal of legacy object types or properties - -**Migration Strategy**: - -```typescript -class VersionAwareProcessor { - processObjects(objects: AttackObject[]) { - return objects.map(obj => { - switch (this.getSpecVersion(obj)) { - case '3.2.0': - return this.processLegacyObject(obj); - case '3.3.0': - return this.processCurrentObject(obj); - default: - return this.processWithFallback(obj); - } - }); - } -} -``` - -## Compatibility Best Practices - -### For Application Developers - -1. **Version Awareness**: Always check specification versions before using new features -2. **Feature Detection**: Use capability detection over version checking when possible -3. **Flexible Parsing**: Use `relaxed` mode in production to handle data variations -4. **Comprehensive Testing**: Test with multiple ATT&CK dataset versions -5. **Documentation**: Document version requirements clearly for users - -### For Data Consumers - -1. **Stay Current**: Regularly update to supported ADM versions -2. **Monitor Changes**: Subscribe to release notes for breaking change notifications -3. **Test Early**: Test with pre-release versions when available -4. **Validate Data**: Implement data quality checks for version compatibility -5. **Plan Migrations**: Schedule regular upgrade cycles aligned with ATT&CK releases - -### For Integration Teams - -1. **Environment Isolation**: Use different versions in development vs production -2. **Automated Testing**: Include compatibility tests in CI/CD pipelines -3. **Monitoring**: Track compatibility issues in production deployments -4. **Rollback Plans**: Maintain ability to downgrade if issues arise -5. **Team Communication**: Share compatibility requirements across teams - -## Common Compatibility Issues - -### Schema Validation Failures - -**Problem**: Objects fail validation with newer specification versions - -**Solution**: - -- Update to compatible ADM version -- Use `relaxed` parsing mode temporarily -- Review and update custom validation logic - -### Missing Object Properties - -**Problem**: Expected properties don't exist in older datasets - -**Solution**: - -```typescript -// Defensive property access -const detectsBy = technique.x_mitre_data_sources || - technique.getDataComponents?.() || - []; -``` - -### Deprecated Feature Usage - -**Problem**: Application uses deprecated object types or relationships - -**Solution**: - -- Migrate to replacement features -- Implement feature detection -- Plan phased migration strategy - -## Future Compatibility Planning - -### Anticipated Changes +--- -- **STIX 2.2 Adoption**: May require major ADM version update -- **ATT&CK Specification 4.0**: Will remove legacy detection relationships -- **New Object Types**: Regular introduction of new ATT&CK object types -- **Performance Improvements**: Schema optimizations may affect validation +© 2020-2025 The MITRE Corporation. -### Staying Prepared +This project makes use of ATT&CK®. -1. **Follow Development**: Monitor ADM and ATT&CK development channels -2. **Participate in Community**: Engage with other users facing similar challenges -3. **Contribute Back**: Share compatibility issues and solutions with the community -4. **Plan Resources**: Budget time and resources for regular compatibility updates +[ATT&CK Terms of Use](https://attack.mitre.org/resources/terms-of-use/) --- diff --git a/docusaurus/src/css/custom.css b/docusaurus/src/css/custom.css index 8fc91ec4..c5fdbf96 100644 --- a/docusaurus/src/css/custom.css +++ b/docusaurus/src/css/custom.css @@ -147,7 +147,7 @@ table { th { font-weight: 600; - text-transform: uppercase; + /* text-transform: uppercase; */ font-size: 0.75rem; letter-spacing: 0.05em; }