Route-Based Security Configuration #

Overview #

XyPriss now supports route-based security configuration, allowing developers to selectively apply security modules to specific routes. This feature addresses the issue where legitimate data (like URLs in template content) was being incorrectly flagged as security threats.

Problem Statement #

Previously, XyPriss security modules (like Path Traversal detection) were applied globally to all routes. This caused false positives where safe data containing URL patterns (e.g., /signup, #demo) in template or content routes were blocked as potential security threats.

Solution #

The new routeConfig option in SecurityConfig allows you to:

Exclude specific routes from security modules (blacklist approach)
Include only specific routes for security modules (whitelist approach)
Apply different security rules to different parts of your application

Configuration #

Basic Example #

import { createServer } from "xypriss";

const app = createServer({
    security: {
        enabled: true,
        pathTraversal: true,
        sqlInjection: true,
        
        // Route-based configuration
        routeConfig: {
            pathTraversal: {
                // Exclude template and content routes from path traversal detection
                excludeRoutes: [
                    "/api/templates/*",
                    "/api/content/*",
                    "/api/security/*"
                ]
            },
            sqlInjection: {
                // Only apply SQL injection detection to database routes
                includeRoutes: [
                    "/api/db/*",
                    "/api/query/*"
                ]
            }
        }
    }
});

Route Pattern Formats #

You can specify routes in three formats:

1. String with Wildcards

excludeRoutes: [
    "/api/templates/*",      // Matches /api/templates/anything
    "/api/content/*",        // Matches /api/content/anything
    "/exact/path"            // Exact match only
]

2. Regular Expressions

excludeRoutes: [
    /^\/api\/templates\/.+$/,
    /^\/api\/content\/.+$/
]

3. RoutePattern Objects (with HTTP method filtering)

excludeRoutes: [
    {
        path: "/api/templates/*",
        methods: ["POST", "PUT"]  // Only exclude for POST and PUT requests
    },
    {
        path: "/api/content/*",
        methods: ["POST"]         // Only exclude for POST requests
    }
]

Available Security Modules #

You can configure route-based rules for the following security modules:

xss - Cross-Site Scripting protection
sqlInjection - SQL Injection detection
pathTraversal - Path Traversal detection
commandInjection - Command Injection detection
xxe - XML External Entity protection
ldapInjection - LDAP Injection detection

Use Cases #

1. Template/Content Routes #

Exclude routes that handle template data or user content that may contain legitimate URLs:

routeConfig: {
    pathTraversal: {
        excludeRoutes: [
            "/api/templates/*",
            "/api/pages/*",
            "/api/content/*"
        ]
    }
}

2. Database Routes Only #

Apply SQL injection detection only to routes that interact with databases:

routeConfig: {
    sqlInjection: {
        includeRoutes: [
            "/api/db/*",
            "/api/query/*",
            "/api/search/*"
        ]
    }
}

3. Mixed Approach #

Combine different strategies for different security modules:

routeConfig: {
    pathTraversal: {
        excludeRoutes: ["/api/templates/*", "/api/content/*"]
    },
    sqlInjection: {
        includeRoutes: ["/api/db/*"]
    },
    xss: {
        excludeRoutes: ["/api/trusted/*"]
    }
}

4. Method-Specific Rules #

Apply security rules only for specific HTTP methods:

routeConfig: {
    pathTraversal: {
        excludeRoutes: [
            {
                path: "/api/templates/*",
                methods: ["POST", "PUT", "PATCH"]  // Only exclude for write operations
            }
        ]
    }
}

How It Works #

Exclude Routes (Blacklist) #

When you specify excludeRoutes:

Security module applies to all routes by default
Routes matching the exclude patterns are skipped
All other routes are protected

pathTraversal: {
    excludeRoutes: ["/api/templates/*"]
}
// Result: Path traversal detection applies everywhere EXCEPT /api/templates/*

Include Routes (Whitelist) #

When you specify includeRoutes:

Security module applies only to matching routes
All other routes are skipped
More restrictive than excludeRoutes

sqlInjection: {
    includeRoutes: ["/api/db/*"]
}
// Result: SQL injection detection applies ONLY to /api/db/*

Priority #

If both includeRoutes and excludeRoutes are specified:

includeRoutes takes priority
excludeRoutes is ignored

Migration Guide #

Before (Global Security) #

const app = createServer({
    security: {
        enabled: true,
        pathTraversal: true,
        sqlInjection: true
    }
});
// Problem: All routes protected, causing false positives

After (Route-Based Security) #

const app = createServer({
    security: {
        enabled: true,
        pathTraversal: true,
        sqlInjection: true,
        
        routeConfig: {
            pathTraversal: {
                excludeRoutes: ["/api/templates/*", "/api/content/*"]
            }
        }
    }
});
// Solution: Template routes excluded from path traversal detection

Best Practices #

Be Specific: Use specific route patterns to minimize security gaps

// Good
excludeRoutes: ["/api/templates/create", "/api/templates/update"]

// Less secure
excludeRoutes: ["/api/*"]

Use Whitelist When Possible: For sensitive modules like SQL injection, use includeRoutes
```
sqlInjection: {
    includeRoutes: ["/api/db/*", "/api/query/*"]
}
```

Document Your Exclusions: Add comments explaining why routes are excluded

routeConfig: {
    pathTraversal: {
        // Template data contains legitimate URLs like /signup, #demo
        excludeRoutes: ["/api/templates/*"]
    }
}

Test Thoroughly: Verify that excluded routes still handle malicious input safely through other means
Regular Review: Periodically review your route configurations to ensure they're still appropriate

Performance Considerations #

Route matching is performed using optimized regex patterns
Minimal performance impact (< 1ms per request)
Patterns are compiled once during initialization

Troubleshooting #

Issue: Security module still blocking excluded route #

Check:

Route pattern matches the actual request path
HTTP method is included (if using RoutePattern objects)
Configuration is properly nested under security.routeConfig

Debug:

// Add logging to verify route matching
console.log('Request path:', req.path);
console.log('Request method:', req.method);

Issue: Security not applied to included routes #

Check:

includeRoutes patterns are correct
No typos in route paths
Security module is enabled globally

Example: Complete Configuration #

import { createServer } from "xypriss";

const app = createServer({
    server: {
        port: 3000,
        host: "localhost"
    },
    
    security: {
        enabled: true,
        level: "enhanced",
        
        // Enable security modules
        xss: true,
        sqlInjection: true,
        pathTraversal: true,
        commandInjection: true,
        
        // Configure route-based security
        routeConfig: {
            // Exclude template routes from path traversal
            pathTraversal: {
                excludeRoutes: [
                    "/api/templates/*",
                    "/api/content/*",
                    "/api/pages/*"
                ]
            },
            
            // Only check SQL injection on database routes
            sqlInjection: {
                includeRoutes: [
                    "/api/db/*",
                    "/api/query/*",
                    "/api/search/*"
                ]
            },
            
            // Exclude trusted content from XSS
            xss: {
                excludeRoutes: [
                    {
                        path: "/api/admin/content/*",
                        methods: ["POST", "PUT"]
                    }
                ]
            }
        }
    }
});

app.start();

Changelog #

Version 4.5.12+ #

Added routeConfig option to SecurityConfig
Added SecurityModuleRouteConfig interface
Added RoutePattern interface for method-specific rules
Implemented route matching logic in SecurityMiddleware
Added support for wildcards, regex, and exact path matching

Support #

For issues or questions about route-based security configuration:

GitHub Issues: XyPriss Issues
Documentation: XyPriss Docs

Introduction to XyPriss routing