shell-subprocess-safety
/shell-subprocess-safety
Wskazuje bezpieczne wzorce uruchamiania procesów potomnych, np. execFileSync zamiast execSync, i tablice argumentów.
- Autor
- kookr-ai ↗
- Repozytorium
- kookr ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Wskazuje bezpieczne wzorce uruchamiania procesów potomnych, np. execFileSync zamiast execSync, i tablice argumentów.
Oryginalny opis (EN)
Shell subprocess safety patterns - execFileSync over execSync, array arguments, shell feature replacements, static analysis guards. Use when spawning child processes, running git/docker/system commands, or reviewing code that calls execSync.
Jak działa
- When to Use
- Non-Negotiable Rules
- Shell Feature Replacements
- Wrapper Method Pattern
- Input Validation Patterns
- Static Analysis Guard
- Common Pitfalls
- Cross-Platform Portability (Linux ↔ macOS)
- See Also
Podgląd SKILL.md
---
name: shell-subprocess-safety
description: Shell subprocess safety patterns - execFileSync over execSync, array arguments, shell feature replacements, static analysis guards. Use when spawning child processes, running git/docker/system commands, or reviewing code that calls execSync.
keywords: execSync, execFileSync, spawnSync, shell injection, command injection, child_process, CWE-78, shellQuote, escapeShellArg, template literal, subprocess, git command, docker command
related: error-handling-patterns, process-lifecycle-patterns, testing-patterns
---
# Shell Subprocess Safety
## When to Use
- Writing code that calls external binaries (git, docker, lsof, grep, etc.)
- Reviewing code that uses `execSync()`, `child_process`, or shell commands
- Migrating existing shell-interpolated commands to safe patterns
- Adding new system commands to production code or scripts
## Non-Negotiable Rules
| # | Rule | Violation | Correct |
|---|------|-----------|---------|
| 1 | **Never `execSync` with interpolation** | `` execSync(`git checkout ${branch}`) `` | `execFileSync('git', ['checkout', branch])` |
| 2 | **Never `execSync` with concatenation** | `execSync('git checkout ' + branch)` | `execFileSync('git', ['checkout', branch])` |
| 3 | **No shell quoting helpers** | `shellQuote(val)`, `escapeShellArg(val)` | Not needed — `execFileSync` bypasses shell |
| 4 | **Array args for all binaries** | `execFileSync('git', 'checkout main')` | `execFileSync('git', ['checkout', 'main'])` |
| 5 | **Validate untrusted input** | Pass raw user string to binary | Validate format (hex SHA, port range) before exec |
## Shell Feature Replacements
| Shell Feature | Node.js Replacement |
|---|---|
| `cmd 2>/dev/null` | `execFileSync(cmd, args, { stdio: ['pipe', 'pipe', 'ignore'] })` |
| `cmd \|\| true` | `try { execFileSync(...) } catch { /* handle or ignore */ }` |
| `cmd1 \| cmd2` | `spawnSync(cmd2, args2, { input: execFileSync(cmd1, args1) })` |
| `cat file \| cmd` | `execFileSync(cmd, args, { input: readFileSync(file) })` |
| `echo "text"` | Return string directly or `Buffer.from(text)` |
| `sleep N` | `Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, N * 1000)` |
## Wrapper Method Pattern
```typescript
// CORRECT: Private wrapper accepts string[] — all call sites pass arrays
private git(args: string[]): string {
return execFileSync('git', args, {
cwd: this.workingDir,
stdio: 'pipe',
timeout: 30_000,
encoding: 'utf-8',
}).trim();
}
// Usage — no shell interpretation of metacharacters
this.git(['checkout', branchName]);
this.git(['merge', '--no-ff', '-m', commitMessage, sourceBranch]);
this.git(['checkout', '--theirs', '--', filePath]);
```
## Input Validation Patterns
```typescript
// SHA validation — hex characters only
function assertSha(sha: string): void {
if (!/^[0-9a-f]{7,40}$/i.test(sha)) {
throw new Error(`Invalid SHA: ${sha}`);
}
}
// Port validation — numeric range
function assertPort(port: number): void {
if (!Number.isInteger(port) || port < 1 || port > 65535) {
throw new Error(`Invalid port: ${port}`);
}
}
```
## Static Analysis Guard
Detect violations by grepping for the two injection-prone shapes
(`execSync` with a template literal; `execSync` with string concatenation):
```bash
grep -rn 'execSync(`' src/
grep -rn 'execSync(.*+' src/
```
Add the checks to CI or a pre-commit hook to prevent regression.
## Common Pitfalls
| Pitfall | Why It Fails | Fix |
|---|---|---|
| `execFileSync('git', 'checkout main')` | Second arg is string not array | Always pass `string[]` |
| `execFileSync('sh', ['-c', cmd])` | Still spawns shell — defeats purpose | Call binary directly |
| `execSync(staticString)` without interpolation | OK but inconsistent | Prefer `execFileSync` for consistency |
| Forgetting `encoding: 'utf-8'` | Returns Buffer not string | Always pass encoding option |
| Not handling exit code 1 | grep returns 1 for no matches | Wrap in try/catch, check `status` |
## Cross-Platform Portability (Linux ↔ macOS)
A binary that exists on both platforms may still take different flags. macOS ships **BSD** coreutils and **bash 3.2** (frozen at GPLv2), so GNU-only flags and bash-4 syntax that pass on Debian fail silently on Mac. Whether you call these via `execFileSync` or in a `.sh` script, prefer the portable form.
| GNU-only / bash-4 | Why it breaks on macOS | Portable form |
|---|---|---|
| `grep -P` / `-oP` | BSD grep has no PCRE | `grep -E` (POSIX ERE), or `perl`/`awk` |
| `sed -i 's/…'` | BSD `sed -i` consumes the next token as a backup suffix | `sed -i.bak 's/…' && rm f.bak`; no-backup = `sed -i '' …` |
| `sed -r` | GNU-only | `sed -E` (both) |
| `readlink -f` | older macOS `readlink` lacks `-f` | realpath helper / `python`/`perl` |
| `stat -c`, `date -d` | BSD uses `-f`, `-v`/`-j -f` | gate on `uname -s` |
| `find -printf`, `xargs -r` | GNU-only | restructure (`-print0`, guard input) |
| `mapfile`/`readarray`, `${var,,}`, `declare -A` | bash 4+ | `while read`, `tr`, plain arrays |
| `echo -n` / `echo -e` | literal under POSIX `/bin/sh` | `printf` |
Runtime-only traps no linter catches — verify on a real Mac (or macOS CI): `"${arr[@]}"` under `set -u` when empty (use `"${arr[@]+"${arr[@]}"}"`); heredoc nested in `$(...)` with a backtick (move to a sibling file); `/proc` absence (use `ps`); `/var`→`/private/var` symlink (resolve with `realpath`/`pwd -P`); pnpm dropping native exec bits (restore `+x` in `prepare`); Unix socket `sun_path` ≤ 103 bytes (short `/tmp` base).
Defense in depth: a diff-scoped linter (a `check-shell-portability` helper) catches the static class on every PR for free; a gated macOS CI job is the only thing that exercises the runtime class. A reviewer pass (e.g. a `macos-compat-reviewer` subagent) covers idioms the linter misses, but cannot confirm runtime traps from reading alone.
## See Also
- [[error-handling-patterns]] — try/catch discipline for failed commands
- [[process-lifecycle-patterns]] — signal handling and cleanup
- [[testing-patterns]] — testing subprocess calls with mocked execFileSync
Wersje
W bazie nie ma innych skilli o nazwie shell-subprocess-safety.
Migawka bazy z 13.11.2026 · wersja paczki e4cf55e99e36 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 82process-lifecycle
Pomaga zmieniać uruchamianie podprocesów, ich anulowanie, sprzątanie drzewa procesów i zabezpieczenia procesów potomnych w Windows. - 82process-lifecycle
Pomaga w zmianach wykonywania podprocesów: anulowaniu, czyszczeniu drzewa procesów i hartowaniu procesów potomnych w Windows. - 100bun-shell
Obsługuje skrypty powłoki w Bun przez Bun.$ i Bun.spawn oraz zarządzanie podprocesami, polecenia powłoki i wykonywanie komend w szablonach tekstowych. - 91hermes-shell-hook-guards
Wymusza strukturalnie reguły zapisane w tekście, np. przez hooki powłoki. - 100shell-review
Sprawdza skrypty powłoki pod kątem poprawności, przenośności i typowych pułapek, na przykład przed zatwierdzeniem zmian. - 100shell-script-review
Przegląda skrypty powłoki pod kątem bezpieczeństwa, poprawności i utrzymania oraz sprawdza, czy są sparowane z testami Bats.