Architectural Traceability
Architectural traceability is the ability to demonstrate, verifiably, that every relevant security requirement has an associated design decision, an implemented control and auditable evidence.
Without traceability, an architecture may be correct but not demonstrably secure - which is insufficient in audit, compliance or post-incident analysis contexts.
Traceability model
The model links five elements in a chain:
Ameaça (Cap. 03) → Requisito de arquitectura → Decisão (ADR) → Controlo implementado → Evidência
| Element | Description | Typical artefact |
|---|---|---|
| Threat | Threat identified in threat modelling (Ch. 03) - STRIDE, PASTA or equivalent | TM record, annotated DFD |
| Architecture requirement | Canonical requirement from this chapter's catalogue that mitigates the threat | 01-catalogo-requisitos.md |
| Decision (ADR) | Architecture Decision Record documenting how the requirement is satisfied in the context of the project | adr/ADR-xxxx.md, decisions section in solution-architecture.md |
| Implemented control | The technical or procedural measure in force that gives effect to the decision | Network configuration, admission policy, review process |
| Evidence | Verifiable artefact that proves the control - versioned, reproducible and auditable | Versioned diagram, CI/CD log, review minutes, completed checklist |
Traceability matrix template
The matrix can be kept as a Markdown table in the repository, as backlog items with labels, or as a section in solution-architecture.md. The format is secondary; the substance - a verifiable link between requirement, decision and evidence - is the determining criterion.
| ARC Req. | Name | Associated threat (Ch. 03) | Decision / ADR | Implemented control | Evidence | Status |
|---|---|---|---|---|---|---|
| ARC-001 | Trust zones identified | Spoofing, Information Disclosure | ADR-003 | C4 diagram with delimited trust boundaries | docs/arch/trust-zones-v3.drawio (rev. 2024-11) | Compliant |
| ARC-005 | Integrated threat modelling | Elevation of Privilege, Tampering | ADR-007 | STRIDE applied in a quarterly design session | docs/tm/checkout-flow-2024-11.md | Compliant |
| ARC-006 | Isolation between sensitive domains | Lateral movement, Info Disclosure | ADR-009 | Kubernetes network policies + ACLs on the API Gateway | CI log: validate-isolation (pipeline #247) | Compliant |
| ARC-011 | Segmentation between environments | Cross-env tampering | ADR-012 | Isolated namespaces + separate credentials per environment | IAM audit 2024-10, network policy review | Compliant |
For L1: the Ameaça associada and Decisão / ADR columns are recommended but not mandatory. For L2 and L3: all fields are mandatory.
Update criteria
The traceability matrix must be updated when:
- an ARC requirement is instantiated or reviewed in the project;
- an ADR is created, updated or invalidated;
- an architectural review event occurs (see the triggers in Operational Glossary);
- the application's risk level is reclassified;
- an exception is approved, renewed or expires.
Outdated traceability is equivalent to the absence of traceability for audit purposes.
Operational instantiation
For instantiation in a project, each ARC requirement is identified with the operational tag SEC-Lx-ARC-CODIGO (e.g. SEC-L2-ARC-005), as described in Taxonomy and Traceability.
The operational tag is the link between the architectural traceability matrix and the project's backlog or compliance management system.
For the requirements catalogue, see ARC Requirements Catalogue. For the validation criteria per requirement, see Architectural Validation Plan. For the decision and evidence model, see Architectural Decision and Evidence. For the management of exceptions to traceability, see Exception Management.