feat(orthrus): server-side Docker proxy listener for agent sessions

[Wikid82]

Problem

After switching a RemoteServer from a generic socat socket proxy to an Orthrus agent, all Docker operations fail with:

Cannot connect to Docker. Please ensure Docker is running and the socket is accessible (e.g., /var/run/docker.sock is mounted).

Root cause: The Orthrus agent already handles streamTypeDocker = 0x01 — when the server opens a yamux stream with that type byte, the agent bridges it to its local /var/run/docker.sock. However, the server-side half was a stub (proxyPort field always 0, GetProxyAddr() always returns ""). Charon's Docker handler had no way to route requests through an agent and fell back to tcp://host:port which points at nothing.

---

What This PR Does

backend/internal/orthrus/session.go

• StartDockerProxy() — binds an ephemeral 127.0.0.1:N TCP listener when an agent connects; idempotency guard (s.listener != nil) prevents double-allocation
• runProxyListener() — accept loop that spawns proxyConn goroutines
• proxyConn() — for each TCP connection: opens a yamux stream, writes type byte 0x01, bidirectionally copies via two io.Copy goroutines + sync.WaitGroup
• GetProxyAddr() — returns "127.0.0.1:N" once the proxy is live; empty string otherwise
• Close() — closes the listener under the mutex; in-flight proxyConn goroutines complete asynchronously as yamux stream close propagates

backend/internal/orthrus/server.go

• Calls sess.StartDockerProxy() after each agent WebSocket connects; logs but does not abort on failure (Docker is optional)

backend/internal/api/handlers/docker_handler.go

• Adds orthrusProxyResolver interface + SetOrthrusResolver() setter
• ListContainers (and other Docker methods) now branch on connection_type == "orthrus":
  • OrthrusAgentUUID == nil → 400
  • orthrusResolver == nil (no encryption key) → 503 with explanation
  • Agent not in sessions map → 502 "Orthrus agent is not currently connected"
  • Agent connected → uses tcp://127.0.0.1:N as Docker host

backend/internal/api/routes/routes.go

• Hoists orthrusServer declaration before the encryption-key block; wires it into dockerHandler after construction (nil is safe — handler returns 503)

---

Tests

12 new acceptance criteria, all green:

Test	Covers
TestAgentSession_StartDockerProxy_ListensOnLoopback	Listener bound to 127.0.0.1
TestAgentSession_StartDockerProxy_GetProxyAddr	Address returned after start
TestAgentSession_StartDockerProxy_CalledTwice	Idempotency — second call returns error, address unchanged
TestAgentSession_Close_ClosesListener	Listener closed on session close
TestAgentSession_ProxyConn_WritesStreamTypeByte	First byte written to yamux stream is 0x01
TestDockerHandler_ListContainers_OrthrusNotConnected	502 when agent offline
TestDockerHandler_ListContainers_OrthrusNoResolver	503 when unconfigured
TestDockerHandler_ListContainers_OrthrusConnected	Docker client uses proxy address
TestDockerHandler_ListContainers_OrthrusMissingUUID	400 for nil agent UUID
+ 3 integration stubs (//go:build integration)	End-to-end proxy flow

Coverage: 88.6% lines / 88.5% statements (gate: 87%). Race detector: clean.

---

Security Notes

• TCP listener is bound exclusively to 127.0.0.1 (loopback) — never exposed outside the host
• Ephemeral port (:0) — no fixed port to block or exploit
• Agent-side muzzle filter already restricts allowed Docker API paths — unchanged
• No credentials in proxy stream; authentication is at the WebSocket layer

---

Checklist

• All pre-commit hooks pass (go-vet, golangci-lint, semgrep)
• 88.6% backend coverage ≥ 87% gate
• Race detector clean
• GORM security scan: no CRITICAL/HIGH findings
• Trivy FS scan: 0 actionable findings
• E2E tests: pass in CI (local Playwright 1.60 blocked by Ubuntu 26.04 infra issue)

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

[github-actions]

✅ Supply Chain Verification Results

✅ PASSED

📦 SBOM Summary

• Components: 1487

🔍 Vulnerability Scan

Severity	Count
🔴 Critical	0
🟠 High	0
🟡 Medium	4
🟢 Low	2
Total	6

📎 Artifacts

• SBOM (CycloneDX JSON) and Grype results available in workflow artifacts

---

_{Generated by Supply Chain Verification workflow • View Details}

[codecov]

Codecov Report

❌ Patch coverage is 95.83333% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
backend/internal/api/handlers/docker_handler.go	95.23%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Implements the server-side half of the Orthrus agent Docker tunnel: when an agent WebSocket connects, the server allocates an ephemeral loopback TCP listener that proxies each TCP connection into a fresh yamux stream prefixed with the 0x01 Docker stream-type byte. The Docker handler now routes connection_type == "orthrus" remote servers through that loopback address instead of tcp://host:port, with explicit 400/502/503 errors for misconfiguration, offline agents, and disabled subsystems.

Changes:

• Add StartDockerProxy/runProxyListener/proxyConn/listener lifecycle to AgentSession and wire the listener start/stop into the WebSocket connect and heartbeat-watcher paths.
• Add orthrusProxyResolver interface + SetOrthrusResolver to DockerHandler and branch on ConnectionType when resolving the Docker host; hoist orthrusServer in routes.go to wire it.
• Add unit tests, an integration-build stub, an extensive feature spec, and a QA/security audit report; minor unrelated test-file whitespace/struct-alignment cleanups.

Reviewed changes

Copilot reviewed 18 out of 21 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
backend/internal/orthrus/session.go	Adds streamTypeDocker, listener field, StartDockerProxy, runProxyListener, proxyConn; updates Close/GetProxyAddr sentinel
backend/internal/orthrus/session_test.go	New tests covering loopback bind, idempotency, close-stops-listener, and type-byte write
backend/internal/orthrus/session_coverage_test.go	Extra coverage for proxyConn Open/Write failure paths; updates existing test for new sentinel
backend/internal/orthrus/server.go	Calls StartDockerProxy on connect; calls sess.Close() in heartbeat-watcher cleanup
backend/internal/orthrus/server_test.go	New end-to-end WebSocket test asserting a loopback proxy address is registered
backend/internal/orthrus/server_coverage_test.go	Updates existing GetProxyAddr test for new listener sentinel
backend/internal/orthrus/proxy_integration_test.go	New //go:build integration skip-stub
backend/internal/api/handlers/docker_handler.go	Adds orthrusProxyResolver interface, setter, and ConnectionType switch with 400/502/503 branches
backend/internal/api/handlers/docker_handler_test.go	New tests for connected/offline/no-resolver/nil-UUID/empty-UUID and nil setter cases
backend/internal/api/routes/routes.go	Hoists orthrusServer declaration and wires SetOrthrusResolver
backend/internal/config/config.go	Re-aligns struct fields (adds CertExpiryWarningDays)
backend/internal/api/handlers/crowdsec_stop_lapi_test.go	Struct-field alignment formatting
backend/internal/api/handlers/crowdsec_coverage_target_test.go	Whitespace/indent cleanup
backend/internal/api/handlers/crowdsec_wave5_test.go, security_notifications_single_source_test.go, system_permissions_*_test.go, certificate_validator_extra_coverage_test.go	Blank-line whitespace cleanups only
SECURITY.md	Updates Last Updated date
docs/reports/qa-security-audit-2026-05-18.md	New QA/security audit report
docs/plans/current_spec.md	Replaces archived CI-fix spec with the Orthrus Docker proxy feature spec