Architecture Decision Records¶
This directory contains Architecture Decision Records (ADRs) for APTL. ADRs capture significant architectural decisions along with their context, rationale, and consequences.
Format¶
We use MADR (Markdown Any Decision Records). Each ADR includes:
- Status:
proposed,accepted,deprecated, orsuperseded by ADR-XXX - Context: The problem or situation driving the decision
- Decision: What we chose and why
- Consequences: Trade-offs (positive, negative, risks)
Principles¶
- ADRs are immutable once accepted. To reverse a decision, create a new ADR that supersedes it.
- ADRs are numbered sequentially and never reused.
- ADRs are versioned with code—they live in the repo, not a wiki.
Index¶
| ADR | Title | Status | Date |
|---|---|---|---|
| 000 | Use Architecture Decision Records | accepted | 2026-03-20 |
| 001 | Migrate from AWS/Terraform to Local Docker Compose | accepted | 2025-08-06 |
| 002 | Wazuh SIEM over Splunk and qRadar | accepted | 2025-08-06 |
| 003 | MCP Common Library with Config-Driven Server Generation | accepted | 2025-08-30 |
| 004 | Persistent SSH Session Architecture with Command Queuing | accepted | 2025-08-30 |
| 005 | Docker Compose Profiles for Selective Deployment | accepted | 2025-09-01 |
| 006 | Four-Network Segmentation Architecture | accepted | 2026-02-07 |
| 007 | Python CLI as Primary Control Plane | accepted | 2026-02-07 |
| 008 | Integrated SOC Stack (MISP, TheHive, Cortex, Shuffle, Suricata) | accepted | 2026-02-22 |
| 009 | Scenario Engine with YAML Specs and Run Archive Collectors | accepted | 2026-03-02 |
| 010 | SonarCloud for Continuous Code Quality | accepted | 2026-03-07 |
| 011 | Notebook-Style Web UI (SvelteKit + FastAPI) | proposed | 2026-03-20 |
| 012 | OpenTelemetry Integration | accepted | 2026-03-21 |
| 013 | Deployment Backend Abstraction Layer | accepted | 2026-03-22 |
| 014 | Scenario Description Language (SDL) | accepted | 2026-03-29 |
| 015 | Declarative Experiment Objectives in the SDL | accepted | 2026-03-29 |
| 016 | Workflows, Targetable Sub-Objects, and Leaf Enum Variables in the SDL | accepted | 2026-03-29 |
| 017 | SDL Runtime Layer | proposed | 2026-03-30 |
| 018 | Control Flow Primitives in the SDL | accepted | 2026-04-01 |
| 019 | Suricata stays IDS-only; packet-level prevention via Wazuh active-response | accepted | 2026-05-02 |
| 020 | Wazuh agents run in-process on target containers; sidecars only for upstream-image carve-outs | accepted | 2026-05-02 |
| 021 | Active-response whitelist enforcement via a standalone iptables AR script | accepted | 2026-05-02 |
| 022 | MISP-driven Suricata rules via a tag-graduated sync service | accepted | 2026-05-03 |
| 023 | Container interaction (list/logs/shell/exec/inspect) on the DeploymentBackend Protocol | accepted | 2026-05-03 |
| 024 | Orchestrator-side purple-team continuity carve-out | accepted | 2026-05-03 |
| 025 | Strict first-party config schema | accepted | 2026-05-05 |
| 026 | Advisory CI Vulnerability Scanning | accepted | 2026-05-09 |
| 027 | Red Team Structured Logging Boundary (SIEM-transport superseded by ADR-033) | accepted (amended) | 2026-05-09 |
| 028 | Runtime-Rendered Service Config | accepted | 2026-05-10 |
| 029 | Control-Plane Secret Handling in Run Data and Local State | accepted | 2026-05-10 |
| 030 | Startup Partial-Readiness Classification | accepted | 2026-05-11 |
| 031 | Lab Orchestration Contract Guards | accepted | 2026-05-12 |
| 032 | Conversation Surface Hardening | accepted | 2026-05-17 |
| 033 | Red-Side Behavioural Capture and Non-Contamination Boundary | accepted | 2026-05-17 |
| 034 | Lab-Managed CA for Verified SOC Stack TLS | accepted | 2026-05-18 |
| 035 | Adopt RAES SDL as APTL's Scenario Authoring Surface (realization model superseded by ADR-046) | accepted (amended) | 2026-05-18 |
| 036 | Snapshot Endpoint Registry Boundary | accepted | 2026-05-18 |
| 037 | Docker Compose Backend Cohesion | accepted | 2026-05-18 |
| 038 | Documentation Style Lint and Published Docs Site | accepted | 2026-06-11 |
| 039 | Web Control Plane Authentication and Loopback Exposure | accepted | 2026-06-14 |
| 040 | Terminal SSH Host-Key Verification Boundary | accepted | 2026-06-13 |
| 041 | Kali Capture Sidecar Ownership Boundary (PTY-typescript residual superseded by ADR-042) | accepted (amended) | 2026-06-20 |
| 042 | Sidecar-Owned PTY Master for Kali Transcript Authenticity | accepted | 2026-06-20 |
| 043 | Suricata Runtime Config Ownership Boundary | accepted | 2026-06-20 |
| 044 | RAES-Aligned Run Reproducibility Record | accepted | 2026-06-25 |
| 045 | Ephemeral Lifecycle Policy Enforcement | accepted | 2026-06-28 |
| 046 | Dynamic RAES Scenario Realization (Image Realization Addendum superseded by ADR-048) | accepted (amended) | 2026-06-29 |
| 047 | RAES Experiment Admission and Trial-Plan Boundary | accepted | 2026-07-19 |
| 048 | APTL Image-Free, Placement-Based Realization Envelope | superseded in part by ADR-051 | 2026-07-20 |
| 049 | Sealed, Disposable Lab Appliance Delivery Boundary | superseded in part by ADR-060 | 2026-07-25 |
| 050 | Terminal Attempt Archival And Atomic Seal Boundary | accepted | 2026-07-28 |
| 051 | Component-Level RAES Realization | accepted | 2026-07-28 |
| 052 | Configured Participant Credential Sourcing | proposed | 2026-08-12 |
| 053 | Pack-Backend Deployment-Serving Interaction Seam | accepted | 2026-08-10 |
| 054 | APTL-to-LilRAE Identity Continuity and Capability Ownership | proposed | 2026-09-05 |
| 055 | Local Runtime Authority and Ownership | proposed | 2026-09-05 |
| 056 | Scenario-Led Capability Qualification | proposed | 2026-09-05 |
| 057 | Agent Execution Compartments | proposed | 2026-09-05 |
| 058 | Adoption and Security Release Gates | proposed | 2026-09-05 |
| 059 | Canonical TechVault Delivery and Host MCP Access | superseded in part by ADR-060 | 2026-09-17 |
| 060 | VM-Only Seat Containment | accepted | 2026-09-20 |