@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/detecting-command-injection-patterns/references/PLAYBOOK.md

@@ -0,0 +1,302 @@
+# Command-Injection Remediation Playbook
+
+The universal pattern: switch to the argument-vector form of your
+language's process-spawn API. Specific snippets per language below.
+
+## Python — subprocess (list form, shell=False)
+
+### Before
+
+```python
+import subprocess
+subprocess.run(f"convert {filename} out.png", shell=True)
+```
+
+### After
+
+```python
+import subprocess
+subprocess.run(["convert", filename, "out.png"], check=True)
+```
+
+### Piping between commands without shell
+
+```python
+# Before (shell pipeline)
+subprocess.run(f"cat {filename} | grep error", shell=True)
+
+# After (Popen chain)
+with subprocess.Popen(["cat", filename], stdout=subprocess.PIPE) as p1:
+    subprocess.run(["grep", "error"], stdin=p1.stdout, check=True)
+```
+
+### Capturing output
+
+```python
+result = subprocess.run(
+    ["convert", filename, "out.png"],
+    capture_output=True, text=True, check=True,
+)
+print(result.stdout)
+```
+
+## Node.js — child_process spawn / execFile
+
+### Before
+
+```javascript
+const { exec } = require('child_process');
+exec(`convert ${filename} out.png`, (err, stdout) => {});
+```
+
+### After (execFile)
+
+```javascript
+const { execFile } = require('child_process');
+execFile('convert', [filename, 'out.png'], (err, stdout) => {});
+```
+
+### After (spawn for streaming)
+
+```javascript
+const { spawn } = require('child_process');
+const child = spawn('convert', [filename, 'out.png']);
+child.stdout.on('data', chunk => process.stdout.write(chunk));
+child.on('close', code => console.log(`exit ${code}`));
+```
+
+### TypeScript with promisify
+
+```typescript
+import { execFile as execFileCallback } from 'child_process';
+import { promisify } from 'util';
+const execFile = promisify(execFileCallback);
+
+const { stdout } = await execFile('convert', [filename, 'out.png']);
+```
+
+## Ruby — Open3.capture3 / Process.spawn
+
+### Before
+
+```ruby
+output = `convert #{filename} out.png`
+```
+
+### After (Open3 — best for capturing output)
+
+```ruby
+require 'open3'
+stdout, stderr, status = Open3.capture3('convert', filename, 'out.png')
+raise "convert failed: #{stderr}" unless status.success?
+```
+
+### After (Process.spawn for fire-and-forget)
+
+```ruby
+pid = Process.spawn('convert', filename, 'out.png')
+Process.wait(pid)
+```
+
+### After (system with explicit args)
+
+```ruby
+# system with multiple args bypasses shell
+system('convert', filename, 'out.png') or raise "convert failed"
+```
+
+## Go — exec.Command with argv
+
+### Before
+
+```go
+cmd := exec.Command("sh", "-c", fmt.Sprintf("convert %s out.png", filename))
+output, _ := cmd.CombinedOutput()
+```
+
+### After
+
+```go
+cmd := exec.Command("convert", filename, "out.png")
+output, err := cmd.CombinedOutput()
+if err != nil {
+    return fmt.Errorf("convert failed: %w", err)
+}
+```
+
+### With context (cancellation / timeout)
+
+```go
+ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+defer cancel()
+cmd := exec.CommandContext(ctx, "convert", filename, "out.png")
+```
+
+## Java — ProcessBuilder with array
+
+### Before
+
+```java
+Runtime.getRuntime().exec("convert " + filename + " out.png");
+```
+
+### After
+
+```java
+ProcessBuilder pb = new ProcessBuilder("convert", filename, "out.png");
+pb.redirectErrorStream(true);
+Process p = pb.start();
+int exitCode = p.waitFor();
+```
+
+### With output capture
+
+```java
+try (BufferedReader reader = new BufferedReader(
+        new InputStreamReader(p.getInputStream()))) {
+    String line;
+    while ((line = reader.readLine()) != null) {
+        System.out.println(line);
+    }
+}
+```
+
+## PHP — proc_open with array form
+
+PHP 7.4+ supports passing an array as the command to `proc_open`,
+which bypasses shell entirely:
+
+### Before
+
+```php
+$output = shell_exec("convert $filename out.png");
+```
+
+### After (PHP 7.4+)
+
+```php
+$descriptors = [
+    0 => ['pipe', 'r'],
+    1 => ['pipe', 'w'],
+    2 => ['pipe', 'w'],
+];
+$process = proc_open(
+    ['convert', $filename, 'out.png'],
+    $descriptors,
+    $pipes
+);
+$stdout = stream_get_contents($pipes[1]);
+fclose($pipes[1]);
+proc_close($process);
+```
+
+### Legacy PHP fallback (with escapeshellarg)
+
+```php
+$cmd = sprintf(
+    "convert %s %s",
+    escapeshellarg($filename),
+    escapeshellarg($outputName)
+);
+$output = shell_exec($cmd);
+```
+
+`escapeshellarg()` wraps the argument in single quotes and escapes
+any embedded single quotes. Defense-in-depth; the no-shell form
+is still stricter.
+
+## C# / .NET — Process.Start with ArgumentList
+
+### Before
+
+```csharp
+Process.Start("cmd.exe", "/c convert " + filename + " out.png");
+```
+
+### After (.NET Core 2.1+)
+
+```csharp
+var psi = new ProcessStartInfo("convert")
+{
+    UseShellExecute = false,
+    RedirectStandardOutput = true,
+};
+psi.ArgumentList.Add(filename);
+psi.ArgumentList.Add("out.png");
+var process = Process.Start(psi);
+```
+
+`ArgumentList` (not `Arguments` string) is the safe path.
+
+## Rust — std::process::Command
+
+```rust
+use std::process::Command;
+
+// Safe by design — Command takes args separately
+let output = Command::new("convert")
+    .arg(&filename)
+    .arg("out.png")
+    .output()
+    .expect("convert failed");
+```
+
+`std::process::Command` doesn't have a shell-wrapped form. Even if
+you wanted one, you'd have to explicitly invoke `sh -c` yourself.
+
+## Pre-commit integration
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: scan-cmdi
+        name: Scan for command-injection patterns
+        entry: python3 plugins/security/penetration-tester/skills/detecting-command-injection-patterns/scripts/scan_cmdi.py
+        language: system
+        args: ['--min-severity', 'high']
+        pass_filenames: false
+```
+
+## CI integration
+
+```yaml
+- name: Command-injection scan
+  run: |
+    python3 plugins/security/penetration-tester/skills/detecting-command-injection-patterns/scripts/scan_cmdi.py \
+        . --min-severity high --format json --output cmdi-scan.json
+- run: |
+    if jq 'length > 0' cmdi-scan.json | grep -q true; then
+      echo "::error::Command-injection pattern detected"
+      cat cmdi-scan.json
+      exit 1
+    fi
+```
+
+## Defense-in-depth additions
+
+For code that legitimately shells out to a binary:
+
+1. **Run the binary as a low-privilege user.** Container-isolated,
+   no write access to host paths.
+2. **Validate inputs against an allow-list before passing.**
+   Filenames matching `^[\w.-]+\.(png|jpg|webp)$`; refuse anything
+   else.
+3. **Drop unused capabilities.** Linux: capset to drop network,
+   raw-socket, etc. for the spawned process.
+4. **Use a dedicated processing queue.** Untrusted file processing
+   should run in a sandboxed worker, not the application server's
+   main process.
+
+## Verification after remediation
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/detecting-command-injection-patterns/scripts/scan_cmdi.py \
+    /path/to/repo --min-severity medium
+```
+
+Expected: exit 0, zero MEDIUM-or-higher findings. Remaining LOW
+findings on `shell=True` with verified static-string arguments are
+acceptable but should be migrated when the surrounding code is
+touched anyway.

package/skills/detecting-command-injection-patterns/references/THEORY.md

@@ -0,0 +1,206 @@
+# Command-Injection Theory
+
+## The recurring shape
+
+Application calls out to a binary for some task: image processing,
+archive extraction, video conversion, DNS resolution, network ping,
+"call this one CLI tool." The naive implementation builds a string,
+passes it to a shell-invocation API. The shell parses the string
+with full shell semantics: `;`, `|`, `&`, `$()`, backticks,
+redirection.
+
+The fix is universal: don't go through the shell. Most APIs have
+a list-of-arguments form that bypasses the shell entirely, treating
+each list element as a literal argument to the binary's `execve()`.
+
+## Why `shell=True` is the default footgun
+
+Python's `subprocess.run(["ls", "-la"])` is safe — `argv` is passed
+to `execve()` directly. `subprocess.run("ls -la", shell=True)` is
+NOT safe because the string goes through `/bin/sh -c`.
+
+The footgun: the list form looks more verbose. New engineers
+default to the string form because it reads like the shell
+command they're used to typing. `shell=True` becomes a
+convenience reflex, then becomes a habit, then ships.
+
+Same pattern in every language:
+
+- Node `exec("cmd arg")` (shell) vs `spawn("cmd", ["arg"])` (no shell)
+- Ruby `` `cmd #{var}` `` (shell) vs `Open3.capture3("cmd", var)` (no shell)
+- Go `exec.Command("sh", "-c", cmd)` (shell) vs `exec.Command("cmd", arg)` (no shell)
+- Java `Runtime.exec(String)` (shell-tokenized) vs `Runtime.exec(String[])` (no shell)
+- PHP `system($cmd)` (shell) vs `pcntl_exec($cmd, [$arg])` (no shell)
+
+## The argument-vector vs command-string distinction
+
+When the OS executes a process via `execve()`, it takes an
+**argument vector** — an array of strings. The first element is the
+program path; subsequent elements are arguments.
+
+A shell-interpreted command string gets tokenized into argv by the
+shell, applying shell rules: word splitting on whitespace, glob
+expansion, variable substitution, command substitution, quoting,
+escape sequences, control operators.
+
+The injection vector is exactly this tokenization step. If you
+build a string `convert input.jpg output.png` and the attacker
+controls `input.jpg`, they substitute `input.jpg; rm -rf /`. The
+shell sees two commands separated by `;`.
+
+If you build an argv `["convert", input_filename, output_filename]`
+and pass it to `execve()` directly, the attacker substituting
+`input.jpg; rm -rf /` as `input_filename` results in a single
+argv element with a literal semicolon in it. `convert` receives
+that as a filename argument, sees no such file, returns an error.
+No second command runs.
+
+## When you DO need a shell (rare)
+
+Some legitimate use cases require shell semantics:
+
+1. **Pipe between two commands.** `cmd1 | cmd2` requires a shell
+   to set up the pipe. Use the list-form Popen with `stdin=` /
+   `stdout=` to chain processes without a shell.
+
+2. **Shell glob expansion.** `cmd /tmp/*.log` requires shell to
+   expand the glob. Better: use Python's `glob.glob()` /
+   Node's `glob` package / etc. to expand to a list, then pass
+   that list as argv.
+
+3. **Environment variable expansion in the command string.**
+   `cmd $HOME/foo` requires shell. Better: read the env var in
+   your application code, pass the expanded string as an argv
+   element.
+
+In every "I need shell semantics" case, the right fix is to move
+the shell-semantic operation into your application code, then
+call out to the binary with explicit argv.
+
+## Per-language idioms
+
+### Python — `subprocess` is the right module
+
+```python
+import subprocess
+
+# UNSAFE — shell builds the string
+subprocess.run(f"convert {filename} out.png", shell=True)
+
+# SAFE — argv list, no shell
+subprocess.run(["convert", filename, "out.png"])
+
+# SAFE — input/output redirection via subprocess args, not shell
+with open("out.txt", "w") as f:
+    subprocess.run(["my-command"], stdout=f)
+```
+
+`subprocess.run()` and `subprocess.Popen()` both accept a list
+argument and default to `shell=False`. Use them.
+
+### Node.js — `child_process.spawn` over `exec`
+
+```javascript
+const { spawn, execFile } = require('child_process');
+
+// UNSAFE — shell builds the string
+const child = exec(`convert ${filename} out.png`);
+
+// SAFE — argv list, no shell
+const child = spawn('convert', [filename, 'out.png']);
+
+// SAFE — execFile is also no-shell by default
+execFile('convert', [filename, 'out.png'], (err, stdout) => { ... });
+```
+
+### Ruby — `Open3.capture3` over backticks
+
+```ruby
+require 'open3'
+
+# UNSAFE — backticks invoke shell
+output = `convert #{filename} out.png`
+
+# SAFE — argv list
+stdout, stderr, status = Open3.capture3('convert', filename, 'out.png')
+
+# SAFE — Process.spawn list form
+pid = Process.spawn('convert', filename, 'out.png')
+```
+
+### Go — `exec.Command` with explicit args
+
+```go
+import "os/exec"
+
+// UNSAFE — shell wrapper
+cmd := exec.Command("sh", "-c", fmt.Sprintf("convert %s out.png", filename))
+
+// SAFE — argv form (Command's default)
+cmd := exec.Command("convert", filename, "out.png")
+```
+
+### Java — `ProcessBuilder` with array
+
+```java
+import java.lang.ProcessBuilder;
+
+// UNSAFE — Runtime.exec(String) tokenizes via shell-like rules
+Runtime.getRuntime().exec("convert " + filename + " out.png");
+
+// SAFE — ProcessBuilder with explicit list
+ProcessBuilder pb = new ProcessBuilder("convert", filename, "out.png");
+Process p = pb.start();
+```
+
+### PHP — `escapeshellarg` or `proc_open` with explicit argv
+
+PHP's standard shell-invocation APIs (`system`, `exec`, `passthru`,
+`shell_exec`) all go through the shell. Either escape every argument
+or use `proc_open` with bypass_shell.
+
+```php
+// UNSAFE
+system("convert $filename out.png");
+
+// PARTIAL FIX — escapeshellarg quotes special chars
+system("convert " . escapeshellarg($filename) . " out.png");
+
+// SAFER — proc_open with bypass_shell
+$descriptors = [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']];
+$process = proc_open(
+    ['convert', $filename, 'out.png'],  // PHP 7.4+ supports array form
+    $descriptors,
+    $pipes
+);
+```
+
+## False-positive patterns
+
+Pre-validated allow-lists make the shell-string call safe by
+construction:
+
+```python
+ALLOWED_OUTPUT_FORMATS = {"png", "jpg", "webp"}
+if output_format not in ALLOWED_OUTPUT_FORMATS:
+    raise ValueError()
+# `output_format` is now constrained to a known-safe set
+subprocess.run(f"convert {filename} out.{output_format}", shell=True)
+```
+
+The `shell=True` is still flagged by the regex scanner, but the
+finding is a false positive after allow-list validation. The
+scanner can't reason about allow-list validation; the human
+reader can.
+
+That said: even with allow-list validation, the no-shell form is
+strictly safer. There's no operational reason to keep the
+shell-wrapper if the no-shell form works.
+
+## Primary sources
+
+- [CWE-78 Command Injection](https://cwe.mitre.org/data/definitions/78.html)
+- [OWASP A03:2021 Injection](https://owasp.org/Top10/A03_2021-Injection/)
+- [OWASP Command Injection Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html)
+- [Python subprocess docs — Security considerations](https://docs.python.org/3/library/subprocess.html#security-considerations)
+- [Node.js child_process docs](https://nodejs.org/api/child_process.html)