ADR Enforcement¶
This directory holds the machine-readable part of ADR enforcement.
The #2090 verification and adoption design applies existing quality-ownership, test-boundary, browser-security and repository identity rules to command and evidence reconciliation. It adds no check, exception, delivery assertion or live qualification claim.
ADR-068's gateway replacement evaluation records the clarified #2274 scope, maintained-product comparison, selected LiteLLM OSS edition, deployment-owned rotation and proposed qualification. Its registry evidence pointer adds no executable check, exception or runtime support claim. Broker parking and the supported keyless-direct path remain unchanged until a separate adoption/cutover decision.
The GCP model-broker IAM guard accepts the cluster-derived
var.workload_identity_pool reference for its exact Kubernetes service account
binding. The owning GKE output is resource-backed so fresh bootstrap creates the
pool before bindings; the allowed role, namespace and service account are unchanged.
The GCP gcp-foundation bootstrap applies the existing purpose-scoped identity
root before runners, images, and platform infrastructure. Its optional private
image-build VPC has no runtime/runner peering, admits builder and validator
management only through IAP, and remains in the independent foundation state.
The option defaults off for existing deployments. Target project/repository IDs
are checked before writes; targeted bootstrap tests and Terraform validation
cover the first-project ordering (ADR-004 purpose separation; ADR-008 private
operator access).
Native GCE image builds explicitly select GCP_RANGE_BACKEND=gce to omit the
GDC-only disk export dependency. Builds retain their immutable image evidence.
Each guest build calls the validation workflow for its exact candidate, and
publishes the image only after validation passes (#2668). A release selects the
published guest images; a deployment imports them after it verifies their build
provenance. No image-promotion workflow exists.
SDK candidate distributions from pull-request CI include their SHA-256 checksums
and are retained under a revision-specific artifact name for independent adapter
builds. Candidate retention grants no publishing authority. The provisional SDK
publishing scaffold remains restricted to main and adapter-sdk-pypi, dormant
pending the release-model decision in #2241. Local wheel qualification requires
no SDK publication.
Files¶
index.yaml: accepted ADRs and their enforceable rulesexceptions.yaml: time-bounded exceptions to specific rules
The files use JSON syntax with a .yaml extension so they stay human-readable while remaining parseable by the standard library.
The #2555 rename preflight applies GEN-002 to repository identity, compatibility and future-deployment templates under the recorded no-deployments premise. It distinguishes registry validity from live enforcement, preserves fail-closed quality routing and names the existing config, secret-admission and provenance owners. It adds no ADR, check, exception or runtime support claim. Renaming cannot waive expired exceptions or missing blocking quality owners; Ground Control project and requirement identities remain independent of the GitHub slug.
ADR-058 records the participant-control realization design under GEN-2005. It is design policy, not a new executable interface contract. Existing registry, guardrail and import checks validate structure; they do not prove the runtime guarantees. Mechanism implementation and real-boundary evidence are required before support is advertised.
The #1583 preparation preflight
applies GEN-002 to ADR-034-R9 and the existing ingestion, authority and worker
boundaries. Its enforcement/evidence matrix distinguishes registry validation
from runtime proof and records the required local/CI routing. It introduces no
new ADR or check. Runtime enforcement now includes exact-image Job admission,
installed IAM/Kubernetes readback, separate worker identities, and fenced
inventory admission. Their behavioral tests complement the repository guards;
the layer-imports check scans the separately built preparation worker through
separate candidate-selection and import-extraction helpers while preserving the
ADR-031 shared-RAES-facade restriction. This keeps the worker check
independently maintainable without changing its enforced boundary.
the operator procedure and
qualification record describe
how the deployed boundaries are exercised.
The documentation coverage manifest links the operator guide and technical
design from the feature and platform indexes under GEN-001.
The #2463 feature-artifact acquisition preflight records ADR-034-R11 and ADR-034-R12 (platform-owned recipe acquisition of backend-owned feature artifacts, tracked in an Engine-owned inventory, acquired once before ranges need them, failing per range) and the matching ADR-034-R4, R6 and R7 and ADR-032-R3 and R9 amendments (streaming delivery with no fixed payload cap). It introduces no new check; the rules are design policy until the implementation lands with its behavioral tests.
The same qualification corrected ADR-008-R7's GCP dynamic-secret conditions. The closed roles contain only Secret Manager permissions; fully qualified secret-name prefixes constrain their resource access. The conditions omit the additional resource-type predicate that rejected real workload calls, and participant suffix checks extract the parent secret ID from version names. The Terraform guard still rejects expanded prefixes, workload-secret access, additional permissions and conditions exceeding Google's complexity limit. Live provisioner probes cover absent and present secrets, creation, version publication, readback, deletion and denied platform-secret access. Portal probes verify both latest and numbered participant versions while rejecting host and directory credentials.
Runtime Enforcement¶
ADR-031-R7 separates trial archive custody from operational sidecars.
CMS stores tenant destination, transfer, and receipt metadata.
The custody design describes the validation and commit boundaries.
The service contract defines the receipt and recovery behavior.
The existing layer checks confine portable RAES validation to shared.raes.
Targeted archive and PostgreSQL service tests verify custody, identity, access, and retention.
No new guard exception or deployment setting is introduced.
ADR-004-R23 generalizes the GCP CI identity module: purpose-separated build, validate, release-scan, deploy and destroy identities are rendered from explicit per-deployment inputs rather than tenant-name branches. The source WIF guard enforces the generic template with pinned CKV_GCP_125 success and no Checkov waiver; numeric repository/owner IDs and exact workflow/ref/Environment tuples are mandatory, and native Terraform tests are registered in the root validation inventory. One project hosts each deployment, its runner and automation identities; deploy and destroy retain trusted project-administration authority. Optional two-project support is deferred. Source-guard regression tests mutate the real module defaults and outputs to cover all retained role, permission and output restrictions.
ADR-063 records the signed CTF receipt binding preflight for #1906. It fixes trusted context, protected signer/key registration, lifecycle fencing and atomic replay evidence while preserving existing validator contracts. The #1906 source implementation supplies runtime, registration, compatibility, replay and provider-conformance evidence. Registry and import checks validate design structure; fresh deployed two-generation evidence remains the #1910 composition gate. This ADR adds no exception.
ADR-011-R9 records the configurable range lease preflight for #27. It binds installation/runtime policy ownership, generation snapshots, extension admission and reuse of canonical cleanup. Registry checks validate this guidance; configuration, migration, concurrency, warm-claim and deployment behavior still require implementation evidence. No runtime check or exception is added here.
Issue #2169's runtime lease-policy preflight extends that rule with a CMS-owned tenant/group overlay, deterministic multi-group resolution, the existing per-generation owner extension, and an explicit separation from workspace tenancy. The CMS models and resolver, revision-checked and strict-audited admin API/UI, cold/warm assignment snapshots, generated contract, SQLite behavior tests, and PostgreSQL concurrency test are the executable evidence for that rule. Provider paths consume the same persisted deadline state and contain no lease-policy branch.
Proposed ADR-059, ADR-060 and ADR-061 record the #681 model-access design: a deployment-owned broker, Engine-owned allocation and mandatory budgets, and evidence-based revocation/operation. Their registry entries are proposed design policy. Existing import and registry checks validate structure; they do not prove the future broker, accounting, cloud isolation or release claims. Implementation and qualification ownership is explicit in the linked backlog.
Accepted ADR-064 supersedes ADR-059's "no-service-account guest default" for GCP: range guests receive a default-on, keyless predict-only Vertex model identity via Workload Identity, mutually exclusive per range with the broker.
Accepted ADR-068 supersedes ADR-067 and the parked broker design in ADR-059, ADR-060 and ADR-061. The broker is parked and not supported for use, and keyless-direct (ADR-064) is the only live guest model path. Any future model access control path is a transparent proxy whose controls are optional, with no controls by default.
The enforcement entrypoint is:
Optionally pass explicit check names as positional arguments:
Current mechanisms:
scripts/adr_guard/adr_guard.py: repo-native policy runneradr-registrytyped interface contracts: accepted ADRs whose closed shape is itself an executable invariant must retain their registered contract kind and exact fields. ADR-032 usesraes-plan-accessor-boundary/v1to pin the serialized-plan ownership split, RAES-free provisioner, fail-closed access, canonical naming identity, exact-pin compatibility evidence, and #2082 delivery boundary. The superseded ADR-054 entry retains itsdedicated-customer-authority/v1shape as historical evidence; ADR-066 is the current customer/deployment decision and carries forward only the named independent-authority, infrastructure-owner, fail-closed, and evidence rules. ADR-055 usesaccessibility-enforcement/v1to pin the WCAG target, incumbent axe/Playwright toolchain, execution cadence, coverage inventory, non-growing finding baseline, manual-audit evidence, central waiver policy, and scanner security posture. These structural checks do not claim that runtime, cloud, browser, or audit evidence has run; those tests remain mandatory at their owning boundary.lilrae-identity-boundary: ADR-024-R6 terminology enforcement. Current architecture prose treats LilRAE and APTL as one identity across a rename, treats TechVault only as a scenario pack, and requires retired TechVault implementation notes to carry a historical boundary while preserving exact commands, paths, symbols, image keys, workflow names, release history, and externalaptl:*locators.scripts/adr_guard/boundary_mock_baseline.json: current legacy first-party internal mock-patch counts for ADR-019. Counts may shrink as tests move to behavioral assertions, but new or increased internal patch counts, including baseline allowance increases against the branch reference, fail theboundary-mock-policycheck. For example, splittingcms/experiments/orchestrator.pyinto a package (#886) moved its test suites onto real-model / cloud-boundary assertions and dropped the associatedcms.experiments.orchestrator.*baseline allowances. Likewise, the CTF god-module decomposition (#683) converted the notification and event lifecycle suites to behavioral coverage (real ORM plus SMTP/template boundary patches only) and dropped theirctf.services.notification.*/ctf.services.event.*allowances..pre-commit-config.yaml: intentionally fast local boundary- The
Deployworkflow's always-presentPre-commitjob runs the file-hygiene and secret-scan subset (trailing-whitespace,end-of-file-fixer, YAML/JSON checks, large-file and merge-conflict checks, private-key detection, and gitleaks) and feedsPR Gate, so protected-branch PRs cannot bypass that baseline through path filters. - Local execution retains commit-message policy, file hygiene, private-key and gitleaks secret detection, and lightweight language formatting/linting. Type checks, architecture and policy guards, IaC validation/security scanners, migration checks, and test suites are CI-only so a commit does not reproduce the repository-wide pipeline.
- GCP bootstrap and deployment migration Jobs explicitly disable model access
and clear its catalog path/digest: these database-only Jobs do not mount the
runtime catalog. Model-broker pods use their application group as
fsGroupso their non-root process can read the projected 0440 fingerprint files. The dedicated provisioner-launcher Role grantsliston pods only in the jobs namespace so cancellation can confirm that foreground Job deletion removed every pod. It grants no pod mutation, log, or exec access (ADR-006-R4). Range-access NetworkPolicies also select the ephemeral post-deploy smoke Job so its documented SSH/RDP probe can reach guests; destination CIDRs and ports remain identical to the existing portal/guacd access boundary. .github/workflows/_quality.yml: CI architecture gate. Every quality unit it routes is declared in the.github/quality-path-filters.yamlcontract (ADR-004-R24), which thequality-path-ownershipcheck reconciles against the whole tracked estate.uat/range-functional-smoke/**is such a unit (range-functional-smoke-lint/-sast/-tests). Its CI jobs cover the harness's deterministic layers only: the harness itself drives a deployed tenant and a live range, so it is operator-invoked and deliberately has no CI execution job and gates no deploy (issue #987). Guard implementation modules remain below the CI file-length threshold; formatting-only maintenance must preserve that bound without changing the guard's exported behavior. Its SonarCloud job restores coverage artifacts, sets up Temurin Java 21, and disables SonarScanner JRE auto-provisioning so the quality gate does not depend on downloading a runtime during analysis. The job uses Node 24-backed action majors for checkout, artifact restore, Java setup, and the SonarQube Cloud scan so runner deprecation warnings do not mask real SonarCloud quality findings. Manual deployment scans explicitly pass the selected Git branch throughsonar.branch.name: scanner auto-detection does not identify branches forworkflow_dispatch, which otherwise publishes tenant analysis to the Sonar project's main branch. Pull-request and push analysis retain auto-detection.- Repository branch protection for
mainanddevrequires the aggregatePR Gate, CodeQL, andLint PR titlewith strict up-to-date status checks. The title-lint workflow triggers on PRs against both branches so the required context reports on each; a required context whose workflow cannot trigger for a base branch never reports and blocks the merge indefinitely (#1868). Admin bypass remains enabled for emergency override; normal changes land through PRs. .github/workflows/codeql-analysis.yml: GitHub CodeQL static analysis with thesecurity-extendedquery suite for Python and JavaScript; runs on pushes tomainanddev, on pull requests against either protected branch, and on a weekly schedule. Least-privilege permissions (contents: read,security-events: write,actions: read); nopull_request_target..github/codeql/codeql-config.ymlincludes synthetic scenario fixtures; private training targets are maintained and scanned in their owning repositories..github/workflows/pr-title-lint.yml: pull-request title validation against the conventional-commit shape Release Please consumes. It runs on PRs targetingdevandmain, the two branches whose protection requires theLint PR titlecontext. Ondevthe lint guards the release signal: squash-merging a feature PR makes the validated title the single commit subject Release Please reads once the change reachesmain(ADR-042-R4). Onmainthe promotion PR is merged with a merge commit and preserves the feature commits, so its title is not a release signal; the lint runs there so the required context reports. Allowed types:security,added,changed,deprecated,removed,fixed,feat,fix,chore,docs,refactor,test,ci,build,perf,revert. Subject must start with a lowercase letter..github/workflows/_shifter-engine.yml: engine image validation and deployment. The provisioner pytest gate and Docker-build validation run on GitHub-hosted runners; self-hosted runners are reserved for the credentialed build and deploy jobs. The credentialed jobs run only on trusted push / manual-dispatch paths, bind a GitHub Environment, require the provisioner test gate, and update ECS withrepo@sha256image identity..github/workflows/deploy.yml: deploy router. Pull-request events are hosted-only (changes, pre-commit, Quality, PR Gate) and never route AWS/GCP reusable deploy jobs. Reusable deploy jobs receive agithub_environmentinput distinct from Terraform environment names so prod applies can be protected by theaws-prodGitHub Environment. GCP manual dispatches use the same allowlisted name for the Terraform root and protected GitHub Environment (gcp-devornazgul), preserving the environment-bound deploy identity. The router separately selects the purpose-scopedgcp-release-scan-*Environment, and the reusable workflow accepts inventory-publishedGCP_WIF_PROVIDER/GCP_SERVICE_ACCOUNTvariables while retaining the legacy secret names as a compatibility path. Deploy preflight checks stop at the deploy Environment boundary; the scanner job validates its own identity only after entering its purpose Environment. The deploy router passesskip_tests: falseliterally into_quality.yml; commit-message flags such as[skip tests]are not accepted on protected branches. Inside_quality.yml,skip_testsmay only skip unit-test, coverage, SonarCloud, and stack-smoke jobs; lint, ADR conformance, IaC security, and other architecture gates always run (ADR-003-R2, #760).- AWS ECR image identity: first-party AWS ECR repositories are immutable.
Portal and engine deploy paths push run-scoped tags only as upload
handles, then consume the resulting ECR digest through SSM/ECS
repo@sha256references. Static Guacamole images are pushed only when the version tag is absent, and Terraform resolves that tag to a digest. .github/dependabot.yml: weekly dependency PRs across every uv (including the standaloneshifter_clienttransport), npm, github-actions, and pre-commit package root in the repo; every block targets thedevintegration branch. One block per package root, and a block's directory must name a root that actually holds a manifest; Dependabot silently ignores a block whose directory does not exist, leaving that root unwatched. The SPA (shifter/shifter_platform/frontend) is a separate npm root fromshifter/shifter_platformand carries its own block; the latter does not reach it (#1880)..claude/hooks/adr_guard_hook.py: Claude post-edit validationAGENTS.md: Codex repo-local policy. Points at.ground-control.yamland.gc/plan-rules.mdfor Ground Control workflow context (canonical GitHub repository, requirements, current MCP entrypoints, and plan rules); enforcement of ADR rules still lives here..ground-control.yamland.gc/plan-rules.md: Ground Control workflow configuration and mandatory plan constraints. Thegithub_repovalue is the canonical GitHub target for agent issue, PR, CI, and traceability operations. The optionalroutingblock opts the repository into per-step/implementrouting while keeping the workflow's gate contract in.gc/plan-rules.md. The configured completion boundary is the rootmake testtarget;make policycomposes the existing ADR, import, diff, and changed-document checks required by the synchronized pre-PR gate. Theroutingblock accepts onlyenabled,default_provider, andstages; a staledefault_fallbackkey, valid when the block was first written and later removed upstream without a migration, was dropped in #1581. Seedocs/technical/dev/adr-enforcement.mdfor how whole-file validation makes an unrecognized key fail closed. The retiredworkflow.test_quality_reviewblock was removed in #2122 because the current Ground Control schema no longer accepts the separate reviewer. The configured pre-push review, pre-commit, CI, and SonarCloud gates remain in force..mcp.json: the repository MCP launch contract runs the releasedgrndctlpackage (grndctl mcp) instead of a mutable source checkout. This keeps the server version aligned with the installed workflow skills while preserving the repository's other MCP servers..github/workflows/ground-control-phase-e.yml: the package-generated, version-pinned Ground Control finalizer. After a delivery PR merges tomainordev, it replays the trusted Phase D handoff throughgrndctl finalize-merged-pr; it performs no implementation verification and has only read permissions plus the issue write needed for the final report and issue close..importlinter: Python package-level architecture contracts.tflint.hcl: Terraform lint configuration withtflint-ruleset-googleplugin. The initial rule set is intentionally conservative so it can hard-fail on current signal without immediately breaking on unrelated legacy Terraform debt..gitleaks.toml: secret scanning configurationsonar-project.properties: SonarCloud project configuration.sonar.html.fileHeaderenforces the ADR-015 file-header convention on HTML templates by failingWeb:HeaderCheckon any template that does not begin with the canonical two-line SPDX Django-comment header. Bootstrap-specificsonar.issue.ignore.multicriteriaentries are limited toscripts/bootstrap/**and cover subprocess argv false positives, fixed infrastructure CIDR defaults, generic module/control-flow size rules, and scanner-consumed inline pragmas; bootstrap still runs Ruff, pytest+coverage, Bandit, and ADR guard in local and CI quality gates..kube-linter.yaml: Kubernetes security and best-practice linting configuration (enforces ADR-006 checks)Checkov: Terraform and Kubernetes IaC security scanning. ADR-004-R11 makes the Terraform CI path a blocking gate usingplatform/terraform/.checkov.yaml; the Kubernetes path remains soft-fail while manifest hardening proceeds as a separate workstream. Accepted-risk waivers MUST have an entry indocs/adr/exceptions.yamlwith owner, reason, expiry, affected paths, and the Checkov policy ID.scripts/check_tf_rds_security/check_tf_rds_security.py: ADR-004-R12 RDS hardening check for the two first-party AWS RDS instances. It requires literal IAM DB auth enablement and an explicit non-empty CA certificate identifier, complementing Checkov's RDS policies.scripts/check_tf_iam_ssm_range_scope/check_tf_iam_ssm_range_scope.py: ADR-004-R17 IAM hardening check that rejects SSM Parameter Store grants on the shared range guest instance role whose Resource wildcards across the environment or range segment (parameter/shifter/*/range/*or an unboundedparameter/shifter/<env>/range/*). The provisioner orchestrator role's env-scoped grant is not inspected. Guards the #1178 cross-tenant credential-access fix.- ADR-004-R21's legacy guest-role issuer and dedicated checker have been removed. ADR-059's broker mediates model access where enforcement is required; ADR-064 adds a default-on, keyless predict-only guest model identity as the baseline. The general IAM checks remain.
scripts/check_tf_iam_role_naming/check_tf_iam_role_naming.pyandscripts/check_tf_iam_elb_scope/check_tf_iam_elb_scope.py: ADR-004-R25 request-owned VPN gateway hardening. The checks pin the exact gateway role and instance-profile permissions-boundary carve-outs and tamper deny, keep GWLB andshifter-vpn-*NLB action/resource namespaces separate, require parent-NLB authorization and ownership resource tags forCreateListener, and require the runtime VPN listener to sendlocal.common_tagsat creation.scripts/adr_guard/adr_guard.pymcp-no-shell-execcheck: flags any file undermcp/(.js,.mjs,.cjs) that importschild_process(any shape: named, default, namespace, CommonJS destructure, or bare-requireproperty access, with or without thenode:prefix) AND uses one of the shell-string call shapes:execSync(...),exec(...), anexecSync as <alias>rename used as<alias>(, orspawn/spawnSync/execFile/execFileSyncinvoked with{ shell: true }. String literals and comments are flattened to whitespace by a small per-state consumer (one helper per state: code / line-comment / block-comment / string, preserving newlines), so"https://..."URLs do not accidentally erase a real call site, and so commented-out call sites or strings containingexecSync as rundo not trip the check or synthesise fake aliases. The check is a cheap pre-commit backstop; motivated bypasses such asconst run = cp.execSync; run(...)are outside its reach by design and rely on code review. Enforces ADR-010-R1 with no current exceptions—mcp/ngfw/*migrated to argv-array helpers via the sharedmcp/shared/aws-helpers.jsmodule in #759, alongside the originalmcp/ops/*migration in #763.scripts/adr_guard/adr_guard.pyboundary-mock-policycheck: enforces ADR-019-R1 for Python tests. The checker statically parses tracked test files forpatch()/ mock.patch()string targets and statically resolvablepatch.object(imported_module_or_class, ...)calls. Targets rooted in first-party Python modules are rejected unless their(test file, target)count is already present inscripts/adr_guard/boundary_mock_baseline.json. Patches against real process/network/cloud/framework transport boundaries, such assubprocess,boto3, HTTP clients, SMTP/socket/SSL, and channel-layer transports, remain allowed. The baseline is a ratchet: lower counts when legacy mock-coupled tests are rewritten; the check compares the committed baseline to the branch reference so authors cannot raise counts to land new topology-coupled tests without a dated ADR exception. During initial adoption, a base branch without the baseline file starts the ratchet from the first merged baseline.
ADR-019 baseline reduction (#957)¶
Issue #957 rewrites the remaining non-decomposed mock-coupled test suites
to behavior tests (drive a public entry point; assert outputs / ORM state /
responses) and shrinks boundary_mock_baseline.json accordingly. Each group
of suites lands as its own commit that removes the corresponding baseline
entries. Completed so far:
-
scripts/bootstrap: issue #687 mechanically split the legacytest_deploy.pysuite into behavior-focused files. The ADR-019 baseline entries were redistributed to the new paths with a dated exception because the ratchet keys on(test file, target); after porting the latest dev GCP/GDC tests, the aggregate bootstrap allowance shrank from 215 to 214 and the deletedwalkthrough_git_commitseam was not carried forward. -
mission_control: core range API, agents, models, and page-view suites (test_range_api*,test_agents,test_models,test_views,test_engine_models); engine-service view suites (test_engine_services,test_engine_services_lifecycle) andtest_asset_hierarchy; the SNS-> WebSocket handler suite (test_handlers), driven against the real in-memory Channels layer; the agent-upload and experiment-script view suites (test_views_uploads,test_views_files), with S3 mocked only at theboto3boundary and the validation / error-sanitization / authorization paths driven for real; the Guacamole token-readiness retry suite (test_guacamole_readiness), mocking the HTTP exchange at the realurllibboundary and recording backoff sleeps viamonkeypatchinstead of a first-partytime.sleeppatch. -
engine: range-lifecycle service suites (engine/services/test_create_range,test_cancel_range,test_destroy_range,test_pause_range,test_resume_range), driven against realRange/Requestrows. ECS is a no-op for create/destroy; pause/resume require a successful dispatch, so they configure ECS viaoverride_settingsand mock the AWS task runner at theboto3boundary. Range-query suites (test_get_range_status,test_get_instance_ips_by_uuid) read real rows'provisioned_instances. The SNS event handler suite (engine/test_handlers) drives the handlers against realRangerows and asserts the persisted status/timestamp updates + audit row. The ECS task-dispatch suites (engine/ecs/**) drive the realshared.cloudtask runner with AWS configured via settings and the ECS client mocked only at theboto3boundary, asserting the dispatch contract reachingboto3(cluster / task definition / container / command line / network config); the local-provisioner routing is driven over the realsubprocess.Popenboundary, and the GCP path drives the real config/env units (_get_engine_task_config,_get_gcp_provisioner_env_overrides) rather than mocking the runner factory. The SSH/secrets/NGFW service suites (engine/services/test_secrets,test_get_rdp_connection_info,test_connect_ngfw_terminal,test_destroy_ngfw,test_ngfw_lifecycle, andengine/ssh/test_ssh_connection) drive realRequest/Instance/Rangerows with the SSH key/RDP secret fetched over theboto3Secrets Manager boundary, the NGFW teardown/lifecycle dispatched over the realengine.ecsboto3 path, and the SSH transport mocked at the third-partyasyncsshlibrary boundary.test_get_ssh_connection_infoandtest_connect_terminalare also driven against a real activeRange: the underlying service previously resolved the range with aprovisioned_instances__containsJSON lookup that the SQLite test backend cannot execute (NotSupportedError); it now resolves the user's active range viaRange.get_active_for_user(consistent withget_rdp_connection_info), removing the non-portable query. With these, the engine group carries no remaining ADR-019 baseline entries. -
cms(core): range-service suites (test_services_range,test_services_range_destroy_cancel,test_services_range_pause_resume,test_services_range_lifecycle). These drive the real CMS services through the full hydrate -> engine -> persist stack against a real DB: a custom DBScenariohydrates a windows-agent range, engine ECS is unconfigured so create/destroy/cancel are no-ops, and pause/resume configure ECS with the AWS task runner mocked at theboto3boundary. Assertions are on persisted cmsRangeInstance/ engineRangestate,AuditLogrows, and the returnedRangeContext. The event-handler suites (test_handlers,test_handlers_ngfw) driveprocess_event/process_range_event/process_ngfw_eventagainst realRangeInstance/Request/Instance/Approws and assert the persisted status (andApp.data.serial_number) updates; the range handler's CTF bridge is verified by connecting a real receiver to therange_status_changedsignal, and dispatcher routing is verified through each sub-handler's real effect Legacy experiment routing was removed by ADR-027 / issue #1195, so dispatcher routing no longer includes the deleted experiments handler. The asset-service and S3-helper suites (test_assets,assets/test_s3) drive the realcms.assets.services(create/delete/storage) against realAgentConfig/OperatingSystem/AuditLogrows and the realcms.assets.s3helper through theshared.cloudAWS adapter, mocked only at theboto3S3 client boundary (withAWS_S3_BUCKET_NAMEset so the real not-configured guard is not tripped); the delete fail-fast path is driven with aboto3ClientErrorand asserts no soft-delete occurs. The presigned-upload lifecycle suites (test_services_upload,test_services_upload_cancel,test_services_upload_complete) driveinitiate_upload/cancel_upload/complete_uploadagainst a real user, real quota/extension validation, and a real signed upload token (round-tripped throughgenerate_upload_token/verify_upload_tokenrather than patched):initiate_uploadasserts the issued token's verified payload;complete_uploadruns the full verify -> header-inspect -> tag ->create_agentstack and asserts the persistedAgentConfig/AuditLog, the magic-byte-mismatch delete-and-abort, and that rejection logs do not leak header bytes; S3 (presign / head / range-GET header read / tag / delete) is mocked only at theboto3boundary. Thecms.servicessuites (test_services,test_services_storage,test_services_agents,test_services_scenarios,test_services_ngfws) drive the agent / storage / range-projection / scenario / NGFW service entrypoints against real rows: the range-projection IP overlay reads a real engineRange'sprovisioned_instancesthroughengine.services.get_instance_ips_by_uuid; the scenario services drive the real registry (built-in templates + DB customs); the NGFW services drive realCredential/Request/Instance/Approws and the seededpanw-ngfwcatalog +deployment_profile/scmcredential types, withcreate_ngfwrunning the full resolve -> provision -> hydrate -> dispatch stack (engine NGFW provisioning is a no-op under unconfigured ECS) and the engine-error path driven by a real engine NGFW instance with an attached range. Impossible-state defensive tests (the ORM returningNone/ a wrong-typed object / a list of dicts) and generic unexpected-exception re-raise tests are dropped per the boundary-mock-policy intent (ADR-019). The model and scenario-hydrator suites (test_models,test_credentials,test_models_agent_config,test_models_asset,test_models_operating_system,test_models_range_instance,test_models_subnet,test_scenario_hydrator) drive real rows for the ORM-dependent cases—Credential/CredentialType create/uniqueness/cascade/PROTECT,active_for_usersoft-delete filtering,RangeInstancecreate/query/select_related,OperatingSystem.get_for_extension, and theSubnetterminal soft-delete invariant—keeping the field-inspection and in-memory property tests as-is.test_scenario_hydratordrives the realhydrate_scenarioagainst real DBScenariorows (loaded through the real registry) and realAgentConfigrows, exercisingfrom_agentOS resolution and agent embedding. With these thecmscore area carries no remaining ADR-019 baseline entries. -
cms/experiments: ADR-027 / issue #1195 removed the legacy experiments app, its script-upload surface, websocket/event handlers, bridge tests, and ADR-019 baseline allowances. New experiment capability must arrive through a new accepted design rather than restoring these deleted suites or their first-party patch baselines. -
management: the service suite (test_services) driveslog_activity/get_user_profile/mark_user_deleted/create_user_profile/save_user_profile/update_cognito_subagainst realUserProfile/ActivityLog/AuditLogrows (accounting for thepost_savesignal that auto-provisions a profile), with the real duplicate-profileIntegrityErrorexercised directly and generic fault-injection tests dropped;test_appsverifies the profile signal wiring through its real effect (creating/saving a user provisions a profile) rather than assertingpost_save.connectshapes; andtest_check_model_fksdrives the real management command against the real (clean) model graph and exercises the violation-count path via the realcompute_stats.managementwas added to theenable_log_propagationfixture so its service logs are observable bycaplog. -
shared: the cloud-storage adapter suites (shared/cloud/test_aws_storage,test_gcp_storage) drive the realAWSObjectStorage/GCPObjectStorage(including their real_get_clientregion/endpoint/client resolution) and mock only the SDK boundary—boto3.clientandgoogle.cloud.storage.Clientrespectively—rather than patching the first-party_get_client.shared/test_emaildrives the realsend_emailthrough the real thread pool and asserts the locmem outbox instead of patchingshared.email.send_email.shared/test_notificationsdrives the real in-processInMemoryChannelLayer(a real channel is subscribed to the user/topic group and the dispatched event is received off the layer) instead of patchingget_channel_layer/async_to_sync; theIntegrityErrorrace-fallback test is dropped because the unique constraint exactly matches theget_or_createlookup, so the fallback is reachable only via a genuine multi-connection race or by mocking the first-party manager.shared/test_audit_storedrives the real audit functions against realAuditLogrows (asserting the persisted row) instead of patchingAuditLog.log, with the swallow path exercised via a real non-JSON payload fault. With these, thesharedarea carries no remaining ADR-019 baseline entries. -
mission_controlGuacamole connection-URL endpoints (test_guacamole_ssh,test_api_instance_ssh_url,test_api_ngfw_ssh_url,test_views_guacamole): drive the real views → realengine.services(get_ssh_connection_info/connect_ngfw_terminal/get_rdp_connection_info, against real READYRangerows and real NGFWInstance/Requestrows) → realmission_control.guacamoleURL builders (real AES/HMAC sign-and-encrypt). Only the cloud/network boundaries are mocked: the boto3 Secrets Manager client that yields the SSH/RDP secret and the urllib Guacamole/api/tokensPOST. Assertions read the returned URL and the decrypted payload that was actually POSTed, instead of patchingengine.services.*/mission_control.guacamole.*/ the bootstrap enqueue. Generic fault-injection tests are replaced with real-boundary equivalents (a Secrets ManagerClientErrordrives the 500 path; an invalid signing secret drives the URL-build failure; a real exhausted bootstrap-worker semaphore drives the 503); the unreachable range-SSHPermissionErrordefensive branch is dropped. Shared cloud/Guacamole boundary helpers live intests/mission_control/conftest.py. -
mission_controlNGFW management pages (test_views_ngfw,test_ngfw_detail): drive the real list/wizard/deprovision/detail HTML views and the create/list/destroy JSON APIs → realcms.servicesNGFW entrypoints (list_ngfws/get_ngfw/create_ngfw/destroy_ngfw/list_credentials) against realApp/Instance/Request/Credentialrows → the real templates and JSON, instead of patching the cms service functions andrender. Engine NGFW provisioning is a no-op (ECS unconfigured), so no cloud mock is needed. NGFW App/credential factories live intests/mission_control/conftest.py. Driving the realngfw_detailrender surfaced (and this PR fixes) a pre-existing product bug the old mocked-rendertest hid:ngfw_detailpassedint(cms NGFWAppContext .instance_id)(a CMS Instance UUID coerced to a 128-bit int) toget_ranges_for_ngfw, which filters the engineRange.ngfw_instance(a 64-bit int FK to the engine NGFW Instance)—different id spaces, so the detail page 500'd on SQLite / showed no linked ranges on Postgres. The view now correlates via the shared provisioningrequest_id(exposed onNGFWAppContext), andget_ranges_for_ngfwresolves the engine NGFW Instance from that request_id and returns theLinkedRangeContextprojection the template already expects.test_ngfw_detailasserts the real linked-ranges render end to end. -
mission_controlconsumers + misc (test_context_processors,test_oidc,test_health,consumers/test_range_status_consumer,consumers/test_ssh_consumer,consumers/test_ssh_consumer_capacity): theactive_rangecontext processor is driven against realRangeInstancerows (the storedrange_speccontrols the projected instances, real group membership decidesis_ctf_participant_only, and runtime private IPs come from a real linked engineRange) instead of patchingget_active_range/is_ctf_participant_only/logger.test_oidcdrives the realShifterOIDCBackend.create_user/update_user/_update_cognito_sub(real mozilla base + realupdate_cognito_sub/audit_auth_event), asserting persisted flags /UserProfile/AuditLog.test_healthdrives the real channel-layer probe over the in-processInMemoryChannelLayerand the real missing-default-layer path (third-partyhealth_checkbackends are still patched for the DB/cache failure cases—those are real boundaries). The WebSocket consumers drive the realconnect_terminal/get_range_by_request_id/audit_session_eventagainst real READYRangerows (@pytest.mark.django_db(transaction=True)sosync_to_asyncsees the committed rows), mocking only the boto3 Secrets Manager and the asyncssh transport boundary; the range-lookup connect paths are additionally covered real bytests/integration/engine/test_consumers_integration.pyandtests/integration/asgi/test_terminal_ws.py. Generic/impossible-state and incidental-logging tests are dropped per the policy intent. -
config / documentation / integration / views misc (
config/test_logout,documentation/test_views,integration/engine/test_range_lifecycle,views/test_launch_range_scenarios):test_logoutdrives the reallogout_viewthrough the test Client with a real session (the real Djangologoutflushes it) instead of patchingconfig.views.logout.documentation/test_viewsdrives the realdoc_indexrender and asserts the capturedresponse.context(nav_tree / active_nav) instead of patchingdocumentation.views.render.test_range_lifecycledrives the realget_rdp_connection_info→get_rdp_passwordover the boto3 Secrets Manager boundary instead of patchingengine.services.get_rdp_password.test_launch_range_scenariosdrives the realmission_control:launch_rangeendpoint → realcms_list_scenarios/cms_get_agent/cms_create_rangeagainst a real custom hydratableScenario+ a real WindowsAgentConfig(engine provisioning is a no-op, so the range staysprovisioning), with the real-boundary CMSError paths (a second launch hits "already have an active range"; an unknown agent classifies to a safe message) andcaplogfor the success/failure log assertions, instead of patchingcms_create_range/cms_list_scenarios/cms_get_agent/logger.
Refactor-survival demonstration (#957)¶
The point of the boundary-mock policy is that behavior tests survive refactors
that mock-coupled tests would not. To demonstrate this concretely, the
generate_username Django-username validator was moved out of the OIDC backend
module (config/oidc.py) into its own config/username.py, and the single
topology reference (OIDC_USERNAME_ALGO = "config.username.generate_username")
was updated. The tests/mission_control/test_oidc.py ShifterOIDCBackend
behavior tests—which exercise generate_username only through the real OIDC
create_user / update_user login flow (via OIDC_USERNAME_ALGO), never naming
the function's location—pass unchanged across the move. Only the function's
own direct unit tests (TestGenerateUsername) updated their import to follow it.
A mock-coupled test that had patched config.oidc.generate_username would have
broken on the move; the behavior tests did not.
Decomposition-owned suites are out of scope here and land with their own
issues: provisioner (#946), ctf/** (#885, #886, #889-#891), and
cms/scenario_editor/** (#887, #888). The legacy cms/experiments
decomposition path was removed by ADR-027 / issue #1195.
ADR-019 baseline reduction (#885)¶
Splitting ctf/views.py into the ctf/views/ package (#885, python:S104)
removed every first-party ctf.views.* patch the CTF view tests carried. The
view tests that drove role/render/participant resolution by patching
ctf.views.get_user_role, ctf.views.render, ctf.views._get_active_participant,
ctf.views._get_participant_for_challenge, and ctf.views._resolve_bracket_filter
were rewritten to behavior tests: organizers are driven through real group
membership (so the real get_user_role resolves), and the render / participant
/ bracket paths run for real under @pytest.mark.django_db with the conftest
user/event/participant fixtures (services mocked only at their already-tracked
boundary). The corresponding 11 ctf.views.* entries were removed from
scripts/adr_guard/boundary_mock_baseline.json (ratchet shrink).
Adding A Rule¶
- Add or update the ADR in
index.yaml. - Implement or wire a check in
scripts/adr_guard/adr_guard.py. - Document the user-visible mechanism in
docs/technical/dev/adr-enforcement.md. - If the rule cannot be enforced yet, add a dated exception in
exceptions.yamlinstead of leaving it implicit.
Exception Format¶
Exceptions are explicit and time-bounded:
[
{
"rule_id": "ADR-001-R1",
"owner": "platform",
"reason": "Temporary migration window",
"expires_on": "2026-06-30",
"checks": ["layer-imports"],
"paths": ["shifter/shifter_platform/ctf/*"]
}
]
Expired exceptions fail adr_guard, and they also stop suppressing: once
expires_on has passed, the entry no longer covers its violations and those
findings resurface on their own. An entry whose expires_on is missing or
unparseable never suppresses anything, so a malformed date cannot buy
open-ended cover. expires_on is inclusive: the exception is live through that
date and dead the day after.
Broker activation now requires an enabled v3 accounting catalog, an exact provider inventory, separate broker/provisioner workload identities and a versioned HMAC Secret reference. Installer projection and real Helm-render tests enforce these bindings. GCP deployment cleanup also removes the narrowly scoped provisioner-to- control enrollment egress policy. Standby infrastructure renders zero broker and control replicas until model access is enabled; no executable deployment or cloud qualification is implied by rendering. See model access operations.
M05 additionally binds active GCP control identities to the distinct numeric service-account IDs read back from Terraform. Installer, Helm schema/templates and startup all reject absent or overlapping IDs. Broker isolation is checked by the existing import contract; real TLS, PostgreSQL races, bounded worker/DB waits and content-sentinel tests lock the runtime boundary. No architectural exception or CI relaxation is introduced. See the implemented broker contract.
The GCP workflow reads a reviewed per-environment model overlay when present,
verifies deploy-owned TLS resources, and projects the sealed catalog into every
runtime ConfigMap consumer. platform/deploy/gcp/** is owned by the GCP scripts
lint, SAST, and test quality unit; a template change therefore cannot bypass
the production-path quality matrix.
Guest model enrollment is projected as allocation/role/target identities alongside an immutable operation input. The tenant-approved adapter manifest declares role bindings; only Engine's admitted allocations can populate them. A trusted SSH stdin channel delivers a one-use token after realization, and Linux tmpfs holds the guest's rotating broker tokens. GCP provisioner admission now permits three non-secret enrollment coordinate/trust values only when they exactly match the runtime ConfigMap. The broker renderer supplies those values for both Helm and Actions. Real TLS helper tests cover trust failure, redirect refusal, state-file permissions and serialized refresh. AWS SSM does not qualify as secret delivery.
The external-runtime test-quality repair makes toolchain-dependent checks
selectable with the integration marker while retaining them in default CI runs.
The bootstrap/GCP script jobs explicitly provision their rendering tools. Chart
security checks assert the default-deny policy bodies for every provider profile,
including the isolated plugin namespace. See testing guidance.
The chart enrollment schema admits the generic cloud endpoint projection: a GCP guest VIP or AWS guest endpoint CIDRs alongside the shared TLS enrollment settings. Its closed property list continues to reject undeclared settings. Real Helm schema tests cover both cloud contracts.
Development-branch integration preserves address-keyed subnet reservations and pre-mutation cleanup across the external runtime seam. Model enrollment now activates pending grants only on one-use token exchange, and re-enrollment revokes old request authority. Accounting retains complete billing evidence, hard request deadlines and owner-first locks alongside request reconciliation.
The latest hook cleanup retains fast syntax/format checks, pure-Python IAM and network scoping guards, and secret/identifier hygiene. Full tests, type checks and external infrastructure scanners remain in CI. Retired scenario-role checks and private-content exclusions are not restored by development-branch merges.
The AWS model-broker module is included in the Terraform validation inventory with active contract tests. Broker and control listeners bind the explicit private pod IPv4 address supplied by the Downward API, with TLS, workload identity and NetworkPolicy enforcing the service boundary. EC2 secret categories derive from a closed authentication-method set. Secret scanning remains enabled without a suppression for these category identifiers.
The isolated GKE plugin pool uses the version-6 Google beta provider required for sandbox configuration. Module contract tests pin the same provider family as both deployment roots, so a newer module-only schema cannot mask an invalid deployment configuration. Native range power capabilities are refused before legacy worker dispatch because native realization has a separate member inventory.
The runtime security annotations also cover Sonar's wildcard-listener and shared
temporary-directory findings: broker/control sockets are private Kubernetes
Services with mandatory TLS, workload authentication and enforced NetworkPolicy;
the plugin /tmp is a per-pod, size-bounded memory volume, with host mounts denied.
These scoped annotations retain those deployment controls and their contract tests.
The GCP image validator's custom role includes instance metadata and label writes required when creating its disposable candidate and scanner VMs. SSH keys stay instance-local with project keys blocked; both VMs retain no service account, no OAuth scopes, and no external IP. This does not grant project metadata writes or service-account attachment permissions. Instance listing and Compute project readback support the existing gcloud IAP/SSH/SCP transport; the role retains no project metadata write permission. The runner starts its IAP listener without a one-shot guest connection check; bounded SSH/LDAP probes still gate validation through first boot and reboot. An exited tunnel process fails promptly instead of consuming the boot timeout.
Deployment configuration cleanup¶
GCP platform execution now uses one root with explicit environment var-files
and separate TF_DATA_DIR metadata. State prefixes, resource addresses and
provider locks remain unchanged. The Terraform validation inventory covers
that common root. Kustomize runtime patches lived in one component until
2571 removed the Kustomize tree (see GitHub-less GCP deployment).¶
Unused connector templates and the drained standalone workshop root are removed with their dedicated CI responsibilities, structural tests and stale exception paths. Maintained Terraform, workflow, Kubernetes and secret checks remain in force. AWS production and optional portal CTFd retain their named owner and working callers. Retired AWS profile admission is removed from bootstrap and the installation registry; its published artifact is regenerated. See the design and operator recovery procedure.
The operator-confirmed repository rename changes the canonical GitHub target
in .ground-control.yaml to Brad-Edwards/bigrae. The local agent rules and
Sonar scan admission match that target. This changes repository routing, not
platform resource names or the Ground Control project identity. Existing
Ground Control connections must restart after the origin changes; their launch
identity remains immutable during a connection.
Before #2571, Kubernetes quality jobs rendered standalone Kustomization roots and validated Components through their consuming overlays. #2571 removed the Kustomize tree and that regression test; the quality jobs now render the Helm chart.
Artifact provenance checks, bootstrap/tool defaults and foundation repository inputs follow the authorized rename. Reusable workflow trust still requires the exact canonical repository, workflow path and immutable revision; foreign libraries remain rejected by native Terraform tests.
GitHub-less GCP deployment (ADR-070)¶
ADR-070 records the GitHub-less GCP deployment model of #2571. The registry adds ADR-070 and revises ADR-003-R5, ADR-003-R6, ADR-004-R5, ADR-004-R9, ADR-004-R11, ADR-004-R23, ADR-006, ADR-007, ADR-033-R2, ADR-035-R1, ADR-037, ADR-053-R3, and ADR-069-R3. Evidence entries that named the removed Kustomize tree now name the chart templates or the deploy command modules.
The guardrails change as follows:
- The
release-workflow-provenancecheck runs at the fast and ci levels. It reads.github/workflows/release-gcp.ymlas data and fails closed. It requiresworkflow_dispatchandworkflow_callas the only triggers (#2660). The only caller is therelease-gcpjob ofrelease-please.yml. That workflow starts only on a push tomain, and the job runs only when a release tag points at the pushed commit. An unconditionalrelease-commitstep after the Release Please action finds that tag and gives the version and the commit. The job inherits no secrets. Each job that publishes must bind thegcp-releaseEnvironment, run on a GitHub-hosted runner, and reject every ref except the release refs before its first publishing step. It also requires SHA-pinned actions, an SBOM and maximum provenance for each pushed build, and an attestation of each built digest withpush-to-registry: true. scripts/check_tf_gcp_wif_trustcovers the closed impersonation grant. It rejects a default ongithub_repository_id,github_owner_id, andpurpose_contexts. Its resolved-plan verifier requires no WIF provider when no federated subject exists, and exactly one provider otherwise. It also requires the token-creator grants to equal the named principals.- The Helm chart is the only Kubernetes renderer.
k8s-schemarenders every supported values file and runskubeconform -strictwith a CRD catalog pinned to one commit.chart-lint-securityrunshelm lintand kube-linter on the same renders, andsecurity-k8sruns Checkov on them. Thek8s-lintjob and thevalidate-gcp-manifestsaction are removed. The ADR guard Kubernetes checks read only the chart renders. - The CKV_K8S_35 and CKV_K8S_38 exceptions now point at the chart Deployments that carry their annotations. Their justifications and expiry dates do not change. The CKV_K8S_43 exception is removed, because the chart pins each image by digest.
no-populated-secret-env-filesscans tracked*-secrets.envfiles underplatform/. The pre-commit hookadr-guard-gcp-overlay-identityis nowadr-guard-gcp-deploy-identity, andno-live-gcp-deploy-identityscans the chart values files.- The
gcp_deployerquality unit routesplatform/deployer/**tocontainer-images-lint-securityand to thegcp-deployer-imagebuild test. - The deploy workflow guard tests read the GCP command modules for the
properties that
_gcp-dev.ymlheld before #2571. These are the HIGH and CRITICAL release scan, the running-image evidence, the private input files, the Connect Gateway credentials, and the single range-zone input.
The local design checks
configure Ground Control's pre-implementation review using the existing Python
compiler and import rules, a code-derived dependency view and exact pytest
observations. Module applicability is configured in .ground-control.yaml.