Mehdi Akiki
Published on

Stop Secret Inheritance in Python Subprocesses

Authors
  • Mehdi Akiki avatar
    Name
    Mehdi Akiki
    Twitter

Reference · Through the layers

The agent can't open your credential file. That sounds reassuring until the process that launched it passes the credential through an environment variable.

There is another path too: an already-open file descriptor. A child doesn't always need the filename if it receives a usable handle to the file.

Before adding more rules about which paths the agent may read, inspect what the launcher hands over at process creation. The starting environment is part of the security design.

This is one part of running generated code inside a defined execution boundary. A restricted filesystem cannot undo a secret the launcher has already delivered to the child.

Separate normal defaults from a wrapper mistake

Python's default close_fds=True closes descriptors other than standard input, output, and error. On POSIX, pass_fds can explicitly preserve selected descriptors. This example deliberately marks one descriptor inheritable and uses close_fds=False for the first launch.

It also supplies a fake token. There is no reason to use a real cloud credential to prove the problem.

The complete Python example opens a temporary file containing dummy text. The child reports whether it can read that descriptor and whether DEMO_SECRET exists in its environment. The second launch excludes both.

This makes the expected behavior easy to inspect. Add a check like this to the real launcher so CI can catch a later change that reintroduces inherited handles or copies all parent variables.

The program prints the two observations as JSON after checking these expected values:

LaunchEnvironment tokenDummy descriptor
Explicit inheritanceThe dummy token textThe dummy file text
Reduced environment and closed descriptorsMissingUnreadable

Neither observation needs a production secret. If the reduced launch reports a token, inspect how env was built. If it reads the dummy descriptor, inspect inheritance settings and any explicit handle list. Keeping those two failures separate makes the result useful when a wrapper changes only one setting.

Build the environment you intend to grant

Passing a reduced environment is clearer than copying everything and deleting a few known secret variables. You may not know the name of the next credential added to the host.

For this fixed observation program, the second launch has this shape:

result = subprocess.run(
    [sys.executable, "-I", "-c", code, str(fd)],
    env={"LANG": "C.UTF-8"},
    close_fds=True,
    stdin=subprocess.DEVNULL,
    capture_output=True,
    text=True,
    timeout=5,
    check=True,
)

code is the fixed observation program in the example. fd refers to its dummy file. Only the launch settings change between the two calls; the child runs the same small program.

The explicit environment contains one harmless setting. close_fds=True excludes descriptors other than the standard streams, which are set deliberately here. -I asks Python to use isolated mode; it doesn't create filesystem or network isolation.

The subprocess reference explains these options, including the platform differences. This descriptor example targets POSIX. Windows handle inheritance needs its own check against the launcher you use there.

Open files can outlive your path decision

An open descriptor refers to an object the process already has. Removing a filename from a tool schema doesn't close that descriptor.

Think about sockets too. A wrapper may open a connection before launching the worker. If it deliberately passes that socket into the child, it has granted a communication path that a later hostname allowlist may never see.

Use an explicit descriptor list when inheritance is required. For each handle, name the purpose and lifetime. “Needed by the worker” is too broad when the parent has database, logging, and administrative connections open at once.

Be careful with standard input and output as well. They are intentionally retained channels. A child can send data to whatever collects its output, and that collector may forward logs outside the job.

The example captures only a small fixed JSON result. For arbitrary generated programs, use bounded output collection. capture_output=True alone can accumulate too much data; a time limit doesn't establish an output limit. The process lifetime example follows the separate problem of ending work after its leader exits.

Keep provider credentials on the trusted side

If a worker needs one API operation, consider a narrow trusted service that performs it with the credential. The worker supplies a validated request for its own job. It doesn't receive a reusable provider key.

That service still needs restrictions on operation, tenant, request size, and cost. Hiding the key doesn't stop abuse if the worker can ask the service to perform any action the key permits.

Its destination checks also need to survive name resolution. The egress broker example keeps a selected connection address separate from the hostname used for TLS verification.

The Deno Sandbox secret design is one concrete example of keeping real key material out of the process through controlled substitution. The general design question is who holds the credential and who authorizes its use.

Check the launcher after configuration changes

Add this kind of dummy-value check to the code that starts jobs. The first launch should show the inheritance. The second should report no dummy token and no readable dummy descriptor. Keep the expected values beside the launcher settings so a future edit doesn't quietly widen them.

Then check the real wrapper under its actual job configuration. A helper library can behave differently from a small direct subprocess.run call, particularly if it changes environments or passes descriptors explicitly.

Minimal inheritance is only one layer. A child running under the same operating-system identity may still read other available files or open network connections. It also needs the intended execution isolation and resource controls.

Start by making the launcher's grant small enough to describe. It is much easier to review two intentional inputs than a copied host environment with a few names removed.