Skip to content

Build and audit the DockerCatAgent container foundation - #1

Merged
danielbrownjr merged 14 commits into
mainfrom
feat/claude-docker-foundation
Oct 14, 2026
Merged

danielbrownjr merged 14 commits into
mainfrom
feat/claude-docker-foundation

Conversation

@danielbrownjr

@danielbrownjr danielbrownjr commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Result

Builds a persistent, Docker/Compose Claude Code CLI environment with non-root defaults, optional SSH and optional integrations. The foundation audit and independent reviews corrected SSH startup failures, real interactive PTY login, trust-anchor validation, host-key recovery, callback/key-file inputs and runtime regression coverage. Default Compose still drops all capabilities and publishes no ports.

The foundation, operator documentation and GitHub backlog remain under review; this PR is draft and is not release or deployment approval.

Implementation and scoped corrections

  • Official signed Claude Debian distribution with verified upstream signing-key fingerprint; Git, tmux and baseline tools.
  • Dedicated full-home/workspace volumes, configurable resource limits and a CLI prerequisite health check.
  • Opt-in key-only SSH, localhost host binding, persistent host identity and restricted local callback forwarding. The opt-in daemon has only the reviewed AUDIT_WRITE, SETUID, SETGID, CHOWN, SYS_CHROOT and DAC_READ_SEARCH capabilities; interactive sessions run as dev.
  • Optional Obsidian read-only or explicit write overlays; existing bind sources are required instead of silently creating missing directories.
  • Canonical decimal callback validation and nonempty regular authorized-key validation, with focused negative tests.
  • Package-generated SSH private host keys removed from image layers. Installed manpages retained to resolve Debian slim alternative-link warnings.
  • Optional transient BuildKit CA-bundle support for trusted proxy builds without disabling TLS or baking session trust into runtime.
  • CI checks every shell script, explicitly checks out the PR head, disables persisted checkout credentials and pins the inspected Node 24 checkout action.

Verification

Current head: a4898c37f14877ed70eb722b5b523305dda7c7c7

Foundation CI run 38594643801: static and build-smoke passed on the exact current head. CI built the image and ran the credential-free regression suite. Job annotations contain only a GitHub runner migration notice, not a warning/failure.

The earlier pre-review local AMD64 audit (Docker 28.4.0 / Compose v2.40.3) passed:

  • Per-script shell syntax, static security checks, seven base/optional/combined/Portainer Compose configurations, YAML/JSON parsing and whitespace checks.
  • Warning-free image build: Claude 2.1.287, Git 2.39.5, tmux 3.3a; non-root writes and no default ports/vault/socket.
  • Synthetic workspace, .claude.json and .claude/ persistence; tmux termination; actual cached rebuild/recreation and independent volumes for a differently named project.
  • Vault read/write denial and explicit write opt-in.
  • Real disposable-key SSH login; missing/wrong-key, root/password, destination, remote-forward and agent-forward denial; effective restrictions and stable host identity. CI fixtures normalize hosted-runner key-file ownership without relaxing StrictModes.
  • 234 documentation links/anchors, 34 shell examples, credential/path checks and an 11-page temporary wiki export.

Historical pre-review local image: sha256:6a30b29c00db4de9a635aff38549f86201ca8e761339dfa89e6ddac35063a5fb. Cached rebuild retained this image ID; this was not an upgraded-version migration test. See audit and validation for evidence boundaries.

GitHub organization and documentation

Project #2 is canonical; do not create another board. Reading it and the linked repository project is denied by integration permissions, so no board changes are claimed. Description/topics edits and detailed branch-protection inspection were also denied. Native branches report main unprotected.

The separate wiki still contains its original welcome page; this PR's prepared pages were not published.

Remaining acceptance and owner decisions

Foundation is incomplete. Subscription login/state continuity (#4), API-key behavior/exposure (#19), Mem OAuth/grants (#21), ARM64 hardware (#2), real Portainer endpoint (#5), VPN/mobile clients and actual tunnel-device denial (#3) still need manual evidence. Tunnel/Unix-socket restrictions were checked through effective configuration.

No license is approved (#6). Root SSH least privilege, encrypted recovery and supply-chain reproducibility remain later scoped work (#9/#7/#8). Docker administrators can access credential-bearing state; outbound access is available; read-only mounts and tool instructions do not prevent permitted data disclosure.

No merge, release, tag, registry image, production deployment or wiki synchronization occurred. Green CI does not authorize any of them.

Independent SSH/security review remediation (2026-10-14)

  • Current code head: a4898c37f14877ed70eb722b5b523305dda7c7c7
  • Verified exact-head CI: Foundation CI run 38594643801, static and build-smoke both successful on this head.
  • DCA-REV-001: interactive SSH now works on GitHub's Linux runner. A real local + remote PTY login as UID 1000, tmux startup, shell exit, ordinary SSH commands and denial cases were verified. The new test revealed Debian login accounting and .bash_logout edge cases; regression now handles real terminal semantics rather than weakening assertions.
  • DCA-REV-002: signed Anthropic apt repository key checking rejects additional, incorrect, and malformed keys. Disposable GPG positive/negative tests passed in CI and the actual image built.
  • DCA-REV-003/004: corrected authorized_keys permissions documentation and trimmed SSH capabilities; eliminated the privileged chmod of a dev-owned path. Default Docker execution remains non-root and capability-free.
  • Related narrow corrections: rebuild the host public-key sidecar from its intact private key, use short test agent-socket paths, explain root docker compose exec behavior, and clarify optional headless OAuth forwarding.
  • The earlier foundation audit describes the pre-review head and is historical evidence, not proof that all review findings were fixed. CPU-limit portability and broader secret scanning are deferred.

Not validated by this CI: live Claude subscription/API login and Mem OAuth, ARM64, actual Portainer deployment, mobile/VPN access, tunnel-device denial and full root-daemon architecture review. The PR remains draft. No merge, release, image publication, or deployment is authorized.

Final targeted review follow-ups (2026-10-14)

  • D-1 (SSH host identity recovery): secure the restored Ed25519 private key before any ssh-keygen -y operation; recover missing or empty public-key sidecars through a temporary file and atomic rename, without rotating identity. Runtime regression tests recreate a disposable container after a 0644 private-key restoration and after an empty .pub, asserting first-start recovery, mode 0600, nonempty public key, stable identity and no temporary-file residue.
  • D-2 (documentation consistency): align the architecture capability roster with the current overlay, distinguish historical audit evidence from current tests, and clarify that SSH callback forwarding is conditional for some MCP OAuth flows rather than required for Claude subscription login.
  • Exact final commit: a4898c37f14877ed70eb722b5b523305dda7c7c7. CI run 38594643801 passed static and Docker runtime jobs. This remains a draft PR, pending owner review and merge authorization. Account-backed and cross-platform acceptance work remains open.

@danielbrownjr danielbrownjr added type: enhancement New capability or improvement area: container Docker image and runtime area: docs Guides and wiki priority: P1 High priority; next planned milestone status: needs-validation Implementation exists; evidence missing labels Oct 14, 2026 — with ChatGPT Codex Connector
@danielbrownjr danielbrownjr changed the title Build portable DockerCatAgent CLI foundation Build and audit the DockerCatAgent container foundation Oct 14, 2026
@danielbrownjr
danielbrownjr marked this pull request as ready for review October 14, 2026 16:34
@danielbrownjr
danielbrownjr merged commit 7906169 into main Oct 14, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: container Docker image and runtime area: docs Guides and wiki priority: P1 High priority; next planned milestone status: needs-validation Implementation exists; evidence missing type: enhancement New capability or improvement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant