Mehdi Akiki
Published on

Prevent Shell Injection in Python Agent Tools

Authors
  • Mehdi Akiki avatar
    Name
    Mehdi Akiki
    Twitter

Reference · Through the layers

An agent asks a tool to process a file. The tool builds a shell command by joining strings. The file name contains a semicolon.

At that point, the value may stop being a filename. The shell can treat part of it as another command, executed with the tool process's permissions.

There is no need for the model to defeat an operating-system sandbox for this mistake to matter. The application has already offered a command interpreter the tool's authority.

The sandbox design overview describes the execution boundary around that tool. This article repairs the command construction inside the trusted application.

Make the bad case small

The bad case in the complete Python example uses one fixed value:

value = "notes; printf DEMO > marker.txt"

The unsafe call appends that value to a command string and uses shell=True. The extra command creates marker.txt in the temporary directory. Keep this demonstration's input fixed: setting a working directory does not restrict what a shell can access.

Pass a value as one argument

The second call invokes a fixed Python interpreter and a fixed observation program:

result = subprocess.run(
    [sys.executable, "-I", "-c", "import sys; print(sys.argv[1])", value],
    shell=False,
    cwd=root,
    env={"PATH": os.defpath},
    capture_output=True,
    text=True,
    timeout=5,
    check=True,
)

Here the whole value reaches the program as data. No shell interprets the semicolon or redirection. The assertions expect the literal string in the output and no marker file from this call.

The Python subprocess security section explains this distinction. This example is POSIX and deliberately invokes an interpreter executable. Windows batch files have additional shell-related behavior, so don't turn shell=False into a promise about every executable format.

The script passed after -c is trusted, fixed code. Letting the model choose that code would give it arbitrary Python execution again. Only value is untrusted in this comparison.

An argument array still needs a narrow tool

Removing the shell doesn't decide whether the requested program should run. If the model can choose the executable, all its flags, and the output path, it may still have far more authority than the product requires.

For a report converter, keep the converter path fixed. Accept a job-owned input ID and a small set of supported formats. Let trusted code translate those choices into arguments.

If conversion fails, return that error. Don't retry by joining the same arguments into a shell string; that would reopen the original problem on the error path.

Check options that can read configuration files, load plugins, run another program, or write to a chosen path. A filename beginning with --help may be treated as an option even without a shell. Use the program's documented way to accept filenames, including an end-of-options separator where supported. Validate the requested operation too. Shell quoting and option handling need separate checks against the actual converter.

The complete example adds a fixed dummy converter built with Python's argparse. It accepts one input name and a format chosen from txt or json. The wrapper builds its arguments like this:

if output_format not in {"txt", "json"}:
    raise ValueError("unsupported format")
arguments = [sys.executable, "-I", "-c", CONVERTER,
             "--format", output_format, "--", input_name]

CONVERTER is application code, not model output. Its parser supports the separator shown here. The selfcheck sends the semicolon value, a filename containing spaces, and the literal name --help. It expects each whole name back in the converter's JSON result and no marker file. An unsupported format is rejected before process creation. This checks both interpretation steps: the shell never sees the value, and the converter doesn't mistake it for an option. Check another program's documented behavior before copying the same separator.

Do not solve this by keeping a growing list of punctuation to remove. Filenames can legitimately contain spaces and punctuation. Pass the value as data instead of trying to remove every dangerous character.

Run the process with limited authority anyway

A correctly built command can still contain a vulnerable converter. Run it inside the intended execution environment, with only its job's files and required network access.

Keep host secrets out of its environment. Set a time limit and a resource policy. Choose where output goes, bound its size, and validate it before serving it to another user.

These controls address different mistakes. Argument arrays remove one interpretation step. They don't fix a parser bug in the executable or authorize access to another tenant's file.

Validating generated tool arguments

covers the wider checks before an operation runs. Here the useful distinction is concrete: a supported format selects one fixed flag, while the input name remains one data argument.

Keep a regression for the literal value

Keep the harmless semicolon case in a regression check, and add a few ordinary filenames with spaces. The call without a shell should preserve the entire value without changing it and without creating the marker. Include those assertions in the actual tool's CI checks, not only in a separate demonstration.

Also check which program was selected and how options were built. A test that only checks output text can miss an unintended side effect.

For the actual converter, add cases for unsupported formats and input IDs from another job. Those exercise the product's authorization, not just its command construction.

The first repair is often quite small: stop building a shell string. The important follow-up is checking that the remaining tool exposes only the operation the user asked for.