ADR-0140: Bind dependency-security decisions to the candidate image
Status: Amended by operator; deployment proportionality policy supersedes conflicting requirements Date: 2026-11-11
Context
The dependency audit retained an advisory count without an exact image, database identity, or raw report. Requirements alone do not describe installed Debian/Python packages, vendored code, downloaded binaries, or emitted browser assets. A release decision needs reproducible evidence for the image that will actually run, with explicit treatment of scanner omissions and exceptions.
Decision
Operator correction, 2026-11-14 UTC
The production deployment policy controls where it conflicts with the original decision below. Roger rejected per-host repeated scans, tooling-only rebuild/rescan cycles, production full-suite reruns and open-ended deployment audits after excessive time/quota consumption. Reuse release evidence and explicit risk acceptance; separate application-image identity from deployment-tool provenance. The original requirements below remain historical rationale and describe parts of the current implementation, not authority to repeat that workflow. Executable alignment is required.
Original decision (subject to the correction above)
Gate the selected common WEPPcloud image and primary frontend lock before activation, using one repository-owned policy interface for CI and deployment. Bind native SBOM, scan, direct inventory, and npm evidence to immutable image and lock identities and retained report hashes. Distinct unrelated images are not covered by this gate.
Reports and advisory database build timestamps must be at most 24 hours old; future timestamps beyond five minutes of clock skew fail. Require successful database refresh before a new scan. An applicable unresolved Critical/High finding blocks activation; applicable Medium findings require a fix or an approved exception. Unknown severity needs explicit review. Low findings remain tracked. A blocked-follow-up label does not authorize activation.
Accepted-risk records require advisory/package/ecosystem/version/path identity, image or lock scope, owner and approver, rationale, evidence, compensating control, creation/expiry timestamps, and review trigger. They expire within 30 days; renewal requires fresh review. Approval hashes come from trusted operator records outside candidate-controlled inputs. PR authors cannot approve their own policy or exception changes.
Retain ordinary CI evidence for at least 90 days and activated-image evidence
for at least 365 days and throughout rollback eligibility, whichever is longer.
Use the owner-selected /workdir/weppcloud-deployments/ private store, with
ignored .local/dependency-security/ evidence/approval areas, 0700 directories
and 0600 records. Retain database bytes or a retrievable immutable database
artifact reference. Public source contains sanitized summaries and hashes.
Roger selected manual evidence transfer: required raw reports must be imported
into this store and checked against their image/lock identities and hashes
before acceptance. CI success alone is not proof of retention. Production stays
on Docker Compose through installed wctl and scripts/deploy-production.sh;
manual transfer adds no registry or alternate deployment path.
PR execution must be isolated from production mounts, credentials, registry write authority, and the production Docker socket. Scanner execution uses explicit image archives/SBOMs in an unprivileged confined process. Missing or malformed evidence, partial parser/analysis results, identity mismatch, stale evidence, and blocking findings fail before any service stop/recreate operation. Scanner-ignored and matcher-suppressed findings still require disposition.
The gate covers selected common images in full, web, worker, fork/archive, batch-derived, and retained rollback paths. Targeted CAP alone is excluded. Recheck selected image IDs immediately before activation; a rollback flag grants no policy bypass. This decision does not authorize production rollout or any specific advisory-risk exception.
For host-local Compose deployment, build and record the candidate before any
service stop, then exit for independent evidence collection and review. A later
resume must bind to a host-specific private receipt and reject before service
changes unless the source revision and cleanliness, dependency lock, deploy
script, installed wctl identity, deploy mode/options, secret-safe canonical
rendered Compose projection, and every service-to-image ID still match. Bind the
host with /etc/machine-id, hostname, and Docker Engine ID; all three must match
on resume.
Store candidate directories beneath
/workdir/weppcloud-deployments/.local/dependency-security/candidates/ and
operator approvals beneath the sibling approvals/ authority. Directories are
0700 and files 0600, owned by the invoking operator, non-symlinked, atomically
published and fsynced. The receipt schema includes its version, creation time,
host/daemon identities, source/build identities, effective configuration hash,
selected services, immutable image map and retained activation-file hashes. The
approval path is derived only from the protected authority root plus the
candidate-receipt hash; it is never accepted from the candidate receipt, CLI or
environment. That separate record binds the candidate hash to evidence manifest,
policy and disposition hashes.
Activation must consume the frozen IDs, not mutable tags. Retain the rendered
Compose configuration and an override mapping every selected locally built
service to its sha256: image ID. After validating the current projection,
activate through the canonical deploy script using only those private retained
files with build and pull disabled. Revalidate the receipt and independent
evidence policy before the first service change and again after any warm wait,
immediately before each activation attempt. Verify running container IDs after
activation as defense in depth, not as the primary substitution control. Generic
--skip-build remains invalid; a retained receipt is not transferable between
hosts or Docker daemons.
Drain default/batch work while the current containers remain running: acquire the owned RQ dequeue fence, wait for started registries to reach zero, and rerun the complete receipt/evidence gate before stopping any service. A gate failure releases only the deployment-owned fence and leaves the prior workload running. Immediately before cutover, also retain the current rendered configuration and running service-to-image ID map. Once any service stop begins, every error path must restore that unchanged known-good map with build/pull disabled, verify the restored container IDs, and only then release the RQ fence. Failed restoration keeps the bounded fence and returns an explicit recovery signal; it never starts an unapproved candidate or resumes dequeue into a partial stack.
Decision Provenance
Decision Venue: Codex execution session, 2026-11-11 UTC; approval recorded at
05:41:25 UTC (2026-11-10 in America/Los_Angeles). The exact message timestamp was
not separately retained.
Participants Present: Roger Lew; Codex.
Decision Owner: Roger Lew.
Implementer: Codex; implementation pending the required baseline.
Review: independent correctness, security, and wepp1 operations agents.
Amendment Venue: Codex execution session, 2026-11-13 UTC. Roger answered “yes” to the explicit question authorizing retained-candidate resume: build once, pin activation to immutable image IDs, independently review evidence, and resume the same host-local Compose candidate without rebuilding. This authorizes the workflow implementation and validation; it does not authorize M5 production service interruption or activation.
Change Summary
Previously there was no artifact-bound common-image dependency activation gate or enforceable freshness/exception/retention policy. The approved limits are 24-hour evidence/database freshness, five-minute future-clock tolerance, 30-day maximum exceptions, and minimum 90-day/365-day evidence retention. Scientific parameterization, application permissions, runtime identities, and existing deployment topology do not change under this decision.
Rationale
Daily freshness bounds advisory staleness. Short, owned exceptions prevent permanent suppression. Exact artifact readback avoids testing one dependency image while activating another. Pre-activation failure preserves availability of the running stack. Retained evidence supports review and rollback decisions.
Alternatives Considered
- Manifest-only counts: rejected because installed and unmanaged components differ from manifests and build-time resolution can drift.
- Scanner exit status alone: rejected by qualification trials that produced exit zero despite a missed GDAL advisory or recovered parser panic.
- Permanent exceptions or stale-evidence fallback: rejected because they hide unresolved exposure and invalidate the release evidence boundary.
- A new hosted vulnerability service: unnecessary; reuse the private store, existing build/test tooling, and a bounded command-line gate.
- Waiting for manual review within one deployment invocation: rejected because it leaves a long-running privileged process open across an unbounded human review interval and complicates interruption and recovery semantics.
Consequences
Scanner/database outages or newly blocking findings can delay deployment. Coverage reconciliation includes unmanaged executables and native parser diagnostics, not only package counts. Private storage and CI ingestion need operational validation. Full pytest, npm lint, and full npm tests must pass on the exact final candidate; scanner qualification does not substitute for them.
Evidence
Risk and Rollback Notes
Preserve the known-good image and running services on gate failure. A retained rollback image must satisfy current policy or have explicit temporary risk acceptance. No emergency override is created here. Changes to these limits or authority require a recorded owner decision and an ADR amendment.
Implementation Notes
The reviewed tool choice is scoped Syft 1.57.1 image-archive inventory followed by Grype 0.121.3 native-SBOM matching. Tool pins and capabilities require explicit review when updated. Enforce cataloger/input restrictions, inspect native analysis uncertainty, include suppressed findings, and preserve explicit failure status. M3/M4 must prove the wired gate, CI storage path, production- equivalent identities, and activation ordering before rollout readiness.