|
| 1 | +# ADR-020: MAESTRO Layer Classification for Threat Findings |
| 2 | + |
| 3 | +**Status**: Accepted |
| 4 | +**Date**: 2026-04-08 |
| 5 | +**Deciders**: Architect |
| 6 | +**Feature**: 084 (MAESTRO Layer Mapping) |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +## Context |
| 11 | + |
| 12 | +tachi's threat model pipeline classifies components by DFD element type (External Entity, Process, Data Store, Data Flow) during Phase 1 (Scope), then dispatches STRIDE and AI threat agents accordingly. However, the pipeline had no awareness of where components sit within an agentic AI architecture stack. This limited the ability to: |
| 13 | + |
| 14 | +1. **Identify architectural concentration risk**: Threats clustered at one layer (e.g., many threats against Foundation Model components) were invisible without manual review. |
| 15 | +2. **Align with industry taxonomy**: Security teams using CSA's MAESTRO framework could not map tachi findings to their existing layer-based security controls. |
| 16 | +3. **Enable layer-based risk aggregation**: The Risk Summary section could not break down findings by architectural layer, making it harder to prioritize remediation across system tiers. |
| 17 | + |
| 18 | +**Constraints**: |
| 19 | +- Classification must not require user-provided layer annotations -- it must be automatic. |
| 20 | +- Classification must be deterministic and auditable (no LLM-based classification of component types). |
| 21 | +- The new field must propagate through the entire pipeline without breaking existing consumers. |
| 22 | +- Classification must handle components that do not fit any layer gracefully (no errors for unclassifiable components). |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +## Decision |
| 27 | + |
| 28 | +We will adopt the **CSA MAESTRO seven-layer taxonomy** as the architectural layer classification framework, implemented via **keyword-based substring matching** during Phase 1 with ordered evaluation (L1 through L7, first match wins). |
| 29 | + |
| 30 | +The implementation adds: |
| 31 | +1. A shared reference file (`maestro-layers-shared.md`) with the canonical keyword-to-layer mapping table. |
| 32 | +2. An optional `maestro_layer` field on the finding IR schema (`schemas/finding.yaml`, schema_version 1.1 to 1.2). |
| 33 | +3. Phase 1 classification: after DFD type assignment, each component is classified by matching its name, description, and DFD type against layer keywords. |
| 34 | +4. Phase 3 inheritance: each finding inherits `maestro_layer` from its target component. |
| 35 | +5. Passive propagation through downstream agents (risk-scorer, control-analyzer, threat-report). |
| 36 | + |
| 37 | +--- |
| 38 | + |
| 39 | +## Rationale |
| 40 | + |
| 41 | +**Reasons**: |
| 42 | +1. **Industry alignment**: CSA MAESTRO is the only published seven-layer taxonomy specifically designed for agentic AI architectures. Using it provides a shared vocabulary with the broader security community. |
| 43 | +2. **Keyword matching reuses proven pattern**: The AI dispatch mechanism (Feature 007) already uses case-insensitive keyword matching to classify components. MAESTRO classification follows the same pattern, reducing implementation risk. |
| 44 | +3. **Deterministic and auditable**: Keyword matching produces the same result every run for the same input, unlike LLM-based classification which could vary between invocations. The keyword table is inspectable and versioned. |
| 45 | +4. **Non-breaking schema extension**: The `maestro_layer` field defaults to "Unclassified", making it backward-compatible with existing threat models and consumers that do not use it. |
| 46 | +5. **Shared reference prevents drift**: Following ADR-019 (shared definitions), the keyword table lives in `tachi-shared` as a single source of truth consumed by all agents that need layer awareness. |
| 47 | + |
| 48 | +--- |
| 49 | + |
| 50 | +## Alternatives Considered |
| 51 | + |
| 52 | +### Alternative 1: LLM-Based Component Classification |
| 53 | +**Pros**: |
| 54 | +- Could handle ambiguous component names more intelligently |
| 55 | +- No keyword table maintenance |
| 56 | + |
| 57 | +**Cons**: |
| 58 | +- Non-deterministic: same component could be classified differently across runs |
| 59 | +- Not auditable: no inspectable mapping table |
| 60 | +- Adds inference cost and latency to Phase 1 |
| 61 | +- Conflicts with tachi's deterministic pipeline design principle |
| 62 | + |
| 63 | +**Why Not Chosen**: Determinism and auditability are critical for security tooling. Keyword matching provides both while handling the vast majority of real-world component names correctly. |
| 64 | + |
| 65 | +### Alternative 2: User-Provided Layer Annotations |
| 66 | +**Pros**: |
| 67 | +- Most accurate classification possible |
| 68 | +- No false positives from keyword matching |
| 69 | + |
| 70 | +**Cons**: |
| 71 | +- Adds mandatory input burden on every threat model run |
| 72 | +- Breaks the current zero-configuration input contract |
| 73 | +- Users unfamiliar with MAESTRO would produce inaccurate annotations |
| 74 | + |
| 75 | +**Why Not Chosen**: Automatic classification with graceful fallback ("Unclassified") delivers value without requiring users to learn a new taxonomy. |
| 76 | + |
| 77 | +### Alternative 3: Custom Layer Taxonomy |
| 78 | +**Pros**: |
| 79 | +- Could be tailored exactly to tachi's needs |
| 80 | +- No dependency on external framework updates |
| 81 | + |
| 82 | +**Cons**: |
| 83 | +- Reinvents an existing standard without adding value |
| 84 | +- No shared vocabulary with the security community |
| 85 | +- Additional maintenance burden to keep custom taxonomy current |
| 86 | + |
| 87 | +**Why Not Chosen**: CSA MAESTRO is well-aligned with tachi's target domain (agentic AI). A custom taxonomy would duplicate effort without meaningful benefit. |
| 88 | + |
| 89 | +--- |
| 90 | + |
| 91 | +## Consequences |
| 92 | + |
| 93 | +### Positive |
| 94 | +- Threat models now include architectural layer context for every component and finding |
| 95 | +- Risk Summary includes a "Risk by MAESTRO Layer" breakdown enabling layer-based prioritization |
| 96 | +- SARIF output tags findings with MAESTRO layer for downstream tooling integration |
| 97 | +- Aligns tachi with CSA's industry-standard framework for agentic AI security |
| 98 | + |
| 99 | +### Negative |
| 100 | +- Keyword matching can misclassify components with ambiguous names (e.g., "API Gateway" could be L4 or L7) |
| 101 | +- Evaluation order (L1-L7) is load-bearing -- reordering keywords changes classification |
| 102 | +- Adding new layers or modifying keywords requires regression testing against all example outputs |
| 103 | + |
| 104 | +### Mitigation |
| 105 | +- Evaluation order follows a specificity gradient (most specific first) to minimize ambiguity |
| 106 | +- "Unclassified" default ensures graceful degradation for unrecognized components |
| 107 | +- All 6 example outputs were regenerated and validated after implementation |
| 108 | +- Keyword table changes are documented with a warning about ordering sensitivity |
| 109 | + |
| 110 | +--- |
| 111 | + |
| 112 | +## Related Decisions |
| 113 | + |
| 114 | +- [ADR-019](ADR-019-shared-definitions-and-model-field-governance.md): Shared definitions pattern that governs where the MAESTRO keyword table lives |
| 115 | +- [ADR-003](ADR-003-stride-per-element-dispatch.md): STRIDE-per-Element dispatch pattern that MAESTRO classification extends |
| 116 | + |
| 117 | +--- |
| 118 | + |
| 119 | +## References |
| 120 | + |
| 121 | +- `.claude/skills/tachi-shared/references/maestro-layers-shared.md` -- Canonical keyword-to-layer mapping |
| 122 | +- `schemas/finding.yaml` -- Finding IR schema with `maestro_layer` field (v1.2) |
| 123 | +- Cloud Security Alliance, "MAESTRO: Multi-Agent Environment Security Toolkit for Reasoning and Orchestration", February 2025 |
0 commit comments