gitea-admin/gh-christianlouis-docuelevate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: change security headers default to disabled

Browse Source 
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>
This commit is contained in:
copilot-swe-agent[bot]
2026-02-10 14:22:47 +00:00
parent 20a0e43a11
commit 956f0c0c2a
5 changed files with 77 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env.demo
+11 -10
View File
@@ -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
SECURITY_AUDIT.md
+23 -23
View File
@@ -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
app/config.py
+4 -4
View File
@@ -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
docs/ConfigurationGuide.md
+9 -9
View File
@@ -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
docs/DeploymentGuide.md
+30 -25
View File
@@ -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)