Secure Headers for Python Web Frameworks

1.0.1 · active · verified Sat Apr 11

Secure is a lightweight Python library designed to effortlessly add essential HTTP security headers to web applications. It supports multiple frameworks like Flask, FastAPI, and Django with a unified, modern API. The library is actively maintained, with the current stable version being 1.0.1, and a 2.0.0 release candidate introducing significant enhancements and API changes.

Warnings

breaking Version 2.0.0 (currently in Release Candidate) introduces a significant API overhaul, including a new preset model (e.g., `Preset.BALANCED`), first-class ASGI/WSGI middleware, and changes to the behavior of `with_default_headers()`. Review the migration guide when upgrading to 2.x.x.
Fix: Consult the official migration guide (e.g., `docs/migration.md` on GitHub) to adapt to the new API and preset models. Consider using `SecureASGIMiddleware` or `SecureWSGIMiddleware` for framework-agnostic integration.
breaking The library underwent a complete API redesign in v1.0.0 from its 0.x.x versions. Old classes like `SecureHeaders` and `SecureCookie` were removed or replaced. Additionally, v1.0.0 requires Python 3.10+.
Fix: Rewrite code using the new `secure.Secure` class and its methods. Ensure your project is running on Python 3.10 or newer. Cookie management functionality has been removed; you'll need a different library or custom implementation for secure cookies.
breaking The `SecureCookie` class and all cookie management features were removed starting from version 0.3.0 and are not present in 1.x.x or 2.x.x. The library now exclusively focuses on HTTP security headers.
Fix: Remove any reliance on `secure.SecureCookie`. Implement secure cookie handling using your web framework's native capabilities or a dedicated cookie security library.
gotcha The `Feature-Policy` HTTP header was renamed to `Permissions-Policy` as part of a specification update. `secure.py` adopted this change in v0.3.0/v1.0.0, so older configurations might be using the deprecated name.
Fix: Update any custom header configurations or policy builders to use `PermissionsPolicy` instead of `FeaturePolicy`.

Install

pip install secure Install stable version

Imports

Secure
```
from secure import Secure
```
Main class for applying security headers.
ContentSecurityPolicy
```
from secure import ContentSecurityPolicy
```
For building custom CSP policies.
PermissionsPolicy
```
from secure import PermissionsPolicy
```
For building custom Permissions Policy headers.
SecureWSGIMiddleware
```
from secure.middleware import SecureWSGIMiddleware
```
Available from v1.x.x, official middleware path for WSGI frameworks (e.g., Flask, Django) in v2.0.0rc1.
SecureASGIMiddleware
```
from secure.middleware import SecureASGIMiddleware
```
Available from v1.x.x, official middleware path for ASGI frameworks (e.g., FastAPI, Starlette) in v2.0.0rc1.
SecureHeaders
```
from secure import Secure
```
The `SecureHeaders` class was part of the 0.x.x API and was removed in v1.0.0. Use `secure.Secure` instead.
SecureCookie
```
N/A (Functionality removed)
```
Cookie management functionality (`SecureCookie` class) was removed entirely in v0.3.0/v1.0.0. This is no longer supported.

Quickstart

This Flask example demonstrates how to integrate `secure.py` by applying default security headers to every response using an `after_request` hook. The `Secure.with_default_headers()` method provides a baseline set of recommended headers.

import os
from flask import Flask, Response
from secure import Secure

app = Flask(__name__)

# Instantiate Secure with default headers (or customize)
# For v2.0.0rc1 and later, consider `Secure.with_preset(Preset.BALANCED)` or middleware.
secure_headers = Secure.with_default_headers()

@app.after_request
def add_security_headers(response: Response):
    secure_headers.set_headers(response)
    return response

@app.route("/")
def home():
    return "Hello, secure world!"

if __name__ == "__main__":
    # In a real application, use a production-ready WSGI server like Gunicorn
    app.run(debug=True)

view raw JSON →