Run untrusted text as arguments, never as shell syntax. A zero-dependency Python library that kills the whole class of injection bugs.
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.
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, ...)
build() returns a list; run() execs it directly. shell=True and bare-string commands are refused by design.
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.
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.
Standard library only. Python 3.8+. No network calls, no data collection, no telemetry.
Result(returncode, stdout, stderr, ok, argv) plus Timeout and SafetyError exceptions. Nothing is hidden.
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".
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.
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.
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.