-
Notifications
You must be signed in to change notification settings - Fork 0
Governance
wiki-sync[bot] edited this page Jul 23, 2026
·
1 revision
Status: Living document · Version: 1.0 · Last updated: 2026-07-23 Scope: the Nightly Well-Architected Framework (NWAF) Agent — an autonomous nightly pipeline that reviews a workload's Terraform + live AWS state against the AWS Well-Architected Framework and reports risk.
This document is the governance spine of the design. It maps the architecture to
the frameworks an architect is expected to work within, consolidates the
trade-offs recorded across the nine ADRs, and states the AI-governance controls.
It does not restate the decisions — see adr/0001…adr/0009 for those; it
governs and cross-references them.
| Framework | Role in this design |
|---|---|
| ISO/IEC 42010 | Structures the architecture description — stakeholders, concerns, viewpoints, and their correspondence to decisions. |
| TOGAF ADM | Locates the work in an architecture method and supplies the decision-governance model (the ADR process = implementation governance + change management). |
| AWS Well-Architected Framework (WAF) | Dual role: the subject the agent reviews and a lens applied to the agent's own architecture (§4). |
| AWS Cloud Adoption Framework (CAF) | The operating perspectives (Governance, Security, Operations, Platform) for how the capability is run. |
| ISO/IEC 25010 | The product-quality model used to score the architecture's quality attributes (§5). |
| Responsible-AI / model-risk governance | The control set for an LLM-in-the-loop system handling sensitive data (§7). |
| Stakeholder | Primary concerns |
|---|---|
| Platform / Cloud Engineering | Reproducibility, operability, cost, maintainability |
| Security / Compliance | Least-privilege, data governance, auditability, no environment mutation |
| Workload owners | Accuracy of findings, actionability, no disruption to their account |
| Leadership / Auditors | Trustworthy WA posture, evidence trail, human accountability |
| AI Governance function | Model risk, prompt-injection defence, hallucination control, HITL |
| Viewpoint | Addresses concern | Primary ADRs / views |
|---|---|---|
| Functional (the pipeline) | reproducibility, accuracy | 0003, 0004; HLD diagram |
| Security (trust boundaries, identity) | least-privilege, no mutation | 0002, 0006, 0007 |
| Data (flows, classification) | data governance | 0004, 0005, 0007 (§7.5) |
| Operational (schedule, delivery, run record) | operability, auditability | 0001, 0006, 0009 |
| Concern | Satisfied by |
|---|---|
| Reproducibility & determinism | 0001 (ephemeral pipeline), 0003 (code-orchestrated flow), 0005 (versioned reference) |
| Data governance (sensitive state) | 0002 (in-region, no training), 0007 (read-only, data-plane deny) |
| Least-privilege | 0003 (per-stage), 0006 (single write scope), 0007 (per-stage roles) |
| Auditability | 0002 (CloudTrail), 0006 (milestones, attribution), 0008 (evidence-linkage) |
| Responsible AI | 0004 (judgment boundary), 0006, 0007, 0008 (HITL) |
| Cost efficiency | 0001 (pay-per-run), 0005 (no always-on RAG) |
The NWAF Agent is a discrete capability, not an enterprise transformation, so it exercises a focused slice of the ADM:
| ADM phase | This work |
|---|---|
| A — Architecture Vision | "Automated, nightly, evidence-based WA posture with human accountability." |
| C — Information Systems Architecture | Application (the pipeline stages, 0003) and Data (flows/classification, 0004/0005/0007). |
| D — Technology Architecture | CodeBuild, Bedrock, scanners, SNS (0001/0002/0004/0009). |
| G — Implementation Governance | The ADR set is the governance instrument — every material choice is a recorded, reviewable decision. |
| H — Architecture Change Management | Each ADR carries an explicit revisit trigger; change is a status transition, not a silent edit. |
The design deliberately separates Architecture Building Blocks (capability, provider-agnostic) from Solution Building Blocks (the concrete product), which is what makes several decisions swappable:
| ABB (capability) | SBB (chosen) | Swap point |
|---|---|---|
| LLM reasoning | Claude via Bedrock | provider layer, 0002 |
| Ephemeral compute | AWS CodeBuild | 0001 revisit → Fargate |
| Live detection | Prowler/Steampipe | 0004 portfolio |
| WA reference retrieval | bundled local index | 0005 revisit → managed store |
| Notification fan-out | Amazon SNS | 0009 revisit → EventBridge |
- Every material decision is an ADR: Status · Context · Decision · Consequences · Alternatives · Revisit trigger · References.
- Status lifecycle: Proposed → Accepted → (Superseded | Revisited).
- Revisit triggers are first-class — each ADR names the condition under which it should be reopened, so the architecture ages by explicit review rather than drift.
- Cross-references keep the set coherent (e.g. 0007 binds 0002/0004/0006/0008).
A WA-review tool should pass its own review. Assessed against the six pillars:
| Pillar | How the agent's own architecture addresses it | ADRs |
|---|---|---|
| Operational Excellence | Deterministic pipeline; buildspec- and IaC-as-code; per-run milestone as an operational record; versioned WA reference. | 0001, 0003, 0005, 0006 |
| Security | Per-stage least-privilege; read-only, write structurally impossible in the reviewed account; no long-lived credentials; data-plane deny; channel secrets isolated from the agent. | 0002, 0007, 0009 |
| Reliability | Idempotent nightly batch on ephemeral compute; no shared mutable state; writes reversible via milestones; a failed run simply re-runs next cycle. | 0001, 0006 |
| Performance Efficiency | Right-sized: no supervisor-LLM overhead; the LLM reads compact structured findings, not raw config dumps; no always-on retrieval tier. | 0003, 0005 |
| Cost Optimization | Pay-per-run compute (no idle); no 24/7 vector cluster; pay-per-token inference; Infracost keeps cost itself in scope. | 0001, 0005 |
| Sustainability | Ephemeral compute means near-zero idle footprint; minimal always-on infrastructure; efficient token use reduces inference energy. | 0001, 0005 |
Known reliability gap (tracked): the nightly batch has no dead-letter / run-failure alerting yet — a failed run is currently silent until the next success. Candidate for a follow-on ADR.
| Characteristic | Design position | Evidence (ADR) |
|---|---|---|
| Security | Strongest attribute — structural read-only, per-stage isolation, no secrets in the agent. | 0002, 0007, 0008, 0009 |
| Reliability | Idempotent, reversible, ephemeral; gap = run-failure alerting. | 0001, 0006 |
| Maintainability | Each stage a testable structured-output function; scanners are maintained OSS; ADRs document intent. | 0003, 0004 |
| Portability | Provider layer + common-subset discipline; ABB/SBB separation. | 0002 |
| Performance Efficiency | Compact structured inputs; no supervisor overhead; no always-on RAG. | 0003, 0005 |
| Functional Suitability | Deterministic detection + honest judgment boundary; over-claim explicitly avoided. | 0004 |
The single view of every decision, the cost accepted, and when to reopen it.
| ADR | Decision | Trade-off accepted | Revisit trigger |
|---|---|---|---|
| 0001 | CodeBuild as runtime | "CI tool used off-label"; coarse compute sizing | Parallel fan-out exceeds concurrent-build quota → Fargate |
| 0002 | Provider portability layer, Bedrock default | Portability holds only on the common feature subset (a discipline) | Need a parity-gated feature → default to Claude Platform on AWS |
| 0003 | Deterministic pipeline + bounded-LLM reconciliation | Not autonomously adaptive across pillars | Reviews need dynamic cross-pillar depth → supervisor pattern |
| 0004 | Per-pillar scanner portfolio | Scanner-version maintenance; Performance/Sustainability partly judgment | Scope grows → add Trivy / Resilience Hub |
| 0005 | Bundled versioned WA reference | Manual corpus refresh a few times/year | Corpus growth or multi-workload fan-out → managed vector store |
| 0006 | Scoped write-back to a dedicated workload | A second (automation) workload to reconcile | Single-workload requirement → attributed answers in shared workload |
| 0007 | Per-stage roles, read-only in target | Per-stage credential + StackSet onboarding complexity | Fleet onboarding friction → Org delegated-admin read-only role |
| 0008 | Selectable report-only / advisory-PR |
advisory_pr adds LLM-generated-Terraform risk |
Confidence proven → widen PR eligibility; or add per-finding gate |
| 0009 | SNS hub + channel adapters | More components (three adapters) | Routing/filtering growth → EventBridge API Destinations |
The system puts an LLM in the loop over sensitive infrastructure data. The controls below make that defensible.
Inference runs on Amazon Bedrock (ADR-0002): data stays in-region, is not used for training, and is reachable over PrivateLink so sensitive state never touches the public internet. No API keys — IAM-scoped invocation only.
The agent ingests untrusted HCL/tfstate. Two layers:
- Per-stage credential isolation (ADR-0007) — a compromised Reconcile stage holds neither the scan role nor the WA-write scope; they never exist there.
- Bedrock Guardrails available as a native prompt-injection / PII filter.
- Detection is deterministic (ADR-0003/0004) — the LLM does not invent findings; it reconciles scanner output.
- Scanner-derived vs judgment is always labelled (ADR-0004); judgment answers are never presented as scanner fact.
- The LLM never fabricates a "fixed/resolved" status — status claims are audited against scanner evidence (ADR-0008).
- Structured (JSON-schema) outputs bound the reconciliation stage.
- No environment mutation — structurally impossible (ADR-0007).
- No mutation of the human WA record — judgment answers proposed, not written (ADR-0006).
-
No auto-remediation —
advisory_propens draft PRs only; humans merge (ADR-0008). - Accepted-risk register honoured — humans own the finding lifecycle.
- Classification: tfstate and live config are sensitive (may contain secrets, account topology).
-
Residency & minimisation: in-region inference; the scan role has an
explicit data-plane deny (no
GetObject/GetSecretValue/kms:Decrypton data) — config is read, values are not (ADR-0007). - No secrets in the agent: channel credentials live in delivery adapters, not the agent (ADR-0009).
- CloudTrail on every AssumeRole and API call (ADR-0002/0007).
- Attribution + evidence on every automated output — each WA answer cites tool + check ID + evidence + run id (ADR-0006/0008).
- Milestones give a reversible, comparable per-run history (ADR-0006).
- Determinism itself is a governance property: the same inputs reproduce the same review.
| AI-governance control | Backed by |
|---|---|
| Data not used for training; in-region; PrivateLink | 0002 |
| No long-lived credentials | 0002, 0007 |
| Prompt-injection blast-radius containment | 0007 |
| Deterministic detection (no invented findings) | 0003, 0004 |
| Judgment vs fact labelling | 0004 |
| No fabricated resolution status | 0008 |
| Environment mutation impossible | 0007 |
| Human record not auto-mutated | 0006 |
| No auto-remediation | 0008 |
| Accepted-risk / human lifecycle control | 0008 |
| Data-plane read deny | 0007 |
| Channel secrets isolated | 0009 |
| Full audit trail + attribution | 0002, 0006, 0007, 0008 |
This document is reviewed when any ADR changes status, when a revisit trigger fires, or at least once per major AWS Well-Architected Framework revision (which also drives the bundled-reference refresh in ADR-0005).
- Decision records:
adr/0001…adr/0009 - HLD diagram:
diagrams/nwaf-agent-hld.png(v2.3) - Business case:
business-case.md(pending)
NWAF Agent repository · generated from docs/ — do not edit wiki pages directly.
Design
Decision Records