A small, focused library for adding modern security headers to Python web applications.

Security headers are one of the simplest ways to raise the security bar for a web application, but they are often applied inconsistently across frameworks and deployments.

secure gives you a single, modern, well typed API for configuring and applying HTTP security headers in Python. It focuses on:

• Good defaults that are safe to adopt.
• A small, explicit API instead of a large framework.
• Support for both synchronous and asynchronous response objects.
• Framework agnostic integration so you can use the same configuration everywhere.

The package is published on PyPI as secure and imported with:

• Apply essential security headers with a few lines of code.
• Share one configuration across multiple frameworks and applications.
• Start from secure presets, then customize as your needs grow.
• Keep header logic out of your views and handlers.
• Use one library for FastAPI, Starlette, Flask, Django, and more.
• Rely on modern Python 3.10+ features and full type hints for better editor support.

If you want your app to ship with a strong security baseline without pulling in a heavyweight dependency, secure is designed for you.

secure integrates with a range of popular Python web frameworks. The core API is framework independent, and each framework uses the same Secure object and methods.

• Secure headers
  Apply headers like Strict-Transport-Security, Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, and more.

• Presets with secure defaults
  Start from opinionated presets like Preset.BASIC and Preset.STRICT, then customize as needed.

• Policy builders
  Compose complex policies such as CSP and Permissions Policy through a fluent API.

• Framework agnostic
  Works with sync and async response objects and does not depend on any single framework.

• Zero external dependencies
  Easy to audit and suitable for security sensitive environments.

• Modern Python design
  Uses Python 3.10+ features and full type hints so your editor and type checker can help you.

• Python 3.10 or higher

  secure targets modern Python and is currently tested on Python 3.10 through 3.13.

  It uses features introduced in Python 3.10, including:

  • Union type operator (|) for cleaner type annotations.
  • Structural pattern matching (match).
  • Improved typing and annotations.
  • functools.cached_property for efficient lazy computation.

  If you need support for Python 3.6 through 3.9, use version 0.3.0 of the library.

• Dependencies

  This library has no external dependencies outside of the Python standard library.

You can install secure with your preferred Python package manager.

The core entry point is the Secure class. A typical simple setup looks like this:

Secure.with_default_headers() is equivalent to Secure.from_preset(Preset.BALANCED), the recommended default profile.

set_headers and set_headers_async both operate on a response object that either:

• Exposes a set_header(name, value) method, or
• Exposes a mutable headers mapping that supports item assignment.

If your framework uses a different contract, see the framework specific guides or use header_items() to apply headers manually.

secure.middleware re-exports SecureWSGIMiddleware and SecureASGIMiddleware. Each middleware accepts a Secure instance (defaulting to Secure.with_default_headers()), overwrites headers by default, and only appends duplicates when a normalized name is included in multi_ok (the default secure.MULTI_OK includes Content-Security-Policy).

Wrap any WSGI stack with SecureWSGIMiddleware, and pass a configured Secure instance if you need a custom CSP or additional headers.

For Django, apply the headers through a middleware class since Django's middleware pipeline wraps requests and responses rather than the raw WSGI callable:

Register the class in your MIDDLEWARE setting to enforce security headers on every response.

SecureASGIMiddleware modifies only HTTP scopes (WebSocket messages pass through untouched). Mount it manually or via FastAPI's add_middleware, and pass any Secure instance if you need to adjust the defaults.

If you need to tailor the CSP, build a custom Secure instance before wiring the middleware:

Shiny for Python apps can be wrapped in the same way:

Pass the multi_ok argument to either middleware to append additional occurrences of headers that must appear multiple times (for example, when downstream code already emits a Content-Security-Policy line).

When you call Secure.with_default_headers() (or Secure.from_preset(Preset.BALANCED)), secure configures the recommended defaults that balance security and usability:

These defaults limit cross origin data leaks, mitigate clickjacking and MIME sniffing, and enforce a conservative Content Security Policy you can extend later. Balanced omits Cache-Control as well as the legacy/compatibility headers (X-Permitted-Cross-Domain-Policies, X-DNS-Prefetch-Control, Origin-Agent-Cluster, X-Download-Options, X-XSS-Protection), so add them manually if your deployment still depends on them.

If you prefer to think in terms of profiles instead of individual headers, secure provides presets via the Preset enum and Secure.from_preset.

The BALANCED preset is the new recommended default and matches Secure.with_default_headers(). It balances security with compatibility while keeping response headers relatively tight:

Balanced omits Cache-Control and the legacy/resource headers included by Preset.BASIC, but you can still add them manually if your deployment relies on them.

The BASIC preset matches Helmet.js defaults and ships with a broader compatibility-focused header set. It is useful when you require the same collection of headers Helmet enables out of the box:

This preset still avoids Cache-Control and Server but includes the extra headers that Helmet adds for historical/compatibility reasons.

The STRICT preset enables stronger protections and is a better fit for security focused deployments that can tolerate tighter restrictions. It is conceptually similar to:

Start with BALANCED and move to STRICT once you have validated that your application works correctly with the stricter Content Security Policy, caching, and frame restrictions. STRICT no longer sets HSTS preload by default, so you can opt-in separately when you are ready.

secure lets you build rich header values through small, focused builder classes. Two common examples are ContentSecurityPolicy and PermissionsPolicy.

Resulting header:

You can treat the CSP builder as a safe string builder for CSP directives and keep all CSP logic in one place.

Resulting header:

Other headers, such as StrictTransportSecurity, CrossOriginOpenerPolicy, CrossOriginEmbedderPolicy, ReferrerPolicy, Server, and XFrameOptions, also have small builder classes that mirror their directive structure.

For most applications, it is enough to construct a Secure instance and call set_headers or set_headers_async. If you want stronger guarantees and clearer failure modes, you can run headers through an explicit pipeline.

Key ideas:

• allowlist_headers enforces a case insensitive allowlist of header names and decides what to do with unexpected headers.
• deduplicate_headers resolves repeated header names so that you end up with clean name, value pairs.
• validate_and_normalize_headers validates header names and values, then freezes them into a single valued, immutable mapping exposed via the .headers property.
• After the pipeline runs through validate_and_normalize_headers(), Secure uses the normalized .headers mapping when set_headers or set_headers_async apply the headers, ensuring dropped entries never reach the wire and sanitized values replace unsafe input.

If you need to emit multi valued headers, such as multiple Set-Cookie fields, you can bypass the single valued mapping and work with header_items() directly:

This pipeline gives you a repeatable, testable flow for going from high level policy objects to concrete headers on the wire.

Below are simple examples for a synchronous and an asynchronous framework. See the framework specific guides for more detailed patterns.

Wraps the Shiny ASGI application and injects headers by intercepting the ASGI http.response.start message.

Injects headers by intercepting the ASGI http.response.start message.

Applies headers directly to the response object returned by call_next.

Applies headers directly to the Flask Response object.

Wraps the WSGI application and injects headers by wrapping start_response. Useful for deployment-level / framework-agnostic WSGI setups.

secure is designed to fail fast and clearly when something is misconfigured, with hooks for logging and diagnostics.

set_headers and set_headers_async may raise:

• HeaderSetError when the underlying response object refuses a header or an unexpected error occurs while setting one.
• AttributeError when the response object implements neither set_header(name, value) nor a mutable headers mapping.
• RuntimeError from set_headers if it detects that the only available setter is asynchronous. In that case, use set_headers_async instead.

The pipeline methods may raise ValueError when configured to do so:

• allowlist_headers with on_unexpected="raise" when encountering an unexpected header name.
• deduplicate_headers with action="raise" when it cannot safely resolve duplicates.
• validate_and_normalize_headers with on_invalid="raise" or when it detects invalid or duplicate entries during normalization.

Passing a logger into these methods is recommended in production so you can see which headers were rejected and why, even when you choose "drop" or "warn" modes instead of raising.

For additional examples, framework specific helpers, and more detailed guidance, see the documentation in the docs directory:

• Configuration details.
• Framework integration notes.
• Reference for header builder classes.
• Migration notes for the v2.0.0 release and preset/default changes: https://github.com/TypeError/secure/tree/main/docs/migration.md

Documentation: https://github.com/TypeError/secure/tree/main/docs

secure implements recommendations from widely used security resources:

• MDN Web Docs (licensed under CC-BY-SA 2.5)
• OWASP Secure Headers Project (licensed under CC-BY-SA 4.0)

Attribution comments are included in the source code where appropriate.

• OWASP Secure Headers Project
• Mozilla Web Security Guidelines
• MDN Web Docs: HTTP Headers
• web.dev security guidance
• W3C

This project is licensed under the terms of the MIT License.

Issues and pull requests are welcome. If you'd like to discuss an idea, please open a GitHub issue so we can align on the design before implementation. See CONTRIBUTING for details.

See CODE_OF_CONDUCT for our Code of Conduct.

See CHANGELOG for a detailed list of changes by release.

Thank you to everyone who contributes ideas, issues, pull requests, and feedback, as well as the maintainers of MDN and OWASP resources that this project builds on.