[Phase 1b] Add Framework Applicability Schema for Entity-Level Mappings

[davidlabianca]

[Phase 1b] Add Framework Applicability Schema for Entity-Level Mappings

Parent Issue

Part of Epic: Uplift CoSAI-RM Persona Model

Can run in parallel with: Phase 1a - Persona Schema Updates (#110 )

---

Objective

Expand the framework ID enum to include ISO 22989 and add applicableTo field to frameworks.schema.json to define which entity types (controls, risks, personas) can map to each framework. This prevents invalid framework mappings.

---

Background

Currently, frameworks can be mapped from any entity type, leading to invalid mappings:

• STRIDE on controls (should be risks only)
• NIST AI RMF on risks (should be controls only)
• No validation to prevent these errors

Solution: Add applicableTo array to specify which entity types can reference each framework.

Entity-Framework Mapping Table:

Framework	Controls	Risks	Personas
mitre-atlas	✅	✅	❌
nist-ai-rmf	✅	❌	❌
stride	❌	✅	❌
owasp-top10-llm	❌	✅	❌
iso-22989	✅	✅	✅

---

Tasks

1. Expand Framework ID Enum

File: risk-map/schemas/frameworks.schema.json

Update framework ID enum to include new framework that will be added in Phase 2:

{
  "id": {
    "type": "string",
    "description": "Unique framework identifier used in mapping references",
    "enum": [
      "mitre-atlas",
      "nist-ai-rmf",
      "stride",
      "owasp-top10-llm",
      "iso-22989"
    ]
  }
}

Rationale: Phase 2 will add ISO 22989 to frameworks.yaml. The schema enum must be updated first to allow validation of persona mappings to this framework.

---

2. Add applicableTo Field to Framework Schema

File: risk-map/schemas/frameworks.schema.json

Add new field applicableTo:

{
  "applicableTo": {
    "type": "array",
    "description": "Entity types that can map to this framework",
    "items": {
      "oneOf": [
        {
          "type": "string",
          "const": "all",
          "description": "Framework applies to all entity types"
        },
        {
          "type": "string",
          "enum": ["controls", "risks", "personas"],
          "description": "Specific entity type that can map to this framework"
        }
      ]
    },
    "minItems": 1,
    "uniqueItems": true
  }
}

Make it required for all frameworks to ensure clear applicability.

Example usage:

frameworks:
  # Entity-level applicability
  - id: mitre-atlas
    name: MITRE ATLAS
    applicableTo:
      - controls  # AML.M* mitigations
      - risks     # AML.T* techniques

  - id: nist-ai-rmf
    name: NIST AI RMF
    applicableTo:
      - controls  # Subcategories like MS-2.3, GV-6.2

  - id: stride
    name: STRIDE
    applicableTo:
      - risks  # Threat categories only

  # Universal frameworks
  - id: iso-22989
    name: ISO 22989
    applicableTo: all  # Applies to all entity types

---

2. Update Validation Scripts

Files to update:

• scripts/hooks/validate_framework_references.py
• scripts/hooks/riskmap_validator/models.py

Changes:

1. Add validation for applicableTo field format
2. Verify entity types in applicableTo are valid
3. Add validation to check if controls/risks are mapping to applicable frameworks
4. Update test fixtures

New validation rules:

• applicableTo must contain valid entity types or "all"
• No duplicate entity types in applicableTo
• Warn if framework has no applicableTo field
• Error if control maps to framework not applicable to controls
• Error if risk maps to framework not applicable to risks

---

3. Update Tests

File: scripts/hooks/tests/test_validate_framework_references.py

New test cases:

def test_framework_applicable_to_valid_entity_types():
    """Test applicableTo field accepts valid entity types"""

def test_framework_applicable_to_all():
    """Test applicableTo accepts 'all' keyword"""

def test_framework_applicable_to_invalid_entity():
    """Test validation fails for invalid entity types"""

def test_framework_applicable_to_empty_array():
    """Test validation fails for empty applicableTo array"""

def test_control_framework_mapping_validation():
    """Test control cannot map to risk-only framework"""

def test_risk_framework_mapping_validation():
    """Test risk cannot map to control-only framework"""

---

4. Documentation Updates

File: risk-map/docs/guide-frameworks.md

Add section:

### Framework Applicability to Entity Types

Frameworks specify which entity types can reference them using the `applicableTo` field:

\`\`\`yaml
frameworks:
  - id: mitre-atlas
    applicableTo:
      - controls  # Controls can map to MITRE ATLAS mitigations
      - risks     # Risks can map to MITRE ATLAS techniques

  - id: nist-ai-rmf
    applicableTo:
      - controls  # Only controls can map to NIST AI RMF

  - id: iso-22989
    applicableTo: all  # All entity types can reference ISO 22989
\`\`\`

This prevents invalid mappings like STRIDE on controls or NIST AI RMF on risks.

---

Validation & Testing

Schema Validation

check-jsonschema --schemafile risk-map/schemas/frameworks.schema.json risk-map/yaml/frameworks.yaml

Run Tests

pytest scripts/hooks/tests/test_validate_framework_references.py -v

Manual Validation

python3 scripts/hooks/validate_framework_references.py --force

---

Success Criteria

• frameworks.schema.json framework ID enum expanded to include iso-22989
• frameworks.schema.json includes applicableTo field definition
• Validation scripts check entity-level framework mappings
• All tests pass (including new test cases)
• Documentation includes entity-level applicability examples
• Pre-commit hooks validate framework applicability

---

Branch Strategy

• Target branch: main (infrastructure update)
• Blocked by: None
• Can run in parallel with: Phase 1a

---

Dependencies

• None (can run in parallel with Phase 1a)

---

Estimated Effort

• Schema updates: 1-2 hours
• Validation script updates: 3-4 hours
• Test updates: 2-3 hours
• Documentation: 1-2 hours
• Total: 7-11 hours

---

Notes

• Do NOT modify frameworks.yaml in this phase (happens in Phase 2)
• Focus only on schema and validation infrastructure
• This change will require Phase 2 to add applicableTo to all frameworks