review remediation: deploy CLI remote-execution security — secret delivery, shell escaping, registry password redaction

[bpamiri]

Problem

The wheels deploy Kamal port has a remote-execution security architecture problem: secrets leak through multiple channels, no value is ever shell-escaped before reaching a remote shell, and env.secret is parsed but never delivered. These are one design problem — how commands and secrets reach the remote host. Paths below are relative to cli/lucli/services/deploy/; verified against origin/develop @ 8971094.

1. Registry password leaks through three channels (DEP-2, High)
commands/RegistryCommands.cfc:12-20 renders docker login <server> -u <user> -p <password> as a flat string. Leak paths: (1) dry-run prints it verbatim — $dispatch appends the full command to the dry-run buffer (cli/DeployRegistryCli.cfc:42, 53, 58-67, 79, 84-85), so wheels deploy registry login --dry-run prints the resolved secret; (2) failed login throws the password — SshClient.$raiseRemoteFailure embeds the first 200 chars of the command in the exception message (lib/SshClient.cfc:146-147, 179-186), so a wrong server/expired credential lands the password in CI logs; (3) remote argv exposure — -p <password> is visible in the remote process table, unescaped. Kamal uses --password-stdin + sensitive(..., redaction:) for exactly these reasons.

2. No shell escaping anywhere in remote command construction (DEP-3, High)
commands/Base.cfc:8-19 space-joins tokens; nothing in the deploy tree quotes values before they hit sess.exec() (lib/SshClient.cfc:118) or local bash -c (cli/DeployBuildCli.cfc:115). Concrete sites: env values as unquoted -e KEY=value (commands/AppCommands.cfc:96-104, commands/AccessoryCommands.cfc:90-98) — spaces break docker run, backticks/$()/; execute on the remote host. ConfigLoader.$interpolate expands ${SECRET} tokens from .kamal/secrets into config strings (config/ConfigLoader.cfc:92-116), so secrets routed into env.clear flow unescaped into remote argv and the DEP-2 exception summaries. Service/role names are never format-validated (config/Validator.cfc:31-41) yet interpolated raw into lockPath() (commands/LockCommands.cfc:25-27), label filters piped to xargs docker rm -f (cli/DeployMainCli.cfc:270-271, commands/PruneCommands.cfc:29-34), and container names. Local build context path is interpolated into [bash, -c, cmd] (commands/BuilderCommands.cfc:12-21). Same defect class as jobs-misc J8 (DatabaseShellHelper).

3. env.secret is parsed but never delivered to containers (DEP-4, High)
config/Env.cfc:22-26 exposes secret() but a repo-wide grep finds zero call sites — only clear() is consumed (commands/AppCommands.cfc:98, commands/AccessoryCommands.cfc:92). There is no env-file build / SFTP-upload / --env-file mechanism anywhere. A user who declares env: secret: [DATABASE_PASSWORD] per the Kamal docs ships containers without that variable, and the natural workaround — moving it to clear: — funnels the secret into the DEP-3 plaintext-argv path.

Impact

Anyone running wheels deploy against a real host risks leaking registry/DB credentials into CI logs, terminals, bug reports, and the remote process table; shell metacharacters in any config value break or inject into the remote shell; and the documented env.secret feature silently ships containers without the declared secret.

Suggested approach

Per campaign guidance, this needs a design pass on the Kamal-port command builder — do not autonomously patch secret handling:

• Switch registry login to printf '%s' <escaped> | docker login --password-stdin; redact the password token in dry-run output and in $raiseRemoteFailure's command summary.
• Promote SecretResolver.$shellEscape (lib/SecretResolver.cfc:116-118) into Base.cfc and apply it to every interpolated value; add a docker-compliant service-name format check to Validator.cfc.
• Implement env-file delivery (SshClient already has uploadString, lib/SshClient.cfc:218-232) or hard-error on a non-empty env.secret until supported.

Acceptance criteria

• No resolved secret appears in dry-run output, exception messages, or remote argv for registry login.
• Every interpolated value reaching a remote/local shell is escaped; a config value containing a space or $( ) is handled safely.
• Service/role names are format-validated before interpolation.
• env.secret is either delivered to containers via env-file or rejected with a clear error.
• Deploy CLI specs cover the escaping and redaction paths.

Source

Internal multi-agent framework review 2026-06-09, wave 2 (issues phase). Findings: followups DEP-2, DEP-3, DEP-4.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — see .ai/wheels/deploy.md for the canonical deploy-subsystem overview (the affected code lives under cli/lucli/services/deploy/).

Fix sketch

Three distinct defects in remote-command construction, bundled in one report. DEP-2 (registry password leak): commands/RegistryCommands.cfc:12-20 builds docker login ... -p <password> as a flat string, which then leaks through the dry-run buffer (cli/DeployRegistryCli.cfc:42, 53, 58-67, 79, 84-85), the SshClient.$raiseRemoteFailure exception summary (lib/SshClient.cfc:146-147, 179-186), and remote argv — fix is to switch to printf '%s' <escaped> | docker login --password-stdin and redact the password token everywhere it's echoed. DEP-3 (no shell escaping): commands/Base.cfc:8-19 space-joins tokens with no quoting; the existing SecretResolver.$shellEscape (lib/SecretResolver.cfc:116-118) needs to be promoted into Base.cfc and applied at every interpolation site (env values in commands/AppCommands.cfc:96-104 and commands/AccessoryCommands.cfc:90-98, label filters in cli/DeployMainCli.cfc:270-271 and commands/PruneCommands.cfc:29-34, lock paths in commands/LockCommands.cfc:25-27, the local bash -c in commands/BuilderCommands.cfc:12-21), plus a docker-compliant service/role name format check in config/Validator.cfc:31-41. DEP-4 (env.secret parsed but undelivered): config/Env.cfc:22-26 exposes secret() but it has zero callers — implement env-file delivery via the existing SshClient.uploadString (lib/SshClient.cfc:218-232) + --env-file, or hard-error on non-empty env.secret until supported. Specs for the escaping and redaction paths under cli/lucli/tests/specs/.

Confidence: `low`

Deploy subsystem is on the auto-downgrade list; the report bundles three distinct security defects spanning argv construction, secret resolution, and env-file delivery, and the reporter explicitly flags this as needing a design pass on the command builder rather than an autonomous patch.

<!-- wheels-bot:triage:2956 -->
<!-- wheels-bot:triage-class:bug -->

[bpamiri]

Deploy-guide audit: empirical scope confirmation for #2956 / #2957 (and the picocli-shadowing issues)

NOT a new issue. The P1 batch-2 guide-behavioral audit (work item p1-16-deploy, 93 claims across all 10 deployment guides, wheels CLI 4.0.3 + develop @ ddeec99/840274b2d, Lucee 7 live harness) independently re-confirmed the following defects that are already inside the scope of existing issues. The coordinator should post this as a COMMENT on #2956 and #2957 (and optionally the picocli issues) — do not refile.

Confirmed inside #2956 scope (env.secret / secrets delivery)

• env.secret never delivered, four documented examples affected (claims fd-05, acc-02, cfg-07, sec-08): on released 4.0.3, env: {clear: {...}, secret: [FOO]} dry-runs emit only the clear -e flags — FOO silently never delivered. On develop (post-fix(cli): deploy remote-exec security — stdin registry login, shell escaping, env.secret fail-fast #3008), Base.cfc::$rejectEnvSecrets throws Wheels.Deploy.EnvSecretUnsupported (AppCommands.cfc:98 / AccessoryCommands.cfc:92). Affected doc examples: first-deploy.mdx step 4, secrets.mdx flow diagram, config-reference.mdx #env, accessories.mdx Postgres (which on 4.0.3 silently boots Postgres WITHOUT a password).
• ⚠ Aggravator worth highlighting on review remediation: deploy CLI remote-execution security — secret delivery, shell escaping, registry password redaction #2956: the init template templates/deploy/init/deploy.yml.mustache still scaffolds an env.secret: [WHEELS_RELOAD_PASSWORD] block — a freshly wheels deploy init-scaffolded config will hard-fail with EnvSecretUnsupported on develop-built CLIs. The template should ship without env.secret until delivery lands.
• Registry login password-in-argv on 4.0.3 (sec-08): confirmed git show v4.0.3 RegistryCommands.cfc:18 inlined -p <password>; develop's --password-stdin via SSH exec-channel stdin (RegistryCommands.cfc:20-28) confirmed — i.e. fix(cli): deploy remote-exec security — stdin registry login, shell escaping, env.secret fail-fast #3008's fix verified present on develop.
• Per-role env merging doesn't exist (cfg-04, cfg-07): role env: parsed (Role.cfc:25-30) but AppCommands.$envArgs uses top-level env only — config-reference.mdx's 4-row precedence table is machinery that isn't implemented. (Also listed in the new accepted-but-ignored-keys issue since the dead role-key half is a distinct root cause.)

Confirmed inside #2957 scope (orchestration / remote-exec parity, by DEP item)

• DEP-4/5 — setup() == deploy() (fd-07, acc-07): DeployMainCli.cfc:162-165 literally return deploy(opts); observed setup --dry-run with a declared redis accessory emits zero accessory commands. Proxy boot chain proxy.details() || proxy.boot() (line 90) unreachable (docker ps exits 0 regardless).
• DEP-5c — docker network create kamal never issued (arch-02): confirmed absent from all dry-run output.
• DEP-6 — remote stdout discarded / audit log never written (fd-08, fd-14, acc-04, arch-02): deploy app details live mode returns "Collected app details on N host(s)" discarding inspect output (DeployAppCli.cfc:46-50); AuditorCommands.record() has zero call sites — /tmp/kamal-audit.log is never written; "output prefixed with [host]" is dry-run-only.
• DEP-7 — flat deploy bootstrap builds a bare SshPool ignoring ssh: config (fd-06): confirmed.
• DEP-11b — extract-secrets key match is case-insensitive (CFML ==), diverging from Kamal (sec-06): confirmed live (extract-secrets b returns the B value).
• DEP-11c — proxy config dir resolves to /home/root for the default root user (arch-02): confirmed (root's home is /root).
• Proxy deploy fired for EVERY role, not just web (cfg-04): observed kamal-proxy deploy myapp --target myapp-job-... for a job role — deploy() loops proxy.deploy per role (DeployMainCli.cfc:92-101). config-reference.mdx says only web gets it.
• Cumulative effect on migrating-from-kamal.mdx (mig-05): "alternate freely between Ruby Kamal and wheels deploy / nothing on the server notices" is aspirational until review remediation: deploy CLI orchestration correctness — multi-host lock bypass, fresh-host bootstrap, discarded stdout/audit log, flat-alias ssh config, roll-up defects #2957 lands (audit log, network, proxy boot, proxy config dir, per-role proxy calls, and the 4.0.3 password-in-argv all diverge on-server).

Confirmed inside the picocli-shadowing issues (#2674 / #2677 / #2697)

• wheels deploy rollback --version=abc1234 → picocli "not a boolean" (LuCLI intercepts --version flag causing failure in wheels deploy command #2674); positional rollback abc1234 works (fd-10, mig-01).
• wheels deploy server bootstrap → LuCLI's picocli server help, exit 0, never reaches the module (wheels deploy server bootstrap is interpreted as LuCLI server command instead of deploy subcommand #2677); flat wheels deploy bootstrap works (fd-06).
• All three nested wheels deploy secrets fetch|extract|print forms picocli-intercepted (wheels deploy secrets fetch invokes LuCLI global secrets command instead of Wheels deploy subcommand #2697); flat fetch-secrets/extract-secrets <key> --from=.../print-secrets work but are documented NOWHERE in secrets.mdx/first-deploy.mdx/hooks.mdx (sec-04, sec-06, mig-01).

Good news the audit also confirmed (no action)

• Dry-run/no-SSH invariant holds everywhere probed; [host] cmd prefix in dry-run (DeployMainCli.cfc:417).
• /health and /ready examples work verbatim; RequestId middleware emits the header once enabled; sentry package installs with the documented mixin surface.
• Container/label/lock/audit-path CONSTANTS all match Kamal byte-for-byte in the command strings (arch-02) — the parity gaps are in execution, not naming.

— guide-behavioral-audit P1 batch 2, work item p1-16-deploy (44 works / 30 docs-wrong / 9 both / 3 code-broken / 7 unverifiable of 93 claims). Full per-claim evidence in the batch-2 raw JSON (catalog header has the path).

[bpamiri]

Closing: the architectural decision this epic asked for (the command-builder design pass) shipped in #3008 (3a47988 — stdin registry login, Base.shellEscape, validate-not-quote names, fail-fast EnvSecretUnsupported), hardened further by #3144 (5bd8c6b), and was empirically re-verified on develop by the 2026-06-12 guide-behavioral audit (see the audit comment above). Residue moved to narrow issues: the init-template env.secret aggravator and the $raiseRemoteFailure secret redaction (filed just now); env-file delivery stays inside the #2957 campaign (Wave 2), which the shipped error message already points at.