Skip to content

README.md

Latest commit

 

History

History
320 lines (224 loc) · 7.71 KB

README.md

File metadata and controls

320 lines (224 loc) · 7.71 KB

GoSQLX CLI Security Validation

This package provides comprehensive input sanitization and security validation for the GoSQLX CLI tool.

Overview

The validate package implements defense-in-depth security measures to protect against:

  • Path traversal attacks
  • Symlink exploitation
  • File size DoS attacks
  • Malicious file types
  • Special file access (devices, pipes, etc.)
  • System path access

Quick Start

Basic Usage

import "github.com/ajitpratap0/GoSQLX/cmd/gosqlx/internal/validate"

// Validate a file with default security settings
err := validate.ValidateInputFile("/path/to/query.sql")
if err != nil {
    log.Fatalf("Security validation failed: %v", err)
}

Custom Validation Settings

validator := validate.NewSecurityValidator()

// Customize security settings
validator.MaxFileSize = 5 * 1024 * 1024  // 5MB limit
validator.AllowSymlinks = false           // Block symlinks (default)
validator.AllowedExtensions = []string{".sql", ".txt"}

// Validate with custom settings
err := validator.Validate("/path/to/file.sql")

Security Features

1. Path Traversal Prevention

Automatically detects and blocks path traversal attempts:

// These will be rejected:
validate.ValidateInputFile("../../../etc/passwd")
validate.ValidateInputFile("/tmp/../../../etc/shadow")

// These are safe:
validate.ValidateInputFile("/safe/dir/query.sql")
validate.ValidateInputFile("./queries/test.sql")

2. Symlink Protection

By default, all symlinks are blocked:

// Symlink will be rejected
err := validate.ValidateInputFile("/path/to/symlink.sql")
// Error: "symlinks are not allowed for security reasons"

// To allow symlinks (not recommended):
validator := validate.NewSecurityValidator()
validator.AllowSymlinks = true
err := validator.Validate("/path/to/symlink.sql")

3. File Size Limits

Default maximum file size is 10MB:

const MaxFileSize = 10 * 1024 * 1024 // 10MB

// Files larger than 10MB are rejected
err := validate.ValidateInputFile("/path/to/huge.sql")
// Error: "file too large: 11000000 bytes (max 10485760)"

// Custom size limit:
validator := validate.NewSecurityValidator()
validator.MaxFileSize = 1024 * 1024 // 1MB

4. File Type Restrictions

Only SQL-related file types are allowed:

Allowed:

  • .sql - SQL files
  • .txt - Text files
  • (no extension) - Files without extensions

Blocked:

  • .exe, .bat, .sh, .py, .js - Executables and scripts
  • .dll, .so, .dylib - Libraries
  • .jar, .deb, .rpm - Packages
  • All other extensions
// These will be rejected:
validate.ValidateInputFile("malware.exe")
validate.ValidateInputFile("script.sh")

// These are allowed:
validate.ValidateInputFile("query.sql")
validate.ValidateInputFile("data.txt")
validate.ValidateInputFile("queries")  // No extension

5. Quick Security Check

Fast pre-validation without filesystem access:

// Check if a path looks safe before processing
if !validate.IsSecurePath(userInput) {
    return fmt.Errorf("insecure path detected")
}

// Blocked patterns:
// - Path traversal: "../../../etc/passwd"
// - Null bytes: "file.sql\x00.txt"
// - System paths: "/etc/passwd", "C:\Windows\System32\config\SAM"

API Reference

Functions

ValidateInputFile(path string) error

Validates a file path with default security settings.

Returns: Error if validation fails, nil if safe

Example:

err := validate.ValidateInputFile("/path/to/file.sql")

ValidateFileAccess(path string) error

Alias for ValidateInputFile - compatible with existing code.

IsSecurePath(path string) bool

Quick security check without filesystem access.

Returns: false if path contains suspicious patterns

Example:

if !validate.IsSecurePath(userInput) {
    return errors.New("insecure path")
}

Types

SecurityValidator

Main validation struct with configurable settings.

Fields:

  • MaxFileSize int64 - Maximum allowed file size (default: 10MB)
  • AllowedExtensions []string - List of allowed file extensions
  • AllowSymlinks bool - Whether to allow symlinks (default: false)
  • WorkingDirectory string - Optional directory restriction

Methods:

NewSecurityValidator() *SecurityValidator

Creates a validator with secure defaults.

Validate(path string) error

Performs comprehensive security validation on a file path.

Validation Steps:

  1. Resolves symlinks and gets real path
  2. Checks if file is a symlink (blocked by default)
  3. Validates path for traversal attempts
  4. Verifies file is a regular file (not device, pipe, etc.)
  5. Checks file size against limit
  6. Validates file extension
  7. Tests read permissions

Security Best Practices

1. Always Use Validation

// ❌ WRONG - No validation
content, _ := os.ReadFile(userProvidedPath)

// ✅ CORRECT - Validate first
if err := validate.ValidateInputFile(userProvidedPath); err != nil {
    return fmt.Errorf("security validation failed: %w", err)
}
content, _ := os.ReadFile(userProvidedPath)

2. Keep Symlinks Disabled

// ✅ RECOMMENDED - Use defaults (symlinks blocked)
err := validate.ValidateInputFile(path)

// ⚠️ USE WITH CAUTION - Only if absolutely necessary
validator := validate.NewSecurityValidator()
validator.AllowSymlinks = true  // Security risk

3. Use Appropriate Size Limits

// For CLI tools processing user files
validator := validate.NewSecurityValidator()
validator.MaxFileSize = 10 * 1024 * 1024  // 10MB (default)

// For automated processing
validator.MaxFileSize = 1 * 1024 * 1024   // 1MB (stricter)

// For trusted internal files
validator.MaxFileSize = 100 * 1024 * 1024 // 100MB (relaxed)

4. Restrict Working Directory

// Restrict file access to specific directory
validator := validate.NewSecurityValidator()
validator.WorkingDirectory = "/safe/queries/dir"

// Only files within /safe/queries/dir will be allowed
err := validator.Validate(path)

Testing

Run the comprehensive test suite:

# Run all tests
go test ./cmd/gosqlx/internal/validate/

# Run with race detection
go test -race ./cmd/gosqlx/internal/validate/

# Run specific security feature tests
go test -v -run TestSecurityFeatures ./cmd/gosqlx/internal/validate/

# Run benchmarks
go test -bench=. ./cmd/gosqlx/internal/validate/

Error Handling

All validation errors include descriptive messages:

err := validate.ValidateInputFile(path)
if err != nil {
    // Examples of error messages:
    // "symlinks are not allowed for security reasons: /path/link -> /real/path"
    // "file too large: 11000000 bytes (max 10485760)"
    // "unsupported file extension: .exe (allowed: [.sql .txt ])"
    // "not a regular file: /dev/null (mode: Dcrw-rw-rw-)"
    // "suspicious path pattern detected: /../"
}

Performance

The validation overhead is minimal:

  • File validation: ~2.5μs per operation
  • Quick path check: ~250ns per operation
  • Memory allocation: ~128 bytes per validation

Impact: < 0.01% overhead on typical CLI operations

Integration

This package is automatically integrated with all GoSQLX CLI commands:

  • gosqlx validate - SQL validation
  • gosqlx format - SQL formatting
  • gosqlx parse - AST parsing
  • gosqlx analyze - SQL analysis

All file inputs are automatically validated before processing.

Security Updates

This package follows OWASP security guidelines and is regularly updated to address new threat vectors.

Current Version: 1.0.0 Last Security Review: 2025-11-05 Test Coverage: 100% Known Vulnerabilities: None

Support

For security issues or questions:

  • Open an issue on GitHub
  • Tag with "security" label
  • For sensitive issues, contact maintainers directly

License

This security validation package is part of GoSQLX and follows the same license.