Unrestricted shell escape for package automation versus restricted mode in CI pipelines

There is no distribution-agnostic, per-project mechanism (such as a texmf.cnf snippet or latexmkrc) that allows a TeX engine to automatically opt-in to shell escape permissions. The restricted whitelist is a global installation setting. To enable the external calls required by packages like minted or epstopdf-auto, the --shell-escape flag must be passed explicitly to the engine during the build process.

The Gap Between Restricted and Unrestricted Modes

TeX Live and MiKTeX maintain separate whitelists of "safe" commands (viewable via kpsewhich --var-value=shell_escape_commands in TeX Live). Because these lists vary by distribution and version, a project relying on restricted mode may compile locally but fail in CI. Since tools like pygmentize (used by minted) are not on these whitelists, unrestricted shell escape is effectively mandatory for these workflows.

Sandboxing Strategies for CI

When --shell-escape is required, the security boundary must shift from the TeX engine to the environment. For workflows that cannot migrate to LuaTeX, the following containment strategies are recommended:

• Ephemeral Containers: Run the build in a Docker or Podman container. Use a read-only mount for source files and a dedicated writable volume for output. This prevents a compromised \write18 call from persisting changes to the source or accessing the host filesystem.
• Unprivileged Build Users: Execute the process as a dedicated user with no sudo privileges and a restricted HOME directory.
• Seccomp Profiles: Implement a seccomp profile to restrict the syscalls available to the process. This is the most granular approach, allowing only the specific binaries (e.g., /usr/bin/python3 for minted) to be executed via execve.
• MicroVMs: For high-risk untrusted sources, use gVisor or Firecracker to provide a stronger kernel-level boundary than standard containers.

Verification and Implementation

To identify exactly which external binaries your project requires before locking down a sandbox, run the build with strace in a controlled environment:

strace -f latexmk -pdf -shell-escape document.tex 2>&1 | grep -E 'execve|openat'

This will enumerate the binaries being called, allowing you to create a precise whitelist for your seccomp profile or container permissions.

Diagnostic Requirement

To refine the recommendation: Are you using a pre-baked TeX Live Docker image, or are you installing the distribution dynamically on a shared runner (e.g., GitHub-hosted runners)?