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

```bash
# 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

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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
```bash
# 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
```bash
# 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.*