✨ feat(filter): validate Engine API 1.55 and gate BuildKit's opaque tunnel (#153)

[scttbnsn]

Implements #153: Engine API 1.55 coverage validation plus an explicit posture for the Compose/BuildKit transport, per the finalized design.

Transport decision

• Default docker compose build uses the /session + /grpc hijacked opaque streams (deprecated in API 1.53, still used by Buildx 0.36.0). These stay denied — they carry secrets, SSH agent forwarding, and arbitrary file sync with no body sockguard can inspect.
• New dedicated ack insecure_accept_opaque_buildkit_tunnels: any allow rule admitting /session, /grpc, or a moby.buildkit.v1.Control/* path fails startup without it. Deliberately separate from insecure_allow_body_blind_writes (that gate models bounded single-resource writes; these tunnels don't fit that threat model).
• Tecnativa GRPC=1/SESSION=1 compat vars still work (auto-ack) but log a deprecation warning naming the new key, preserving drop-in migration.
• New drydock-with-build.yaml / portwing-with-build.yaml presets take the classic-builder path (DOCKER_BUILDKIT=0) with docs stating plainly that the BuildKit denial is intentional. In-tunnel gRPC mediation is deferred to v1.7 (epic to be filed).

API 1.55 gap closures

Unknown mount types now fail closed; Mount.Subpath validated; TmpfsOptions.Options privilege-gated behind allow_tmpfs_privileged_options; network EnableIPv4 gated by network.allow_disable_ipv4 and GwPriority round-trips; GET /images/{name}/attestations?statement=true denied by default behind response.allow_attestation_statements (conformance test walks all shipped presets); X-Registry-Auth/X-Registry-Config bounded-decoded (8 KiB cap, all base64 variants, fail-closed, serveraddress checked against the registry allowlist, credentials never logged); new opt-in response.redact_host_topology; container-update resource-control field-set completeness test; max-supported-version.txt pin (1.55) + regression test + monthly quality-api-version-watch.yml workflow; h2c-preface integration test proving no HTTP/2 upgrade surface; fuzz-seed corpus extended (/v1.55/, /session, /grpc).

SwapBytes/MemorySwappiness intentionally not duplicated here — #152's resource-limit guard owns update-path resource semantics.

Follow-ups to file (not in this PR)

BuildKit gRPC mediation epic (v1.7); allow_endpoint_config narrowing; pinned multi-Engine CI matrix (26.1/28.0/29.2/29.7); bounding exec.go's inspect decode.

Verification

go build, go test ./..., golangci-lint, go vet all clean; full pre-push hook suite green after rebase onto the merged Wave 1 trunk (#149/#151/#152 logging and config integrations resolved and re-tested).

Fixes #153

✨ Added

• Added insecure_accept_opaque_buildkit_tunnels as an explicit opt-in for /session, /grpc, and moby.buildkit.v1.Control/* access.
• Added classic-build presets for Drydock and Portwing. They use POST /build and keep BuildKit tunnels denied.
• Added response.redact_host_topology and response.allow_attestation_statements config flags.
• Added request_body.container_create.allow_tmpfs_privileged_options and request_body.network.allow_disable_ipv4 config flags.
• Added monthly/manual workflow quality-api-version-watch.yml to check the pinned Engine API ceiling.
• Added tests for BuildKit tunnel gating, compat auto-ack, H2C rejection, container mount checks, network checks, registry header parsing, response filtering, and version pin validation.

🔧 Changed

• Updated compat handling to auto-set InsecureAcceptOpaqueBuildkitTunnels when GRPC=1 or SESSION=1 is present.
• Updated response filter wiring to pass host-topology redaction and attestation allow flags.
• Updated build, image pull, container create, network, and registry auth filters with stricter request checks.
• Updated preset docs to describe classic-builder-only support and BuildKit denial.
• Updated configuration, security, and preset docs for the new gates and defaults.
• Pinned the supported Docker Engine API version to 1.55.

🐛 Fixed

• Rejected unknown mount types in container create.
• Rejected unsafe Mount.Subpath values.
• Rejected privileged tmpfs options unless explicitly allowed.
• Rejected EnableIPv4: false unless explicitly allowed.
• Rejected non-zero GwPriority when endpoint config is not allowed.
• Rejected malformed or disallowed X-Registry-Auth and X-Registry-Config headers.
• Rejected attestation statement fetches by default.
• Rejected raw HTTP/2 cleartext client prefaces.

🔒 Security

• BuildKit tunnels stay denied unless the new explicit acknowledgment is set.
• Registry auth and config headers now use bounded decode and allowlist checks.
• Registry denial reasons do not leak decoded credentials.
• /info host-topology fields can now be redacted.
• POST /images/*/attestations?statement=true is denied by default.

⚠️ Breaking

• Existing BuildKit tunnel access now fails closed unless insecure_accept_opaque_buildkit_tunnels is enabled.
• Compose build paths that depend on BuildKit streams are denied unless a classic-builder preset is used.
• API 1.55 support is now the pinned ceiling.
• Unknown mount types now fail closed.
• EnableIPv4: false, GwPriority, tmpfs privileged options, and attestation statements now require explicit policy opt-in.
• Legacy GRPC and SESSION env vars now emit a deprecation warning.
• The version-watch workflow will fail when Docker docs move past the pinned API version.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sockguard-website	Ready	Preview	Aug 5, 2026 1:11pm

[coderabbitai]

Warning

Review limit reached

@scttbnsn, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 44 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 93d77033-ca88-4220-8fa3-1616e4b9d6b6

📥 Commits

Reviewing files that changed from the base of the PR and between 1a8ff33 and acd6fba.

📒 Files selected for processing (2)

• docs/content/docs/configuration.mdx
• docs/content/docs/security.mdx

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/153-engine-api-validation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (4)

app/internal/filter/build_test.go (1)

1328-1345: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use a table-driven middleware test.

Convert this standalone case to a table-driven test. Keep the malformed Base64 case in the table. This makes the middleware contract ready for malformed JSON and over-limit header cases.

As per coding guidelines, **/*_test.go: “Write tests as table-driven tests using testing.T and httptest.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/internal/filter/build_test.go` around lines 1328 - 1345, Convert
TestMiddlewareDeniesBuildWithMalformedRegistryConfigHeader into a table-driven
test with named cases, retaining the malformed Base64 header scenario and its
forbidden response assertion. Structure each case to support adding malformed
JSON and over-limit header inputs, while preserving the middleware setup and
upstream-denial behavior.

Source: Coding guidelines

app/internal/filter/container_create.go (1)

719-727: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

validMountSubpath does not reject . or embedded traversal into a cleaned-safe path — confirm the intended posture.

Current behavior: path.Clean collapses "a/../b" to "b" and allows it. That is safe. "." is also allowed, which is equivalent to no subpath. Both are acceptable. One gap remains: an empty-after-trim value such as " " is not "", is not absolute, and cleans to " ", so it passes as a literal directory name. That matches Docker semantics, so no change is required unless you want strings.TrimSpace normalization for parity with the rest of the file.

No action needed if the posture is intentional.

Also applies to: 1246-1293

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/internal/filter/container_create.go` around lines 719 - 727, Confirm that
validMountSubpath intentionally permits "." and traversal that path.Clean safely
normalizes, as well as whitespace-only values treated as literal directory names
under Docker semantics. No code changes are required unless the project
explicitly wants strings.TrimSpace normalization for parity with nearby
validation.

app/internal/filter/container_create_test.go (1)

2871-2913: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add case-variant mount-type cases.

denyUnknownMountTypeReason lowercases Mount.Type. No case tests exist. Add "BIND" and "Volume" cases to pin the intended behavior, and to catch a divergence if the bind allowlist check compares Type case-sensitively.

Proposed added cases

 		{
 			name: "image mount type passes through when trust is off",
 			body: `{"HostConfig":{"Mounts":[{"Type":"image","Source":"alpine:latest"}]}}`,
 		},
+		{
+			name: "uppercase bind mount type still allowlist-checked",
+			body: `{"HostConfig":{"Mounts":[{"Type":"BIND","Source":"/safe"}]}}`,
+		},
+		{
+			name:       "uppercase bind mount type with non-allowlisted source denied",
+			body:       `{"HostConfig":{"Mounts":[{"Type":"BIND","Source":"/etc"}]}}`,
+			wantReason: `container create denied: bind mount source "/etc" is not allowed`,
+		},

Adjust wantReason to the exact string denyBindMountReason produces.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/internal/filter/container_create_test.go` around lines 2871 - 2913,
Extend TestContainerCreateUnknownMountType with cases for mount types "BIND" and
"Volume", verifying they follow the same behavior as their lowercase
equivalents. For the bind case, use an allowlisted source and set wantReason to
the exact denyBindMountReason output if the source is denied; ensure the
assertions pin case-insensitive mount-type handling.

app/internal/filter/container_update_test.go (1)

298-305: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Compare the field set, not the slice order.

The index-by-index assertion fails when a maintainer inserts a new field out of alphabetical position, even though the policy behavior is unchanged. Order carries no meaning for a presence check. Compare as a set and keep the length guard.

Proposed change

-	if len(containerUpdateResourceControlFields) != len(want) {
-		t.Fatalf("containerUpdateResourceControlFields has %d fields, want %d: %v", len(containerUpdateResourceControlFields), len(want), containerUpdateResourceControlFields)
-	}
-	for i, field := range want {
-		if containerUpdateResourceControlFields[i] != field {
-			t.Fatalf("containerUpdateResourceControlFields[%d] = %q, want %q", i, containerUpdateResourceControlFields[i], field)
-		}
-	}
+	got := slices.Clone(containerUpdateResourceControlFields)
+	slices.Sort(got)
+	wantSorted := slices.Clone(want)
+	slices.Sort(wantSorted)
+	if !slices.Equal(got, wantSorted) {
+		t.Fatalf("containerUpdateResourceControlFields = %v, want %v", got, wantSorted)
+	}

Add "slices" to the imports.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/internal/filter/container_update_test.go` around lines 298 - 305, Update
the assertions covering containerUpdateResourceControlFields to compare field
membership as an unordered set rather than index-by-index, while retaining the
existing length guard. Add the slices import and use its set-equivalence helper
so reordered fields pass while additions or removals still fail.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/content/docs/configuration.mdx`:
- Line 56: Update the redact_host_topology descriptions at
docs/content/docs/configuration.mdx lines 56, 257, 1040, and 1174 to list the
actual GET /info fields cleared by this setting: Containerd, FirewallBackend,
DiscoveredDevices, and NRI, replacing the kernel/OS/arch/name/labels examples.

In `@docs/content/docs/security.mdx`:
- Line 148: Update the description near the classic POST /build comparison to
identify its request body as bounded and inspectable tar data, using the
application/x-tar build-context semantics instead of describing it as
JSON-decodable. Preserve the surrounding contrast with the ongoing binary
session/gRPC transport.

---

Nitpick comments:
In `@app/internal/filter/build_test.go`:
- Around line 1328-1345: Convert
TestMiddlewareDeniesBuildWithMalformedRegistryConfigHeader into a table-driven
test with named cases, retaining the malformed Base64 header scenario and its
forbidden response assertion. Structure each case to support adding malformed
JSON and over-limit header inputs, while preserving the middleware setup and
upstream-denial behavior.

In `@app/internal/filter/container_create_test.go`:
- Around line 2871-2913: Extend TestContainerCreateUnknownMountType with cases
for mount types "BIND" and "Volume", verifying they follow the same behavior as
their lowercase equivalents. For the bind case, use an allowlisted source and
set wantReason to the exact denyBindMountReason output if the source is denied;
ensure the assertions pin case-insensitive mount-type handling.

In `@app/internal/filter/container_create.go`:
- Around line 719-727: Confirm that validMountSubpath intentionally permits "."
and traversal that path.Clean safely normalizes, as well as whitespace-only
values treated as literal directory names under Docker semantics. No code
changes are required unless the project explicitly wants strings.TrimSpace
normalization for parity with nearby validation.

In `@app/internal/filter/container_update_test.go`:
- Around line 298-305: Update the assertions covering
containerUpdateResourceControlFields to compare field membership as an unordered
set rather than index-by-index, while retaining the existing length guard. Add
the slices import and use its set-equivalence helper so reordered fields pass
while additions or removals still fail.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 224bb263-4890-4bf9-be8c-f3dfcc0d7569

📥 Commits

Reviewing files that changed from the base of the PR and between 04ce375 and 1a8ff33.

⛔ Files ignored due to path filters (1)

• CHANGELOG.md is excluded by !CHANGELOG.md

📒 Files selected for processing (34)

• .github/workflows/quality-api-version-watch.yml
• app/configs/drydock-with-build.yaml
• app/configs/drydock-with-compose.yaml
• app/configs/portainer.yaml
• app/configs/portwing-with-build.yaml
• app/configs/portwing-with-compose.yaml
• app/internal/cmd/rules.go
• app/internal/cmd/rules_test.go
• app/internal/cmd/serve.go
• app/internal/cmd/serve_h2c_test.go
• app/internal/config/compat.go
• app/internal/config/compat_test.go
• app/internal/config/config.go
• app/internal/config/filter_options.go
• app/internal/filter/build.go
• app/internal/filter/build_test.go
• app/internal/filter/container_create.go
• app/internal/filter/container_create_test.go
• app/internal/filter/container_create_types.go
• app/internal/filter/container_update_test.go
• app/internal/filter/fuzz_test.go
• app/internal/filter/image_pull.go
• app/internal/filter/image_pull_test.go
• app/internal/filter/network.go
• app/internal/filter/network_test.go
• app/internal/filter/registry_auth.go
• app/internal/filter/registry_auth_test.go
• app/internal/filter/version_pin_test.go
• app/internal/responsefilter/filter.go
• app/internal/responsefilter/filter_test.go
• app/testdata/docker-api/max-supported-version.txt
• docs/content/docs/configuration.mdx
• docs/content/docs/presets.mdx
• docs/content/docs/security.mdx