BASH_XTRACEFD Since bash 4.1: Always-On Traces or a Gated Debug Descriptor

Answers to the three questions

1. Gate it. Xtrace records commands after expansion, so deploy --token "$API_TOKEN" lands in the log with the real credential. In a CI runner that archives logs as shared artifacts, always-on tracing is a standing secret leak. A flag such as [[ -n "${DEBUG:-}" ]] && set -x keeps the default path clean; the cost — a failed run without diagnostics — is recoverable by re-running the job with the flag set. Treat even gated trace logs as sensitive, since anyone with pipeline access can flip the flag.

2. Check the interpreter, not the shebang. BASH_XTRACEFD exists only in bash 4.1+; POSIX sh, dash, and ash ignore it, and CI runners sometimes invoke scripts with sh regardless of the shebang, silently disabling the feature. Guard on BASH_VERSINFO and fail loudly. For the descriptor, prefer bash's dynamic allocation over a fixed number — exec {BASH_XTRACEFD}>>"$TRACE_LOG" opens a valid fd and sets the variable atomically, avoiding collisions that a hardcoded BASH_XTRACEFD=9 risks. If you inherit a descriptor instead, a write test such as : >&$BASH_XTRACEFD confirms it is open before you depend on it; an invalid fd makes bash report an error and lose the trace, which is exactly the "failed but untraced" outcome to avoid.

3. Redact by construction, not by filtering. No fully automatic option exists. The reliable approaches are: toggle xtrace off around credential use ({ set +x; ...; } 2>/dev/null, then re-enable), and pass secrets via files or stdin (--token-file, curl -K -) so the expanded command line contains a path rather than a value. Post-filtering the log is only a backstop — patterns miss encodings and partial values. This preserves the failing command's structure while the secret never reaches the descriptor.

Verification

Confirm the routing works on your runner: bash -c 'echo "$BASH_VERSION"; exec {BASH_XTRACEFD}>/tmp/x.log; set -x; echo hi; { set +x; } 2>/dev/null; cat /tmp/x.log' — trace lines should appear in the file, not on stderr. Also invoke the script under sh explicitly to confirm the version guard trips, and test the closed-fd path to confirm the pre-check catches it.

Assumptions and uncertainty

This assumes bash is the intended interpreter and that the CI system archives logs. Behavior is version-sensitive: minimal containers and macOS's /bin/bash 3.2 are common surprises, so keep the BASH_VERSINFO guard even on a modern runner. The bash 4.1 introduction and dynamic-fd behavior are well-established, but exact error wording on an invalid descriptor varies by version — verify on your target rather than pattern-matching messages.