From 956f0c0c2a1fc63159bf2a02a0bc09e5b43700e0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 10 Feb 2026 14:22:47 +0000 Subject: [PATCH] refactor: change security headers default to disabled Security headers are now disabled by default since most deployments use a reverse proxy (Traefik, Nginx) that already adds these headers. Enable with SECURITY_HEADERS_ENABLED=true for direct deployments. Changes: - Set security_headers_enabled default to False in app/config.py - Update all documentation to reflect new default - Comment out examples in .env.demo (now showing disabled state) - Update SECURITY_AUDIT.md to reflect reverse proxy as default deployment - Tests still pass (3 passed, 8 skipped as expected with headers disabled) Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com> --- .env.demo | 21 ++++++++------- SECURITY_AUDIT.md | 46 +++++++++++++++---------------- app/config.py | 8 +++--- docs/ConfigurationGuide.md | 18 ++++++------- docs/DeploymentGuide.md | 55 +++++++++++++++++++++----------------- 5 files changed, 77 insertions(+), 71 deletions(-) diff --git a/.env.demo b/.env.demo index 3d41784e..649f6d73 100644 --- a/.env.demo +++ b/.env.demo @@ -22,29 +22,30 @@ MAX_UPLOAD_SIZE=1073741824 # MAX_SINGLE_FILE_SIZE=104857600 # **Security Headers** (see SECURITY_AUDIT.md and docs/DeploymentGuide.md) -# Enable security headers middleware in the application -# Set to false if deploying behind a reverse proxy (Traefik, Nginx, etc.) that already adds these headers -SECURITY_HEADERS_ENABLED=true +# Disabled by default since most deployments use a reverse proxy (Traefik, Nginx, etc.) +# that already adds these headers. Set to true only if deploying directly without a reverse proxy. +# SECURITY_HEADERS_ENABLED=false +# If you enable security headers, you can also configure individual headers: # Strict-Transport-Security (HSTS) - Forces HTTPS connections # Only effective when served over HTTPS. Disable if not using HTTPS or if proxy adds this header -SECURITY_HEADER_HSTS_ENABLED=true -SECURITY_HEADER_HSTS_VALUE="max-age=31536000; includeSubDomains" +# SECURITY_HEADER_HSTS_ENABLED=true +# SECURITY_HEADER_HSTS_VALUE="max-age=31536000; includeSubDomains" # Content-Security-Policy (CSP) - Controls resource loading # Customize based on your application's resource loading needs # Default allows self-hosted resources, inline scripts/styles, and external images -SECURITY_HEADER_CSP_ENABLED=true -SECURITY_HEADER_CSP_VALUE="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:;" +# SECURITY_HEADER_CSP_ENABLED=true +# SECURITY_HEADER_CSP_VALUE="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:;" # X-Frame-Options - Prevents clickjacking attacks # Options: DENY (no framing), SAMEORIGIN (same origin framing only), ALLOW-FROM uri -SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true -SECURITY_HEADER_X_FRAME_OPTIONS_VALUE="DENY" +# SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true +# SECURITY_HEADER_X_FRAME_OPTIONS_VALUE="DENY" # X-Content-Type-Options - Prevents MIME sniffing # Always set to 'nosniff' when enabled -SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true +# SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true # **Authentication** AUTH_ENABLED=true diff --git a/SECURITY_AUDIT.md b/SECURITY_AUDIT.md index eafd94e9..08097901 100644 --- a/SECURITY_AUDIT.md +++ b/SECURITY_AUDIT.md @@ -245,8 +245,8 @@ ftp = ftplib.FTP() # nosec B321 - Plaintext FTP intentional when configured - ✅ ProxyHeadersMiddleware for reverse proxy setup (X-Forwarded-* headers) - ✅ SessionMiddleware with strong secret validation - ✅ **Security headers middleware implemented** - Configurable HSTS, CSP, X-Frame-Options, X-Content-Type-Options ([#174](https://github.com/christianlouis/DocuElevate/issues/174)) - - Enabled by default for direct deployment - - Configurable to disable when reverse proxy handles headers + - Disabled by default (typical deployment uses reverse proxy that adds headers) + - Can be enabled for direct deployment without reverse proxy - Individual header control and customization - Documented in DeploymentGuide.md and ConfigurationGuide.md - ⏳ **TODO:** Implement proper CORS configuration (currently not configured) ([#175](https://github.com/christianlouis/DocuElevate/issues/175)) @@ -656,27 +656,12 @@ SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true ### Deployment Scenarios -#### Direct Deployment (No Reverse Proxy) +#### Reverse Proxy Deployment (Traefik, Nginx, etc.) - DEFAULT -Security headers are **enabled by default** for direct deployments: +**Most deployments use a reverse proxy**, which is why security headers are **disabled by default** in DocuElevate. The reverse proxy should add these headers. ```bash -# .env configuration -SECURITY_HEADERS_ENABLED=true -SECURITY_HEADER_HSTS_ENABLED=true -SECURITY_HEADER_CSP_ENABLED=true -SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true -SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true -``` - -All headers are added by the application middleware. - -#### Reverse Proxy Deployment (Traefik, Nginx, etc.) - -When deploying behind a reverse proxy that already adds security headers, **disable the middleware** to avoid duplication: - -```bash -# .env configuration +# .env configuration (or omit - this is the default) SECURITY_HEADERS_ENABLED=false ``` @@ -697,13 +682,28 @@ add_header X-Frame-Options "DENY" always; add_header X-Content-Type-Options "nosniff" always; ``` +#### Direct Deployment (No Reverse Proxy) + +If deploying directly without a reverse proxy, **enable security headers**: + +```bash +# .env configuration +SECURITY_HEADERS_ENABLED=true +SECURITY_HEADER_HSTS_ENABLED=true +SECURITY_HEADER_CSP_ENABLED=true +SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true +SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true +``` + +All headers are added by the application middleware. + ### Configuration Options All security headers are configurable via environment variables: | Setting | Purpose | Default | |---------|---------|---------| -| `SECURITY_HEADERS_ENABLED` | Master enable/disable | `true` | +| `SECURITY_HEADERS_ENABLED` | Master enable/disable | `false` | | `SECURITY_HEADER_HSTS_ENABLED` | Enable HSTS | `true` | | `SECURITY_HEADER_HSTS_VALUE` | HSTS configuration | `max-age=31536000; includeSubDomains` | | `SECURITY_HEADER_CSP_ENABLED` | Enable CSP | `true` | @@ -738,8 +738,8 @@ All security headers are configurable via environment variables: 1. **Defense in Depth:** Multiple layers of browser-side security 2. **Flexible Configuration:** Adapts to different deployment scenarios 3. **Industry Best Practices:** Follows OWASP security recommendations -4. **Easy Deployment:** Works out-of-the-box with sensible defaults -5. **Reverse Proxy Compatible:** Can be disabled when proxy handles headers +4. **Smart Defaults:** Disabled by default for typical reverse proxy deployments +5. **Reverse Proxy Compatible:** Works seamlessly with Traefik, Nginx, etc. 6. **Well Documented:** Comprehensive documentation for all scenarios ### Testing diff --git a/app/config.py b/app/config.py index c641e9c0..d08dea76 100644 --- a/app/config.py +++ b/app/config.py @@ -175,11 +175,11 @@ class Settings(BaseSettings): ) # Security Headers Configuration (see SECURITY_AUDIT.md and docs/DeploymentGuide.md) - # When deploying behind a reverse proxy (Traefik, Nginx, etc.), disable these headers - # if your proxy already adds them to avoid duplication + # Disabled by default since most deployments use a reverse proxy (Traefik, Nginx, etc.) + # that already adds these headers. Enable if deploying directly without a reverse proxy. security_headers_enabled: bool = Field( - default=True, - description="Enable security headers middleware. Set to False if reverse proxy handles headers.", + default=False, + description="Enable security headers middleware. Set to True if deploying without reverse proxy.", ) # Strict-Transport-Security (HSTS) - Forces HTTPS connections diff --git a/docs/ConfigurationGuide.md b/docs/ConfigurationGuide.md index 5a8b503a..3498621c 100644 --- a/docs/ConfigurationGuide.md +++ b/docs/ConfigurationGuide.md @@ -100,13 +100,13 @@ DocuElevate can monitor multiple IMAP mailboxes for document attachments. Each m ### Security Headers -DocuElevate supports HTTP security headers to improve browser-side security. These headers are enabled by default but should be disabled if your reverse proxy (Traefik, Nginx, etc.) already adds them. See [Deployment Guide - Security Headers](DeploymentGuide.md#security-headers) for detailed configuration examples. +DocuElevate supports HTTP security headers to improve browser-side security. **These headers are disabled by default** since most deployments use a reverse proxy (Traefik, Nginx, etc.) that already adds them. Enable only if deploying directly without a reverse proxy. See [Deployment Guide - Security Headers](DeploymentGuide.md#security-headers) for detailed configuration examples. #### Master Control | **Variable** | **Description** | **Default** | |-----------------------------|-------------------------------------------------------------------------|-------------| -| `SECURITY_HEADERS_ENABLED` | Enable/disable security headers middleware. Set to `false` if reverse proxy handles headers. | `true` | +| `SECURITY_HEADERS_ENABLED` | Enable/disable security headers middleware. Set to `true` if deploying without reverse proxy. | `false` | #### Strict-Transport-Security (HSTS) @@ -173,9 +173,15 @@ Prevents browsers from MIME-sniffing responses away from the declared content-ty #### Configuration Examples +**Reverse Proxy Deployment (Default - Traefik, Nginx):** +```bash +# Headers disabled by default - reverse proxy handles them +# SECURITY_HEADERS_ENABLED=false # Can be omitted +``` + **Direct Deployment (No Reverse Proxy):** ```bash -# Enable all security headers (default) +# Enable all security headers SECURITY_HEADERS_ENABLED=true SECURITY_HEADER_HSTS_ENABLED=true SECURITY_HEADER_CSP_ENABLED=true @@ -183,12 +189,6 @@ SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true ``` -**Behind Reverse Proxy (Traefik, Nginx):** -```bash -# Disable security headers (let proxy handle them) -SECURITY_HEADERS_ENABLED=false -``` - **Custom Configuration:** ```bash # Enable headers but customize values diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index 0d030d35..5f5a42c5 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -56,7 +56,7 @@ Access the web interface at `http://localhost:8000` and the API documentation at ### Security Headers -DocuElevate includes built-in support for HTTP security headers to improve browser-side security. These headers are enabled by default but can be configured based on your deployment scenario. +DocuElevate includes built-in support for HTTP security headers to improve browser-side security. **These headers are disabled by default** since most deployments use a reverse proxy (Traefik, Nginx, etc.) that already adds these headers. #### Supported Security Headers @@ -65,31 +65,12 @@ DocuElevate includes built-in support for HTTP security headers to improve brows - **X-Frame-Options**: Prevents the page from being loaded in frames (clickjacking protection) - **X-Content-Type-Options**: Prevents browsers from MIME-sniffing responses -#### Direct Deployment (No Reverse Proxy) +#### Reverse Proxy Deployment (Traefik, Nginx, etc.) - DEFAULT -If you're running DocuElevate directly without a reverse proxy, security headers are enabled by default: +**Most deployments use a reverse proxy**, which is why security headers are disabled by default in DocuElevate. The reverse proxy should add these headers. ```bash -# In .env file -SECURITY_HEADERS_ENABLED=true -SECURITY_HEADER_HSTS_ENABLED=true -SECURITY_HEADER_CSP_ENABLED=true -SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true -SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true -``` - -**Note**: HSTS only works when serving content over HTTPS. If using HTTP for development, you can disable it: - -```bash -SECURITY_HEADER_HSTS_ENABLED=false -``` - -#### Reverse Proxy Deployment (Traefik, Nginx, etc.) - -When deploying behind a reverse proxy that adds security headers, **disable the built-in headers** to avoid duplication: - -```bash -# In .env file +# In .env file (or omit - this is the default) SECURITY_HEADERS_ENABLED=false ``` @@ -146,11 +127,35 @@ server { } ``` -Then set `SECURITY_HEADERS_ENABLED=false` in your `.env` file. +Then keep `SECURITY_HEADERS_ENABLED=false` in your `.env` file (or omit it, as this is the default). + +#### Direct Deployment (No Reverse Proxy) + +If you're running DocuElevate **directly without a reverse proxy**, enable security headers: + +```bash +# In .env file +SECURITY_HEADERS_ENABLED=true +``` + +You can also configure individual headers: + +```bash +SECURITY_HEADER_HSTS_ENABLED=true +SECURITY_HEADER_CSP_ENABLED=true +SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true +SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true +``` + +**Note**: HSTS only works when serving content over HTTPS. If using HTTP for development, you can disable it: + +```bash +SECURITY_HEADER_HSTS_ENABLED=false +``` #### Customizing Security Headers -You can customize individual header values in your `.env` file: +If you enable security headers, you can customize individual header values in your `.env` file: ```bash # Customize HSTS (e.g., shorter duration for testing)