@objctp/opencode-shell-routines 1.2.0

package/skills/shell-security/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: shell-security
+description: Audit a bash script for security risks the linters miss: destructive commands, system-file writes, hardcoded credentials, insecure permissions, and dynamic execution (eval/source). Run the bundled detector, classify each finding by severity, and offer safer fixes on approval. Use when checking a script's safety ("audit for vulnerabilities", "is this safe?", "secure this script"). For quoting and general standards use shell-best-practices; for overall quality review use shell-review.
+allowed-tools: Read, Grep, Bash, Write, Edit
+argument-hint: [script-path]
+---
+
+# Shell Security Skill
+
+Analyse bash scripts for security vulnerabilities, warn about risks, and automatically fix issues with safer alternatives upon approval.
+
+## Target
+
+**Target script:** `$ARGUMENTS`
+
+If `$ARGUMENTS` is not provided, prompt the user to specify which script to audit. If `$ARGUMENTS` is a directory, scan each `.sh` file in that directory.
+
+## How It Works
+
+1. **Read the script** -- Understand purpose and context
+2. **Run `scripts/security-audit.sh "$TARGET"`** -- Do not replicate its grep patterns manually; always use the script
+3. **Interpret results** -- Consult all `references/` files (`dangerous-commands.md`, `security-patterns.md`, `sensitive-files.md`) and `examples/` (`secure-script-example.sh` for safer patterns, `dangerous-command-review.md` for output format) for context; categorise as Fatal/Severe/Moderate. For dynamic execution findings (`eval`/`source` with variables), classify each as **by design** (developer tool inherently executes code), **needs review** (handles untrusted input), or **safe** (variable is internally generated). Report "by design" findings as informational, not actionable issues. See the Assessment guide in `references/dangerous-commands.md` under the Dynamic Execution section.
+4. **Warn with context** -- Explain risk, provide line number, suggest safer alternative
+5. **Offer to fix** -- For fixable issues, offer to apply safer alternatives
+6. **Confirm before modifying** -- Always ask for approval before applying any fix
+
+**Done when** every detector category has run via `scripts/security-audit.sh`; each finding has a line, severity (Fatal/Severe/Moderate), and safer alternative; every dynamic-execution finding is classified (by design / needs review / safe); and no fix is applied without explicit approval.
+
+## Scope
+
+This skill covers **destructive commands, credentials, sensitive files, insecure permissions, and dynamic execution patterns**. For quoting and general best practices, use shell-best-practices instead. For overall quality review, use shell-review instead.
+
+## What It Checks (Unique Coverage)
+
+| Category                    | Examples                                             | Already Covered By |
+| --------------------------- | ---------------------------------------------------- | ------------------ |
+| **Destructive commands**    | `rm -rf /`, `dd`, fork bombs, `chmod 777`            | UNIQUE             |
+| **System file risks**       | Editing `/etc/passwd`, `/etc/sudoers`, `/etc/shadow` | UNIQUE             |
+| **Credential exposure**     | Hardcoded API keys, secrets in code                  | UNIQUE             |
+| **Sensitive file patterns** | `.env`, `.pem`, `.key`, credentials files            | UNIQUE             |
+| **Dynamic execution**       | `eval` with variables, dynamic `source`, indirect commands | UNIQUE |
+
+**NOT covered here** (use existing tools):
+| Issue | Use Instead |
+|-------|-------------|
+| Unquoted variables | ShellCheck, shell-best-practices |
+| Pipe to `sh`/`bash` | shell-best-practices |
+| Temp file issues | shell-best-practices |
+| Syntax errors | bash -n hook |
+| Formatting | shfmt hook |
+
+## Auto-Fix Behaviour
+
+**Auto-fixable issues** (applied upon approval):
+
+- Add `--preserve-root` to rm commands
+- Replace hardcoded credentials with environment variables
+- Add confirmation prompts to dangerous commands
+- Replace `chmod 777` with specific permissions
+- Add guards before system file operations
+
+**Requires manual review**:
+
+- Fork bomb patterns (need architecture review)
+- Destructive commands with variable paths
+- System file modifications (needs intent clarification)
+
+**Always confirm before modifying** -- even for auto-fixable issues, the workflow is:
+
+1. Show the dangerous code
+2. Explain the risk
+3. Show the safer alternative
+4. Prompt the user for approval before applying the fix
+
+## Integration
+
+**How shell-security fits with existing tooling:**
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    EXISTING TOOLING (runs first)                     │
+├─────────────────────────────────────────────────────────────────────┤
+│  Hooks (PostToolUse):  ShellCheck │ shfmt │ bash -n                │
+│  LSP:                  bash-language-server (real-time)              │
+│  Skills:               shell-best-practices (eval, quoting, temp)    │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│              shell-security (UNIQUE coverage only)                  │
+├─────────────────────────────────────────────────────────────────────┤
+│  Focus: Destructive commands │ System files │ Credentials │ 777    │
+│  Action: Warn + Auto-fix (with permission)                          │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    shell-review (final output)                      │
+├─────────────────────────────────────────────────────────────────────┤
+│  Consolidates: ShellCheck + shell-security + other findings         │
+│  Output: Structured review with severity categories                 │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+**Key point**: shell-security does NOT duplicate what ShellCheck/shell-best-practices already catch. It focuses on:
+
+- **Destructive command severity** ([FATAL]/[SEVERE]/[MODERATE]) with security context
+- **System file awareness** (knows `/etc/passwd` is sensitive)
+- **Credential detection** (recognises API keys, secrets)
+- **Dynamic execution detection** (flags eval/source with variable arguments)
+- **Auto-fix capability** (can apply safer alternatives)
+
+## References
+
+- `references/dangerous-commands.md` -- Catalogue of destructive commands with risk levels and safer alternatives
+- `references/security-patterns.md` -- Conceptual map of detection categories and auto-fix status
+- `references/sensitive-files.md` -- Files that require careful handling
+
+Always read all references and examples before producing audit results.
+
+## Examples
+
+- `examples/dangerous-command-review.md` -- Sample review output with remediation
+- `examples/secure-script-example.sh` -- Secure coding reference
+
+## Scripts
+
+- `scripts/security-audit.sh` -- Reusable audit script that runs all detection grep patterns against a target file or directory.

package/skills/shell-security/examples/dangerous-command-review.md

@@ -0,0 +1,231 @@
+# Dangerous Command Review Example
+
+This example demonstrates how the `shell-security` skill reviews a script containing dangerous commands and offers fixes.
+
+## Input Script
+
+```bash
+#!/usr/bin/env bash
+# deploy.sh - Deploy application to production
+
+set -e
+
+# Configuration
+TARGET_DIR="/var/www/app"
+BACKUP_DIR="/var/backups/app"
+API_KEY="sk-1234567890abcdefghijklmnop"
+DB_PASSWORD="SuperSecretPass123"
+
+# Clean previous deployment
+rm -rf /var/www/app_old
+rm -rf $TARGET_DIR
+
+# Create backup
+tar -czf "$BACKUP_DIR/backup-$(date +%Y%m%d).tar.gz" "$TARGET_DIR"
+
+# Extract new files
+tar -xzf deploy.tar.gz -C "$TARGET_DIR"
+
+# Set permissions
+chmod -R 777 "$TARGET_DIR"
+
+# Update database
+mysql -u root -p"$DB_PASSWORD" -e "UPDATE users SET active=1"
+
+# Clean up temporary files
+find / -name "*.tmp" -exec rm {} \;
+
+# Restart service
+systemctl restart app-service
+```
+
+## Review Output
+
+```
+Scanning deploy.sh for security issues (unique coverage)...
+
+Found 6 issues:
+
+1. ◆  Line 13: rm -rf targeting system directory
+   What: rm -rf /var/www/app_old
+   Risk: Deletes directory without validation, could delete wrong path
+   Fix: Add validation and --preserve-root flag
+   [Apply fix] [Show diff] [Skip]
+
+   Proposed fix:
+   ```bash
+   [[ -d "/var/www/app_old" ]] || { echo "Directory not found" >&2; exit 1; }
+   rm -rf --preserve-root /var/www/app_old
+   ```
+
+2. ● Line 14: Unquoted variable in rm command
+   What: rm -rf $TARGET_DIR
+   Risk: If TARGET_DIR is empty, may delete unexpected files
+   Fix: Quote variable and add --preserve-root
+   [Apply fix] [Show diff] [Skip]
+
+   Proposed fix:
+   ```bash
+   rm -rf --preserve-root "$TARGET_DIR"
+   ```
+
+3. ● Line 9: Hardcoded API key
+   What: API_KEY="sk-1234567890abcdefghijklmnop"
+   Risk: Credential exposed in version control
+   Fix: Use environment variable
+   [Apply fix] [Show diff] [Skip]
+
+   Proposed fix:
+   ```bash
+   API_KEY="${API_KEY:?API_KEY environment variable not set}"
+   ```
+
+4. ● Line 10: Hardcoded database password
+   What: DB_PASSWORD="SuperSecretPass123"
+   Risk: Credential exposed in version control
+   Fix: Use environment variable or credential store
+   [Apply fix] [Show diff] [Skip]
+
+   Proposed fix:
+   ```bash
+   # Use MySQL config file instead
+   db_password="${DB_PASSWORD:?DB_PASSWORD not set}"
+   mysql -u root -p"$db_password" -e "..."
+   # OR: use ~/.my.cnf for credentials
+   ```
+
+5. ● Line 23: chmod 777 on application directory
+   What: chmod -R 777 "$TARGET_DIR"
+   Risk: Makes directory world-writable, security vulnerability
+   Fix: Use specific permissions (755 for dirs, 644 for files)
+   [Apply fix] [Show diff] [Skip]
+
+   Proposed fix:
+   ```bash
+   find "$TARGET_DIR" -type d -exec chmod 755 {} \;
+   find "$TARGET_DIR" -type f -exec chmod 644 {} \;
+   ```
+
+6. ▲  Line 29: find from root directory
+   What: find / -name "*.tmp" -exec rm {} \;
+   Risk: Searches entire filesystem, slow and risky
+   Fix: Limit search scope to specific directories
+   [Apply fix] [Show diff] [Skip]
+
+   Proposed fix:
+   ```bash
+   find "$TARGET_DIR" -name "*.tmp" -delete
+   find /tmp -maxdepth 1 -name "*.tmp" -delete
+   ```
+
+---
+Severity Summary:
+◆  Fatal:    1
+●  Severe:   4
+▲  Moderate: 1
+
+Note: ShellCheck will catch other issues (unquoted variables on line 26, etc.)
+Run shellcheck deploy.sh for additional linting.
+```
+
+## Remediation Workflow
+
+When the user selects `[Apply fix]` for all issues:
+
+```
+✔ Applying fixes...
+
+1. ✔ Added validation to rm -rf /var/www/app_old
+2. ✔ Added quotes and --preserve-root to rm -rf $TARGET_DIR
+3. ✔ Replaced hardcoded API_KEY with environment variable
+4. ✔ Replaced hardcoded DB_PASSWORD with environment variable
+5. ✔ Replaced chmod 777 with specific permissions
+6. ✔ Limited find scope to TARGET_DIR
+
+All fixes applied. Review the changes:
+git diff deploy.sh
+```
+
+## Fixed Script
+
+```bash
+#!/usr/bin/env bash
+# deploy.sh - Deploy application to production
+
+set -euo pipefail
+
+# Configuration - use environment variables for secrets
+: "${TARGET_DIR:=/var/www/app}"
+: "${BACKUP_DIR:=/var/backups/app}"
+: "${API_KEY:?API_KEY environment variable not set}"
+: "${DB_PASSWORD:?DB_PASSWORD environment variable not set}"
+
+# Validate directories exist
+for dir in "$TARGET_DIR" "$BACKUP_DIR"; do
+    [[ -d "$dir" ]] || { echo "Error: Directory not found: $dir" >&2; exit 1; }
+done
+
+# Clean previous deployment (with validation)
+if [[ -d "/var/www/app_old" ]]; then
+    rm -rf --preserve-root /var/www/app_old
+fi
+
+# Create backup
+tar -czf "$BACKUP_DIR/backup-$(date +%Y%m%d).tar.gz" "$TARGET_DIR"
+
+# Extract new files
+tar -xzf deploy.tar.gz -C "$TARGET_DIR"
+
+# Set permissions (specific, not 777)
+find "$TARGET_DIR" -type d -exec chmod 755 {} \;
+find "$TARGET_DIR" -type f -exec chmod 644 {} \;
+
+# Update database (credentials from environment)
+mysql -u root -p"$DB_PASSWORD" -e "UPDATE users SET active=1"
+
+# Clean up temporary files (limited scope)
+find "$TARGET_DIR" -name "*.tmp" -delete
+find /tmp -maxdepth 1 -name "*.tmp" -delete
+
+# Restart service
+systemctl restart app-service
+```
+
+## Additional ShellCheck Findings
+
+After shell-security fixes, ShellCheck may report:
+
+```
+Line 35: mysql -u root -p"$DB_PASSWORD" -e "..."
+         ^-- SC2154: DB_PASSWORD is referenced but not assigned.
+         (This is expected - we require it as environment variable)
+
+Line 35: mysql -u root -p"$DB_PASSWORD" -e "..."
+         ^-- SC2016: Expressions don't expand in single quotes.
+         (Use double quotes for variable expansion in command)
+```
+
+## Warning Format Template
+
+When the skill detects issues, it uses this format:
+
+> Symbols are coloured in `security-audit.sh` output: ◆ purple (Fatal), ● red (Severe), ▲ yellow (Moderate), ✔ light green (OK).
+
+```markdown
+◆/●/▲ **[Severity] [Issue type detected]**
+
+**What was detected:**
+Line N: `code_snippet`
+
+**Why this matters:**
+- Risk explanation
+- Impact assessment
+- Common scenarios that cause problems
+
+**Safer alternative:**
+```bash
+# Fixed code with explanation
+```
+
+Shall I apply this fix? (This will [describe what the fix does])
+```

package/skills/shell-security/examples/secure-script-example.sh

@@ -0,0 +1,317 @@
+#!/usr/bin/env bash
+# secure-script-example.sh
+# Demonstrates secure alternatives to common dangerous patterns
+
+set -euo pipefail
+
+###
+### :::: Configuration :::: ###########
+###
+
+# Require environment variables for secrets
+: "${DATABASE_URL:?DATABASE_URL environment variable not set}"
+: "${API_KEY:?API_KEY environment variable not set}"
+: "${APP_HOME:?APP_HOME environment variable not set}"
+
+# Directory paths with validation
+BACKUP_DIR="${APP_HOME}/backups"
+TEMP_DIR="${APP_HOME}/tmp"
+LOG_DIR="${APP_HOME}/logs"
+
+###
+### :::: Initialization :::: ##########
+###
+
+# Create directories with secure permissions
+function init_directories() {
+  local dir
+  for dir in "$BACKUP_DIR" "$TEMP_DIR" "$LOG_DIR"; do
+    if [[ ! -d "$dir" ]]; then
+      mkdir -p "$dir"
+      chmod 700 "$dir"
+    fi
+  done
+}
+
+###
+### :::: Safe File Operations :::: ####
+###
+
+# Safe file deletion with validation
+function safe_delete() {
+  local target="$1"
+  local force="${2:-false}"
+
+  # Validate target exists
+  if [[ ! -e "$target" ]]; then
+    echo "Warning: Target does not exist: $target" >&2
+    return 1
+  fi
+
+  # Validate target is within allowed directory
+  local real_target
+  real_target=$(realpath "$target")
+  if [[ ! "$real_target" =~ ^"$APP_HOME" ]]; then
+    echo "Error: Refusing to delete outside APP_HOME: $target" >&2
+    return 1
+  fi
+
+  # Confirm deletion unless forced
+  if [[ "$force" != "true" ]]; then
+    echo "Delete: $target"
+    read -r -p "Confirm? [y/N] " response
+    [[ "$response" =~ ^[Yy]$ ]] || return 1
+  fi
+
+  # Delete with safety flags
+  rm -rf --preserve-root -- "$target"
+}
+
+# Safe temporary file creation
+function safe_tempfile() {
+  local prefix="${1:-script}"
+  local tmpfile
+
+  tmpfile=$(mktemp "${TEMP_DIR}/${prefix}.XXXXXX") || return 1
+  chmod 600 "$tmpfile"
+  echo "$tmpfile"
+}
+
+# Safe file writing with backup
+function safe_write() {
+  local file="$1"
+  local content="$2"
+
+  # Validate file path
+  if [[ ! "$file" =~ ^"$APP_HOME" ]] && [[ ! "$file" =~ ^"$TEMP_DIR" ]]; then
+    echo "Error: Refusing to write outside APP_HOME: $file" >&2
+    return 1
+  fi
+
+  # Create backup if file exists
+  if [[ -f "$file" ]]; then
+    local backup
+    backup="${file}.bak.$(date +%Y%m%d_%H%M%S)"
+    cp "$file" "$backup"
+    echo "Backup created: $backup"
+  fi
+
+  # Write content
+  printf '%s\n' "$content" >"$file"
+  chmod 600 "$file"
+}
+
+###
+### :::: Secure Permissions :::: ######
+###
+
+# Set specific permissions instead of 777
+function set_permissions() {
+  local target="$1"
+
+  # Directories: 755 (rwxr-xr-x)
+  find "$target" -type d -exec chmod 755 {} \;
+
+  # Files: 644 (rw-r--r--)
+  find "$target" -type f -exec chmod 644 {} \;
+
+  # Executable scripts: 755
+  find "$target" -type f -name "*.sh" -exec chmod 755 {} \;
+
+  # Sensitive files: 600
+  find "$target" -type f \( -name "*.key" -o -name "*.pem" -o -name ".env" \) -exec chmod 600 {} \;
+}
+
+###
+### :::: Secure Database Operations :::: #####
+###
+
+# Use MySQL with config file instead of command-line password
+function mysql_query() {
+  local query="$1"
+
+  # Create temporary MySQL config
+  local my_cnf
+  my_cnf=$(safe_tempfile mysql) || return 1
+
+  # Write credentials to temp config (will be deleted)
+  cat >"$my_cnf" <<EOF
+[client]
+user="${DB_USER:-root}"
+password="${DB_PASSWORD}"
+host="${DB_HOST:-localhost}"
+EOF
+
+  # Execute query with config file
+  mysql --defaults-file="$my_cnf" -e "$query"
+  local status=$?
+
+  # Securely delete config
+  shred -u "$my_cnf"
+
+  return "$status"
+}
+
+###
+### :::: Safe Cleanup :::: ############
+###
+
+# Clean temporary files within scope only
+function cleanup_temp_files() {
+  local days="${1:-7}"
+
+  # Only clean within TEMP_DIR
+  find "$TEMP_DIR" -type f -mtime +"$days" -delete
+
+  # Clean old backups (keep last 10)
+  find "$BACKUP_DIR" -maxdepth 1 -name 'backup-*.tar.gz' -printf '%T@ %p\0' |
+    sort -zrn |
+    tail -zn +11 |
+    cut -zd ' ' -f2- |
+    xargs -r0 rm --
+}
+
+###
+### :::: Signal Handling :::: #########
+###
+
+# Secure trap handler (use function, not eval)
+function cleanup_handler() {
+  local exit_code=$?
+
+  echo "Cleaning up..." >&2
+
+  # Remove temp files
+  [[ -d "${TEMP_DIR:-}" ]] && rm -rf -- "${TEMP_DIR:?}"/*
+
+  # Log exit
+  [[ -d "${LOG_DIR:-}" ]] && echo "Script exited with code: $exit_code" >>"$LOG_DIR/exit.log"
+
+  exit "$exit_code"
+}
+
+# Register cleanup handler (function reference, not string)
+trap cleanup_handler EXIT
+
+###
+### :::: Input Validation :::: ########
+###
+
+# Validate directory path
+function validate_directory() {
+  local dir="$1"
+  local create="${2:-false}"
+
+  # Check if absolute path
+  [[ "$dir" = /* ]] || {
+    echo "Error: Path must be absolute: $dir" >&2
+    return 1
+  }
+
+  # Check if within allowed paths
+  if [[ ! "$dir" =~ ^"$APP_HOME" ]] && [[ ! "$dir" =~ ^/tmp ]]; then
+    echo "Error: Path outside allowed directories: $dir" >&2
+    return 1
+  fi
+
+  # Create if requested
+  if [[ "$create" == "true" ]] && [[ ! -d "$dir" ]]; then
+    mkdir -p "$dir"
+    chmod 755 "$dir"
+  fi
+
+  return 0
+}
+
+# Validate filename (prevent path traversal)
+function validate_filename() {
+  local filename="$1"
+
+  # Reject path traversal attempts
+  if [[ "$filename" =~ \.\. ]]; then
+    echo "Error: Path traversal detected: $filename" >&2
+    return 1
+  fi
+
+  # Reject absolute paths (should be relative)
+  if [[ "$filename" = /* ]]; then
+    echo "Error: Absolute path not allowed: $filename" >&2
+    return 1
+  fi
+
+  # Reject special characters
+  if [[ "$filename" =~ [[:space:]] ]]; then
+    echo "Error: Spaces not allowed in filename: $filename" >&2
+    return 1
+  fi
+
+  return 0
+}
+
+###
+### :::: Safe Command Execution :::: ##
+###
+
+# Execute command with timeout and resource limits
+function safe_execute() {
+  local timeout="${1:-300}" # 5 minutes default
+  shift
+  local cmd=("$@")
+
+  # Set resource limits
+  ulimit -t "$timeout" # CPU time
+  ulimit -v 4194304    # Max 4GB virtual memory
+  ulimit -u 100        # Max 100 processes
+
+  # Execute with timeout
+  timeout "$timeout" "${cmd[@]}"
+}
+
+###
+### :::: Example Usage :::: ###########
+###
+
+function main() {
+  # Initialize
+  init_directories
+
+  # Example: Safe file operations
+  local tempfile
+  tempfile=$(safe_tempfile data)
+  echo "Processing data in $tempfile"
+
+  # Example: Safe deletion
+  # safe_delete "$APP_HOME/old_data" false  # Ask for confirmation
+  # safe_delete "$APP_HOME/cache" true      # Force deletion
+
+  # Example: Set secure permissions
+  # set_permissions "$APP_HOME/public"
+
+  # Example: Cleanup
+  cleanup_temp_files 30
+
+  echo "Operations completed successfully"
+}
+
+# Run main if executed directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  main "$@"
+fi
+
+###
+### :::: Security Checklist :::: ###########
+###
+
+# ✔ set -euo pipefail for error handling
+# ✔ Environment variables for secrets (no hardcoding)
+# ✔ Path validation before operations
+# ✔ realpath for canonical paths
+# ✔ --preserve-root for rm
+# ✔ mktemp for temporary files
+# ✔ Specific permissions (no 777)
+# ✔ Function references in trap (not eval)
+# ✔ Input validation (path traversal prevention)
+# ✔ Resource limits for commands
+# ✔ Secure credential handling (MySQL config file)
+# ✔ Cleanup handlers for temp files
+# ✔ Confirmation prompts for destructive operations