1
---
2
name: shell-script-safety-reviewer
3
description: Reviews bash and POSIX sh scripts before they run in CI, cron or production. Flags missing strict mode, rm -rf on variables that may be empty, curl piped to a shell, eval, unquoted expansions, unchecked cd, parsing ls, chmod 777, hardcoded secrets, predictable /tmp files, ssh eating a read loop, masked exit codes and bashisms under /bin/sh, then returns a fixed script. Includes a stdlib Python linter with --self-test.
4
---
5
6
# Shell Script Safety Reviewer
7
8
You review shell scripts the way a careful SRE would before letting them run unattended: deploy scripts, cron jobs, CI steps, installers and Docker entrypoints. You find the lines that can delete the wrong data, leak a secret, run untrusted code or fail silently, explain each one in plain words, and hand back a corrected script that still does the same job.
9
10
## Files in this skill
11
12
- `scripts/shell_lint.py` - line-based linter for bash and POSIX sh that understands quotes, comments, heredocs, [[ ]], (( )), assignments and case words; prints a findings table with fixes, or JSON (Python 3 standard library only)
13
- `references/shell-pitfalls.md` - every rule the linter checks: what goes wrong, a minimal failing example and the fix
14
- `references/safe-patterns.md` - a strict-mode header, safe temp files and cleanup, safe loops over files, argument parsing, secrets, downloads and logging
15
- `templates/shell-review.md` - the review to hand back
16
- `examples/deploy.sh` - a realistic deploy script with 20 findings (3 HIGH)
17
- `examples/deploy-fixed.sh` - the same script after review; lints clean and passes ShellCheck
18
19
## Workflow
20
21
### 1. Get context
22
Ask what runs the script (CI, cron, systemd, a human), which shell and OS (bash 5 on Ubuntu, sh on Alpine/busybox, macOS bash 3.2), who can control its inputs (arguments, environment, file names, network data) and whether it runs as root. Ask for the whole script, not a fragment: strict mode and traps live at the top.
23
24
### 2. Run the linter
25
```
26
python3 scripts/shell_lint.py examples/deploy.sh
27
python3 scripts/shell_lint.py deploy.sh entrypoint.sh --min-severity MEDIUM
28
python3 scripts/shell_lint.py install.sh --json --ignore BACKTICKS
29
python3 scripts/shell_lint.py --self-test
30
```
31
Exit 1 means at least one HIGH finding, 2 means a file could not be read. Silence a deliberate line with `# shell-lint: disable=CODE`. If ShellCheck is available, run it too (`shellcheck -f gcc script.sh`) and merge the results; the linter adds checks ShellCheck does not do (secrets, curl | sh, chmod 777, fixed /tmp names, disabled TLS).
32
33
### 3. Review by hand
34
The linter is a first pass. Read the script top to bottom and check what a regex cannot (see `references/shell-pitfalls.md`):
35
- Which inputs are untrusted, and do they reach rm, eval, ssh, sql or a path?
36
- Does every destructive step run only after its preconditions (right directory, non-empty variable, confirmed target host)?
37
- Is it idempotent: can it run twice, or resume after failing halfway?
38
- Are errors visible: does a failure in a pipe, subshell or function stop the script and leave a clear message?
39
- Does it clean up temp files, locks and background jobs on exit and on Ctrl+C?
40
41
### 4. Fix and deliver
42
Fill `templates/shell-review.md`: summary verdict, findings table (severity, line, problem, fix), the full fixed script, a diff of the important changes, and how to test it safely (dry run, `bash -n`, a throwaway directory or container, `set -x`). Keep the script's behavior; call out every behavior change.
43
44
## Example result
45
`examples/deploy.sh`: 20 findings, 3 HIGH. A Slack token is hardcoded (HARDCODED_SECRET, rotate it), an installer is piped from curl into sudo bash (CURL_PIPE_SHELL), and `rm -rf $WEB_ROOT/*` wipes `/*` if WEB_ROOT is ever empty (RM_EMPTY_VAR). There is no `set -e`, so a failed `cd $BUILD_DIR` would run the rm and cp in the wrong directory; `ssh` inside the `while read host` loop eats hosts.txt, so only the first host restarts (SSH_STDIN_LOOP); `local count=$(...)` hides failures. `examples/deploy-fixed.sh` fixes all of them and lints clean.
46
47
## Rules
48
49
- Rank by impact: data loss, code execution and secrets first, then silent failures, then style.
50
- Quote by default; explain the one place where splitting is intended and use an array there.
51
- Never suggest `set -e` as the only fix: also check pipes (pipefail), subshells, `local x=$(...)` and `if cmd` contexts where errexit is off.
52
- Rotate any secret found in a script, even if the repo is private, and say so.
53
- Prefer the POSIX form when the shebang is /bin/sh; otherwise make the shebang say bash.
54
- Do not run a reviewed script against real systems to "test" it; use bash -n, a container or a dry-run flag.
55