shell/immich/SECURITY-CHECKLIST.md

Shell Script Security Checklist

This checklist provides comprehensive security validation for shell scripts, based on the security review of the Immich restoration system and broader shell script ecosystem.

Critical Security Validations

1. Input Validation and Sanitization

✅ Path Validation

• All paths validated against traversal attacks (../, ./)
• Paths resolved with realpath to detect symlink attacks
• Strict character whitelist validation (^[a-zA-Z0-9/_-]+$)
• Absolute path requirements enforced where appropriate
• Path existence and permissions verified before operations

# SECURE: Comprehensive path validation
local resolved_path=$(realpath "$USER_PATH" 2>/dev/null || echo "$USER_PATH")
if [[ "$USER_PATH" =~ \.\. ]] || [[ "$resolved_path" =~ \.\. ]]; then
    echo "Error: Path traversal detected"
    exit 1
fi
if [[ ! "$USER_PATH" =~ ^[a-zA-Z0-9/_-]+$ ]]; then
    echo "Error: Invalid characters in path"
    exit 1
fi

✅ Database Identifier Validation

• Database names validated with strict regex (^[a-zA-Z0-9_]+$)
• Usernames validated with alphanumeric patterns
• SQL parameters properly quoted in all operations
• No dynamic SQL construction without validation

# SECURE: SQL injection prevention
if [[ ! "$DB_NAME" =~ ^[a-zA-Z0-9_]+$ ]]; then
    echo "Error: Invalid database name"
    exit 1
fi

✅ File Input Validation

• File extensions validated against whitelist
• File size limits enforced where appropriate
• MIME type validation for uploaded files
• File content scanning for malicious patterns

2. Command Injection Prevention

✅ Variable Expansion Security

• All variables quoted in command contexts ("$VAR")
• No eval usage without extreme validation
• No exec usage with user-controlled input
• Command substitution properly secured ($(command) vs backticks)

# SECURE: Proper variable quoting
if [[ "$USER_INPUT" =~ ^[a-zA-Z0-9_-]+$ ]]; then
    result=$(some_command "$USER_INPUT")
fi

# INSECURE: Unquoted variables
result=$(some_command $USER_INPUT)  # DON'T DO THIS

✅ Command Construction

• No string concatenation for command building
• Array usage for complex command construction
• Proper escaping of special characters
• Validation before any system() or shell execution calls

3. File Operation Security

✅ Archive Extraction Safety

• Use --no-absolute-names with tar extraction
• Extract to secure temporary directories first
• Validate archive contents before extraction
• Set restrictive permissions on temporary directories

# SECURE: Safe archive extraction
temp_dir=$(mktemp -d)
chmod 700 "$temp_dir"
tar --no-absolute-names -xzf "$ARCHIVE" -C "$temp_dir"

✅ File Permission Management

• Set minimal required permissions
• Use numeric permissions for clarity
• Validate file ownership before operations
• Cleanup temporary files with secure deletion

✅ Symlink Attack Prevention

• Use realpath to resolve symlinks before operations
• Validate final resolved paths
• Avoid following symlinks in sensitive operations
• Check for TOCTOU (Time-of-Check-Time-of-Use) races

4. Container and Service Security

✅ Container Lifecycle Management

• Proper container startup verification
• Container health checks before operations
• Graceful container shutdown after operations
• Container cleanup on error conditions

# SECURE: Container lifecycle management
if ! docker ps -q --filter "name=mycontainer" | grep -q .; then
    echo "Error: Container not running"
    exit 1
fi

# Perform operations...

# Always cleanup
docker stop mycontainer 2>/dev/null || true

✅ Service Dependencies

• Service availability checked before operations
• Graceful fallback when services unavailable
• Proper error handling for service failures
• Service state restoration on errors

✅ Resource Management

• Proper cleanup of Docker containers
• Network resource cleanup
• File descriptor management
• Memory usage monitoring for large operations

5. Error Handling and Cleanup

✅ Comprehensive Error Handling

• set -e used appropriately (not in test scripts)
• Error trap handlers implemented for cleanup
• All temporary resources cleaned up on exit
• Proper exit codes for different error conditions

# SECURE: Comprehensive cleanup
cleanup() {
    if [[ -n "$TEMP_DIR" && -d "$TEMP_DIR" ]]; then
        rm -rf "$TEMP_DIR"
    fi
    if [[ "$SERVICE_STOPPED" == "true" ]]; then
        systemctl start myservice
    fi
}
trap cleanup EXIT ERR

✅ Information Disclosure Prevention

• No sensitive data in log files
• Error messages don't reveal system internals
• Proper handling of credentials in environment
• Secure temporary file naming

6. Logging and Monitoring

✅ Security Event Logging

• All security-relevant events logged
• Timestamps included in all log entries
• Log rotation and retention policies
• No sensitive data in logs (passwords, tokens)

✅ Monitoring Integration

• Critical operations have monitoring hooks
• Failure conditions trigger appropriate alerts
• Performance metrics collected for analysis
• Security events forwarded to SIEM if applicable

Advanced Security Considerations

1. Privilege Management

• Scripts run with minimal required privileges
• sudo usage limited to specific commands, not entire scripts
• User context switching properly handled
• File ownership maintained correctly

2. Network Security

• HTTPS used for all external communications
• Certificate validation enabled
• Network timeouts configured appropriately
• No hardcoded URLs or endpoints

3. Data Protection

• Sensitive data encrypted at rest
• Secure deletion of temporary sensitive files
• Proper handling of backup data
• Data integrity verification

4. Race Condition Prevention

• File locking implemented for critical sections
• Atomic operations used where possible
• Proper ordering of operations
• TOCTOU vulnerabilities addressed

Testing and Validation

Security Testing Requirements

• Path traversal attack testing
• Command injection testing
• SQL injection testing (if applicable)
• Container security testing
• Error condition testing
• Privilege escalation testing

Automated Security Scanning

• Static analysis tools integrated
• Dependency vulnerability scanning
• Container image security scanning
• Secrets detection in code

Documentation Requirements

Security Documentation

• Threat model documented
• Security assumptions documented
• Known limitations documented
• Security contact information provided

Operational Security

• Deployment security requirements
• Monitoring and alerting setup
• Incident response procedures
• Regular security review schedule

Common Anti-Patterns to Avoid

❌ Dangerous Practices

# DON'T: Unquoted variables
if [ $VAR = "value" ]; then

# DON'T: Command injection vulnerability
result=$(cat $USER_FILE)

# DON'T: Path traversal vulnerability
cp "$USER_PATH" /safe/location/

# DON'T: SQL injection vulnerability
mysql -e "SELECT * FROM users WHERE name='$USERNAME'"

# DON'T: Insecure temporary files
temp_file=/tmp/myfile.$$

✅ Secure Alternatives

# DO: Quoted variables
if [[ "$VAR" = "value" ]]; then

# DO: Input validation
if [[ "$USER_FILE" =~ ^[a-zA-Z0-9/_-]+$ ]]; then
    result=$(cat "$USER_FILE")
fi

# DO: Path validation
if [[ "$USER_PATH" =~ ^[a-zA-Z0-9/_-]+$ ]] && [[ ! "$USER_PATH" =~ \.\. ]]; then
    cp "$USER_PATH" /safe/location/
fi

# DO: Parameterized queries
if [[ "$USERNAME" =~ ^[a-zA-Z0-9_]+$ ]]; then
    mysql -e "SELECT * FROM users WHERE name='$USERNAME'"
fi

# DO: Secure temporary files
temp_file=$(mktemp)
chmod 600 "$temp_file"

Review Process

Pre-Deployment Review

1. Automated Scanning: Run static analysis tools
2. Manual Review: Follow this checklist completely
3. Security Testing: Execute security test cases
4. Documentation Review: Verify security documentation
5. Peer Review: Have another developer review security aspects

Post-Deployment Monitoring

1. Log Analysis: Monitor for security events
2. Performance Monitoring: Watch for unusual patterns
3. Regular Reviews: Schedule periodic security reviews
4. Incident Response: Maintain response procedures

Continuous Security

1. Security Updates: Keep dependencies updated
2. Threat Intelligence: Monitor for new attack patterns
3. Training: Keep team updated on security practices
4. Documentation: Maintain current security documentation

---

This checklist should be used for all shell script security reviews and updated based on new threats and best practices.