Catch the 100x Bug Before Code
Plan, threat model, and ship a design review for a DoD payment API using pytm and Structurizr.
Introduction
30 Second Summary
Every government AI program eventually needs sanitized data, audit logs, and a clean path from commercial AWS to GovCloud. The teams that scaffold these patterns on day one ship. The teams that retrofit them after iteration 10 stall.
In this project, you will scaffold a production-grade iteration-01 repo for a sanitization and synthetic data middleware system. You will write zero running code and provision zero cloud resources, but every documentation artifact, stub, and operational script will be in place from day one.
What You'll Build
A fully scaffolded repo for a sanitization and synthetic data middleware system, the foundation layer for a 22-iteration government AI systems engineering program.
By the end of this project, you'll have:
- A two-block README with the Data Handling and Commercial-to-GovCloud Mirror discipline that an ISSO can assess in 30 seconds.
- A program-level RFC-001 documenting the middleware-first one-way-door decision with contract surfaces for four downstream systems.
- Clean Terraform and pytest stubs, operational scripts, a hash-chain audit log schema, and a reviewer comprehension exercise with measured results.
- A SECURITY.md and CONTRIBUTING.md with program-level governance artifacts that survive audit.
Are there any prerequisites?
This project assumes daily operational experience with RMF, ATO, STIG, FedRAMP vocabulary, NIST 800-53 structure, Terraform idioms, AWS boundary-account patterns, and Python packaging. It does NOT teach any of those.
You need Python 3.13+, Terraform 1.x, Git, a GitHub account, a bash shell, and a text editor or IDE.
Before We Start
Before We Start...
Initialize the Repo and Directory Structure
Before any documentation or RFC can exist, the repo needs a directory structure that mirrors the program's architecture.
Government program repos fail review when engineers add directories ad hoc across iterations. The fix is to lay down the full skeleton in iteration 01, including stubs for operational scripts, build logs, and measurement artifacts that most teams forget until an auditor asks. In this step, you will create the entire directory tree, all placeholder files, the Python package stub, Terraform stubs, and operational scripts in one pass.
In This Step, Get Ready To:
- Create the full directory tree for the iteration-01 system with all subdirectories.
- Scaffold the LICENSE, .gitignore, Python package, Terraform stubs, and operational scripts.
- Verify that terraform plan, pytest, and the Python package import all pass clean.
Create the Repo and Directory Skeleton
The program follows a systems/ layout where each iteration lives under a numbered subdirectory. This iteration is 01-sanitization-and-synthetic-data-middleware. The subdirectories cover RFCs, architecture diagrams, source code, infrastructure-as-code, tests, operational scripts, measurements, and build logs.
- Create a new directory called ai-government-systems-engineering and navigate into it.
mkdir ai-government-systems-engineering && cd ai-government-systems-engineering- Initialize a Git repository in this root directory.
git init- Create the full directory tree in a single mkdir -p command.
mkdir -p systems/01-sanitization-and-synthetic-data-middleware/{rfc,architecture,src/sanitize_midware,terraform,tests,scripts,measurements,build-log/2026/Q2}What does this command do?
The -p flag creates parent directories as needed, and the brace expansion {rfc,architecture,...} creates all sibling directories in one shot. This gives you the full skeleton without running multiple commands.
- Verify the tree was created correctly.
find systems -type d | sortYou should see 10 directories including rfc/, architecture/, src/sanitize_midware/, terraform/, tests/, scripts/, measurements/, and build-log/2026/Q2/.
Create the LICENSE, .gitignore, and Placeholder Files
Every file from this point forward lives under systems/01-sanitization-and-synthetic-data-middleware/. Navigate there now.
cd systems/01-sanitization-and-synthetic-data-middleware- Create the MIT LICENSE file.
cat > LICENSE << 'EOF'
MIT License
Copyright (c) 2026
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
EOF- Create the .gitignore combining the GitHub Python and Terraform templates with explicit entries for secrets and environment files.
cat > .gitignore << 'EOF'
# Python
__pycache__/
*.py[cod]
*$py.class
*.egg-info/
dist/
build/
.venv/
*.egg
.pytest_cache/
# Terraform
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
crash.log
# Secrets and environment
.env
.envrc
secrets/
EOFWhy a secrets/ directory in .gitignore?
The secrets/ exclusion is a defense-in-depth pattern. Even though this iteration handles only Class 1 synthetic data, the gitignore establishes the convention that any future secrets directory is automatically excluded. This prevents accidental commits of credentials in later iterations when real KMS key policies and boundary account configurations are in play.
- Create the empty placeholder files for cert-proof, architecture, build log, and measurements.
touch cert-proof.md
touch architecture/overview.md
touch build-log/2026/Q2/2026-04-20.md
touch measurements/readme-comprehension.mdWhy create empty files now?
These files are stubs. You will fill them with real content in Step 4. Creating them now ensures the directory tree is complete and verifiable in a single pass. It also means find . -type f | sort shows the full manifest at any point during the project.
Create the Python Package and Terraform Stubs
The Python package uses the src/ layout, which is the current Python packaging best practice. This avoids import confusion between the installed package and the source directory.
- Create src/sanitize_midware/__init__.py with the version string.
cat > src/sanitize_midware/__init__.py << 'EOF'
"""Sanitization and Synthetic Data Middleware - Iteration 01 scaffold."""
__version__ = "0.0.1"
EOF- Create src/sanitize_midware/audit.py with the hash-chain audit log schema as a commented-out docstring.
cat > src/sanitize_midware/audit.py << 'EOF'
"""Hash-chain audit log schema.
Each audit row contains a `prev_row_hash` field that is the SHA-256 hash
of the previous row, creating a tamper-evident chain. If any row is
modified or deleted, the chain breaks.
Schema fields:
tool - which AI tool was invoked
model - which model was used
prompt_hash - SHA-256 of the prompt (never the raw prompt)
response_hash - SHA-256 of the response
data_class - classification level of the data involved
redaction_summary - what was redacted and how
timestamp - ISO 8601 timestamp
prev_row_hash - SHA-256 of the entire previous row (the chain link)
This schema satisfies AU-2 (Event Logging) and AU-12 (Audit Record
Generation) by providing verifiable integrity of the audit trail.
Implementation arrives in a later iteration. This file defines the
contract only.
"""
# Future dataclass shape:
#
# @dataclass
# class AuditRow:
# tool: str
# model: str
# prompt_hash: str
# response_hash: str
# data_class: str
# redaction_summary: str
# timestamp: str
# prev_row_hash: str
EOFWhat is a hash-chain audit log?
Each row stores the SHA-256 hash of the previous row in its prev_row_hash field. This creates a tamper-evident chain: if any row is modified or deleted after the fact, the hash of the next row no longer matches, and the tampering is detectable. Notice that the schema stores prompt_hash and response_hash, never the raw prompt or response, to avoid storing sensitive data in the audit trail itself.
- Create the three Terraform stub files. The main.tf needs only a terraform {} block with a required_version constraint.
cat > terraform/main.tf << 'EOF'
terraform {
required_version = ">= 1.0"
}
EOF
cat > terraform/variables.tf << 'EOF'
# Variables will be defined as resources are added in later iterations.
EOF
cat > terraform/outputs.tf << 'EOF'
# Outputs will be defined as resources are added in later iterations.
EOFWhy Terraform stubs with zero resources?
A main.tf with only a terraform {} block produces a clean plan with zero resources. No providers are needed for this iteration. The point is to prove the IaC pattern is valid from day one, so later iterations add resources into an already-working Terraform workspace instead of debugging initialization issues alongside real infrastructure changes.
- Create the placeholder test file.
cat > tests/test_placeholder.py << 'EOF'
"""Placeholder test to verify pytest runs clean from iteration 01."""
def test_scaffold_exists():
"""Confirm the test harness is operational."""
assert True
EOF- Create the three operational script stubs and make them executable.
cat > scripts/spinup.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail
echo "[spinup] Iteration 01 - no resources to provision. Scaffold only."
EOF
cat > scripts/teardown.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail
echo "[teardown] Iteration 01 - no resources to tear down. Scaffold only."
EOF
cat > scripts/cost-check.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail
echo "[cost-check] Iteration 01 - \$0. No cloud resources provisioned."
EOF
chmod +x scripts/spinup.sh scripts/teardown.sh scripts/cost-check.shWhy stub operational scripts from day one?
Spinup, teardown, and cost-check scripts are artifacts that every iteration will need. Creating them as stubs now establishes the pattern so it never needs retrofitting. When iteration 05 adds real AWS resources, the scripts already exist and just need real commands added.
- Create pyproject.toml at the system root (the current directory).
cat > pyproject.toml << 'EOF'
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "sanitize-midware"
version = "0.0.1"
description = "Sanitization and Synthetic Data Middleware - Government AI Systems Engineering"
requires-python = ">=3.13"
[tool.setuptools.packages.find]
where = ["src"]
EOFNow verify everything is in place.
- Run find . -type f | sort to see the full file manifest.
find . -type f | sortWhat should I see?
You should see all of these files listed:
./.gitignore
./LICENSE
./architecture/overview.md
./build-log/2026/Q2/2026-04-20.md
./cert-proof.md
./measurements/readme-comprehension.md
./pyproject.toml
./scripts/cost-check.sh
./scripts/spinup.sh
./scripts/teardown.sh
./src/sanitize_midware/__init__.py
./src/sanitize_midware/audit.py
./terraform/main.tf
./terraform/outputs.tf
./terraform/variables.tf
./tests/test_placeholder.py- Verify the Python package import works.
PYTHONPATH=src python -c "from sanitize_midware import __version__; print(__version__)"This should print 0.0.1.
- Verify Terraform initializes and plans clean.
cd terraform && terraform init && terraform planWhat should I see?
You should see "Terraform has been successfully initialized" followed by "No changes. Your infrastructure matches the configuration." with 0 resources. This confirms the IaC workspace is valid even though no resources exist yet.
- Navigate back to the system root and run pytest.
cd ..
pytest tests/You should see 1 test collected and 1 passed.
- Verify the operational scripts run without error.
bash scripts/spinup.sh
bash scripts/teardown.sh
bash scripts/cost-check.shEach script should print its stub message and exit cleanly.
Terraform plan fails with "No configuration files"?
Check that your main.tf contains at least a terraform {} block with a required_version constraint. An empty .tf file is valid HCL but some Terraform versions emit a warning. Also make sure you ran terraform init before terraform plan. If you see provider-related errors, remove any required_providers block. No providers are needed for this iteration.
Still stuck? Help me debug my Terraform init issue.
Your directory skeleton is complete and every verification check passes clean. Next up, you will write the two-block README that makes this repo assessable by any ISSO in 30 seconds.
Write the Two-Block README
Your repo skeleton is in place with every directory, stub, and placeholder file ready. Now you need the artifact that every reviewer reads first: the README. Most engineers write READMEs as marketing copy. In a government AI program, the README is a compliance artifact. An ISSO or AO should be able to assess risk in 30 seconds without reading anything else in the repo.
In This Step, Get Ready To:
- Write the Data Handling and Commercial-to-GovCloud Mirror blocks at the top of the README.
- Write the 30-second summary, capabilities list, and downstream system dependencies.
- Stub the import section, measurable outcomes, and iteration status.
Write the Data Handling and Commercial-to-GovCloud Mirror Blocks
The two-block discipline is the genuinely new pattern in this project. Two structured blocks go at the very top of the README, immediately after the title and one-sentence description. They answer the two questions every security reviewer asks first: "What kind of data does this touch?" and "Where does this run?"
- Open systems/01-sanitization-and-synthetic-data-middleware/README.md in your editor.
- Add a level-1 heading and a one-sentence description of the system.
- Add the Data Handling block immediately below the description.
- Add the Commercial-to-GovCloud Mirror block immediately below the Data Handling block.
# Sanitization and Synthetic Data Middleware
Middleware for sanitization, synthetic data generation, and hash-chain audit logging for government AI systems.
## Data Handling
| Field | Value |
|---|---|
| **Data Classification** | Class 1 — Synthetic data only |
| **Data Source** | Generated synthetic datasets; NO production or agency data |
| **PII / CUI Presence** | None. NO real CUI, PII, FOUO, or classified data touches this system. |
| **Non-Real Flag Mechanism** | Every synthetic record carries a `synthetic: true` flag and a generation timestamp |
## Commercial-to-GovCloud Mirror
| Field | Value |
|---|---|
| **Current Environment** | AWS Commercial (us-east-1) |
| **Target Environment** | AWS GovCloud (us-gov-west-1) |
| **NIST 800-53 Rev 5 Controls** | AC-4, AU-2, AU-12, SC-8, SI-4 |
| **Portability Readiness** | 20 Terraform variable changes or fewer |
| **Boundary Account Pattern** | Dedicated boundary account with KMS key policy isolation |Why Two Blocks at the Top?
An ISSO reviewing your repo does not have time to read a full README. These two blocks give them the data classification and deployment target in 30 seconds. The Data Handling block answers "Can this system leak real data?" The Commercial-to-GovCloud Mirror block answers "Is this ready for a controlled environment?" Everything else in the README is context for engineers.
What Are These NIST 800-53 Controls?
Each control maps to a specific capability the middleware provides:
- AC-4 (Information Flow Enforcement): the middleware controls data flow between sanitization, inference, and downstream systems.
- AU-2 (Event Logging): the middleware defines what events get logged.
- AU-12 (Audit Record Generation): the hash-chain audit log is the implementation of this control.
- SC-8 (Transmission Confidentiality and Integrity): the middleware handles data in transit between sanitization and inference.
- SI-4 (System Monitoring): the audit log feeds the monitoring pipeline.
What Does "20 Terraform Variable Changes or Fewer" Mean?
AWS GovCloud uses two isolated regions: us-gov-west-1 and us-gov-east-1. GovCloud ARNs use arn:aws-us-gov: instead of arn:aws:. If your Terraform is well-parameterized, switching from commercial to GovCloud requires only changing region, ARN prefix, endpoint URLs, and account IDs. That is the portability claim you are documenting.
Write the 30-Second Summary, Capabilities, and Downstream Systems
Below the two blocks, the README shifts from compliance shorthand to engineering context. The 30-second summary explains the pain in plain English. The capabilities list tells engineers what the middleware provides. The downstream systems section tells them who depends on it.
- Add a 30-Second Summary section explaining the core problem: AI systems in government environments cannot use real data during development, and there is no standardized middleware for sanitization, synthetic generation, or audit logging.
- Add a What This System Provides section listing four capabilities as bullets.
- Add a Four Downstream Systems section listing each system with a one-sentence description of what it imports from this middleware.
## 30-Second Summary
AI systems in government environments cannot use real data during development.
There is no standardized middleware for sanitization, synthetic data generation,
or audit logging. Every team builds its own, creating incompatible implementations
that cannot be cross-audited. This middleware solves that.
## What This System Provides
- **Synthetic data generators** (4 types: tabular, text, image metadata, network telemetry)
- **2-path sanitization** (redact or replace) with configurable rulesets
- **Air-gapped inference pipeline** for models that must not reach external endpoints
- **Hash-chain audit log** providing tamper-evident records of every inference call
## Four Downstream Systems
1. **cATO Pipeline** — Imports audit log evidence for the Continuous Monitoring (CONMON) pillar. Without this middleware's hash-chain log, there is no automated evidence feed.
2. **Zero Trust Boundary Enforcement** — Imports sanitization status to make access decisions. The boundary enforcer needs proof that data has been classified and sanitized before transit.
3. **AI Threat Detection** — Imports inference telemetry (prompt hashes, response hashes, model identifiers) to detect adversarial prompt patterns.
4. **FedRAMP High Landing Zone** — Imports the audit log schema and data classification tags to satisfy customer-responsible controls in the AU and SI families.Why Does cATO Need This Middleware?
cATO (Continuous Authorization to Operate) replaces point-in-time ATO with continuous risk assessment. Its three pillars are Continuous Monitoring (CONMON), Active Cyber Defense (ACD), and Secure Software Supply Chain (SSSC). The CONMON pillar requires continuous audit evidence. Without the middleware's hash-chain audit log, there is no automated evidence feed for the CONMON pipeline. That dependency is why the middleware is built first.
Write the Import Stub, Measurable Outcomes, and Status
The final sections of the README establish forward references and measurable targets. The import stub tells downstream teams where integration instructions will live. The measurable outcomes section defines success criteria for the entire 22-iteration program. The status line tells any reader exactly where this system is in its lifecycle.
- Add a How to Import section with a stub note that real content arrives in iteration 19/20.
- Add a Measurable Outcomes at Series End section listing four metrics with targets.
- Add a Status line at the bottom.
## How to Import
> Stub. Integration instructions and package publishing will be documented in iterations 19 and 20.
> For now, downstream systems should treat the contract surfaces defined in
> [RFC-001](rfc/RFC-001-middleware-as-unblocker.md) as the source of truth.
## Measurable Outcomes at Series End
| Metric | Target | Defined In |
|---|---|---|
| Leak rate | 0 real-data leaks across all 22 iterations | This iteration |
| Throughput | TBD | Iteration 05 |
| Audit coverage | 100% of inference calls logged | This iteration |
| Latency | TBD | Iteration 07 |
## Status
Iteration 01 of 22. Scaffold complete, no code yet.Pro tip: stub with intent
The "TBD" entries in the measurable outcomes table are not laziness. They are intentional forward references to the iteration where the metric will be defined. This prevents premature commitments. When iteration 05 defines throughput targets, the README gets updated with real numbers. A reviewer seeing "TBD" with a specific iteration number knows the question has been scoped, not forgotten.
Verify your completed README by checking the following:
- Confirm the Data Handling block contains all 4 lines: data classification, data source, PII/CUI presence, and non-real flag mechanism.
- Confirm the Commercial-to-GovCloud Mirror block contains all 5 lines, including the exact NIST controls AC-4, AU-2, AU-12, SC-8, SI-4.
- Confirm the README explicitly states that NO real CUI/PII/FOUO/classified data touches this system.
- Try the 30-second test: can you identify the data classification, target environment, and number of downstream systems by reading only the top two blocks?
Your README is now a compliance-grade artifact, not marketing copy. Next up, you will write RFC-001 documenting the one-way-door decision to build this middleware before any downstream system.
Write RFC-001 Middleware as Unblocker
Your README establishes what this system is and who depends on it. Now you need to document why the middleware is built first. A program-level RFC is not a design doc for a feature. It is a one-way-door decision record that downstream teams will cite for years when someone asks "why can't I just do my own sanitization?"
In This Step, Get Ready To:
- Write the Status, Context, and Decision sections of RFC-001.
- Define contract surfaces for all four downstream systems in the Consequences section.
- Document two rejected alternatives with clear rationale for each.
Write the Status, Context, and Decision Sections
The Status of this RFC is "Accepted" because building the middleware first is a one-way-door decision. Once downstream systems start depending on these contract surfaces, reversing the decision means rearchitecting four systems. The Context section carries the argumentative weight. It needs to explain why the middleware is the unblocker for the entire program.
- Create the file rfc/RFC-001-middleware-as-unblocker.md.
- Add a title: RFC-001: Sanitization and Synthetic Data Middleware as Program Unblocker.
- Set Status: Accepted with the current date.
- Write the Context section (target 400-600 words).
The Context section must establish the core dependency problem. The four downstream systems all need sanitized data and audit logs, but none of them can produce those capabilities themselves.
Your Context section should cover these points:
- AI systems in government environments cannot use real data during development. There is no standardized middleware for sanitization, synthetic generation, or audit logging.
- Name the four downstream systems: cATO pipeline, Zero Trust boundary enforcement, AI Threat Detection, and FedRAMP High Landing Zone.
- Explain that without centralized middleware, each downstream system would independently solve sanitization, creating four incompatible implementations.
- Reference that cATO requires continuous audit evidence. The three pillars (Continuous Monitoring, Active Cyber Defense, Secure Software Supply Chain) all depend on a verifiable audit trail that the middleware provides.
- State explicitly that NO real CUI/PII/FOUO/classified data is involved. This system handles Class 1 synthetic data only.
After the Context, write the Decision section (target 200-400 words).
- State the decision clearly: build the sanitization and synthetic data middleware first, before cATO or any other downstream system.
- Explain that this decision is one-way-door because once downstream systems integrate against the middleware's contract surfaces, reversing the build order means rearchitecting all four consumers.
- Reference the 22-iteration program structure. The middleware is iteration 01. Downstream systems begin integration in later iterations.
What Is a One-Way-Door Decision?
A one-way-door decision is one that is difficult or impossible to reverse once downstream dependencies form around it. In this program, once the cATO pipeline starts consuming the middleware's audit log format and the Zero Trust system depends on the sanitization API shape, changing the middleware's contract surfaces would break all four downstream systems simultaneously. That is why this decision gets an RFC, not a Slack thread.
Why a Program-Level RFC Instead of a Design Doc?
A design doc describes how to build a feature. A program-level RFC documents a sequencing decision that constrains the entire build order across multiple systems. Design docs are read by the team building the feature. Program-level RFCs are read by every downstream team lead who needs to understand why their system cannot start until this one ships.
Write the Consequences Section With Contract Surfaces
The Consequences section is what makes this RFC a living document. When a downstream team asks "why can't I just do my own sanitization?", the answer lives here. For each of the four downstream systems, you need to define exactly what it inherits, what interface it depends on, and what breaks if the middleware decision is reversed.
- Write the Consequences section (target 400-600 words).
- For each downstream system, define three things: what it imports from the middleware, the interface it depends on (function signature, data format, or API shape), and what would break if the middleware decision were reversed.
Here is what each downstream system's contract surface should cover:
- cATO pipeline: imports the hash-chain audit log. Depends on the audit row schema (tool, model, prompt_hash, response_hash, data_class, redaction_summary, timestamp, prev_row_hash). Without the middleware, cATO has no automated evidence feed for its Continuous Monitoring pipeline.
- Zero Trust boundary enforcement: imports the sanitization function's data classification output. Depends on the data_class field to enforce boundary crossing rules. Without the middleware, Zero Trust has no classification signal to gate data flow.
- AI Threat Detection: imports prompt and response hashes for anomaly detection. Depends on the prompt_hash and response_hash fields being SHA-256. Without the middleware, threat detection would need to compute its own hashes, duplicating logic and risking inconsistency.
- FedRAMP High Landing Zone: imports the redaction_summary for compliance evidence. Depends on the middleware proving that sensitive data was handled according to NIST 800-53 AC-4 (Information Flow Enforcement) and SC-8 (Transmission Confidentiality and Integrity). Without the middleware, the Landing Zone has no application-level evidence for the customer-responsible controls.
Why Are Customer-Responsible Controls the Gap?
FedRAMP High covers 421 controls across 17 families. AWS GovCloud meets the FedRAMP High baseline at the infrastructure level, but over 60% of controls are customer-responsible. Tools like the Landing Zone Accelerator provide the infrastructure baseline but not the application-level controls (AC, AU, IA, SC, SI). The middleware's audit log and sanitization directly address this application-level gap.
Write the Alternatives Considered Section
Every strong RFC documents the roads not taken. This section prevents future engineers from re-litigating the decision by showing that the alternatives were already evaluated and rejected with clear reasoning.
- Write the Alternatives Considered section documenting two rejected alternatives.
Document these two alternatives and why each was rejected:
- Alternative 1: Lead with cATO and retrofit middleware later. Rejected because cATO needs audit evidence from day one. The Continuous Monitoring pillar requires a verifiable audit trail. Without the middleware's hash-chain audit log, there is no automated evidence feed for the CONMON pipeline. Retrofitting the audit format later would break any monitoring integrations already built against a different schema.
- Alternative 2: Each downstream system builds its own sanitization. Rejected because it creates four incompatible data classification schemes. Cross-system audit correlation becomes impossible when each system defines data_class differently. The Zero Trust system cannot gate data flow if the cATO system classifies data one way and the Landing Zone classifies it another.
After writing all sections, verify the word count.
- Run wc -w to check the total word count.
wc -w rfc/RFC-001-middleware-as-unblocker.mdWhat Should I See?
The output should show a number between 1,500 and 2,500. If you are under 1,500, your Context or Consequences sections likely need more detail on the specific contract surfaces. If you are over 2,500, look for repeated arguments or overly detailed interface specifications that belong in a separate design doc, not in the RFC.
Pro tip: anchor to AU-2 and AU-12
When writing the cATO contract surface, reference NIST 800-53 AU-2 (Event Logging) and AU-12 (Audit Record Generation) explicitly. AU-2 defines what gets logged. AU-12 defines how audit records are generated. The middleware's hash-chain audit log is the implementation of both controls. Citing specific control IDs makes the RFC auditor-readable, not just engineer-readable.
Your RFC-001 is complete. This is the document that downstream teams will reference when they need to understand why the middleware exists and what they can depend on. Next, you will fill in the remaining artifacts: the cert-proof stub, architecture placeholder, build log, and the reviewer comprehension exercise.
Write the Remaining Artifacts
Your README and RFC are the heavyweight artifacts. Now you need to fill in the supporting files that round out the scaffold: the certification evidence stub, the architecture sketch, the build log, the audit schema docstring, and the reviewer comprehension exercise.
These artifacts look small individually. Together, they establish patterns that every future iteration inherits. A build log that exists from day one never needs retrofitting. A reviewer exercise that ships with the repo proves the documentation works, not just that it exists.
In This Step, Get Ready To:
- Write the cert-proof stub and architecture placeholder with an ASCII diagram.
- Write the build log entry and the hash-chain audit docstring.
- Create the reviewer comprehension exercise with 5 questions and a timing template.
Write Cert-Proof.md and Architecture/Overview.md
The cert-proof.md file tracks certification evidence that ties back to the system's boundary design. In a government program, auditors ask for proof that the engineers building the system hold relevant certifications. Stubbing this from iteration 01 means the file is never forgotten during an audit scramble.
- Open cert-proof.md in your editor.
- Add the following content.
# Certification Evidence
## AWS Solutions Architect – Professional (SAP)
- **Status**: In-progress
- **Date started**: 2026-04-20
- **Expected completion**: 2026-Q3
## Relevance
This systems boundary design and KMS key policy architecture are part of
the certification evidence for the sanitization and synthetic data
middleware. The SAP certification validates the engineer's competence in
designing multi-account, multi-region architectures with encryption at
rest and in transit.
## Updates
This file will be updated as the certification progresses.
Final evidence (certificate number, date) will be recorded here.Now create the architecture placeholder. The full architecture diagram arrives in iteration 21. For now, an ASCII sketch establishes the middleware's position in the system.
- Open architecture/overview.md in your editor.
- Add the following content.
# Architecture Overview
> Placeholder – full diagram arrives in iteration 21.
## System Position (ASCII Sketch)
```
┌──────────────────┐
│ Data Sources │
│ (synthetic only)│
└────────┬─────────┘
│
▼
┌──────────────────────────────────────┐
│ Sanitization & Synthetic Data │
│ Middleware (this system) │
│ │
│ - Synthetic generators (4 types) │
│ - 2-path sanitization │
│ - Air-gapped inference pipeline │
│ - Hash-chain audit log │
└──┬─────────┬──────────┬─────────┬───┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────┐ ┌────────┐ ┌────────┐ ┌──────────┐
│ cATO │ │Zero │ │AI │ │FedRAMP │
│ │ │Trust │ │Threat │ │High │
│ │ │Boundary│ │Detect │ │Landing │
│ │ │Enforce │ │ │ │Zone │
└──────┘ └────────┘ └────────┘ └──────────┘
```
## Notes
- All data flowing through the middleware is Class 1 synthetic only.
- NO real CUI/PII/FOUO/classified data touches this system.
- The four downstream systems import sanitized data and audit evidence
from this middleware.Why Stub the Architecture Now?
The sketch is intentionally rough. Its purpose is to claim the file path and establish the four-downstream-system relationship in a visual format. When iteration 21 replaces this with a full diagram, the file path stays the same. Every link, reference, and CI check that points to architecture/overview.md continues to work.
Write the Build Log Entry and Audit.py Hash-Chain Docstring
The build log is a daily engineering journal for the program. It records decisions, open questions, and what was shipped. The audit.py docstring defines the hash-chain schema that satisfies AU-2 (Event Logging) and AU-12 (Audit Record Generation) before any code exists.
- Open build-log/2026/Q2/2026-04-20.md in your editor.
- Add the following content.
# Build Log – 2026-04-20
## What Was Done
- Scaffold created for iteration 01 (sanitization and synthetic data middleware).
- RFC-001 (Middleware as Unblocker) written and accepted.
- Reviewer comprehension exercise planned.
- All stubs in place: Python package, Terraform, scripts, cert-proof, architecture.
## Decisions Made
1. **Middleware before cATO**: RFC-001 documents the rationale. The four
downstream systems (cATO, Zero Trust, AI Threat Detection, FedRAMP High
Landing Zone) all depend on sanitized data and audit logs that only
the middleware provides.
2. **Hash-chain audit log**: Schema defined in `audit.py` docstring.
Implementation deferred to iteration 03.
3. **Two-block README discipline**: Data Handling and Commercial-to-GovCloud
Mirror blocks established as the standard for all 22 iterations.
## Open Questions
- What synthetic data generator types will iteration 02 prioritize?
- Should the hash-chain use SHA-256 or SHA-3? (Leaning SHA-256 for
FIPS 140-2 compatibility.)
- When does the first real `terraform apply` happen? (Tentatively iteration 04.)
## Reviewer Exercise
- Status: Template created, exercise not yet run.
- Results will be appended after execution.Now update the audit schema docstring. The hash-chain approach creates a tamper-evident log. Each row contains a prev_row_hash field that is the SHA-256 hash of the previous row. If any row is modified or deleted, the chain breaks. This is the pattern that feeds the cATO continuous monitoring pipeline.
- Open src/sanitize_midware/audit.py in your editor.
- Replace the file contents with the following.
"""
audit.py – Hash-chain audit log schema for sanitization middleware.
Approach
--------
Each audit row contains a `prev_row_hash` field that stores the SHA-256
hash of the entire previous row (serialized as canonical JSON). This
creates a tamper-evident chain: if any row is modified, inserted, or
deleted after the fact, the chain breaks and the tampering is detectable.
This pattern satisfies:
- AU-2 (Event Logging): defines the event types logged.
- AU-12 (Audit Record Generation): provides the generation mechanism.
Schema (not implemented yet – target iteration 03)
--------------------------------------------------
Each row is a dictionary (or dataclass) with these fields:
{
"tool": str, # which AI tool was invoked
"model": str, # which model was used
"prompt_hash": str, # SHA-256 of the prompt (never the raw prompt)
"response_hash": str, # SHA-256 of the response
"data_class": str, # classification level of the data involved
"redaction_summary": str, # what was redacted and how
"timestamp": str, # ISO 8601 timestamp
"prev_row_hash": str, # SHA-256 of the previous row (the chain link)
}
Notes
-----
- Prompt and response are NEVER stored in plaintext. Only their hashes
are recorded. This prevents the audit log itself from becoming a
sensitive data store.
- The first row in the chain uses a well-known genesis hash
(e.g., SHA-256 of the empty string).
- All data passing through this system is Class 1 synthetic only.
NO real CUI/PII/FOUO/classified data is involved.
"""Why Hash the Prompt Instead of Storing It?
Storing raw prompts in the audit log would turn the log itself into a sensitive data store. By recording only the SHA-256 hash, you can verify that a specific prompt was used without exposing its contents. An investigator who holds the original prompt can hash it and confirm it matches the log entry.
Write the Reviewer Comprehension Exercise Template
This is the artifact that proves your README works. Most documentation is never tested. This exercise treats the README as a system under test. A reviewer reads only the README and answers 5 questions. If they score below 5/5 or take more than 2 minutes, the README has a bug.
- Open measurements/readme-comprehension.md in your editor.
- Add the following content.
# README Comprehension Exercise
## Purpose
This exercise tests whether the README communicates critical information
effectively. The reviewer reads ONLY the README and answers the questions
below. Target: 5/5 correct in under 2 minutes.
If the reviewer misses a question or exceeds 2 minutes, the README has a
bug. Revise the README and re-run.
## Questions
1. What data classification does this system handle?
2. Which NIST 800-53 controls are cited in the README?
3. How many downstream systems depend on this middleware?
4. Is any real CUI/PII/FOUO/classified data involved?
5. What iteration is this, and how many total iterations are in the program?
## Timing Template
| Field | Value |
|----------------|-------|
| Reviewer name | |
| Start time | |
| End time | |
| Elapsed time | |
| Score (out of 5)| |
## Answer Key (for scorer only)
1. Class 1 synthetic data only.
2. AC-4, AU-2, AU-12, SC-8, SI-4.
3. Four (cATO, Zero Trust, AI Threat Detection, FedRAMP High Landing Zone).
4. No. NO real CUI/PII/FOUO/classified data touches this system.
5. Iteration 01 of 22.
## Results Log
(Append results after each run.)
### Run 1
- Date:
- Reviewer:
- Elapsed time:
- Score:
- README revisions needed (if any):Pro tip: test your own README first
Before handing the exercise to a colleague, close the README, wait 5 minutes, then try answering the questions yourself from memory. If you wrote the README and still hesitate on a question, a fresh reviewer will definitely struggle. Fix the README before the real test.
Every supporting artifact is now in place. Your scaffold has a cert-proof stub, an architecture sketch, a build log with today's decisions, a hash-chain audit schema, and a reviewer exercise ready to run. Next up, you will execute that exercise and run the full verification suite to prove everything is clean.
Run the Reviewer Exercise and Final Verification
You have every artifact in place. Now you prove it works. The reviewer comprehension exercise is the final quality gate for your README. If a qualified reviewer cannot answer five basic questions in under two minutes, the README fails, not the reviewer.
In This Step, Get Ready To:
- Execute the reviewer comprehension exercise and record measured results.
- Run the full verification suite across Terraform, pytest, and file structure.
- Update the build log with final results and commit everything to GitHub.
Run the Reviewer Exercise
The README is the artifact under test here. The reviewer is the instrument. If the instrument gives a bad reading, you fix the artifact, not the instrument.
- Pick a colleague or simulate one yourself. If simulating, close all files except the README.
- Open measurements/readme-comprehension.md and review the five questions.
- Start a timer and hand the reviewer only the README.
- Have the reviewer answer all five questions from memory of the README alone.
- Stop the timer when the reviewer finishes.
- Record the results in the timing template: reviewer name, start time, end time, elapsed time, and score out of 5.
The target is 5/5 correct in under 2 minutes. The five questions are:
- What data classification does this system handle?
- Which NIST 800-53 controls are cited?
- How many downstream systems depend on this middleware?
- Is any real CUI/PII/FOUO/classified data involved?
- What iteration is this, and how many total?
What if the reviewer misses a question or takes too long?
Go back to your README and fix the problem. The most common failures are burying the data classification below the fold, omitting the NIST control identifiers from the mirror block, or writing the downstream systems section as prose instead of a scannable list. Revise and re-run the exercise until the target is met.
Here is an example of what the completed timing template looks like in measurements/readme-comprehension.md:
## Reviewer Comprehension Results
| Field | Value |
|----------------|--------------------|
| Reviewer | J. Martinez |
| Start time | 14:02:00 |
| End time | 14:03:38 |
| Elapsed | 1m 38s |
| Score | 5/5 |
### Answers
1. Class 1 synthetic data only
2. AC-4, AU-2, AU-12, SC-8, SI-4
3. Four downstream systems
4. No real CUI/PII/FOUO/classified data
5. Iteration 01 of 22Pro tip: self-simulation
If you are simulating the reviewer yourself, close the README after reading it, then answer from memory. Do not scroll back. The point is to test whether the two-block discipline made the critical facts stick in a single pass.
Run the Full Verification Suite
Every verification check from the previous steps runs again now as a final gate. This confirms nothing broke while you were writing artifacts.
- Navigate to the terraform/ directory and run the Terraform verification.
cd terraform && terraform init && terraform planWhat should I see?
You should see "No changes. Your infrastructure matches the configuration." with 0 resources to add, change, or destroy. This confirms the Terraform stubs are clean.
- Navigate back to the system root and run pytest.
cd ..
pytest tests/What should I see?
You should see 1 test collected, 1 passed. The placeholder test confirms the pytest harness is wired correctly.
- Check the RFC-001 word count.
wc -w rfc/RFC-001-middleware-as-unblocker.mdWhat should I see?
The word count should be between 1,500 and 2,500. If it is under 1,500, the Consequences section likely needs more detail on the contract surfaces. If it is over 2,500, the Context section is probably over-explaining background that the target audience already knows.
- Verify the full file tree.
find . -type f -not -path './.git/*' | sortConfirm every expected file is present. Cross-reference against the directory structure you created in Step 1.
- Commit everything and push to GitHub.
git add -A
git commit -m "Iteration 01: scaffold complete, RFC-001 written, reviewer exercise passed"
git push origin mainPush failing with authentication errors?
If you have not set up your GitHub remote yet, add it before pushing. Replace the URL with your actual repository URL. If you are using HTTPS, you may need a personal access token instead of a password. Help me troubleshoot my GitHub push.
Record Final Results in the Build Log
The build log is your operational record. It captures what happened, what was decided, and what comes next. Updating it after verification closes the loop on this iteration.
- Open build-log/2026/Q2/2026-04-20.md.
- Add a Verification Results section with the following entries.
## Verification Results
- **Terraform plan**: 0 resources planned (clean)
- **pytest**: 1 collected, 1 passed
- **RFC-001 word count**: [YOUR_COUNT] (target: 1,500-2,500)
- **Reviewer exercise**: [SCORE]/5 in [TIME] (target: 5/5 under 2 min)
- **All files committed**: Yes
- **Pushed to GitHub**: Yes
## Next Iteration
Iteration 02 covers data-class tagging primitives. Will implement the
`DataClass` enum, the tagging function, and the first real pytest tests
against the classification logic.What does this command do?
This is not a command. It is a markdown block you append to the existing build log entry. The verification results section creates a permanent record that this iteration's quality gates were met. The next iteration pointer ensures continuity across the 22-iteration program.
- Replace [YOUR_COUNT] with your actual wc -w output, [SCORE] with the reviewer's score, and [TIME] with the elapsed time.
- Save the file.
- Commit and push the updated build log.
git add build-log/2026/Q2/2026-04-20.md
git commit -m "Build log: verification results and reviewer exercise recorded"
git push origin mainYour iteration 01 scaffold is complete. Every artifact is in place, every verification check has passed, and the reviewer exercise has proven that your README communicates critical information in under two minutes. Iteration 02 will bring the first real code: the DataClass enum and tagging function that the hash-chain audit log depends on.
Secret mission
Add Program-Level Security and Contribution Governance
Most open-source repos ship with SECURITY.md and CONTRIBUTING.md from day one. Most government program repos forget both until an auditor asks. This stretch challenge adds vulnerability disclosure and RFC submission governance before anyone has to ask.
Before you go
Clean Up Your Resources
This project runs entirely locally with no cloud resources provisioned and no paid services. There are no ongoing costs. Decide whether to keep your resources as-is, pause them to come back later, or delete them entirely.
Resources you used:
- Local Git repository at ai-government-systems-engineering/ with the full directory tree.
- GitHub remote repository.
- Terraform local state file (.terraform/ directory created by terraform init).
- Python package stub (src/sanitize_midware/).
- Documentation artifacts (README, RFC-001, cert-proof, architecture overview, build log, reviewer exercise).
Keep everything running
No action needed. Choose this if you are still actively building and plan to continue to Iteration 02 (data-class tagging primitives) soon.
- Your local repo and GitHub remote stay as they are.
- The .terraform/ directory contains only initialization metadata and uses negligible disk space.
- No cloud resources are running, so there is nothing to accrue cost.
Pause - I'll come back to this later
Free up local disk space from generated artifacts while keeping your source files and GitHub remote intact.
- Remove the Terraform initialization directory by running rm -rf terraform/.terraform from the system root.
- Remove any __pycache__/ and .pytest_cache/ directories by running find . -type d -name '__pycache__' -exec rm -rf {} + && find . -type d -name '.pytest_cache' -exec rm -rf {} +.
- Confirm your latest commit is pushed to GitHub so you can re-clone later.
- When you return, run terraform init from the terraform/ directory to reinitialize.
Delete - I don't want to use this again
Remove all project resources from your local machine and GitHub.
- Delete the local repository by running rm -rf ai-government-systems-engineering/ from the parent directory.
- Delete the GitHub repository by going to your repo's Settings page, scrolling to the Danger Zone section, and selecting Delete this repository.
- Confirm the deletion by typing the repository name when prompted.
Mission accomplished
That's a Wrap!
Nice work! You just scaffolded a production-grade government AI systems engineering repo with zero running code and zero cloud resources. Every program-level artifact pattern is in place from day one, ready to survive Staff-level review and auditor scrutiny.
Here's what you built and learned:
- A two-block README with the Data Handling and Commercial-to-GovCloud Mirror discipline that an ISSO can assess in 30 seconds, verified by a timed reviewer comprehension exercise.
- A program-level RFC-001 documenting the one-way-door middleware-first decision with contract surfaces defined for four downstream systems: cATO pipeline, Zero Trust boundary enforcement, AI Threat Detection, and FedRAMP High Landing Zone.
- A hash-chain audit log stub, Terraform stubs producing a clean terraform plan with zero resources, passing pytest, and operational script stubs so the pattern never needs retrofitting.
- Security and contribution governance artifacts (SECURITY.md and CONTRIBUTING.md) with vulnerability disclosure policy and RFC submission process that survive audit.
Ready to quiz yourself?