Quick Start

from nexios import NexiosApp
from nexios.middleware.security import SecurityMiddleware

app = NexiosApp()

# Basic usage with defaults
app.add_middleware(SecurityMiddleware())

# Advanced configuration
app.add_middleware(
    SecurityMiddleware(
        csp_enabled=True,
        hsts_enabled=True,
        ssl_redirect=True,
        frame_options="DENY"
    )
)

Security Features

1. Content Security Policy (CSP)

CSP

Content Security Policy is a powerful security feature that helps prevent XSS attacks by controlling which resources can be loaded.

security = SecurityMiddleware(
    csp_enabled=True,
    csp_policy={
        'default-src': ["'self'"],
        'script-src': ["'self'", "'unsafe-inline'"],
        'style-src': ["'self'", 'https://fonts.googleapis.com'],
        'img-src': ["'self'", 'data:', 'https:'],
        'font-src': ["'self'", 'https://fonts.gstatic.com'],
        'connect-src': ["'self'", 'https://api.example.com']
    },
    csp_report_only=False  # Set to True for testing
)

2. Cross-Origin Resource Sharing (CORS)

CORS Configuration

Carefully configure CORS settings to balance security and functionality.

security = SecurityMiddleware(
    cors_enabled=True,
    allowed_origins=["https://example.com"],
    allowed_methods=["GET", "POST"],
    allowed_headers=["Content-Type", "Authorization"],
    expose_headers=["X-Custom-Header"],
    max_age=3600,
    allow_credentials=True
)

3. HTTP Strict Transport Security (HSTS)

security = SecurityMiddleware(
    hsts_enabled=True,
    hsts_max_age=31536000,  # 1 year
    hsts_include_subdomains=True,
    hsts_preload=True
)

4. XSS Protection

security = SecurityMiddleware(
    xss_protection=True,
    xss_mode="block"  # or "filter"
)

5. Frame Options

security = SecurityMiddleware(
    frame_options="DENY",  # or "SAMEORIGIN"
    # Or allow specific origin:
    frame_options_allow_from="https://trusted.com"
)

6. SSL/HTTPS Redirect

security = SecurityMiddleware(
    ssl_redirect=True,
    ssl_host="secure.example.com",
    ssl_permanent=True  # 301 redirect
)

7. Cross-Origin Policies

security = SecurityMiddleware(
    cross_origin_opener_policy="same-origin",
    cross_origin_embedder_policy="require-corp",
    cross_origin_resource_policy="same-origin"
)

8. Permissions Policy

security = SecurityMiddleware(
    permissions_policy={
        'camera': "'none'",
        'microphone': "'self'",
        'geolocation': ["'self'", "https://maps.example.com"],
        'payment': "'self'"
    }
)

9. Cache Control

security = SecurityMiddleware(
    cache_control="no-store, no-cache, must-revalidate, proxy-revalidate",
    clear_site_data=["cache", "cookies", "storage"]
)

10. Expect-CT

security = SecurityMiddleware(
    expect_ct=True,
    expect_ct_max_age=86400,
    expect_ct_enforce=True,
    expect_ct_report_uri="https://example.com/report"
)

Complete Configuration Example

Full Configuration

from nexios import NexiosApp
from nexios.middleware import SecurityMiddleware

app = NexiosApp()

security = SecurityMiddleware(
    # Content Security Policy
    csp_enabled=True,
    csp_policy={
        'default-src': ["'self'"],
        'script-src': ["'self'", "'unsafe-inline'"],
        'style-src': ["'self'", 'https://fonts.googleapis.com'],
        'img-src': ["'self'", 'data:', 'https:'],
        'connect-src': ["'self'", 'https://api.example.com']
    },
    csp_report_only=False,

    # CORS
    cors_enabled=True,
    allowed_origins=["https://example.com"],
    allowed_methods=["GET", "POST", "PUT", "DELETE"],
    allowed_headers=["*"],
    expose_headers=["X-Custom-Header"],
    max_age=3600,
    allow_credentials=True,

    # HSTS
    hsts_enabled=True,
    hsts_max_age=31536000,
    hsts_include_subdomains=True,
    hsts_preload=True,

    # XSS Protection
    xss_protection=True,
    xss_mode="block",

    # Frame Options
    frame_options="DENY",

    # Content Type Options
    content_type_options=True,

    # Referrer Policy
    referrer_policy="strict-origin-when-cross-origin",

    # SSL/HTTPS
    ssl_redirect=True,
    ssl_host="secure.example.com",
    ssl_permanent=True,

    # Cache Control
    cache_control="no-store, no-cache",
    clear_site_data=["cache", "cookies"],

    # Cross-Origin Policies
    cross_origin_opener_policy="same-origin",
    cross_origin_embedder_policy="require-corp",
    cross_origin_resource_policy="same-origin",

    # Expect-CT
    expect_ct=True,
    expect_ct_max_age=86400,
    expect_ct_enforce=True,

    # Trusted Types
    trusted_types=True,
    trusted_types_policies=["default", "escape"],

    # Server
    hide_server=True
)

app.add_middleware(security)

Best Practices

Production Settings

Production Security

For production environments, we recommend:

1. Enable HTTPS redirect
2. Enable HSTS
3. Set strict CSP rules
4. Enable all security headers
5. Configure proper CORS settings

security = SecurityMiddleware(
    # Force HTTPS
    ssl_redirect=True,
    ssl_permanent=True,
    
    # Strict CSP
    csp_enabled=True,
    csp_policy={
        'default-src': ["'self'"],
        'script-src': ["'self'"],
        'object-src': ["'none'"],
        'base-uri': ["'self'"],
        'frame-ancestors': ["'none'"]
    },
    
    # HSTS
    hsts_enabled=True,
    hsts_max_age=31536000,
    hsts_include_subdomains=True,
    
    # Other Security Headers
    frame_options="DENY",
    content_type_options=True,
    referrer_policy="strict-origin-when-cross-origin",
    
    # Hide Server Info
    hide_server=True
)

Development Settings

Development Mode

For development, you might want to relax some settings:

security = SecurityMiddleware(
    # Disable HTTPS redirect
    ssl_redirect=False,
    
    # Relaxed CSP for development tools
    csp_policy={
        'default-src': ["'self'"],
        'script-src': ["'self'", "'unsafe-inline'", "'unsafe-eval'"],
        'style-src': ["'self'", "'unsafe-inline'"],
        'connect-src': ["'self'", "ws://localhost:*"]
    },
    
    # Allow all origins in development
    cors_enabled=True,
    allowed_origins=["*"],
    
    # Disable HSTS in development
    hsts_enabled=False
)

Header Reference

Header	Purpose	Default
Content-Security-Policy	Control resource loading	self only
X-Frame-Options	Prevent clickjacking	DENY
X-XSS-Protection	XSS filter	1; mode=block
Strict-Transport-Security	Force HTTPS	max-age=31536000
X-Content-Type-Options	Prevent MIME sniffing	nosniff
Referrer-Policy	Control referrer info	strict-origin-when-cross-origin
Permissions-Policy	Control browser features	Various restrictions
Clear-Site-Data	Clear browser data	None
Cross-Origin-*-Policy	Cross-origin isolation	same-origin

Common Scenarios

API Server

security = SecurityMiddleware(
    cors_enabled=True,
    allowed_origins=["https://api.example.com"],
    allowed_methods=["GET", "POST", "PUT", "DELETE"],
    allowed_headers=["Authorization", "Content-Type"],
    expose_headers=["X-Request-ID"],
    allow_credentials=True
)

Static Website

security = SecurityMiddleware(
    csp_policy={
        'default-src': ["'self'"],
        'img-src': ["'self'", "data:", "https:"],
        'style-src': ["'self'", "https://fonts.googleapis.com"],
        'font-src': ["'self'", "https://fonts.gstatic.com"]
    },
    frame_options="DENY",
    cache_control="public, max-age=31536000"
)

WebSocket Server

security = SecurityMiddleware(
    cors_enabled=True,
    allowed_origins=["https://example.com"],
    csp_policy={
        'default-src': ["'self'"],
        'connect-src': ["'self'", "wss://ws.example.com"]
    }
)

Troubleshooting

Common Issues

1. CSP Blocking Resources: Check browser console for CSP violations
2. CORS Issues: Verify allowed origins and methods
3. HSTS Problems: Cannot be easily undone, use carefully
4. Mixed Content: Ensure all resources use HTTPS

More Information

• MDN Web Security
• OWASP Security Headers
• Content Security Policy
• Report URI