Skip to content

Security: semutdev/goigniter

Security

docs/security.md

GoIgniter Security Guide

This document outlines the security features and best practices when using GoIgniter framework.

Table of Contents

  1. Security Headers Middleware
  2. CSRF Protection
  3. Rate Limiting
  4. Session Security
  5. File Upload Security
  6. CORS Configuration
  7. Error Handling in Production
  8. Query Builder (SQL Injection)
  9. Server Timeouts
  10. Request Body Limits

Security Headers Middleware

The SecurityHeaders middleware adds essential security headers to all responses.

Usage

package main

import (
    "github.com/semutdev/goigniter/system/core"
    "github.com/semutdev/goigniter/system/middleware"
)

func main() {
    app := core.New()
    
    // Basic security headers
    app.Use(middleware.SecurityHeaders())
    
    // Or with custom configuration
    app.Use(middleware.SecurityHeadersWithConfig(middleware.SecurityConfig{
        XSSProtection:         true,
        ContentTypeNosniff:    true,
        XFrameOptions:         "DENY",
        HSTS:                  true,  // Only for HTTPS
        HSTSMaxAge:            31536000,
        HSTSIncludeSubdomains: true,
        ContentSecurityPolicy: "default-src 'self'",
        ReferrerPolicy:        "strict-origin-when-cross-origin",
    }))
    
    app.Run(":8080")
}

Headers Added

Header Value Purpose
X-XSS-Protection 1; mode=block Enables browser XSS filter
X-Content-Type-Options nosniff Prevents MIME type sniffing
X-Frame-Options DENY Prevents clickjacking
Strict-Transport-Security max-age=31536000 Forces HTTPS (when enabled)
Referrer-Policy strict-origin-when-cross-origin Controls referrer information

CSRF Protection

CSRF (Cross-Site Request Forgery) protection is essential for web applications with forms.

Basic Usage

package main

import (
    "github.com/semutdev/goigniter/system/core"
    "github.com/semutdev/goigniter/system/middleware"
)

func main() {
    app := core.New()
    
    // Enable CSRF protection
    app.Use(middleware.CSRF())
    
    // For forms, include CSRF token
    app.GET("/form", func(c *core.Context) error {
        token := middleware.CSRFToken(c)
        html := `<form method="POST">
            <input type="hidden" name="csrf_token" value="` + token + `">
            <input type="text" name="data">
            <button type="submit">Submit</button>
        </form>`
        return c.HTML(200, html)
    })
    
    app.POST("/form", func(c *core.Context) error {
        // CSRF is automatically validated
        return c.String(200, "Success!")
    })
    
    app.Run(":8080")
}

Skip CSRF for API Routes

// Skip CSRF for API routes (using token authentication instead)
app.Use(middleware.CSRFWithConfig(middleware.CSRFConfig{
    Skipper: middleware.CSRFAPISkipper("/api"),
}))

// Or skip specific paths
app.Use(middleware.CSRFWithConfig(middleware.CSRFConfig{
    Skipper: middleware.CSRFSkipper("/api", "/webhook"),
}))

AJAX Requests

For AJAX requests, include the token in a header:

// Get token from meta tag or cookie
const token = document.querySelector('meta[name="csrf-token"]').content;

fetch('/api/data', {
    method: 'POST',
    headers: {
        'X-CSRF-Token': token,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({ data: 'example' })
});

Rate Limiting

Rate limiting protects against DoS attacks and abuse.

Basic Usage

// Limit to 100 requests per minute
app.Use(middleware.RateLimit(100, time.Minute))

// Limit to 10 requests per second
app.Use(middleware.RateLimit(10, time.Second))

Custom Configuration

app.Use(middleware.RateLimitWithConfig(middleware.RateLimitConfig{
    Max:     100,
    Window:  time.Minute,
    Message: "Too many requests, please try again later",
    KeyFunc: func(c *core.Context) string {
        // Use IP + User ID for more granular limiting
        return c.IP() + "_" + c.GetString("user_id")
    },
}))

Client IP Behind a Reverse Proxy

c.IP() (the default rate-limit key) returns the TCP peer address. X-Forwarded-For and X-Real-IP are ignored unless the peer is a trusted proxy, because any client can spoof those headers to get a fresh rate-limit bucket on every request. When running behind Nginx, Caddy or a load balancer, register it:

app.SetTrustedProxies("127.0.0.1", "10.0.0.0/8")

c.IP() then walks X-Forwarded-For from right to left and returns the first address that is not a trusted proxy.

Different Limits for Different Routes

// Global rate limit
app.Use(middleware.RateLimit(1000, time.Minute))

// API rate limit (stricter)
apiGroup := app.Group("/api")
apiGroup.Use(middleware.RateLimit(100, time.Minute))

Session Security

Sessions support both HMAC signing and AES-256 encryption.

Basic Session (Signed Only)

package main

import (
    "github.com/semutdev/goigniter/system/core"
    "github.com/semutdev/goigniter/system/libraries/session"
)

func main() {
    // Initialize session with secret key
    session.Init(session.Config{
        Secret:      os.Getenv("APP_KEY"), // required, >= 32 bytes (panics otherwise)
        CookieName:  "goigniter_session",
        MaxAge:      86400, // 24 hours
        Secure:      true,  // Set true in production (HTTPS)
        SameSite:    http.SameSiteStrictMode,
    })
    
    app := core.New()
    
    app.GET("/", func(c *core.Context) error {
        sess := session.Get(c)
        sess.Set("user_id", 123)
        sess.Save(c)
        return c.String(200, "Session saved")
    })
    
    app.Run(":8080")
}

Encrypted Session (Recommended for Production)

import (
    "github.com/semutdev/goigniter/system/libraries/session"
)

func main() {
    // Generate a secure encryption key (32 bytes for AES-256)
    encryptKey := session.MustGenerateKey(32)
    
    session.Init(session.Config{
        Secret:      os.Getenv("APP_KEY"), // required, >= 32 bytes (panics otherwise)
        Encrypt:     true,
        EncryptKey:  encryptKey,
        Secure:      true,  // HTTPS only
        SameSite:    http.SameSiteStrictMode,
    })
    
    // ... rest of application
}

Security Best Practices for Sessions

  1. Always use HTTPS (Secure: true)
  2. Use Strict SameSite (SameSiteStrictMode)
  3. Encrypt sensitive data (Encrypt: true)
  4. Use strong secret keys (minimum 32 bytes)
  5. Regenerate session after login

File Upload Security

The upload library has built-in security protections.

Basic Usage

import (
    "github.com/semutdev/goigniter/system/libraries/upload"
)

func handleUpload(c *core.Context) error {
    uploader := upload.New(upload.Config{
        UploadPath:   "./uploads",
        AllowedTypes: "jpg|jpeg|png|gif|pdf",
        MaxSize:      5000, // 5MB in KB
        FileName:     "random",
        CreateDirs:   true,
    })
    
    result, err := uploader.Do("file", c.Request)
    if err != nil {
        // Handle specific errors
        switch err {
        case upload.ErrFileTooBig:
            return c.String(400, "File too large")
        case upload.ErrInvalidType:
            return c.String(400, "File type not allowed")
        case upload.ErrSuspiciousFile:
            return c.String(400, "Suspicious file detected")
        case upload.ErrMimeMismatch:
            return c.String(400, "File content doesn't match extension")
        }
        return c.String(500, "Upload failed")
    }
    
    return c.JSON(200, result)
}

Security Features

  1. Mandatory allowlist - AllowedTypes is required; uploads fail with ErrNoAllowedTypes when it is empty
  2. Dangerous extension blocking - PHP, EXE, BAT, SH, etc. are blocked, and so are files browsers execute (HTML, SVG, JS) to prevent stored XSS
  3. Double extension detection - file.php.jpg is blocked
  4. Null byte injection prevention - file.php%00.jpg is blocked
  5. Path traversal prevention - ../ in filename is blocked
  6. MIME type validation - Extension must match content type
  7. Magic byte validation - Actual file content is checked
  8. Unguessable random names - FileName: "random" uses crypto/rand
  9. Image size limit - ImageProcessor rejects images above MaxPixels (default 50 MP) before decoding, preventing decompression bombs

Additional Recommendations

  1. Store uploads outside web root
  2. Use random filenames to prevent enumeration
  3. Set proper file permissions (not executable)
  4. Scan for viruses using ClamAV or similar
  5. Limit file size appropriately

CORS Configuration

CORS (Cross-Origin Resource Sharing) should be configured carefully.

Secure Configuration

// Recommended: Explicitly list allowed origins
app.Use(middleware.CORSWithConfig(middleware.CORSConfig{
    AllowOrigins:     []string{"https://yourdomain.com", "https://app.yourdomain.com"},
    AllowMethods:     []string{"GET", "POST", "PUT", "DELETE"},
    AllowHeaders:     []string{"Origin", "Content-Type", "Authorization"},
    AllowCredentials: true,
    MaxAge:           86400,
}))

// For development only (not recommended for production)
app.Use(middleware.CORSWithConfig(middleware.CORSConfig{
    AllowOrigins: []string{"http://localhost:3000"},
}))

Warning

  • Never use AllowOrigins: []string{"*"} with AllowCredentials: true
  • Default configuration now has empty AllowOrigins for security

Error Handling in Production

Never expose internal error details to users. GoIgniter hides them by default:

  • An error returned by a handler is logged server-side and the client only gets 500 Internal Server Error (or 413 for an oversized body). Call app.SetDebug(true) in development to send the error text instead.
  • Recovery() responds with ProductionMessage and never includes the panic value unless ShowErrorDetails: true is set.
app.SetDebug(os.Getenv("APP_ENV") == "local")

Secure Recovery Configuration

app.Use(middleware.RecoveryWithConfig(middleware.RecoveryConfig{
    ShowErrorDetails:   false, // default; set true only in development
    ProductionMessage:  "Something went wrong. Please try again later.",
    DisablePrintStack:  false, // Log stack internally, don't show to user
    LogFunc: func(c *core.Context, err any, stack []byte) {
        // Log to your monitoring system
        log.Printf("[ERROR] %v\nRequest: %s %s\nStack: %s", 
            err, c.Method(), c.Path(), stack)
    },
}))

Query Builder (SQL Injection)

Values passed to Where, WhereIn, Insert and Update are always sent as ? parameters. Table names, column names, operators and sort directions cannot be parameters, so the query builder validates them and returns an error instead of running the query:

  • Tables/columns must be names: id, users.name, users.* or users.name AS alias (ErrInvalidIdentifier)
  • Where operators: =, !=, <>, <, >, <=, >=, LIKE, NOT LIKE (ErrInvalidOperator)
  • OrderBy direction: ASC or DESC (ErrInvalidDirection)
  • Update() / Delete() without Where() fail with ErrNoWhere; use WhereRaw("1 = 1") to affect all rows on purpose

Still map user input to a whitelist:

columns := map[string]string{"0": "id", "1": "name", "2": "price"}
orderCol := columns[c.Query("sort")]
if orderCol == "" {
    orderCol = "id"
}
orderDir := "asc"
if c.Query("dir") == "desc" {
    orderDir = "desc"
}
database.Table("products").OrderBy(orderCol, orderDir).Get(&products)

SelectRaw, WhereRaw and Having are not validated: never build their SQL text from user input, pass values as ? arguments.


Server Timeouts

app.Run(addr) starts the server with read/write/idle timeouts (header 10s, read 60s, write 120s, idle 120s) so slow clients cannot hold connections open forever (Slowloris). To change them, pass your own server:

app.RunServer(&http.Server{
    Addr:              ":8080",
    ReadHeaderTimeout: 5 * time.Second,
    ReadTimeout:       5 * time.Minute, // large uploads
    WriteTimeout:      5 * time.Minute,
    IdleTimeout:       120 * time.Second,
})

Request Body Limits

Prevent memory exhaustion attacks by limiting request body size.

Every request body is capped at core.DefaultBodyLimit (32 MB). Reading past it fails, and a handler that returns that error gets a 413 response. Change the global cap with:

app.SetBodyLimit(10 << 20) // 10 MB; <= 0 removes the limit

Use BindWithLimit / BodyWithLimit for a tighter per-route limit:

Usage

app.POST("/api/data", func(c *core.Context) error {
    var data map[string]any
    
    // Bind with 1MB limit
    err := c.BindWithLimit(&data, 1<<20) // 1MB
    if err == core.ErrBodyTooLarge {
        return c.String(413, "Request body too large")
    }
    if err != nil {
        return c.String(400, "Invalid request")
    }
    
    return c.JSON(200, data)
})

Complete Security Setup Example

package main

import (
    "log"
    "net/http"
    "os"
    "time"
    
    "github.com/semutdev/goigniter/system/core"
    "github.com/semutdev/goigniter/system/libraries/session"
    "github.com/semutdev/goigniter/system/middleware"
)

func main() {
    // Session setup with encryption
    session.Init(session.Config{
        Secret:      os.Getenv("SESSION_SECRET"),
        Encrypt:     true,
        EncryptKey:  session.MustGenerateKey(32),
        Secure:      true,
        SameSite:    http.SameSiteStrictMode,
    })
    
    app := core.New()
    
    // Security headers
    app.Use(middleware.SecurityHeaders())
    
    // Rate limiting
    app.Use(middleware.RateLimit(100, time.Minute))
    
    // Recovery (hide details in production)
    app.Use(middleware.RecoveryWithConfig(middleware.RecoveryConfig{
        ShowErrorDetails:  os.Getenv("APP_ENV") == "local",
        ProductionMessage: "Internal Server Error",
    }))
    
    // CSRF (skip for API routes)
    app.Use(middleware.CSRFWithConfig(middleware.CSRFConfig{
        Skipper: middleware.CSRFAPISkipper("/api"),
    }))
    
    // CORS for specific origins only
    app.Use(middleware.CORSWithConfig(middleware.CORSConfig{
        AllowOrigins: []string{"https://yourdomain.com"},
    }))
    
    // Your routes here...
    
    log.Fatal(app.Run(":8080"))
}

Security Checklist

  • Enable Security Headers middleware
  • Enable CSRF protection for web routes
  • Configure Rate Limiting
  • Use encrypted sessions with HTTPS
  • Validate file uploads
  • Configure CORS with explicit origins
  • Hide error details in production
  • Limit request body size
  • Use HTTPS in production
  • Keep dependencies updated

There aren't any published security advisories