ESProfiler Handbook
Models

Framework Description Model (FDM)

The Framework Description Model (FDM) is a simple, universal JSON/YAML data structure for describing taxonomic frameworks such as MITRE ATT&CK, NIST CSF, and others in a machine-readable, query-efficient format.

Frameworks are classified by their primary purpose

TypeDescription
BEHAVIORDescribes adversary tactics, techniques, and behavior
DEFENSIVEOutlines countermeasures, hardening strategies, and defense-in-depth
COMPLIANCECaptures regulatory controls and obligations
ASSESSMENTUsed in security assessments, threat modeling, and red/purple team testing
TAXONOMYDefines abstract categories or logical groupings

🌐 Global Conventions

The Framework Description Model (FDM) follows strict structural and formatting rules to ensure consistency across different frameworks and tools.

🧱 Structure & Hierarchy

  • All frameworks are modeled as a strict tree. The root represents a globally unique framework namespace (e.g., MITRE-ATTCK).
  • Each item in the tree is a Node, and nodes are referenced using structured paths.
  • Frameworks must have:
    • Minimum depth: 1 (top-level nodes are at depth 1; nodes is optional, so an empty framework also validates)
    • Maximum depth: 10 (enforced by the @MaxFrameworkDepth validation, default 10)

📁 Path Conventions

Path TypeFormat ExampleDescription
Local Path/TA0001/T1566/001Path inside a single framework (version and root inferred)
Absolute PathMITRE-ATTCK~V17.1/TA0001/T1566/001Fully-qualified path including root and version
Absolute Agnostic PathMITRE-ATTCK~/TA0001/T1566/001Absolute path that always resolves to the latest version of a node (resolved by api-mfs, not by NodePath; see below)
Version FormatV1, V1.0.2, V1.0.2-betaIn an absolute path: V followed by up to three dot-separated numbers and an optional -suffix
  • Paths must use / as the only separator — no trailing slashes.
  • Path segments must match: ^[A-Z0-9-]{2,30}$
  • Absolute paths require a version with a V prefix (for example V17.1). A framework version such as 2024.07 is still valid on the framework itself. The patterns are in the validation rules.

🔁 When to Use Version-Agnostic Paths (~)

Version-agnostic absolute paths (e.g. MITRE-ATTCK~/TA0001/T1566/001) are designed for scenarios where the most current structure of a node is desired, regardless of framework version.

Use CaseUse Version-Agnostic Path
Threat modeling✅
Capability mapping✅
Persistent relationships✅
Static reports or audits❌ Use version-specific
Version-pinned exports❌ Use version-specific

NodePath does not parse version-agnostic paths: PATH_ABSOLUTE_REGEX requires a version. The ~ form is handled in api-mfs (PathParser), which resolves it to the latest framework version.

Think of ~ like a "latest" tag in Docker — it always points to the most up-to-date structure of a node.


🏷️ Naming Conventions

  • Node labels (e.g., TA0001) must match: ^[A-Z0-9-]{2,30}$
  • Node names (e.g., Initial Access) must:
    • Be between 2 and 100 characters
    • Match: ^[\p{L}0-9&\/.,_()"' -]{2,100}$ (letters of any script, digits, and & / . , _ ( ) " ', space and -)

📝 Descriptions & Metadata

  • All descriptions support markdown format and must be between:
    • 20–20,000 characters
  • Frameworks may define up to 100 authors (each author name up to 100 characters)
  • Nodes may define up to 100 external references (references)

🔗 Relationship Inheritance & Summarization

  • Relationships defined at a node are inherited downwards by all children and descendants.
  • Summarization must work in both directions:
    • 🔼 Upwards: Relationships from ancestors should be visible at each node
    • 🔽 Downwards: Relationships defined on children/descendants should also be summarized at their parents

📎 Examples

  • A risk linked to /TA0001 applies to all children like /TA0001/T1566/001
  • When viewing /TA0001/T1566, summaries include risks from its parent (TA0001) and its children (001, 002, etc.)

✅ These conventions ensure that frameworks are strictly validated, consistent, and query-efficient for real-time use in applications, APIs, and analytics platforms.


🔎 Why This Matters

This model enables you to store external relationships (e.g., risk, compliance, CVEs) in a flat table, and still perform meaningful joins against a branch of the tree.


🌲 Tree-Structured Frameworks

Frameworks are modeled as hierarchical trees of Nodes. Each node:

  • Has a unique label (e.g. TA0001, T1566)
  • May have children, forming branches
  • Can be referenced via structured paths

Example

MITRE-ATTCK~V17.1
├── TA0001 (Initial Access)
│ ├── T1566 (Phishing)
│ │ ├── 001 (Spearphishing Attachment)
│ │ └── 002 (Spearphishing Link)

📌 Node Paths & Identifiers

Framework nodes are uniquely referenced using path strings, supported by the NodePath class:

TypeExampleUse Case
Local Path/TA0001/T1566/001Internal lookup within a framework
Absolute PathMITRE-ATTCK~V17.1/TA0001/T1566/001Globally resolvable path with version control
Absolute Latest PathMITRE-ATTCK~/TA0001/T1566/001Globally resolvable path that always targets the latest framework version

Each path maps to a hashed Location (NodePath.Location). Hashes are 32-bit xxHash (seed 0) of the local path (version and root are not part of the hash), so the same local path gives the same IDs in every framework version.


⚡ The PathLookup Engine

What is it?

PathLookup (com.esprofiler.models.common.PathLookup) is a high-performance, hash-indexed traversal and lookup engine that provides:

  • 🔍 Branch lookup: The node itself plus all of its descendants
  • 🔁 Ancestor lookup: All parents up to the top-level node (excluding the node itself)
  • 🧒 Child lookup: Direct children
  • 🧬 Family lookup: All nodes with the same label
  • 🍃 Leaf lookup: All terminal nodes (no children)
  • ⚡ Efficient dynamic and precomputed operation

Why It Matters

FDM nodes may be referenced externally in a flat relational table — such as risk mappings, compliance controls, or CVE links.

To retrieve all applicable relations for a branch (e.g. a tactic), we can use the PathLookup to:

  • Retrieve all node identifiers (int hash IDs)
  • Use these in a fast WHERE id IN (...) query

🔑 This decouples the hierarchical framework structure from flat external mappings while maintaining high-speed query resolution.


✅ Supported Lookup Methods

Using com.esprofiler.models.common.PathLookup:

MethodDescriptionReturn Type
getBranch(path)🎯 The node itself 🔽 All descendants (downwards). Ancestors are not included; use getAncestors for thoseIntArrayList
getAncestors(path)🔼 All parent nodes up to the top-level node (excludes the node itself)IntArrayList
getChildren(path)👶 Immediate children (1 level down only)IntArrayList
getFamily(path)🧬 All nodes in the framework sharing the same label (family group)IntArrayList
getLeafNodes()🍃 All leaf (terminal) nodes in the entire frameworkIntArrayList
getLeafNodes(path)🍃 All leaf nodes within the subtree of the provided pathIntArrayList
getLocation(path)🧭 Returns the hashed Location object for a given path (String only)NodePath.Location

getBranch, getAncestors, getChildren, getFamily and getLeafNodes(path) each accept either a local path String or a NodePath. Unknown paths return an empty list. PathLookup also provides getLeafNodesObjects(), getAbsolute(path), getLocal(path) and isValidNodePath(path).


🚀 Example Use Cases


🧠 Precomputed vs. Dynamic Lookup

ModeDescription
PrecomputedCaches every node's branch at init for instant getBranch lookup — best for static or filtered views
DynamicTraverses the tree on each getBranch request — ideal when memory is critical or branches change

The boolean only controls the branch cache. The children, ancestor, family and node indexes are always built at construction.

You can instantiate PathLookup in either mode. The dropdown has an example and estimated timings for a framework of about 1,500 nodes.


Node State

Each node within a framework has a defined state indicating whether it is currently active and should be used, or whether it has been deprecated or replaced by newer framework nodes. To support this, every node includes a state field. If no value is provided, the state defaults to ACTIVE.

The state field is a polymorphic object:

  • ACTIVE (default) — the node is active and should be used.
  • DEPRECATED — the node will be removed in a future version.
  • REPLACED — the node has been replaced by one or more other nodes, for example when one node is split for more granularity. The replacement field is a set of local NodePaths (1 to 100 entries, each must be a local path).

📌 Developer Integration Summary

Built on fastutil for high-performance primitive collections

Uses 32-bit xxHash for consistent, compact ID mapping

Designed for frameworks with 10K+ nodes (design target; the library enforces no node-count limit)

Supports absolute and local path access

A full Cyber Kill Chain example and the field reference are in the dropdowns. The production Cyber Kill Chain FDM (prod-files/lockheed-martin/cyber-kill-chain/fdm_lm-ckc.json in data-fdm-converter) uses the root LHM-CKC, with phases PH-01 to PH-07 and the six courses of action as children of each phase.

Copyright © 2026