fix(private-tools): resolve executables against PATH not cwd on Windows

[iankhou]

Fixes #1919.

Follow-up to #1763 / #1849. Windows-specific hardening of executable resolution on the no-shell run() path.

Problem

resolveExecutable() — on Windows a bare program name spawned without a shell is searched for in the working directory before PATH, so a file planted in a handed-over cloud assembly (e.g. docker.bat) shadows the real binary. This can result in unexpected behavior.

run() spawns via cross-spawn (cross-spawn@7.0.6), whose resolver is which@2.0.2, and its getPathInfo builds the Windows search path cwd-first — which.js#L17-L24 (cwd prepended at L20-L21):

  const pathEnv = cmd.match(/\//) || isWindows && cmd.match(/\\/) ? ['']
    : (
      [
        // windows always checks the cwd first
        ...(isWindows ? [process.cwd()] : []),
        ...(opt.path || process.env.PATH ||
          /* istanbul ignore next: very unusual */ '').split(colon),
      ]
    )

Fix

run()/runSync() now resolve the executable to an absolute PATH hit up front and refuse a name that is not on PATH, rather than let the cwd satisfy it. The resolver only ever returns an absolute candidate: relative PATH entries (e.g. .) are skipped, quoted PATH entries are unwrapped, and a name containing a dot is probed exactly (matching which). We honor explicit paths (absolute or containing a separator).

Testing

• Unit tests for resolveExecutable (cross-platform via a platform override; run on the Ubuntu build job).

Tested on a Windows machine on Node v24.18.0, since there's no Windows unit-test lane in CI (it may or may not be worthwhile to introduce one at a later time, depending on how often we need these types of changes). Installed a cross-built tarball of @aws-cdk/private-toolsand introduced a hostile docker.bat in the cwd. All three checks ran in the same session.

Step 1 - Setup

On Windows, install the tarball and run the following to create the bad batfile:

@'
@echo off
echo shadow-ran
'@ | Out-File -Encoding ascii .\docker.bat

Step 2 - Negative Control

Run the following to check the negative control:

node -e "const r=require('cross-spawn').sync('docker',['--version'],{stdio:'inherit',encoding:'utf-8'}); console.log('exit:', r.status)"

Expected: shadow-ran + CONTROL: VULNERABLE.

Step 3 - Fixed code

Then run the fixed code:

node -e "require('@aws-cdk/private-tools/lib/subprocess').run(['docker','--version']).then(r=>console.log('RAN:', JSON.stringify(r.stdout.trim()))).catch(e=>console.log('REFUSED:', e.message))"

My Windows machine had Docker installed, so it showed:

RAN: "Docker version 29.6.2, build dfc4efb"

However, if your machine doesn't have Docker installed, it should show something like:

REFUSED: ... ENOENT

In either case, we showed that shadow-ran did not run. If our verification failed, we would have seen something like:

RAN: "shadow-ran"

Step 4 - env/PATH fallback

node -e "require('@aws-cdk/private-tools/lib/subprocess').run(['node','--version'], { env: { FOO: 'bar' } }).then(r=>console.log('FALLBACK PASS:', r.stdout.trim())).catch(e=>console.log('FALLBACK FAIL:', e.message))"

It shows:

FALLBACK PASS: v24.18.0

Test	Path exercised	cwd docker.bat ran?	Result
Negative control (reproduces the vuln)	cross-spawn.sync('docker', ...) directly (base-equivalent)	YES — printed shadow-ran, wrote pwned.txt
Fix	patched run(['docker','--version'])	NO — real docker v29.6.2 ran, no pwned.txt	✅ PASS
env/PATH fallback	run(['node','--version'], { env: { FOO: 'bar' } }) (PATH-less custom env)	n/a	✅ v24.18.0

Takeaways

• Confirms on Windows that a bare name resolves the cwd shim first (the control), and that the fix shadows it out (resolves to the real on-PATH binary).
• The env/PATH fallback (8a0a0d7) resolves a PATH-less custom env via process.env.PATH instead of a synthetic ENOENT.

Checklist

• Unit tests added/updated
• Integration tests
• No manual edits to generated files

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

Hardens Windows subprocess execution against executable shadowing and unsafe %VAR% path expansion.

Changes:

• Resolves bare Windows executables through PATH before spawning.
• Rejects shell-bound Windows paths containing %...%.
• Adds Windows subprocess and unit coverage.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
packages/@aws-cdk/private-tools/lib/subprocess/index.ts	Adds executable resolution and ENOENT handling.
packages/@aws-cdk/private-tools/test/subprocess/subprocess.test.ts	Tests PATH resolution and .cmd escaping.
packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/environment.ts	Rejects unsafe percent-containing paths.
packages/@aws-cdk/toolkit-lib/test/api/cloud-assembly/environment.test.ts	Tests percent-path rejection.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.