shellguard.

Run untrusted text as arguments, never as shell syntax. A zero-dependency Python library that kills the whole class of injection bugs.

Live · EUR49 one-time · 111 tests green

shellguard self-audit CI: live status

Buy now · EUR49 Pay from €1 See the bug it kills

The bug

Every automation system eventually does this:

full = f"cd {dir} && run --model {model} {prompt}"
subprocess.run(full, shell=True)

A prompt containing ( makes bash abort with syntax error near unexpected token. A prompt containing backticks or dollar-parens executes attacker-chosen commands. Both failures were observed in production.

The rule

Never build a shell string from untrusted text. Build an argv list. execve semantics keep each token a token — no parser, no metacharacters, no surprises.

import shellguard as sg

sg.run(["echo", "(17*23)"])          # -> "(17*23)\n"
sg.run(["echo", "`echo INJECTED`"])  # -> literal text, not a command
sg.run(["echo", "$(echo INJECTED)"]) # -> literal text
sg.run(["false"])                    # -> Result(returncode=1, ok=False, ...)

What you get

argv, not strings

build() returns a list; run() execs it directly. shell=True and bare-string commands are refused by design.

111 tests green

26 real attack cases + 16 license-key cases + 24 CLI cases + 18 delivery cases + 27 audit cases. Parentheses, backticks, dollar-parens, semicolons, pipes, ampersands, newline, quotes, globs, tilde, env expansion, redirection, unicode, binary bytes, timeouts, cwd, env, exit codes.

sg audit

Scans your repo for shell=True, os.system/os.popen, asyncio.create_subprocess_shell and string subprocess calls, including import-aliased forms. Exit 1 on findings, --json for CI.

Zero dependencies

Standard library only. Python 3.8+. No network calls, no data collection, no telemetry.

Readable failures

Result(returncode, stdout, stderr, ok, argv) plus Timeout and SafetyError exceptions. Nothing is hidden.

Try the exact failure

The library ships with a real attack suite. Each case encodes a failure mode that a shell-string builder actually hits:

$ PYTHONPATH=src python -m unittest discover -s tests -p "test_*.py"
Ran 111 tests in 1.2s
OK

That suite is the product. It is the difference between "we hope the prompt is clean" and "the prompt cannot be parsed".

CI gate

The badge above is this library's own live self-audit: every push runs the published GitHub Action against the source. Add the same gate to your pipeline:

- uses: actions/checkout@v4
- uses: derbaroser-eng/shellguard-action@v1
  with:
    path: src

Exit 0 clean, exit 1 on findings (the build fails), exit 2 on bad input. The release wheel is sha256-verified before install, and option-injection paths are rejected.

Install & use

pip install https://github.com/derbaroser-eng/shellguard-lib/releases/download/v1.4.0/shellguard-1.4.0-py3-none-any.whl

The shellguard name on PyPI is an unrelated package, so install from the release asset above (or clone shellguard-lib). The sg alias is not published.

Paying buyers are fulfilled automatically: the EUR49 checkout emits a Stripe checkout.session.completed event, and sg deliver turns it into a signed, order-bound license key plus the delivery email. Same order, same key — a retried webhook cannot mint a second key.

License & delivery

EUR49 one-time. MIT license. You receive the full source, the 111-test suite, and a short integration guide. Delivery is automatic and offline: sg deliver --session event.json --secret SECRET --min-cents 4900 --currency EUR. No subscription, no cloud, no data leaves your machine.

Buy now · EUR49 Pay from €1