Modern Python library for HTTP security headers with safe defaults, configurable presets, and first-class ASGI/WSGI middleware (FastAPI, Django, Flask, Shiny, and more).
secure
Define HTTP security headers once. Apply them consistently across Python web apps.
secure provides a small, dependency-free API for configuring modern security headers across common Python web frameworks through ASGI middleware, WSGI middleware, or framework response hooks.
Use it when you want to avoid copy-pasted header strings spread across handlers, hooks, and middleware.
Quick links: Quick start · Headers · Middleware
Why use secure
Setting headers manually is fine for one endpoint. It gets harder to review when values are copied across routes, response hooks, reverse-proxy settings, and different framework integrations.
secure helps you:
- Keep one
Securepolicy object instead of scattered header strings - Apply the same policy through ASGI middleware, WSGI middleware, or response hooks
- Start with practical presets, then customize headers for your application
- Use builders for complex headers such as Content Security Policy and Permissions Policy
- Make duplicate handling, header overwrites, and validation explicit
Installation
uv add secure
or
pip install secureQuick start
FastAPI / ASGI middleware
Use middleware when you can attach secure once and cover the whole application.
from fastapi import FastAPI
from secure import Secure
from secure.middleware import SecureASGIMiddleware
app = FastAPI() secureheaders = Secure.withdefault_headers()
app.addmiddleware(SecureASGIMiddleware, secure=secureheaders)
Response hooks and handlers
Use the same policy object in framework hooks, middleware callbacks, or handlers that expose a response object with headers support.
from secure import Secure
secureheaders = Secure.withdefault_headers()
secureheaders.setheaders(response)
or
await secureheaders.setheaders_async(response)Secure.withdefaultheaders() maps to Preset.BALANCED, a practical default designed to be customized.
What headers are applied by default
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin
Content-Security-Policy: default-src 'self'; base-uri 'self'; font-src 'self' https: data:; form-action 'self'; frame-ancestors 'self'; img-src 'self' data:; object-src 'none'; script-src 'self'; script-src-attr 'none'; style-src 'self' https: 'unsafe-inline'; upgrade-insecure-requests
Strict-Transport-Security: max-age=31536000; includeSubDomains
Permissions-Policy: geolocation=(), microphone=(), camera=()
Referrer-Policy: strict-origin-when-cross-origin
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGINThis preset reflects modern browser guidance from MDN and OWASP. It reduces cross-origin risk, prevents MIME sniffing, and provides a conservative Content Security Policy you can extend.
The default CSP avoids unsafe script execution by default, but CSP is context-sensitive. Interactive apps, dashboards, CDNs, analytics, embedded content, or other third-party integrations may require additional configuration.
Presets
from secure import Preset, Secure
Secure.from_preset(Preset.BALANCED) Secure.from_preset(Preset.BASIC) Secure.from_preset(Preset.STRICT)
- BALANCED: practical default for many applications
- BASIC: Helmet-style compatibility
- STRICT: tighter CSP and isolation
Middleware
secure provides both ASGI and WSGI middleware.
- Overwrites headers by default
- Allows controlled duplication via
multi_ok - Only modifies HTTP responses in ASGI apps
ASGI
from secure import Secure
from secure.middleware import SecureASGIMiddleware
secureheaders = Secure.withdefault_headers() app = SecureASGIMiddleware(app, secure=secure_headers)
WSGI
from secure import Secure
from secure.middleware import SecureWSGIMiddleware
secureheaders = Secure.withdefault_headers() app = SecureWSGIMiddleware(app, secure=secure_headers)
Django example
from secure import Secure
class SecureHeadersMiddleware: def init(self, get_response): self.getresponse = getresponse self.secure = Secure.withdefaultheaders()
def call(self, request): response = self.get_response(request) self.secure.set_headers(response) return response
Framework integration examples
These examples show common integration paths. See the full framework integration guide for additional frameworks and notes about first-class middleware versus minimal fallback examples.
FastAPI
from secure.middleware import SecureASGIMiddleware
app.addmiddleware(SecureASGIMiddleware, secure=secureheaders)
Flask
@app.after_request
def addsecurityheaders(response):
secureheaders.setheaders(response)
return responseShiny for Python
from shiny import App
from secure.middleware import SecureASGIMiddleware
app = SecureASGIMiddleware(App(), secure=secure_headers)
Interactive apps often need CSP configuration for their script, style, and asset loading patterns.
Policy builders
Content Security Policy
from secure.headers import ContentSecurityPolicy
csp = ( ContentSecurityPolicy() .default_src("'self'") .script_src("'self'", "cdn.example.com") )
Permissions Policy
from secure.headers import PermissionsPolicy
permissions = ( PermissionsPolicy() .geolocation("'self'") .camera("'none'") )
Header pipeline and validation
Use the optional pipeline when you need stricter control:
secure_headers = (
Secure.withdefaultheaders()
.allowlist_headers(...)
.deduplicate_headers(...)
.validateandnormalize_headers(...)
)This makes header allowlists, deduplication, normalization, and validation explicit instead of leaving those choices spread across application code.
Requirements
- Python 3.10+
- No external dependencies
Documentation
Read the full documentation.
Learn more
License
MIT License
Contributing
Issues and pull requests are welcome.
Acknowledgements
Built using guidance from MDN and OWASP secure headers recommendations.
