Argument injection: abusing command-line options
Argument injection happens when attacker-controlled input becomes an additional command-line option rather than a data value. Even applications that correctly avoid a shell can be vulnerable: if a user value that begins with `-` is passed to a program, it may be parsed as a flag that changes the program's behaviour.
How it works
Many programs accept options anywhere in their argument list. If an application runs `tar -xf archive $USERFILE` or `curl $URL` and the attacker controls the value, supplying something that starts with `-` injects a new option instead of a filename or URL.
Because this abuses the target program's own option parser, it works with shell-free exec APIs (ProcessBuilder, execFile, subprocess lists) — there is no shell to blame. The impact depends on the program: curl's `-o`/`--output` writes files, tar's `--checkpoint-action=exec` and `--use-compress-program` run commands, and `--config`/`-K` options read attacker-named files.
Representative payloads
Illustrative fragments for authorized testing. The injected marker commands (id, whoami) are harmless proofs of execution — swap in your engagement’s agreed markers.
--checkpoint=1 --checkpoint-action=exec=sh shell.shLinux / UnixGNU tar options that run a command at a checkpoint — classic argument injection into a tar invocation.
-o /var/www/html/shell.phpLinux / UnixWindowscurl/wget output option: when the URL argument is attacker-controlled, writes the response to an arbitrary path.
--use-compress-program=idLinux / Unixtar option that invokes an external program; abused to run arbitrary commands.
-R root@host -D 1080Linux / UnixExample of injecting extra ssh options when a hostname argument is user-controlled.
When it works
- A user value is passed as a positional argument to a program that accepts options interspersed with operands.
- The application does not place a `--` end-of-options marker before the value.
- The value can begin with `-` or `--` (not validated against an allowlist).
When it fails
- The application inserts `--` before user operands so the program stops option parsing.
- The value is validated to a shape that cannot start with a dash (e.g. digits, or a path the app fully controls).
- The target program does not accept options after operands (strict POSIX ordering).
Detection
Look for user-supplied operands that start with '-' and for target programs invoked with unexpected flags.
Signals to look for
- Values beginning with - or -- in fields meant to be filenames, URLs or hostnames.
- Process command lines where a program runs with options known for code/file effects (--checkpoint-action, -o, --config, --use-compress-program).
- Files written to web-root or config paths shortly after a download/archive operation.
Where to look
Remediation
The correct fix: Insert a `--` end-of-options separator before user operands and validate that values can't impersonate a flag.
Principles
- Pass `--` before any user-controlled operand so the target program treats it as data, not an option.
- Pin the flags your application needs explicitly and reject user values that start with `-`.
- Prefer a library binding (HTTP client, archive library) over invoking CLI tools whose option surface you don't control.
Safe APIs by runtime
Add '--' as an argument before user operands; validate the operand doesn't start with '-'.
execFile("tar", ["-xf", archive, "--", userFile]);Shell-free exec does NOT stop argument injection — still add -- and validate operands.
subprocess.run(["curl", "--", url]) # plus validate url schemeNot a fix: Assuming that avoiding the shell is enough. Argument injection abuses the target program's own parser, so a safe exec API without a `--` guard is still vulnerable.
For the full secure-coding matrix across languages, see the command injection prevention guide.
Frequently asked questions
- Is argument injection the same as command injection?
- They're related but distinct. Classic command injection adds a new command via shell syntax; argument injection stays within one program but smuggles in extra options. Argument injection can work even when no shell is used.