feat(isolation): add serviceGateways kit vocabulary

[mogul]

Summary

Add the patterns-side neutral hybrid/v1 serviceGateways kit vocabulary for kit-declared, acq-managed service gateways.

This PR includes:

• ADR 0003 for the service-gateway vocabulary and tradeoffs.
• Schema support for serviceGateways[], v1 kit-local Compose runtime files, required runtime.compose.service, sandbox/agent exposure through expose.env, and optional interface.port only when inferable from the named Compose service.
• Validator checks for kit-local Compose files, safe named Compose service existence, service-scoped port inference, no privileged containers, floating-image warnings, and expose.env values mapped to url.
• README authoring guidance and focused pytest coverage.

Tracking: GSA-TTS/agentic-coding-quickstart#472

ADR

The ADR is integrations/isolation/docs/decisions/0003-service-gateways-vocabulary.md.

It captures the core decisions:

• Use the neutral field name serviceGateways.
• v1 uses kit-local Compose files only.
• v1 requires runtime.compose.service to identify the gateway service in multi-service Compose files.
• Expose the resolved gateway URL into the sandbox/agent via expose.env.
• Do not broaden sandbox egress or give API keys to the agent.
• Keep backend routing details out of the kit schema.
• Keep future backends such as Kubernetes possible without changing the semantic contract.

Verification

Commands run:

PATH="$PWD/.venv/bin:$PATH" make validate-kits

Result: passed. All 7 acq-kits valid.

uv run --link-mode=copy --extra dev pytest scripts/tests/test_validate_kits_service_gateways.py scripts/tests/test_validate_kits_ports.py scripts/tests/test_validate_kits_volumes.py scripts/tests/test_validate_kits_injection.py scripts/tests/test_validate_kits_network_tier.py -v

Result: passed. 94 tests passed.

uv run --link-mode=copy --extra dev ruff check integrations/isolation/acq-kits/validate-kits.py scripts/tests/test_validate_kits_service_gateways.py

Result: passed.

PATH="$PWD/.venv/bin:$PATH" make validate

Result: passed. Existing advisory warnings were reported for documented PII/CUI terms and network-tier deep-subdomain review signals.

PATH="$PWD/.venv/bin:$PATH" make generate-check

Result: passed. INDEX.yaml and CATALOG.md are up to date.

PATH="$PWD/.venv/bin:$PATH" make test

Result: passed. 422 tests passed.

git diff --check

Result: passed.

AI Assistance

This PR was prepared with AI assistance from OpenCode Agent. A human reviewer remains responsible for review and merge.

[wz-gsa]

AI-assisted review (OpenCode), advisory — needs a human to confirm before it drives a change. Reviewed at head cfce305.

Reading this as a schema change rather than docs+tests: it widens what a kit is allowed to be, letting a kit start host-side Compose services. The ADR is careful and the test file is genuinely thorough (20 cases including degraded paths). Two gaps in the validator, both about the distance between what the ADR asserts in prose and what the code enforces.

1. privileged: true is the only escape primitive checked (integrations/isolation/acq-kits/validate-kits.py:206-211).

def _compose_has_privileged_service(compose_doc: object) -> bool:
    """True when any Compose service declares privileged: true."""
    return any(
        isinstance(service, dict) and service.get("privileged") is True
        for service in _compose_services(compose_doc).values()
    )

I grepped the whole validator for docker.sock, network_mode, pid:, cap_add, security_opt, devices, and build: — zero hits. So a gateway Compose file declaring volumes: ["/var/run/docker.sock:/var/run/docker.sock"], network_mode: host, pid: host, cap_add: [SYS_ADMIN], security_opt: ["apparmor:unconfined"], devices:, or build: passes with zero errors and zero warnings — each reaching privilege equal to or greater than privileged: true.

ADR-0003 states the boundary in prose ("a gateway that needs host-level privileges, broad mounts, or Docker socket access is outside this vocabulary"), while the code enforces one keyword. A validator returning errors == [] over an unmodeled Compose file is reporting measured-clean on something it did not look at. Either extend the check to the full escape set, or make an unmodeled top-level service key an explicit error so a reviewer sees "I did not model this" rather than silence.

2. include: / extends: defeat the kit-local path guarantee (validate-kits.py:342-355, schemas/kit-hybrid-v1.schema.json:247-253).

Both layers constrain only the entry files in runtime.compose.files[] — the schema regex requires a kit-local relative .ya?ml, and the validator does compose_path.relative_to(kit_dir.resolve()). But then it yaml.safe_loads each entry and inspects only services; grepping for include or extends in the validator returns zero hits. Compose's own include: and service.extends.file let a kit-local file pull in ../../../anything.yaml or a workspace path, and nothing resolves them.

So the schema's "may reference only Compose files shipped inside the kit" is true of the declared list and false of the resulting configuration. Reject include: and extends: {file: …} in gateway Compose files, or resolve and re-check them.

One thing I'd like an answer to rather than a change: the trust escalation is documented but not machine-readable. This vocabulary lets a fetched kit start host-side containers, and the control is a sentence — "Remote service-gateway kits must come from trusted kit sources" — with no schema field, no validator check, and nothing telling acq apart a local kit from one pulled via ACQ_EXTRA_KITS (a plain git URL + SHA). Either the trust gate should live somewhere a machine can read it, or the ADR should state plainly that v1 relies entirely on human review of the kit source.

Also noting, not as a finding: floating image tags are a warning, not an error (validate-kits.py:196-204), which the ADR states deliberately. It diverges from this repo's exact-pinning norm, and warnings tend to stay warnings.

Method: static analysis at head cfce305, compared against main's validator and schema. No kit was executed and no Compose file was run. I did not check these findings against a real docker compose config — they are gaps in what the validator inspects, not demonstrated exploits. bin/injection-scan.sh clean.

[wz-gsa]

AI-assisted adversarial review (nexus-agents pr_review, 5-role panel: architect/security/devex/catfish/scope_steward), advisory — needs a human to confirm before it drives a change. 5-0 request_changes, all voters completed, high confidence (0.78–0.85). This is a cross-cutting schema vocabulary every future kit author would build against, so the bar here is higher than a single kit — and all 5 voters independently converged on the same structural gap, plus one critical-severity finding.

1. No schema change in the diff, despite this being described as a schema-level vocabulary (all 5 voters, blocking). The diff touches only acq-kits/README.md and validate-kits.py. New code comments assert schema facts that don't exist after this change (_GATEWAY_PROTOCOLS "mirrors the schema enum"; the PR description says "authoring mistakes are caught by schema"). Either additionalProperties: false rejects every kit that declares serviceGateways (the vocabulary is inert), or the schema is permissive and none of the claimed structural guarantees actually exist — a reviewer can't tell which from this diff, and it's the exact question I asked the panel to check.

2. Critical: the stated security boundary is documented, not enforced (catfish, severity: critical; confirmed independently by all 5 voters with concrete fixtures). The ADR's premise is that the gateway — not the agent — is the credential/policy enforcement boundary, running outside the agent's reach. The only container-hardening check is privileged: true. Every voter independently constructed a Compose fixture that passes validation cleanly while granting host-equivalent control:

• volumes: ["/var/run/docker.sock:/var/run/docker.sock"]
• cap_add: [SYS_ADMIN]
• network_mode: host / pid: host / userns_mode: host
• security_opt: [apparmor:unconfined]

catfish: "checking privileged alone is worse than checking nothing: it signals enforcement that doesn't exist." For a vocabulary whose entire justification is being the enforcement point in an otherwise deny-by-default egress model (ADR 0002), this is the one thing that most needs to actually hold.

3. Path containment is bypassable via Compose's own include:/extends: (Security, catfish). The "kit-local-only, must stay under kit dir" guarantee is enforced only against the literal runtime.compose.files[] list. Compose natively resolves top-level include: and service-level extends: {file: ...} relative to the compose file — neither is inspected, so a compliant-looking kit can pull in arbitrary out-of-kit files (and the privileged/image scans never see them).

4. runtime.compose.files is never required to be non-empty (Architect, DevEx, catfish, Scope Steward). compose_files = compose.get("files") or [] with no emptiness check. A gateway declaring only name/interface/runtime.compose.service/expose.env — with zero Compose files — validates with zero errors, and because inspected_compose/found_named_service stay False, the service-existence check and the port-ambiguity check are both silently skipped too. The strictest-looking invariants are the easiest to bypass, by omission.

5. Host-published ports are accepted as valid endpoint sources (Security, catfish, Scope Steward). _compose_service_candidate_ports reads Compose's ports: (host-published) and expose: (container-internal) interchangeably. Per the PR's own framing, the gateway holds real credentials; a ports: ["8080:8080"] gateway is reachable from the LAN with no auth requirement anywhere in the schema, and the validator both allows this and derives the advertised "narrow, policy-controlled" endpoint from it.

6. ~140 lines of new security-relevant parsing ship with zero tests/fixtures (all 5 voters). No kit in the tree declares serviceGateways, so every new branch — path traversal rejection, port inference, the url-token check, floating-tag warning — is dead code in CI on merge day.

7. ADR numbering collision, confirmed by all 5 voters as requested. integrations/isolation/docs/decisions/0003-service-gateways-vocabulary.md collides with another unmerged PR's 0003-* ADR in this repo. Not a content defect, but whichever merges second needs a renumber — worth resolving before either lands so the history isn't ambiguous.

Minor/non-blocking, several voters: the closing paren in the expose.env invalid-name check is dedented to column 12 (legal Python via implicit line-continuation, but will trip black --check/ruff format); Scope Steward separately flagged the hand-rolled Compose port-parsing (_parse_compose_port, candidate-port union across expose/ports) as reaching past the existing-tool check — docker compose config --format json already resolves services/ports canonically, and it's arguably premature machinery given zero real consumer kits exist yet.

The vocabulary concept itself isn't in question (Scope Steward explicitly separated "is this schema idea worth having" — yes — from "is this specific implementation's enforcement real" — no). Given items 2–5 involve genuine container-escape surface in infrastructure every future kit would inherit, I'd treat this one as higher-priority to resolve than a typical implementation-detail review.

[wz-gsa]

Heads-up, no action needed from you: we've moved out of your way on the ADR number.

integrations/isolation/docs/decisions/0003- was claimed by two open PRs — this one (opened 2026-09-15) and my #423 (opened 2026-09-18). Different filenames, so git would have merged both cleanly and left two ADR-0003s in the same directory, with every later "ADR 0003 (isolation)" reference ambiguous.

You claimed it first and your number isn't cited anywhere outside this PR, so #423 is now ADR 0004 (dae9e3a), and I've followed the rename through #436's two comment references plus issues #424/#425/#435. serviceGateways keeps 0003 — nothing for you to change.

Worth noting there's a similar pair still open in quickstart: #507 and #504 both add an 0030-, and #500 already holds 0031 while #504's comment says #510 will take it. Both of those are yours to settle; I raised it on #507 with a suggestion that #504 keeps 0030 since its number is already cited cross-repo from this repo's ADR-0004.

My earlier review findings on this PR (the validator's privileged: true-only escape check, and include:/extends: not being resolved) are unchanged by any of this.

[mogul]

Re-review requested for PR #416.

AI-assisted update by OpenCode Agent; human review is required before merge.

Changes since the prior review:

• Updated the PR branch from origin/main with a non-destructive merge commit.
• Confirmed serviceGateways is present in schemas/kit-hybrid-v1.schema.json with runtime.compose.files minItems: 1, required runtime.compose.service, interface, and expose.env shape constraints.
• Hardened integrations/isolation/acq-kits/validate-kits.py for service-gateway Compose files:
  • rejects empty runtime.compose.files and still verifies the named service exists in referenced kit-local Compose files;
  • rejects Compose include: and service extends.file indirection;
  • rejects host-published Compose ports: instead of using them as gateway endpoint evidence;
  • infers candidate ports only from internal expose: entries when interface.port is omitted;
  • rejects privileged: true, Docker socket mounts, host path mounts, host network_mode / pid / ipc / userns_mode / cgroup, cap_add, security_opt confinement disabling, devices, and build;
  • rejects unresolved Compose interpolation in high-risk fields where validation cannot prove the resolved value is safe;
  • rejects local file-reference features (env_file, secrets.file, configs.file).
• Added regression tests for the security-relevant validator paths, including the adversarial follow-up cases.
• Clarified in the ADR, schema description, and acq-kits README that v1 source trust is not machine-readable schema/validator enforcement; it remains a human review and consumer-configuration decision.
• ADR numbering was checked after merging origin/main; serviceGateways remains ADR 0003 and no numbering conflict is present on this branch.

Adversarial review before push:

• Ran a read-only sub-agent adversarial review focused on the service gateway schema/validator boundary.
• Findings were addressed before this push: Compose interpolation bypasses, cgroup: host, and env_file / secrets.file / configs.file local file references.

Verification transcript:

• python3 -m py_compile integrations/isolation/acq-kits/validate-kits.py passed.
• PATH="$PWD/.venv/bin:$PATH" make validate-kits passed: all 8 acq-kits valid.
• PATH="$PWD/.venv/bin:$PATH" make validate passed: 47/47 files passed validation; existing advisory sensitive-term and balanced-allowlist warnings were reported, no validation failures.
• PATH="$PWD/.venv/bin:$PATH" make test passed: 441 tests passed.
• PATH="$PWD/.venv/bin:$PATH" pytest scripts/tests/test_validate_kits_service_gateways.py passed: 40 tests passed.
• PATH="$PWD/.venv/bin:$PATH" make generate-check passed: INDEX.yaml and CATALOG.md up to date.
• PATH="$PWD/.venv/bin:$PATH" ruff check integrations/isolation/acq-kits/validate-kits.py scripts/tests/test_validate_kits_service_gateways.py passed.
• PATH="$PWD/.venv/bin:$PATH" ruff format --check integrations/isolation/acq-kits/validate-kits.py scripts/tests/test_validate_kits_service_gateways.py passed.

Notes:

• Local python was not present on PATH, so verification used python3 and a local .venv created with uv run --extra dev; no dependency files were intentionally changed.
• Commit signing is recommended but not enforced. The environment's signing agent socket was unavailable, so the merge and fix commits were created with per-command commit.gpgsign=false rather than changing repository or global git config.

[mogul]

CI/status follow-up for head 6b5aa67c7d92e4aa7455b88eb1de37fc2180672e: all reported PR checks passed after push. Passing checks: Conventional Commit Title, Python Lint & Test, Python 3.12 Compatibility, Markdown Lint, Link Check, Pattern Validation, and acq-kits Tests. PR remains blocked only by required human review (reviewDecision: REVIEW_REQUIRED).

[wz-gsa]

Reviewed the serviceGateways validator (validate-kits.py, +12 functions) against the schema. Two blockers, two should-fix. Every finding below is verified end-to-end: the claim is run through the PR's actual _compose_escape_errors, and the consequence is confirmed against Docker Compose v5.5.1 and Docker Engine 29.8.0 via docker inspect.

This comment was revised after I started the Docker daemon. My first version asserted privileged: 1 as a second evasion form; that is wrong — Compose rejects it. The correction and the exact measured truthy set are in the blocker below, and the proposed helper has changed accordingly. Two findings were also upgraded once I could observe the engine. I would rather restate the whole review correctly than leave a wrong claim standing.

Context for the scrutiny: a kit declares a Compose file that acq then runs, kits are fetched from a remote repo, and this validator is the only gate between a kit author and a container on the operator's machine.

---

Blocker 1 — privileged: "true" passes validation and yields a fully privileged container

# validate-kits.py:268
if service.get("privileged") is True:

Python identity against a bool. Through the PR's own function:

privileged: true     -> BLOCKED
privileged: "true"   -> ALLOWED  (bypass)
privileged: "yes"    -> ALLOWED  (bypass)
privileged: "on"     -> ALLOWED  (bypass)

And the engine honours the string form:

$ docker compose up -d                       # privileged: "true"
$ docker inspect --format '{{.HostConfig.Privileged}}'
true

container CapEff: 000001ffffffffff     <- every capability
normal    CapEff: 00000000a80425fb

Correction to my earlier version

I previously claimed privileged: 1 also evades. It does not:

privileged: 1     -> validating compose.yml: services.a.privileged must be a boolean or string
privileged: "1"   -> error while interpolating services.a.privileged: invalid boolean: 1

Compose rejects both integer forms, so the value == 1 arm in my earlier suggestion was dead code. The real evasion set, measured exhaustively:

ACCEPTED as true:  true TRUE True / yes YES / on ON / y Y     (case-insensitive)
REJECTED outright: 1  "1"  t  f
Correctly falsy:   false  no  n  off

Suggested fix

_COMPOSE_TRUE = frozenset({"true", "yes", "on", "y"})

def _is_compose_true(value: object) -> bool:
    """Compose accepts YAML booleans and a case-insensitive string set; the engine
    coerces both. Integers are rejected by Compose itself, so they are not here."""
    if value is True:
        return True
    return isinstance(value, str) and value.strip().lower() in _COMPOSE_TRUE

Verified against all 17 forms above with zero mismatches. Worth routing any other Compose boolean through the same helper so the next one added inherits it.

---

Blocker 2 — bare $VAR interpolation evades every check that depends on it

# validate-kits.py:228
return "${" in value

Only the braced form. Compose interpolates bare $VAR as well, and the difference is decisive — through the PR's own function:

pid: ${PIDMODE}   -> BLOCKED  ("declares pid with Compose interpolation")
pid: $PIDMODE     -> ALLOWED  (bypass)

$ PIDMODE=host docker compose up -d
$ docker inspect --format '{{.HostConfig.PidMode}}'
host

So pid: $PIDMODE gives the host PID namespace with a clean validation pass. The same helper guards network_mode, ipc, userns_mode, cgroup, cap_add, devices, and build, so each has the identical hole.

The volume case is the one I would fix first. _volume_source returns the literal $HOME, which starts with none of /, ~, or ., so it falls past all three arms at :304-315 with no error:

_compose_escape_errors on '- $HOME:/hostfs:ro'  ->  NO ERRORS

$ docker compose up -d
$ docker inspect --format '{{range .Mounts}}{{.Type}} {{.Source}} -> {{.Destination}}{{end}}'
bind /Users/williamjzujkowski -> /hostfs

$ docker exec … ls /hostfs
2026-02-23_Passwords.kdbx
Applications
Desktop

A kit fetched from a remote repo gets a readable bind mount of the operator's home directory, including a password database. I raised this as a should-fix before I could run the daemon; having watched it mount, it belongs here.

Suggested fix

_COMPOSE_VAR_RE = re.compile(r"\$[A-Za-z_][A-Za-z0-9_]*")

if isinstance(value, str):
    # Compose escapes a literal $ as $$; strip those before looking for a bare $VAR.
    return "${" in value or _COMPOSE_VAR_RE.search(value.replace("$$", "")) is not None

./conf:/etc/conf  -> False        $HOME:/hostfs    -> True
data:/data        -> False        ${HOME}:/hostfs  -> True
price$5           -> False
$$escaped         -> False        <- my first attempt wrongly flagged this
$$HOME:/x         -> False

The $$ handling matters: my initial regex rejected Compose's escape for a literal $, which would have failed legitimate kits.

---

Should-fix 1 — device_cgroup_rules is unchecked, while devices is blocked

device_cgroup_rules: ["b 7:* rmw"]   -> ALLOWED
devices: ["/dev/sda:/dev/sda"]       -> BLOCKED     (control)
group_add: ["0"]                     -> ALLOWED

It reaches the engine intact:

$ docker inspect --format '{{.HostConfig.DeviceCgroupRules}}'
[b 7:* rmw]

device_cgroup_rules grants device access by major:minor — functionally the same class as devices. Blocking one and not the other reads as an oversight. group_add is worth a line too (adding the host docker GID matters if a socket is ever reachable), though it is conditional rather than a primitive.

Full measured coverage:

CHECKED  : build cap_add cgroup devices ipc network_mode pid privileged security_opt userns_mode volumes
NOT SEEN : cgroup_parent device_cgroup_rules dns entrypoint extra_hosts group_add sysctls tmpfs user uts

I am deliberately not flagging uts, sysctls, cgroup_parent, tmpfs, dns, extra_hosts, user, or entrypoint — none is a container-escape primitive by itself here, and padding the list would make the real items easier to dismiss.

---

Verified correct, including one thing worth calling out

The degraded path is right, and that is rare. Every continue in the compose loop at :477-500 is preceded by an errors.append(), so a missing, unparseable, non-relative, or kit-escaping Compose file fails validation rather than being skipped. And inspected_compose is a genuine coverage flag:

if inspected_compose and compose_service and not found_named_service:

so the service-name assertion cannot pass vacuously when nothing was read. That is the discipline this repo has had to retrofit elsewhere, present here unprompted.

Also checked and clean:

• _volume_source handles both short ("/host:/ctr") and long ({type: bind, source: …}) syntax — the classic single-syntax bypass is closed.
• docker.sock matched by substring before the path checks, so the error names the real reason.
• security_opt catches unconfined, seccomp=, apparmor=.
• Relative volume sources resolved and confined with relative_to(kit_dir).
• build: refused outright; include: and extends.file both refused.
• _parse_compose_port excludes bool from its int branch — a trap someone clearly thought about.
• _uses_floating_image behaves per its docstring, and the registry-port case (reg:5000/alpine) is handled correctly.

---

Claims I withdrew rather than report

• pid: HOST (uppercase) evading == "host". Now tested with a live daemon: Error response from daemon: invalid PID mode: HOST. The engine rejects it, so there is no bypass. Withdrawn.
• nginx:stable passing _uses_floating_image. Correct per the docstring ("untagged or explicitly tagged latest"), and the warning already says "pin a stable tag or digest". Not a defect.

---

One design note, unrelated to defects

expose.env's rule — "Values are symbolic names, not literals; v1 supports only 'url'", enforced with const: "url" — is the cleanest answer in this codebase to "a kit must not name a credential it does not own". Strictly better than handing a kit a variable name and trusting it. If a provider-facing equivalent is ever needed, this is the pattern to copy rather than reinvent.

---

AI-assisted review (OpenCode), prepared on operator instruction. Advisory. Both blockers are small fixes with disproportionate blast radius; the two should-fix items are genuinely minor.

[mogul]

Re-review requested for the updated PR branch.

Thank you for the corrected, measured review. The reported blockers were valid. This update rebases the branch onto current origin/main and addresses them as follows:

• rejects Compose-supported truthy strings for privileged (true, yes, on, and y, case-insensitively), in addition to YAML boolean true;
• fails closed for both braced ${VAR} and bare $VAR Compose interpolation in high-risk fields, while preserving Compose $$ literal-dollar escapes;
• rejects interpolated privileged values explicitly;
• rejects device_cgroup_rules and group_add, including interpolated forms;
• adds regression coverage for all reported bypass forms and escaped-dollar non-regressions.

An independent read-only adversarial review was run before this push. It identified the missing interpolated-privileged guard; that guard and its braced/bare interpolation tests are included in this update. No unresolved material findings remain from that review.

Verification:

python3 -m py_compile integrations/isolation/acq-kits/validate-kits.py  PASS
uv run --link-mode=copy --extra dev pytest scripts/tests/test_validate_kits_service_gateways.py -v  PASS (55 passed)
make validate-kits  PASS
make validate  PASS
make generate-check  PASS
make test  PASS (462 passed)
ruff check integrations/isolation/acq-kits/validate-kits.py scripts/tests/test_validate_kits_service_gateways.py  PASS
ruff format --check integrations/isolation/acq-kits/validate-kits.py scripts/tests/test_validate_kits_service_gateways.py  PASS
git diff --check  PASS

Commit: 48eda7d fix(isolation): close service gateway Compose bypasses

AI-assisted update by OpenCode Agent. Human review remains required before merge. Please re-review the updated head.

[wz-gsa]

AI-assisted re-review (OpenCode), advisory — needs a human to confirm before it drives a change. Reviewed head 48eda7d5.

Both blockers and both should-fixes are closed. I re-ran my original bypasses against the new code rather than reading the diff. One new finding, same class as blocker 1.

Blocker 1 — truthy-string privileged — closed

_is_compose_true normalizes with .strip().lower() against {true,yes,on,y}. Re-ran my exact bypasses plus surrounding cases:

True 'true' 'yes' 'on' 'y'        -> BLOCKED   (my three bypasses now caught)
'TRUE' 'Yes' 'ON' 'Y' 'True'      -> BLOCKED   (case-insensitive)
' true ' '\ttrue\n'               -> BLOCKED   (whitespace-padded)
'${PRIV}' '$PRIV'                 -> BLOCKED   (interpolation arm)
False 'false' 'no' 'off' 'n'      -> allowed   (correct)
'1' 1 '0' 0 't'                   -> allowed   (see note below)

Blocker 2 — bare $VAR interpolation — closed, and the $$ escape is right

_COMPOSE_VAR_RE handles the bare form, and stripping $$ first means the Compose literal-dollar escape is not misread as interpolation. Probed the boundary:

'${PIDMODE}' '$PIDMODE'   -> BLOCKED   (my bypass now caught)
'pre$VAR-post'            -> BLOCKED   (mid-string)
'$_X'                     -> BLOCKED   (leading underscore is a valid var name)
'$$PIDMODE' '$$' 'a$$b'   -> allowed   (escaped literal, correct)
'$$HOME/$REAL'            -> BLOCKED   (escape plus a real var — correct)
'${A}$$'                  -> BLOCKED
'$1' '$9abc' '$'          -> allowed   (not valid Compose var names)

The '$$HOME/$REAL' case is the one I would have expected a naive implementation to get wrong, and it is right. Recursion into lists and dicts is there too, so cap_add: ["$CAP"] is covered.

Should-fixes — closed

device_cgroup_rules and group_add are both rejected, each with a paired interpolation check. 55/55 in test_validate_kits_service_gateways.py.

New finding (should-fix): Compose lifecycle hooks carry their own privileged

Pulled the upstream Compose spec to check whether privileged appears anywhere other than the service body. It appears in three places:

$defs.container_spec.properties.privileged      {"type": ["boolean","string"]}   <- checked
$defs.service_hook.properties.privileged        {"type": ["boolean","string"]}   <- NOT checked
$defs.workload_spec.…build.…privileged          {"type": ["boolean","string"]}   <- n/a, build already rejected

service_hook is post_start / pre_stop. Neither the validator nor the test suite mentions them:

$ grep -n 'post_start\|pre_stop\|service_hook' validate-kits.py            (no matches)
$ grep -n 'post_start\|pre_stop' test_validate_kits_service_gateways.py    (no matches)

So a gateway can declare a privileged lifecycle hook and pass the gate — the same escape blocker 1 was about, one level down. The upstream schema typing it as ["boolean","string"] is also what made the truthy-string bypass possible in the first place, so the two findings share a root cause. The fix is mechanical: run the existing _is_compose_true / _has_compose_interpolation pair over service.get("post_start") and service.get("pre_stop") entries.

Worth noting the schema does confirm your design choice: typing these fields as ["boolean","string"] is exactly why identity-against-True was never sufficient, and _is_compose_true is the right shape of fix.

Two small notes, not findings

• '1' and 1 are allowed for privileged. The Compose spec types the field as boolean-or-string without enumerating the accepted strings, so whether the engine coerces "1" is engine-specific rather than spec-defined. I did not find an authoritative list, so I am not claiming it is a bypass — flagging that the truthy set is an allowlist of four spellings, and if the engine accepts more, the set needs them. If you confirmed the four against an engine, saying so in the comment would pin it.
• 't' is allowed while 'y' is blocked. Harmless asymmetry; 't' is not in the Compose truthy set either, so this is consistent with the four-spelling allowlist.

---

Method: transcribed _is_compose_true and _has_compose_interpolation and probed 24 privileged values and 14 interpolation forms, including every bypass from my prior review; fetched the upstream compose-spec.json and walked it for every occurrence of privileged; grepped the validator and its test file for hook coverage; ran the cited suite (55 passed).

UNVERIFIED: I did not stand up a Compose engine, so the "does the engine coerce "1"" question above is open, and the docker inspect confirmation from my earlier review is not re-run on this head. Your make validate / make test (462) results are taken on your evidence.

[wz-gsa]

Both blockers closed. I re-ran my original reproductions against this head, and separately settled the one residual question I had about the truthy set.

Blocker 1 — string-form privileged now caught

_is_compose_true (:247) replaces the is True identity check. Run against the real function at this head:

privileged=True     -> True        privileged='1'      -> False
privileged='true'   -> True        privileged=1        -> False
privileged='True'   -> True        privileged='false'  -> False
privileged='TRUE'   -> True        privileged=False    -> False
privileged='yes'    -> True        privileged=None     -> False
privileged='on'     -> True

The '1' / 1 question — settled, and your set is exactly right

My open worry was that privileged: 1 and privileged: "1" return False. I could not settle it from the compose-spec schema, which declares privileged as {"type": ["boolean", "string"]} with no enum. So I asked the real binary (piped on stdin, nothing written to disk):

$ docker compose version
Docker Compose version v5.5.1

privileged: 1        -> validating -: services.a.privileged must be a boolean or string
privileged: "1"      -> invalid boolean: 1
privileged: "0"      -> invalid boolean: 0
privileged: "true"   -> privileged: true
privileged: "TRUE"   -> privileged: true
privileged: "yes"    -> privileged: true
privileged: "on"     -> privileged: true
privileged: "y"      -> privileged: true
privileged: "n"      -> false
privileged: "off"    -> false
privileged: "false"  -> false

So 1 and "1" are rejected by Compose itself — the file never loads, and there is nothing for the validator to miss. Confirmed upstream in compose-go (loader/interpolate.go:133-147), whose toBoolean accepts exactly true/false/y/yes/on/n/no/off and errors on anything else.

_COMPOSE_TRUE = {"true", "yes", "on", "y"} is therefore precisely Compose's own truthy set, not an approximation. No residual gap. Worth a short comment on that frozenset recording where the set comes from, so a future reader does not "helpfully" add "1" and widen it past what Compose accepts — but that is a nit, not a finding.

Blocker 2 — bare $VAR interpolation now caught

_has_compose_interpolation (:231-241) with _COMPOSE_VAR_RE = \$[A-Za-z_][A-Za-z0-9_]*:

'$HOME:/hostfs'    -> True       <- my original bypass, now caught
'${HOME}:/hostfs'  -> True
'$DOCKER_SOCK'     -> True
'$$HOME:/hostfs'   -> False      <- correct: $$ is a literal $ in Compose
'/safe:/safe'      -> False

The $$ handling is the part I would most likely have got wrong myself, and it is right: value.replace("$$", "") before matching, so an escaped dollar is not mistaken for interpolation.

Also the right verdict shape — interpolation is reported as declares privileged with Compose interpolation; validation cannot prove it safe (:285) rather than as a privilege grant. That distinguishes "this is dangerous" from "I cannot tell", which is the distinction that matters for a gate.

Verdict: approving

Both blockers verified closed against the actual code, and the one question I left open resolves in the implementation's favour.

What I did not verify, so the approval is not read as broader than it is: I did not re-run my earlier live-daemon tests at this head (the earlier round proved HostConfig.Privileged=true and CapEff 000001ffffffffff for the string form, and that $HOME:/hostfs mounted a real home directory). Those established the consequence; this round establishes the detection, which is what changed. I also have not exercised include:/extends: resolution, which I raised earlier as a separate should-fix — if that is still open it is not blocking this approval.

AI-assisted review (OpenCode), approved on the maintainer's authority with their explicit go-ahead for this PR. Advisory — a human owns the merge.

[wz-gsa]

Correcting the formal review state: the head is unchanged at 48eda7d and the service-hook bypass from my 2026-10-08 review remains unresolved. / hook objects have their own boolean-or-string field in the upstream Compose schema, but the validator and tests do not inspect them. A gateway can therefore pass validation with a privileged lifecycle hook. Please apply the existing / checks to hook entries before merge. The later approval under my account came from a concurrent review that confirmed the original four fixes but did not include this new finding.

[mogul]

Re-review requested for the updated PR branch.

This update resolves the remaining blocking review: service lifecycle hooks can independently declare privileged. The service-gateway Compose validator now inspects every post_start and pre_stop hook entry and rejects both Compose-supported truthy privileged values and unresolved interpolated values.

Added regression coverage for both hook types and both direct-true and $VAR interpolation forms.

Verification transcript:

python -m py_compile integrations/isolation/acq-kits/validate-kits.py  PASS
uv run --link-mode=copy --extra dev pytest scripts/tests/test_validate_kits_service_gateways.py -v  PASS (59 passed)
make validate-kits  PASS (10 kits valid)
make validate  PASS (47/47 files; existing advisory warnings only)
make generate-check  PASS
make test  PASS (466 passed)
uv run --link-mode=copy --extra dev ruff check integrations/isolation/acq-kits/validate-kits.py scripts/tests/test_validate_kits_service_gateways.py  PASS
uv run --link-mode=copy --extra dev ruff format --check integrations/isolation/acq-kits/validate-kits.py scripts/tests/test_validate_kits_service_gateways.py  PASS
git diff --check  PASS

The Make targets were executed with the local .venv/bin prepended because this environment provides python3, not python.

Commit: 04f4f21 fix(isolation): validate privileged lifecycle hooks

AI-assisted update by OpenCode Agent. Human review remains required before merge. Please re-review the updated head.