Merge pull request #6 from DataDog/migrate_derivitive_to_parent_child

Migrate derivative to parent child

Author: sethsec

.claude/CLAUDE.md

@@ -7,23 +7,42 @@ This document contains project-specific anti-patterns and style guidelines for w
 
 ## Anti-Patterns to Avoid
 
-### 1. Path Name Formatting
+### 1. Inconsistent Terminology for Parent/Variant Relationships
+
+**WRONG:** Mixing terminology inconsistently
+- Using "child" in UI text
+- Using "primary" in YAML field names
+- Using "parent" in user-facing documentation
+
+**CORRECT:** Use terminology appropriate to context
+- **In YAML/code**: Always use `parent` field name
+- **In UI/user-facing text**: Always use "Primary Technique" and "Variants"
+- **In comments**: Use "primary" and "variant" for clarity
+
+**Rationale**: We maintain this hybrid approach for semantic clarity:
+- `parent` is concise and conventional in code (`parent.id`, `parent.modification`)
+- "Primary Technique" conveys foundational/original technique to users
+- "Variant" explains what the path IS (expanded applicability) not just hierarchy
+
+See [Terminology section in CLAUDE.md](../CLAUDE.md#terminology-parentchild-vs-primaryvariant) for complete guidance.
+
+### 2. Path Name Formatting
 
 **WRONG:** `iam:PassRole+sagemaker:CreateTrainingJob`
 
 **CORRECT:** `iam:PassRole + sagemaker:CreateTrainingJob`
 
 Always include spaces before and after the `+` sign when combining multiple permissions in the `name` field.
 
-### 2. PowerUserAccess is NOT Administrative Access
+### 3. PowerUserAccess is NOT Administrative Access
 
 **WRONG:** `The role must have administrative permissions (e.g., AdministratorAccess or PowerUserAccess)`
 
 **CORRECT:** `The role must have administrative permissions (e.g., AdministratorAccess or an equivalent custom policy)`
 
 PowerUserAccess does NOT provide administrative permissions (it specifically excludes IAM actions). When describing administrative access requirements in prerequisites, use "AdministratorAccess or an equivalent custom policy" instead.
 
-### 3. Description Field Line Breaks
+### 4. Description Field Line Breaks
 
 **WRONG:**
 ```yaml
@@ -38,15 +57,15 @@ description: A principal with `iam:PassRole` and `ec2:RunInstances` can create a
 
 Descriptions should be single-line in YAML (no artificial line breaks at ~80 characters). They will flow naturally in the UI based on container width.
 
-### 4. Missing Backticks for IAM Permissions
+### 5. Missing Backticks for IAM Permissions
 
 **WRONG:** `A principal with iam:PassRole and ec2:RunInstances...`
 
 **CORRECT:** ``A principal with `iam:PassRole` and `ec2:RunInstances`...``
 
 All IAM permissions in descriptions, recommendations, and text should be formatted with backticks for code styling. This applies everywhere EXCEPT in the `name` field (which should be plain text).
 
-### 5. Using Legacy Permission Format
+### 6. Using Legacy Permission Format
 
 **WRONG (deprecated format):**
 ```yaml

.github/CODEOWNERS

@@ -1 +1 @@
-* @sethsec @christophetd @raesene @andrewkrug
+* @sethsec @christophetd @raesene @andrewkrug

CLAUDE.md

@@ -19,6 +19,32 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 3. **Website Layer**: Static HTML/CSS/JS site for browsing paths
 4. **CI/CD Layer**: GitHub Actions for validation and deployment
 
+## Terminology: Parent/Child vs Primary/Variant
+
+We use **different terminology in different contexts** for clarity and semantic meaning:
+
+### In YAML Files and Code
+- **`parent` field**: Points to the parent path (e.g., `parent.id: iam-002`)
+- **Why**: Concise, follows common data structure conventions, natural for hierarchical references
+
+### In UI and Documentation
+- **"Primary Technique"**: The foundational/original technique (what YAML calls the "parent")
+- **"Variant"**: A modification that expands applicability by removing prerequisites (what YAML calls the "child")
+- **Why**: Semantic clarity - "variant" explains WHAT it is, not just that there's a hierarchy
+
+### Key Concepts
+- **Primary techniques** have no `parent` field - they are the foundational attacks
+- **Variant techniques** have a `parent` field with `id` and `modification`
+- **Variants add required permissions** that remove prerequisites from the primary technique
+- **Example**: IAM-002 (primary) requires < 2 keys. IAM-003 (variant) adds DeleteAccessKey to work even with 2 keys.
+
+### When Contributing
+- In YAML: Use `parent` field for variants
+- In documentation/comments: Refer to "primary techniques" and "variants"
+- In UI text: Display "Primary Technique" and "Variants (N)"
+
+See [SCHEMA.md](SCHEMA.md#parent-object-optional) for detailed parent/child relationship criteria.
+
 ## Quick Start Commands
 
 ### Essential Commands

SCHEMA.md

@@ -4,10 +4,23 @@ This document defines the YAML schema used for documenting AWS IAM privilege esc
 
 ## Schema Version
 
-Current version: `1.4.0`
+Current version: `1.6.0`
 
 ### Version History
 
+#### Version 1.6.0 (2025-01-15)
+- **Breaking change**: `parent` field changed from string to nested object
+- Added `parent.id` (string, required if parent present): The parent path ID
+- Added `parent.modification` (string, required if parent present): Explanation of what permission(s) the child adds to remove a prerequisite
+- Clarifies parent/child relationship: child adds required permission(s) that expand attack applicability by removing parent's prerequisites
+- Parent/child is specifically for variants where child works in scenarios where parent fails
+
+#### Version 1.5.0 (2025-01-15)
+- Added `parent` optional field for structured parent-child relationships between paths
+- Enables filtering for primary vs. variant techniques
+- Supports programmatic discovery of technique families
+- Works alongside `discoveryAttribution.derivativeOf` for comprehensive lineage tracking
+
 #### Version 1.4.0 (2025-01-11)
 - Added `detectionTools` optional field for documenting open source detection tool coverage
 - Tool metadata (names, descriptions, GitHub links) stored in `metadata.json`
@@ -349,6 +362,102 @@ discoveryAttribution:
 
 ### Optional Fields
 
+#### `parent` (object, optional)
+Defines a parent-child relationship when this path is a variant that adds required permission(s) to bypass a prerequisite of the parent technique.
+
+This field creates a structured parent-child relationship between paths, enabling:
+- Easy filtering for primary vs. variant paths in the UI
+- Programmatic discovery of related techniques
+- Clear explanation of what makes the child variant necessary
+
+**Parent object structure:**
+- `id` (string, required): The parent path ID
+- `modification` (string, required): Explanation of what required permission(s) this child adds and which prerequisite it removes/bypasses
+
+**Terminology Note:**
+We use different terminology in different contexts for clarity:
+- **In YAML/code**: `parent` field (concise, follows common data structure conventions)
+- **In UI/documentation**: "Primary Technique" and "Variants" (semantic, conveys meaning)
+
+Rationale:
+- **`parent` field name**: Natural for pointing upward in the hierarchy (`parent.id`), concise in YAML
+- **"Primary Technique"**: Conveys that this is the foundational/original technique
+- **"Variant"**: Explains WHAT it is (a modification that expands applicability), not just that it's a child
+
+This hybrid approach gives semantic clarity where users see it (UI/docs) while keeping code simple and conventional.
+
+**When to use parent/child:**
+- ✅ Parent path is exploitable with specific prerequisites (e.g., "user must have < 2 access keys")
+- ✅ Child path adds required permission(s) that remove/bypass those prerequisites
+- ✅ Child works in scenarios where parent fails
+- ✅ Same core attack technique, just expanded applicability
+
+**When NOT to use parent/child (use relatedPaths instead):**
+- ❌ Different categories (new-passrole vs existing-passrole)
+- ❌ Alternative approaches that don't remove prerequisites (siblings)
+- ❌ Neither path works without additional permissions (no true "base" case)
+
+**Key principle:** Child adds permission(s) to the **required** section that expand when the attack works by removing parent's prerequisites.
+
+**Examples:**
+
+**Parent/Child (correct usage):**
+- IAM-002 (CreateAccessKey) → IAM-003 (CreateAccessKey + DeleteAccessKey)
+  - Parent requires: User has < 2 access keys
+  - Child removes prerequisite: Can delete existing key first
+- Lambda-003 (UpdateFunctionCode) → Lambda-004 (UpdateFunctionCode + InvokeFunction)
+  - Parent requires: Function has existing trigger
+  - Child removes prerequisite: Brings own execution via InvokeFunction
+
+**Not Parent/Child (siblings - use relatedPaths):**
+- Glue-003 (PassRole + CreateJob + StartJobRun) and Glue-004 (PassRole + CreateJob + CreateTrigger)
+  - Neither works without the third permission
+  - Different execution methods, not removing prerequisites
+  - These are alternative approaches, not variants
+
+**Relationship to `discoveryAttribution`:**
+- The `parent` field is for machine-readable technical relationships
+- The `discoveryAttribution` field is for human-readable credit and attribution
+- Keep both - they serve different purposes
+
+Example:
+```yaml
+# IAM-003 (child/variant)
+id: iam-003
+name: iam:CreateAccessKey + iam:DeleteAccessKey
+parent:
+  id: iam-002
+  modification: "Adds iam:DeleteAccessKey to enable exploitation even when the target user already has 2 access keys (AWS maximum). The attacker deletes one existing key before creating their own, removing the prerequisite that the user must have fewer than 2 keys."
+discoveryAttribution:
+  firstDocumented:
+    author: Spencer Gietzen
+    organization: Rhino Security Labs
+    date: 2019
+    link: https://rhinosecuritylabs.com/aws/aws-privilege-escalation-methods-mitigation/
+```
+
+```yaml
+# IAM-002 (primary/parent technique)
+id: iam-002
+name: iam:CreateAccessKey
+# No parent field - this is a primary technique
+discoveryAttribution:
+  firstDocumented:
+    author: Spencer Gietzen
+    organization: Rhino Security Labs
+    date: 2019
+    link: https://rhinosecuritylabs.com/aws/aws-privilege-escalation-methods-mitigation/
+```
+
+```yaml
+# Lambda-004 (child/variant)
+id: lambda-004
+name: lambda:UpdateFunctionCode + lambda:InvokeFunction
+parent:
+  id: lambda-003
+  modification: "Adds lambda:InvokeFunction to enable exploitation even when the target function has no existing trigger mechanism. Removes the prerequisite that something must already be invoking the function."
+```
+
 #### `prerequisites` (object or array)
 Conditions that must be met for the escalation to work.