Bash Script Validator

Mindset

Treat a clean ShellCheck run as the floor, never the ceiling, of validation. ShellCheck is a static analyzer: it never executes the script, so it cannot catch a missing file, a wrong permission, or an exit code that only shows up under a real workload. Always run the script against representative inputs, in a sandbox or container, after ShellCheck passes — not instead of it. Never accept a blanket # shellcheck disable=SCxxxx at the top of a file; a global suppression hides every future violation of that rule, not just the one the author intended to silence. Verify the shebang matches the actual syntax used in the body before trusting either signal alone: a #!/bin/sh script written with bash-only syntax ([[ ]], declare -A) will pass a naive bash-mode check and then fail silently on Alpine, BusyBox, or any strict POSIX sh. Check exit-code propagation explicitly — a function that swallows a real failure with || true or an unconditional exit 0 breaks set -e for every caller upstream of it, and that failure mode does not show up in ShellCheck's output at all.

When to Use

Use this skill when validating an existing bash or POSIX sh script, running ShellCheck against a script and interpreting its output, auditing a script for security issues (command injection, unsafe eval, unquoted expansions), checking whether a script marked #!/bin/sh is actually POSIX-compliant, or debugging why a script behaves differently across environments.

When NOT to Use

Do not use this skill to write a new script from scratch — that is the bash-script-generator skill's job; this one only validates and explains, it does not author the initial structure. Do not use it for scripts in a different language interpreted by a shebang (Python, Perl, Ruby) — those need their own linters, not ShellCheck or bash-specific portability checks.

Validation & Response

Run the Validator

bash scripts/validate.sh <script-path>

Required Workflow

1. Run: bash scripts/validate.sh <script-path>
2. Read the validation output and identify all issues
3. Read references/common-mistakes.md for fix patterns
4. Read references/shellcheck-reference.md for SC error explanations (if needed)
5. For EACH issue found:
   a. Show the problematic code
   b. Explain the issue (referencing documentation)
   c. Provide the corrected code
   d. Explain why the fix improves the script

Example Output

========================================
BASH/SHELL SCRIPT VALIDATOR
========================================
File: myscript.sh
Detected Shell: bash

[SYNTAX CHECK]
✓ No syntax errors found (bash -n)

[SHELLCHECK]
myscript.sh:15:5: warning: Quote to prevent word splitting [SC2086]
myscript.sh:23:9: error: Use || exit to handle cd failure [SC2164]

[CUSTOM CHECKS]
⚠ Potential command injection: eval with variable found
  Line 42: eval $user_input

ℹ Useless use of cat detected
  Line 18: cat file.txt | grep pattern

========================================
VALIDATION SUMMARY
========================================
Errors:   2
Warnings: 3
Info:     1

Response Format Template

## Validation Results

Found X errors, Y warnings, Z info issues.

### Issue 1: Unquoted Variable (Line 25)

**Problem:**
\`\`\`bash
if [ ! -f $file ]; then  # Word splitting risk
\`\`\`

**Reference:** See `common-mistakes.md` section "1. Unquoted Variables"

**Fix:**
\`\`\`bash
if [ ! -f "$file" ]; then  # Properly quoted
\`\`\`

**Why:** Unquoted variables undergo word splitting and glob expansion,
causing unexpected behavior with filenames containing spaces or special characters.

Example Scripts

Located in assets/ directory:

• good-bash.sh — Well-written bash script demonstrating best practices
• bad-bash.sh — Poorly-written bash script with common mistakes
• good-shell.sh — POSIX-compliant sh script
• bad-shell.sh — sh script with bashisms and errors

Installation Requirements

Required

• bash or sh (for running scripts)

ShellCheck Installation Options

Option 1: System-wide (Recommended)

brew install shellcheck        # macOS
apt-get install shellcheck     # Ubuntu/Debian
dnf install shellcheck         # Fedora

Option 2: Automatic via Wrapper (Python required)

./scripts/shellcheck_wrapper.sh --cache script.sh
# Clears cache: ./scripts/shellcheck_wrapper.sh --clear-cache

Option 3: Manual Python install

pip3 install shellcheck-py

The validator works without ShellCheck but provides enhanced validation when available.

Technical Details & Directory Structure

Automatic Shell Detection

• #!/bin/bash, #!/usr/bin/env bash → bash
• #!/bin/sh, #!/usr/bin/sh → POSIX sh
• #!/bin/zsh → zsh / #!/bin/ksh → ksh / #!/bin/dash → dash

Exit Codes

• 0: No issues found — 1: Warnings found — 2: Errors found

Validation Logic

1. File existence and readability check
2. Shebang detection → determines shell type
3. Syntax validation → bash -n or sh -n
4. ShellCheck validation → if installed, with appropriate shell dialect
5. Custom security checks → unsafe eval, command injection, rm -rf, unquoted variables
6. Custom portability checks → bashisms in sh scripts
7. Summary generation → color-coded report with counts

Layout

bash-script-validator/
├── scripts/validate.sh
├── references/         # bash, shell, shellcheck, common-mistakes, grep, awk, sed, regex
└── assets/             # good-bash.sh, bad-bash.sh, good-shell.sh, bad-shell.sh

Anti-Patterns

NEVER rely only on ShellCheck for validation

• WHY: ShellCheck catches syntax and safety issues statically but does not execute the script; runtime errors like missing files, wrong permissions, and incorrect exit codes only surface during actual execution with real inputs.
• BAD: Pass ShellCheck with zero warnings and ship the script without running it against representative inputs in a real or sandboxed environment.
• GOOD: Run ShellCheck first (fast, catches most issues), then test in a container or sandboxed environment with representative inputs to catch runtime failures.

NEVER disable ShellCheck rules globally with a file-level directive

• WHY: A global # shellcheck disable=SCxxxx at the top of a file defeats the purpose of linting and silently hides real issues in code added later, long after the original suppression rationale is forgotten.
• BAD: # shellcheck disable=SC2086 at the top of the file to silence all quoting warnings across every line in the script.
• GOOD: Add per-line suppressions only where the behavior is intentional and documented: # shellcheck disable=SC2086 # word splitting intentional here.

NEVER treat POSIX sh and bash scripts identically

• WHY: POSIX sh does not support arrays, [[ ]], $(()) arithmetic, or many bash extensions; scripts marked #!/bin/sh will fail with bash-only syntax on some systems (Alpine Linux, minimal containers, many CI runners).
• BAD: Use #!/bin/sh as the shebang but write bash-specific syntax like declare -A or [[ -n $var ]] — the script will fail silently or with cryptic errors on non-bash sh implementations.
• GOOD: Use #!/usr/bin/env bash for scripts that require bash features; use #!/bin/sh only for scripts that are tested with strict POSIX compliance using shellcheck --shell=sh.

NEVER use exit 0 or || true to suppress error propagation

• WHY: Explicitly returning 0 from a function or subshell that encountered an error hides failures from the caller, breaks set -e propagation, and makes debugging silent failures much harder.
• BAD: validate() { run_check || true; return 0; } — the function always succeeds even when run_check fails, so callers cannot detect the failure.
• GOOD: Return meaningful exit codes and let set -e propagate failures: validate() { run_check; } — if run_check fails, validate fails, and the caller can act on the exit code.

References

Core References

• bash-reference.md — Bash-specific features, parameter expansion, arrays, control structures, functions, best practices, common pitfalls
• shell-reference.md — POSIX sh compliance, portable constructs, differences from bash, POSIX utilities
• shellcheck-reference.md — ShellCheck error codes explained, severity levels, configuration options, CI/CD integration
• common-mistakes.md — 25+ common shell scripting mistakes with real-world examples and correct solutions

Tool References

• grep-reference.md — BRE/ERE patterns, common grep patterns, performance tips
• awk-reference.md — Field processing, pattern matching, arrays, log analysis, CSV/text processing
• sed-reference.md — Substitution patterns, address ranges, in-place editing, common one-liners
• regex-reference.md — BRE vs ERE, POSIX character classes, metacharacters, common patterns
• GNU Bash Manual
• POSIX Shell Specification
• ShellCheck
• GNU grep / GNU awk / GNU sed