{"id":19866591,"url":"https://github.com/mitre-attack/attack-data-model","last_synced_at":"2026-02-17T22:03:07.162Z","repository":{"id":257890858,"uuid":"597192140","full_name":"mitre-attack/attack-data-model","owner":"mitre-attack","description":"ATT\u0026CK Data Model (ADM): A TypeScript library for structured interaction with MITRE ATT\u0026CK datasets. Uses Zod schemas, TypeScript types, and ES6 classes to provide a type-safe, object-oriented interface for STIX 2.1 formatted ATT\u0026CK data. Features parsing, validation, and serialization capabilities.","archived":false,"fork":false,"pushed_at":"2026-02-10T20:27:32.000Z","size":12767,"stargazers_count":65,"open_issues_count":12,"forks_count":17,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-02-10T22:52:30.694Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://mitre-attack.github.io/attack-data-model/","language":"MDX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mitre-attack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-03T20:44:58.000Z","updated_at":"2026-02-10T19:50:01.000Z","dependencies_parsed_at":"2024-10-21T17:25:28.551Z","dependency_job_id":"bec17ddd-df66-42c1-8728-bc9c23762d3b","html_url":"https://github.com/mitre-attack/attack-data-model","commit_stats":null,"previous_names":["mitre-attack/attack-data-model"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/mitre-attack/attack-data-model","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitre-attack%2Fattack-data-model","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitre-attack%2Fattack-data-model/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitre-attack%2Fattack-data-model/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitre-attack%2Fattack-data-model/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitre-attack","download_url":"https://codeload.github.com/mitre-attack/attack-data-model/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitre-attack%2Fattack-data-model/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29556632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T18:16:07.221Z","status":"ssl_error","status_checked_at":"2026-02-17T18:16:04.782Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T15:26:29.776Z","updated_at":"2026-02-17T22:03:07.157Z","avatar_url":"https://github.com/mitre-attack.png","language":"MDX","readme":"# MITRE ATT\u0026CK® Data Model\n\n**A TypeScript library for working with MITRE ATT\u0026CK data using STIX 2.1**\n\nThe ATT\u0026CK Data Model (ADM) provides a type-safe, object-oriented interface for working with MITRE ATT\u0026CK datasets.\nBuilt on STIX 2.1 compliance, it uses Zod schemas and TypeScript types to ensure data integrity while providing intuitive relationship navigation between ATT\u0026CK objects.\n\n**[CLICK HERE](https://mitre-attack.github.io/attack-data-model) \u003csup\u003e[1](#footnotes)\u003c/sup\u003e** to browse the ATT\u0026CK schemas in a user-friendly interface.\n\n## Key Features\n\n- **Type-Safe Data Parsing**: ADM validates STIX 2.1 bundles using Zod schemas, ensuring data model compliance and type safety.\n- **Easy Relationship Navigation**: Each object instance contains pointers to related objects, simplifying the process of navigating between techniques, tactics, and other ATT\u0026CK elements.\n- **Supports Multiple Data Sources**: Load ATT\u0026CK datasets from different sources, including GitHub, local files, URLs, and TAXII 2.1 servers (more data sources in development).\n- Parsing, validation, and serialization of ATT\u0026CK data\n- ES6 classes for object-oriented data manipulation\n\n## Supported Data Sources\n\n- **`attack`**: Load ATT\u0026CK data from the official MITRE ATT\u0026CK STIX 2.1 GitHub repository. This serves as the source of truth for MITRE ATT\u0026CK content.\n- **`file`**: Load ATT\u0026CK data from a local JSON file containing a STIX 2.1 bundle.\n- **`url`**: Load ATT\u0026CK data from a URL endpoint serving STIX 2.1 content.\n- **`taxii`**: (Coming soon) Load ATT\u0026CK data from a TAXII 2.1 server.\n\n## Installation\n\n### Quick Start (Latest Version)\n\nTo install the latest version of the ADM from npm:\n\n```bash\nnpm install @mitre-attack/attack-data-model\n```\n\n### Choosing the Right Version\n\nThe ADM library version you need depends on which version of the ATT\u0026CK dataset you're working with. The library follows its own versioning scheme (separate from ATT\u0026CK releases) to support ongoing development while maintaining compatibility with specific ATT\u0026CK data versions.\n\n#### Version Compatibility Guide\n\n| If you're working with...    | Install ADM version | Command                                              |\n| ---------------------------- | ------------------- | ---------------------------------------------------- |\n| ATT\u0026CK v18.x (upcoming)      | 5.x (upcoming)      | `npm install @mitre-attack/attack-data-model@^5.0.0` |\n| ATT\u0026CK v15.x to v17.x        | 4.x (latest)        | `npm install @mitre-attack/attack-data-model@^4.0.0` |\n| Older ATT\u0026CK versions (\u003cv15) | Not supported       | Consider upgrading your ATT\u0026CK data                  |\n\n#### How to Check Your ATT\u0026CK Version\n\nIf you're unsure which version of ATT\u0026CK data you have:\n\n1. **From a STIX bundle file**: Look for the `x_mitre_attack_spec_version` field in the collection object\n   ```json\n   {\n     \"type\": \"x-mitre-collection\",\n     \"id\": \"x-mitre-collection--1f5f1533-f617-4ca8-9ab4-6a02367fa019\",\n     \"name\": \"Enterprise ATT\u0026CK\",\n     \"x_mitre_attack_spec_version\": \"3.2.0\"\n   }\n   ```\n1. **Check the compatibility matrix**: Check which spec version your STIX bundle or object is supported by in the [Compatibility Guide](./COMPATIBILITY.md)\n\n### Installing Specific Versions\n\nTo install a specific version of the ADM:\n\n```bash\n# Install exact version\nnpm install @mitre-attack/attack-data-model@4.0.0\n\n# Install latest patch within major version\nnpm install @mitre-attack/attack-data-model@^4.0.0\n\n# Install latest minor/patch within major.minor version\nnpm install @mitre-attack/attack-data-model@~4.0.0\n```\n\n### Version Mismatch Warnings\n\nThe ADM will validate that your data matches the expected ATT\u0026CK Specification version. If there's a mismatch, you may encounter:\n\n- **Validation errors**: When the data structure doesn't match what the ADM expects\n- **Missing properties**: When using older data with a newer ADM version\n- **Unrecognized fields**: When using newer data with an older ADM version\n\n### Recommended Approach\n\nFor most users, we recommend:\n\n1. **Use the latest ADM version** (`npm install @mitre-attack/attack-data-model`)\n2. **Load current ATT\u0026CK data** directly from the official repository (the ADM can do this automatically)\n3. **Keep both updated** regularly to access new techniques, updates, and features\n\nExample of loading the latest ATT\u0026CK data:\n\n```javascript\nimport {\n  registerDataSource,\n  loadDataModel,\n  DataSourceRegistration,\n} from '@mitre-attack/attack-data-model';\n\nconst dataSource = new DataSourceRegistration({\n  source: 'attack',\n  domain: 'enterprise-attack',\n  version: '17.1',\n  parsingMode: 'strict',\n});\n\nconst dataSource = await registerDataSource(dataSource);\nconst attackEnterpriseLatest = loadDataModel(dataSource);\n```\n\nFor more details on version compatibility, see the [Compatibility Guide](https://mitre-attack.github.io/attack-data-model/docs/principles/attack-versioning).\n\n## ATT\u0026CK Specification\n\nThe ADM is built upon the [MITRE ATT\u0026CK® Specification](https://mitre-attack.github.io/attack-data-model/schemas/), which formally defines the structure, properties, and relationships of ATT\u0026CK objects. The ATT\u0026CK Specification serves as the authoritative source for how ATT\u0026CK data should be represented and interacted with.\n\nThe ADM provides a codified expression of the ATT\u0026CK Specification using Zod schemas and TypeScript types. By implementing the specification in code, the ADM ensures that all data parsed and manipulated through the library adheres to the defined standards of the ATT\u0026CK data model. This includes strict validation of object structures, types, and required properties, providing developers with confidence in the integrity and consistency of the data they work with.\n\nWhile the ATT\u0026CK Specification defines the data model itself, the ADM includes additional software engineering elements such as utility functions, classes, and methods to facilitate easier interaction with ATT\u0026CK data. As such, the ADM is subject to its own development lifecycle and versioning, independent of the ATT\u0026CK Specification.\n\nThe version of the ATT\u0026CK Specification that the ADM is based on is indicated in the [ATTACK_SPEC_VERSION](./ATTACK_SPEC_VERSION) file located in the repository. This file contains a single line specifying the semantic version of the ATT\u0026CK Specification that the current ADM release is pinned to.\n\nIt's important to note that the ADM's versioning may not directly align with the versioning of the ATT\u0026CK Specification. The ADM follows its own semantic versioning release cadence to accommodate ongoing software engineering changes, enhancements, and fixes that may occur more frequently than updates to the ATT\u0026CK Specification itself.\n\nBy maintaining separate versioning, the ADM can evolve as a software library while remaining aligned with the underlying ATT\u0026CK data model defined by the specification. This approach ensures that developers have access to the latest features and improvements in the ADM without being constrained by the update schedule of the ATT\u0026CK Specification.\n\n## Documentation\n\nFor detailed API documentation and usage examples, please refer to the [ATT\u0026CK Data Model TypeScript API Documentation](USAGE.md).\n\nFor additional context about the ATT\u0026CK specification, please refer to the [ATT\u0026CK Specification Guide](https://mitre-attack.github.io/attack-data-model/schemas/).\n\n## Basic Usage\n\n### Loading the ADM\n\nHere's an example script that demonstrates how to use the ADM library to load ATT\u0026CK data from the official MITRE ATT\u0026CK GitHub repository:\n\n```typescript\nimport {\n  registerDataSource,\n  loadDataModel,\n  DataSourceRegistration,\n} from '@mitre-attack/attack-data-model';\n\n(async () =\u003e {\n  // Instantiating a DataSourceRegistration object will validate that the data source is accessible and readable\n  const dataSource = new DataSourceRegistration({\n    source: 'attack', // Built-in index to retrieve ATT\u0026CK content from the official MITRE ATT\u0026CK STIX 2.1 GitHub repository\n    domain: 'enterprise-attack',\n    version: '15.1', // Omitting 'version' will default to the latest version available in the repository\n    parsingMode: 'relaxed', // 'strict' or 'relaxed' - 'relaxed' mode will attempt to parse and serialize data even if it contains errors or warnings\n  });\n\n  try {\n    // Register the data source and retrieve the unique ID\n    const uuid = await registerDataSource(dataSource);\n    if (uuid) {\n      // Load the dataset using the unique ID\n      const attackEnterpriseLatest = loadDataModel(uuid);\n\n      // Access ATT\u0026CK objects by type using object properties\n      const techniques = attackEnterpriseLatest.techniques;\n      const tactics = attackEnterpriseLatest.tactics;\n\n      const technique = techniques[0];\n\n      // Type hinting is supported for all object properties\n      if (technique.x_mitre_is_subtechnique) {\n        // Access related objects with helpful getter methods\n        console.log(technique.getParentTechnique());\n      }\n    }\n  } catch (error) {\n    console.error(error);\n  }\n})();\n```\n\n### Parsing and Validating a Tactic\n\n```typescript\nimport { tacticSchema } from '@mitre-attack/attack-data-model';\n\nconst validTactic = {\n  id: 'x-mitre-tactic--4ca45d45-df4d-4613-8980-bac22d278fa5',\n  type: 'x-mitre-tactic',\n  name: 'Execution',\n  description: 'The adversary is trying to run malicious code.',\n  x_mitre_shortname: 'execution',\n  // ... other required fields\n};\n\ntry {\n  const parsedTactic = tacticSchema.parse(validTactic);\n  console.log('Tactic parsed successfully:', parsedTactic.name);\n} catch (error) {\n  console.error('Validation error:', error);\n}\n```\n\n### Handling Invalid Data\n\n```typescript\nimport { tacticSchema } from '@mitre-attack/attack-data-model';\nimport { z } from 'zod';\n\nconst invalidTactic = {\n  // Missing required fields\n  id: 'x-mitre-tactic--4ca45d45-df4d-4613-8980-bac22d278fa5',\n  type: 'x-mitre-tactic',\n};\n\ntry {\n  tacticSchema.parse(invalidTactic);\n} catch (error) {\n  if (error instanceof z.ZodError) {\n    console.log('Validation errors:', error.errors);\n  }\n}\n```\n\nFor more detailed examples, please refer to the [examples](./examples/README.md) folder in the repository.\n\n## How It Works\n\n1. **Data Registration**: Datasets are registered via `registerDataSource`. You specify the source of the data (e.g., `attack`, `file`, `url`, `taxii`) and provide any necessary options (such as `domain` and `version` for ATT\u0026CK datasets). This function returns a unique identifier for the registered data source.\n2. **Data Loading**: The `loadDataModel` function is used to load registered data models by their unique identifier.\n3. **Parsing and Validation**: Once the data is loaded, it is parsed by Zod schemas, ensuring that the data conforms to the expected STIX 2.1 specification.\n4. **Serialization**: Valid objects are converted into TypeScript class instances, allowing for type-safe interaction and relationship navigation.\n5. **Relationship Mapping**: The library automatically processes all \"relationship\" objects in the dataset, creating links between techniques, tactics, groups, and other ATT\u0026CK objects.\n\n## Parsing Modes\n\n- **Strict Mode**: Data must pass all validation checks to be ingested. If any objects are rejected, the registration is aborted.\n- **Relaxed Mode**: Invalid objects are logged, but the library will ignore parsing errors and attempt to load the dataset anyway. Use with caution, as this may cause unexpected downstream usage errors.\n\n## Compatibility Matrix\n\nOur [Compatibility documentation](https://mitre-attack.github.io/attack-data-model/principles/versioning-philosophy) tracks the compatibility between versions of the ATT\u0026CK Data Model (ADM) TypeScript API (`@mitre-attack/attack-data-model`) and versions of the MITRE ATT\u0026CK dataset (`mitre-attack/attack-stix-data`).\n\n## Contributing\n\nWe welcome contributions! Please see our contributor guide for more information: \u003chttps://mitre-attack.github.io/attack-data-model/docs/contributing/\u003e\n\n## Footnotes\n\n\u003csup\u003e1\u003c/sup\u003e The [schemas site](https://mitre-attack.github.io/attack-data-model) is dynamically generated from the contents of the `@latest` distribution channel / `main` branch. We do not currently maintain separate documentation for previous releases, though we hope to in the future.\n\n## License\n\nThis project is licensed under the Apache 2.0 License.\n\n## Notice\n\nCopyright 2020-2025 The MITRE Corporation.\n\nThis project makes use of ATT\u0026CK\n\n[ATT\u0026CK Terms of Use](https://attack.mitre.org/resources/terms-of-use/)\n","funding_links":[],"categories":["MDX"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitre-attack%2Fattack-data-model","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitre-attack%2Fattack-data-model","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitre-attack%2Fattack-data-model/lists"}