pax_global_header00006660000000000000000000000064147044243600014516gustar00rootroot0000000000000052 comment=813fb2d08a5db436bd7b56c19fadd29dd173f159 secure-1.0.1/000077500000000000000000000000001470442436000130035ustar00rootroot00000000000000secure-1.0.1/.gitignore000066400000000000000000000061231470442436000147750ustar00rootroot00000000000000# Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class # C extensions *.so # Distribution / packaging .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ share/python-wheels/ *.egg-info/ .installed.cfg *.egg MANIFEST # PyInstaller # Usually these files are written by a python script from a template # before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *.spec # Installer logs pip-log.txt pip-delete-this-directory.txt # Unit test / coverage reports htmlcov/ .tox/ .nox/ .coverage .coverage.* .cache nosetests.xml coverage.xml *.cover *.py,cover .hypothesis/ .pytest_cache/ cover/ # Translations *.mo *.pot # Django stuff: *.log local_settings.py db.sqlite3 db.sqlite3-journal # Flask stuff: instance/ .webassets-cache # Scrapy stuff: .scrapy # Sphinx documentation docs/_build/ # PyBuilder .pybuilder/ target/ # Jupyter Notebook .ipynb_checkpoints # IPython profile_default/ ipython_config.py # pyenv # For a library or package, you might want to ignore these files since the code is # intended to run in multiple environments; otherwise, check them in: # .python-version # pipenv # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. # However, in case of collaboration, if having platform-specific dependencies or dependencies # having no cross-platform support, pipenv may install dependencies that don't work, or not # install all needed dependencies. #Pipfile.lock # poetry # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. # This is especially recommended for binary packages to ensure reproducibility, and is more # commonly ignored for libraries. # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control #poetry.lock # pdm # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. #pdm.lock # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it # in version control. # https://pdm.fming.dev/latest/usage/project/#working-with-version-control .pdm.toml .pdm-python .pdm-build/ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm __pypackages__/ # Celery stuff celerybeat-schedule celerybeat.pid # SageMath parsed files *.sage.py # Environments .env .venv env/ venv/ ENV/ env.bak/ venv.bak/ # Spyder project settings .spyderproject .spyproject # Rope project settings .ropeproject # mkdocs documentation /site # mypy .mypy_cache/ .dmypy.json dmypy.json # Pyre type checker .pyre/ # pytype static type analyzer .pytype/ # Cython debug symbols cython_debug/ # PyCharm # JetBrains specific template is maintained in a separate JetBrains.gitignore that can # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. #.idea/ .idea .DS_Storesecure-1.0.1/CHANGELOG.md000066400000000000000000000037511470442436000146220ustar00rootroot00000000000000# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] - Placeholder for upcoming changes. ## [1.0.1] - 2024-10-18 ### Fixed - Improved performance of `Secure.set_headers` by reducing redundant type checks. ([#26](https://github.com/TypeError/secure/issues/26)) ## [1.0.0] - 2024-09-27 ### Breaking Changes - Full redesign of the `secure.py` library with modern Python (3.10+) support. - Major API overhaul for improved usability and Pythonic design. ### Added - Enhanced support for FastAPI and asynchronous frameworks. - Added type hints and better type annotations for a smoother developer experience. - Refined default security headers for improved protection across web frameworks. - Support for modern Python features such as the union operator (`|`) and `cached_property`. ## [0.3.0] - 2021-04-27 ### Breaking Changes - Full redesign of Secure API. - Removal of cookie support. ### Added - Added type hints for better developer experience. - Added support for FastAPI. ### Changed - Replaced Feature-Policy with Permissions-Policy (#10). ## [0.2.1] - 2018-12-24 ### Added - Added support for Masonite framework. - Added docstrings for `SecureHeaders` and `SecureCookie`. ### Changed - Upper-cased SameSite enum to `SameSite.LAX` / `SameSite.STRICT`. - Modified hug implementation for SecureHeaders and SecureCookie. - Renamed `Feature.Values.All` to `Feature.Values.All_` to avoid conflict with the built-in `all`. ### Fixed - Removed trailing semicolon from Feature Policy. ## [0.2.0] - 2018-12-16 ### Added - Added policy builder `SecurePolicies` in `policies.py`. - Added `Expires` header for legacy browser support. - Added `max-age` directive to `Cache-Control` header. ### Changed - Renamed `XXS` argument to `XXP`. - Modified `set-cookie` to use Flask's native method. secure-1.0.1/LICENSE000066400000000000000000000020621470442436000140100ustar00rootroot00000000000000MIT License Copyright (c) 2018-2024 Caleb Kinney Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. secure-1.0.1/MANIFEST.in000066400000000000000000000000371470442436000145410ustar00rootroot00000000000000include LICENSE exclude tests/*secure-1.0.1/README.md000066400000000000000000000266501470442436000142730ustar00rootroot00000000000000# secure.py _A simple, yet powerful way to secure your Python web applications across multiple frameworks._ [![PyPI Version](https://img.shields.io/pypi/v/secure.svg)](https://pypi.org/project/secure/) [![Python Versions](https://img.shields.io/pypi/pyversions/secure.svg)](https://pypi.org/project/secure/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Downloads](https://pepy.tech/badge/secure)](https://pepy.tech/project/secure) [![License](https://img.shields.io/pypi/l/secure.svg)](https://github.com/TypeError/secure/blob/main/LICENSE) [![GitHub Stars](https://img.shields.io/github/stars/TypeError/secure.svg)](https://github.com/TypeError/secure/stargazers) ## **Introduction** In today's web landscape, security is paramount. **secure.py** is a lightweight Python library designed to effortlessly add **security headers** to your web applications, protecting them from common vulnerabilities. Whether you're using **Django**, **Flask**, **FastAPI**, or any other popular framework, `secure.py` provides a unified API to enhance your application's security posture. --- ## **Why Use secure.py?** - 🔒 **Apply Essential Security Headers**: Implement headers like CSP, HSTS, and more with minimal effort. - 🛠️ **Consistent API Across Frameworks**: A unified approach for different web frameworks. - ⚙️ **Customizable with Secure Defaults**: Start secure out-of-the-box and customize as needed. - 🚀 **Easy Integration**: Compatible with Python's most-used frameworks. - 🐍 **Modern Pythonic Design**: Leverages Python 3.10+ features for cleaner and more efficient code. --- ## **Supported Frameworks** **secure.py** supports the following Python web frameworks: | Framework | Documentation | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [aiohttp](https://docs.aiohttp.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#aiohttp) | | [Bottle](https://bottlepy.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#bottle) | | [CherryPy](https://cherrypy.dev/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#cherrypy) | | [Django](https://www.djangoproject.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#django) | | [Falcon](https://falconframework.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#falcon) | | [FastAPI](https://fastapi.tiangolo.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#fastapi) | | [Flask](http://flask.pocoo.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#flask) | | [Masonite](https://docs.masoniteproject.com/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#masonite) | | [Morepath](https://morepath.readthedocs.io) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#morepath) | | [Pyramid](https://trypyramid.com) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#pyramid) | | [Quart](https://quart.palletsprojects.com/en/latest/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#quart) | | [Responder](https://responder.kennethreitz.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#responder) | | [Sanic](https://sanicframework.org) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#sanic) | | [Starlette](https://www.starlette.io/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#starlette) | | [Tornado](https://www.tornadoweb.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#tornado) | | [TurboGears](https://turbogears.org/) | [Integration Guide](https://github.com/TypeError/secure/blob/main/docs/frameworks.md#turbogears) | --- ## **Features** - 🔒 **Secure Headers**: Automatically apply headers like `Strict-Transport-Security`, `X-Frame-Options`, and more. - 🛠️ **Customizable Policies**: Flexibly build your own security policies using method chaining. - 🌐 **Framework Integration**: Compatible with various frameworks, ensuring cross-compatibility. - 🚀 **No External Dependencies**: Lightweight and easy to include in any project. - 🧩 **Easy to Use**: Integrate security headers in just a few lines of code. - ⚡ **Asynchronous Support**: Async support for modern frameworks like **FastAPI** and **Starlette**. - 📝 **Enhanced Type Hinting**: Complete type annotations for better developer experience. - 📚 **Attribution to Trusted Sources**: Implements recommendations from MDN and OWASP. --- ## **Requirements** - **Python 3.10** or higher This library leverages modern Python features introduced in Python 3.10 and 3.11, such as: - **Union Type Operator (`|`)**: Simplifies type annotations. - **Structural Pattern Matching (`match` statement)**: Enhances control flow. - **Improved Type Hinting and Annotations**: Provides better code clarity and maintenance. - **`cached_property`**: Optimize memory usage and performance. **Note:** If you're using an older version of Python (3.6 to 3.9), please use version **0.3.0** of this library, which maintains compatibility with those versions. - **Dependencies** This library has no external dependencies outside of the Python Standard Library. --- ## **Installation** You can install secure.py using pip, pipenv, or poetry: **pip**: ```bash pip install secure ``` **Pipenv**: ```bash pipenv install secure ``` **Poetry**: ```bash poetry add secure ``` --- ## **Getting Started** Once installed, you can quickly integrate `secure.py` into your project: ### Synchronous Usage ```python import secure # Initialize secure headers with default settings secure_headers = secure.Secure.with_default_headers() # Apply the headers to your framework response object secure_headers.set_headers(response) ``` ### Asynchronous Usage For frameworks like **FastAPI** and **Starlette** that support asynchronous operations, use the async method: ```python import secure # Initialize secure headers with default settings secure_headers = secure.Secure.with_default_headers() # Apply the headers asynchronously to your framework response object await secure_headers.set_headers_async(response) ``` ### **Example Usage** ```python import secure # Create a Secure instance with default headers secure_headers = secure.Secure.with_default_headers() # Apply default secure headers to a response object secure_headers.set_headers(response) ``` --- ## **Default Secure Headers** By default, `secure.py` applies the following headers when using `with_default_headers()`: ```http Cache-Control: no-store Cross-Origin-Opener-Policy: same-origin Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; object-src 'none' Strict-Transport-Security: max-age=31536000 Permissions-Policy: geolocation=(), microphone=(), camera=() Referrer-Policy: strict-origin-when-cross-origin Server: X-Content-Type-Options: nosniff ``` --- ## **Policy Builders** `secure.py` allows you to customize headers such as **Content-Security-Policy** and **Permissions-Policy** with ease: ### **Content-Security-Policy Example** ```python import secure # Build a custom CSP policy csp = ( secure.ContentSecurityPolicy() .default_src("'self'") .script_src("'self'", "cdn.example.com") .style_src("'unsafe-inline'") .img_src("'self'", "images.example.com") .connect_src("'self'", "api.example.com") ) # Apply it to secure headers secure_headers = secure.Secure(csp=csp) ``` **Resulting HTTP headers:** ```http Content-Security-Policy: default-src 'self'; script-src 'self' cdn.example.com; style-src 'unsafe-inline'; img-src 'self' images.example.com; connect-src 'self' api.example.com ``` ### **Permissions-Policy Example** ```python import secure # Build a custom Permissions Policy permissions = ( secure.PermissionsPolicy() .geolocation("'self'") .camera("'none'") .microphone("'none'") ) # Apply it to secure headers secure_headers = secure.Secure(permissions=permissions) ``` **Resulting HTTP headers:** ```http Permissions-Policy: geolocation=('self'), camera=('none'), microphone=('none') ``` --- ## **Framework Examples** ### **FastAPI** ```python from fastapi import FastAPI from secure import Secure app = FastAPI() secure_headers = Secure.with_default_headers() @app.middleware("http") async def add_security_headers(request, call_next): response = await call_next(request) await secure_headers.set_headers_async(response) return response @app.get("/") def read_root(): return {"Hello": "World"} ``` ### Flask ```python from flask import Flask, Response from secure import Secure app = Flask(__name__) 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, world" if __name__ == "__main__": app.run() ``` --- ## **Documentation** For more details, including advanced configurations and integration examples, please visit the **[full documentation](https://github.com/TypeError/secure/tree/main/docs)**. --- ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) We have included attribution comments in the source code where appropriate. --- ## **Resources** - [OWASP - Secure Headers Project](https://owasp.org/www-project-secure-headers/) - [Mozilla Web Security Guidelines](https://infosec.mozilla.org/guidelines/web_security) - [MDN Web Docs: Security Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#security) - [web.dev: Security Best Practices](https://web.dev) - [The World Wide Web Consortium (W3C)](https://www.w3.org) --- ### **License** This project is licensed under the terms of the **[MIT License](https://opensource.org/licenses/MIT)**. --- ## **Contributing** Contributions are welcome! If you'd like to contribute to `secure.py`, please feel free to open an issue or submit a pull request on **[GitHub](https://github.com/TypeError/secure)**. --- ## **Changelog** For a detailed list of changes, please refer to the **[CHANGELOG](https://github.com/TypeError/secure/blob/main/CHANGELOG.md)**. --- ## **Acknowledgements** We would like to thank the contributors of MDN Web Docs and OWASP Secure Headers Project for their invaluable resources and guidelines that help make the web a safer place. secure-1.0.1/docs/000077500000000000000000000000001470442436000137335ustar00rootroot00000000000000secure-1.0.1/docs/README.md000066400000000000000000000142171470442436000152170ustar00rootroot00000000000000# Secure Headers Documentation Welcome to the documentation for **Secure Headers**, a flexible Python library for managing HTTP security headers. This guide will help you get started with configuring headers, integrating with various web frameworks, and understanding how each security header works. --- ## 📖 Table of Contents - [Getting Started](#getting-started) - [Supported Frameworks](#supported-frameworks) - [Security Headers](#security-headers) - [Additional Resources](#additional-resources) - [Contributing](#contributing) --- ## 🚀 Getting Started To quickly get started using Secure Headers, check out the basic configuration guide in the main README: - [Quick Start Guide](../README.md#basic-usage) For installation instructions, see the [Installation section](./installation.md). For usage examples, see the [Usage Guide](./usage.md). For detailed configuration options, see the [Configuration Guide](./configuration.md). --- ## 🔧 Supported Frameworks Secure Headers is compatible with many popular Python web frameworks. Below are the integration guides for each supported framework, consolidated in the [Frameworks Integration Guide](./frameworks.md): | Framework | Documentation | | ----------------------------------------------------- | ----------------------------------------------- | | [aiohttp](https://docs.aiohttp.org) | [Integration Guide](./frameworks.md#aiohttp) | | [Bottle](https://bottlepy.org) | [Integration Guide](./frameworks.md#bottle) | | [CherryPy](https://cherrypy.dev/) | [Integration Guide](./frameworks.md#cherrypy) | | [Django](https://www.djangoproject.com) | [Integration Guide](./frameworks.md#django) | | [Falcon](https://falconframework.org) | [Integration Guide](./frameworks.md#falcon) | | [FastAPI](https://fastapi.tiangolo.com) | [Integration Guide](./frameworks.md#fastapi) | | [Flask](http://flask.pocoo.org) | [Integration Guide](./frameworks.md#flask) | | [Masonite](https://docs.masoniteproject.com/) | [Integration Guide](./frameworks.md#masonite) | | [Morepath](https://morepath.readthedocs.io) | [Integration Guide](./frameworks.md#morepath) | | [Pyramid](https://trypyramid.com) | [Integration Guide](./frameworks.md#pyramid) | | [Quart](https://quart.palletsprojects.com/en/latest/) | [Integration Guide](./frameworks.md#quart) | | [Responder](https://responder.kennethreitz.org/) | [Integration Guide](./frameworks.md#responder) | | [Sanic](https://sanicframework.org) | [Integration Guide](./frameworks.md#sanic) | | [Starlette](https://www.starlette.io/) | [Integration Guide](./frameworks.md#starlette) | | [Tornado](https://www.tornadoweb.org/) | [Integration Guide](./frameworks.md#tornado) | | [TurboGears](https://turbogears.org/) | [Integration Guide](./frameworks.md#turbogears) | If your framework is not listed here, Secure Headers can likely still be integrated. Refer to the [Custom Framework Integration Guide](./frameworks.md#custom-frameworks) for general integration tips. --- ## 🛡️ Security Headers Secure Headers supports many critical HTTP security headers. Below is a list of headers you can configure, along with detailed documentation for each: - [Cache-Control](./headers/cache_control.md) Configure caching behavior to protect sensitive content. - [Content-Security-Policy](./headers/content_security_policy.md) Prevent XSS and data injection attacks by controlling allowed content sources. - [Cross-Origin-Embedder-Policy](./headers/cross_origin_embedder_policy.md) Enhance cross-origin security by specifying cross-origin resource policies. - [Cross-Origin-Opener-Policy](./headers/cross_origin_opener_policy.md) Prevent attackers from accessing your global objects via cross-origin documents. - [Custom Headers](./headers/custom_header.md) Define and manage custom HTTP headers for advanced configurations. - [Permissions-Policy](./headers/permissions_policy.md) Control access to browser features such as geolocation, camera, and microphone. - [Referrer-Policy](./headers/referrer_policy.md) Manage how much referrer information is shared during navigation. - [Server](./headers/server.md) Hide or customize the `Server` header to prevent exposing your server details. - [Strict-Transport-Security (HSTS)](./headers/strict_transport_security.md) Ensure that communication is only over HTTPS by enforcing strict transport security. - [X-Content-Type-Options](./headers/x_content_type_options.md) Prevent MIME-sniffing attacks by ensuring the browser follows the declared `Content-Type`. - [X-Frame-Options](./headers/x_frame_options.md) Protect against clickjacking by controlling whether your content can be framed. --- ## 📚 Additional Resources - [MDN Web Docs - HTTP Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) Explore more about HTTP headers and their use cases. - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/) Learn about security best practices for HTTP headers from OWASP. - [Mozilla Observatory](https://observatory.mozilla.org/) A security tool to check the implementation of security headers on your site. - [Security Headers by Scott Helme](https://securityheaders.com/) A free tool to test your site for missing security headers. - [HSTS Preload List](https://hstspreload.org/) Learn about adding your domain to the HTTP Strict Transport Security (HSTS) preload list. - [CSP Evaluator by Google](https://csp-evaluator.withgoogle.com/) A tool for analyzing Content Security Policies to ensure strong security practices. --- ## 💬 Contributing We welcome contributions! If you'd like to contribute or have any feedback, feel free to: - **Open an Issue**: Report bugs or request features. - **Submit a Pull Request**: Contribute code or documentation improvements. - **Contact Us**: Reach out via [GitHub](https://github.com/TypeError/secure). secure-1.0.1/docs/configuration.md000066400000000000000000000076031470442436000171320ustar00rootroot00000000000000# Configuration Guide ## Overview This guide provides detailed information on how to configure `secure.py` beyond the default settings. You can customize security headers, override default behavior, and extend the functionality to meet your application’s unique security requirements. --- ## Default Headers By default, `secure.py` applies a set of widely-used security headers that provide a strong baseline of protection. These include: - **Strict-Transport-Security (HSTS)**: Ensures that browsers only connect to your site over HTTPS. - **X-Frame-Options**: Protects against clickjacking attacks by controlling whether your site can be embedded in an iframe. - **X-Content-Type-Options**: Prevents browsers from MIME-sniffing a response away from the declared `Content-Type`. - **Content-Security-Policy (CSP)**: Mitigates Cross-Site Scripting (XSS) and data injection attacks by defining allowed content sources. ### Applying Default Headers To quickly apply these default headers, use the following command: ```python secure_headers = Secure.with_default_headers() ``` This is the simplest way to secure your application without manually configuring each individual header. However, for applications with specific security requirements, you can customize headers as needed. --- ## Customizing Headers Each security header can be customized to meet your application’s unique needs. Below are examples of how to modify some commonly used headers. ### Example: Customizing `X-Frame-Options` to Allow Same-Origin Embedding If you want to allow your site to be embedded in an iframe, but only by pages from the same origin, use the following configuration: ```python secure_headers = Secure( xfo=Secure.XFrameOptions().sameorigin() ) ``` This protects against clickjacking while maintaining functionality for same-origin embedding, such as internal dashboards. ### Example: Customizing `Strict-Transport-Security` To ensure that all subdomains of your site are accessed over HTTPS, and to add your domain to the HSTS preload list, you can configure `Strict-Transport-Security` like this: ```python secure_headers = Secure( hsts=Secure.StrictTransportSecurity().max_age(63072000).include_subdomains().preload() ) ``` This configuration enforces HTTPS for 2 years (`max-age=63072000`), applies the rule to all subdomains, and preloads your site into browsers' HSTS lists. --- ## Extending Default Behavior You can also extend the default behavior by adding custom headers. This is useful when your application requires additional non-standard security headers. ### Example: Adding a Custom Header ```python from secure import CustomHeader custom_header = CustomHeader("X-Custom-Header", "CustomValue") secure_headers = Secure(custom=[custom_header]) ``` In this example, a custom HTTP header `X-Custom-Header` is added to the response, allowing you to inject additional security policies or tracking information as required by your application. --- ## Combining Presets with Customization You can use one of the built-in presets as a starting point and then further customize specific headers to meet your security needs. ### Example: Customizing a Preset ```python from secure import Secure, Preset secure_headers = Secure.from_preset(Preset.BASIC) secure_headers.hsts.max_age(63072000) # Override the default max-age value ``` This approach allows you to quickly set up basic security headers while customizing certain parameters to fit your application’s security posture. --- ## Summary `secure.py` offers flexibility in how you configure your security headers. Whether you’re using the default settings, customizing individual headers, or adding custom headers, the library allows you to secure your application effectively. For more advanced use cases, consider combining presets with custom configurations. For more details on each supported header, refer to the [Security Headers Documentation](./headers). secure-1.0.1/docs/frameworks.md000066400000000000000000000375741470442436000164550ustar00rootroot00000000000000# Framework Integration `secure.py` supports several popular Python web frameworks. Below are examples showing how to set the default security headers in each framework, along with a brief introduction and links to each project. Additionally, we provide guidance for integrating Secure Headers with custom or unsupported frameworks. ## Table of Contents - [aiohttp](#aiohttp) - [Bottle](#bottle) - [CherryPy](#cherrypy) - [Django](#django) - [Falcon](#falcon) - [FastAPI](#fastapi) - [Flask](#flask) - [Masonite](#masonite) - [Morepath](#morepath) - [Pyramid](#pyramid) - [Quart](#quart) - [Responder](#responder) - [Sanic](#sanic) - [Starlette](#starlette) - [Tornado](#tornado) - [TurboGears](#turbogears) - [Web2py](#web2py) - [Custom Frameworks](#custom-frameworks) --- ### Note: Overriding the `Server` Header in Uvicorn-based Frameworks If you're using Uvicorn as the ASGI server (commonly used with frameworks like FastAPI, Starlette, and others), Uvicorn automatically injects a `Server: uvicorn` header into all HTTP responses by default. This can lead to multiple `Server` headers when using `Secure.py` to set a custom `Server` header. To prevent Uvicorn from adding its default `Server` header, you can disable it by passing the `--no-server-header` option when running Uvicorn, or by setting `server_header=False` in the `uvicorn.run()` method: ```python import uvicorn uvicorn.run( app, host="0.0.0.0", port=8000, server_header=False, # Disable Uvicorn's default Server header ) ``` If you're using Uvicorn via Gunicorn (e.g., with the `UvicornWorker`), note that this setting is not passed through automatically. In such cases, you may need to subclass the worker to fully override the `Server` header. For more information, refer to the [Uvicorn Settings](https://www.uvicorn.org/settings/#http). --- ## aiohttp **[aiohttp](https://docs.aiohttp.org)** is an asynchronous HTTP client/server framework for asyncio and Python. It's designed for building efficient web applications with asynchronous capabilities. ### Middleware Example ```python from aiohttp import web from secure import Secure secure_headers = Secure.with_default_headers() @web.middleware async def add_security_headers(request, handler): response = await handler(request) await secure_headers.set_headers_async(response) return response app = web.Application(middlewares=[add_security_headers]) app.router.add_get("/", lambda request: web.Response(text="Hello, world")) web.run_app(app) ``` ### Single Route Example ```python from aiohttp import web from secure import Secure secure_headers = Secure.with_default_headers() async def handle(request): response = web.Response(text="Hello, world") await secure_headers.set_headers_async(response) return response app = web.Application() app.router.add_get("/", handle) web.run_app(app) ``` --- ## Bottle **[Bottle](https://bottlepy.org)** is a fast, simple, and lightweight WSGI micro web-framework for Python. It's perfect for small applications and rapid prototyping. ### Middleware Example ```python from bottle import Bottle, response, run from secure import Secure secure_headers = Secure.with_default_headers() app = Bottle() @app.hook("after_request") def add_security_headers(): secure_headers.set_headers(response) run(app, host="localhost", port=8080) ``` ### Single Route Example ```python from bottle import Bottle, response, run from secure import Secure secure_headers = Secure.with_default_headers() app = Bottle() @app.route("/") def index(): secure_headers.set_headers(response) return "Hello, world" run(app, host="localhost", port=8080) ``` --- ## CherryPy **[CherryPy](https://cherrypy.dev)** is a minimalist, object-oriented web framework that allows developers to build web applications in a way similar to building other Python applications. ### Middleware Example ```python import cherrypy from secure import Secure secure_headers = Secure.with_default_headers() class HelloWorld: @cherrypy.expose def index(self): cherrypy.response.headers.update(secure_headers.headers) return b"Hello, world" config = { "/": { "tools.response_headers.on": True, "tools.response_headers.headers": secure_headers.headers } } cherrypy.quickstart(HelloWorld(), "/", config) ``` ### Single Route Example ```python import cherrypy from secure import Secure secure_headers = Secure.with_default_headers() class HelloWorld: @cherrypy.expose def index(self): cherrypy.response.headers.update(secure_headers.headers) return b"Hello, world" cherrypy.quickstart(HelloWorld()) ``` --- ## Django **[Django](https://www.djangoproject.com)** is a high-level Python web framework that encourages rapid development and clean, pragmatic design. ### Middleware Example ```python from django.http import HttpResponse from secure import Secure secure_headers = Secure.with_default_headers() def set_secure_headers(get_response): def middleware(request): response = get_response(request) secure_headers.set_headers(response) return response return middleware ``` ### Single Route Example ```python from django.http import HttpResponse from secure import Secure secure_headers = Secure.with_default_headers() def home(request): response = HttpResponse("Hello, world") secure_headers.set_headers(response) return response ``` --- ## Falcon **[Falcon](https://falconframework.org)** is a minimalist WSGI library for building speedy web APIs and app backends. ### Middleware Example ```python import falcon from secure import Secure secure_headers = Secure.with_default_headers() class SecureMiddleware: def process_response(self, req, resp, resource, req_succeeded): secure_headers.set_headers(resp) app = falcon.App(middleware=[SecureMiddleware()]) class HelloWorldResource: def on_get(self, req, resp): resp.text = "Hello, world" app.add_route("/", HelloWorldResource()) ``` ### Single Route Example ```python import falcon from secure import Secure secure_headers = Secure.with_default_headers() class HelloWorldResource: def on_get(self, req, resp): resp.text = "Hello, world" secure_headers.set_headers(resp) app = falcon.App() app.add_route("/", HelloWorldResource()) ``` --- ## FastAPI **[FastAPI](https://fastapi.tiangolo.com)** is a modern, fast web framework for building APIs with Python 3.6+. ### Middleware Example ```python from fastapi import FastAPI from secure import Secure app = FastAPI() secure_headers = Secure.with_default_headers() @app.middleware("http") async def add_security_headers(request, call_next): response = await call_next(request) await secure_headers.set_headers_async(response) return response ``` ### Single Route Example ```python from fastapi import FastAPI, Response from secure import Secure app = FastAPI() secure_headers = Secure.with_default_headers() @app.get("/") def read_root(response: Response): secure_headers.set_headers(response) return {"Hello": "World"} ``` --- ## Flask **[Flask](https://flask.palletsprojects.com)** is a lightweight WSGI web application framework. ### Middleware Example ```python from flask import Flask, Response from secure import Secure app = Flask(__name__) secure_headers = Secure.with_default_headers() @app.after_request def add_security_headers(response: Response): secure_headers.set_headers(response) return response ``` ### Single Route Example ```python from flask import Flask, Response from secure import Secure app = Flask(__name__) secure_headers = Secure.with_default_headers() @app.route("/") def home(): response = Response("Hello, world") secure_headers.set_headers(response) return response ``` --- ## Masonite **[Masonite](https://docs.masoniteproject.com)** is a modern and developer-friendly Python web framework. ### Middleware Example ```python from masonite.foundation import Application from masonite.response import Response from secure import Secure app = Application() secure_headers = Secure.with_default_headers() def add_security_headers(response: Response): secure_headers.set_headers(response) return response ``` ### Single Route Example ```python from masonite.request import Request from masonite.response import Response from masonite.foundation import Application from secure import Secure app = Application() secure_headers = Secure.with_default_headers() @app.route("/") def home(request: Request, response: Response): return add_security_headers(response.view("Hello, world")) ``` --- ## Morepath **[Morepath](https://morepath.readthedocs.io)** is a Python web framework that provides URL to object mapping. ### Middleware Example Morepath doesn’t have middleware. Use per-view settings as shown in the single route example. ### Single Route Example ```python import morepath from secure import Secure secure_headers = Secure.with_default_headers() class App(morepath.App): pass @App.path(path="") class Root: pass @App.view(model=Root) def hello_world(self, request): response = morepath.Response("Hello, world") secure_headers.set_headers(response) return response morepath.run(App()) ``` --- ## Pyramid **[Pyramid](https://trypyramid.com)** is a small, fast Python web framework. ### Middleware Example ```python from pyramid.config import Configurator from pyramid.response import Response from secure import Secure secure_headers = Secure.with_default_headers() def add_security_headers(handler, registry): def tween(request): response = handler(request) secure_headers.set_headers(response) return response return tween ``` ### Single Route Example ```python from pyramid.config import Configurator from pyramid.response import Response from secure import Secure secure_headers = Secure.with_default_headers() def hello_world(request): response = Response("Hello, world") secure_headers.set_headers(response) return response ``` --- ## Quart **[Quart](https://quart.palletsprojects.com)** is an async Python web framework. ### Middleware Example ```python from quart import Quart, Response from secure import Secure app = Quart(__name__) secure_headers = Secure.with_default_headers() @app.after_request async def add_security_headers(response: Response): await secure_headers.set_headers_async(response) return response ``` ### Single Route Example ```python from quart import Quart, Response from secure import Secure app = Quart(__name__) secure_headers = Secure.with_default_headers() @app.route("/") async def index(): response = Response("Hello, world") await secure_headers.set_headers_async(response) return response ``` --- ## Responder **[Responder](https://responder.kennethreitz.org)** is a fast web framework for building APIs. ### Middleware Example ```python import responder from secure import Secure api = responder.API() secure_headers = Secure.with_default_headers() @api.route("/") async def add_security_headers(req, resp): await secure_headers.set_headers_async(resp) ``` ### Single Route Example ```python import responder from secure import Secure api = responder.API() secure_headers = Secure.with_default_headers() @api.route("/") async def home(req, resp): resp.text = "Hello, world" await secure_headers.set_headers_async(resp) ``` --- ## Sanic **[Sanic](https://sanicframework.org)** is a Python web framework written for fast performance. ### Middleware Example ```python from sanic import Sanic, response from secure import Secure app = Sanic("SecureApp") secure_headers = Secure.with_default_headers() @app.middleware("response") async def add_security_headers(request, resp): secure_headers.set_headers(resp) ``` ### Single Route Example ```python from sanic import Sanic, response from secure import Secure app = Sanic("SecureApp") secure_headers = Secure.with_default_headers() @app.route("/") async def index(request): resp = response.text("Hello, world") secure_headers.set_headers(resp) return resp ``` --- ## Starlette **[Starlette](https://www.starlette.io)** is a lightweight ASGI framework. ### Middleware Example ```python from starlette.applications import Starlette from starlette.responses import Response from starlette.middleware.base import BaseHTTPMiddleware from secure import Secure secure_headers = Secure.with_default_headers() class SecurityHeadersMiddleware(BaseHTTPMiddleware): async def dispatch(self, request, call_next): response = await call_next(request) await secure_headers.set_headers_async(response) return response ``` ### Single Route Example ```python from starlette.applications import Starlette from starlette.responses import Response from secure import Secure secure_headers = Secure.with_default_headers() async def homepage(request): response = Response("Hello, world") await secure_headers.set_headers_async(response) return response ``` --- ## Tornado **[Tornado](https://www.tornadoweb.org)** is a Python web framework designed for asynchronous networking. ### Middleware Example Tornado doesn't directly support middleware, but you can use it in each request handler as shown in the single route example. ### Single Route Example ```python import tornado.ioloop import tornado.web from secure import Secure secure_headers = Secure.with_default_headers() class MainHandler(tornado.web.RequestHandler): def get(self): self.write("Hello, world") secure_headers.set_headers(self) ``` --- ## TurboGears **[TurboGears](https://turbogears.org)** is a full-stack framework. ### Middleware Example ```python from tg import AppConfig, Response, TGController, expose from secure import Secure secure_headers = Secure.with_default_headers() class SecureMiddleware: def __init__(self, req, resp): secure_headers.set_headers(resp) config = AppConfig(minimal=True, root_controller=TGController) config["middleware"] = [SecureMiddleware] ``` ### Single Route Example ```python from tg import AppConfig, Response, TGController, expose from secure import Secure secure_headers = Secure.with_default_headers() class RootController(TGController): @expose() def index(self): response = Response("Hello, world") secure_headers.set_headers(response) return response ``` --- ## Web2py **[Web2py](http://www.web2py.com)** is a free web framework designed for rapid development of database-driven applications. ### Middleware Example Web2py doesn't directly support middleware, but you can use it in each route. ### Single Route Example ```python from gluon import current from secure import Secure secure_headers = Secure.with_default_headers() def index(): secure_headers.set_headers(current.response) return "Hello, world" ``` --- ## Custom Frameworks If you are using a framework that is not listed here, `secure.py` can still be integrated. Most frameworks offer a way to manipulate response headers, which is all you need to apply security headers. ### General Steps: 1. **Identify the Response Object**: Each framework typically has a response object or an equivalent that allows you to modify HTTP headers. 2. **Set Headers**: Use the `set_headers()` or `set_headers_async()` method to inject security headers into the response before sending it back to the client. 3. **Asynchronous Support**: For asynchronous frameworks, ensure that you're calling the correct async version of methods. ### Example: ```python from secure import Secure secure_headers = Secure().with_default_headers() def add_secure_headers(response): secure_headers.set_headers(response) return response # Apply the `add_secure_headers` function wherever your framework handles responses. ``` --- ### Need Help? If you encounter any issues integrating Secure Headers with your custom framework, feel free to open an issue on our [GitHub repository](https://github.com/TypeError/secure) or consult the framework's documentation for handling response headers. secure-1.0.1/docs/headers/000077500000000000000000000000001470442436000153465ustar00rootroot00000000000000secure-1.0.1/docs/headers/cache_control.md000066400000000000000000000042371470442436000205010ustar00rootroot00000000000000# Cache-Control Header ## Purpose The `Cache-Control` header is used to define caching mechanisms for both requests and responses. Properly configuring this header can ensure sensitive data isn't inadvertently cached, and resources are served fresh when necessary. ## Best Practices - **`no-store`**: Prevents any caching of sensitive data. - **`max-age=0`**: Ensures the content is always fresh. - **`immutable`**: Helps improve caching efficiency for resources that never change. - **`no-transform`**: Ensures the intermediaries do not modify the content. ## Configuration in `secure.py` The `CacheControl` class in `secure.py` allows flexible configuration of this header. It supports adding directives like `no-cache`, `no-store`, `max-age`, and others to ensure appropriate caching behavior. ### Example Configuration ```python secure_headers = Secure( cache=CacheControl() .no_store() .max_age(0) ) ``` ### Methods Available - **`no_store()`**: Prevents all caching. - **`no_cache()`**: Requires revalidation before caching. - **`max_age(seconds)`**: Specifies the maximum time a resource is considered fresh. - **`must_revalidate()`**: Forces caches to revalidate content before serving it. - **`immutable()`**: Indicates that the resource is immutable and doesn't need revalidation. ## Example Usage To set up a `Cache-Control` header with no caching allowed and a max-age of 0: ```python cache_control = CacheControl().no_cache().no_store().max_age(0) print(cache_control.header_name) # Output: 'Cache-Control' print(cache_control.header_value) # Output: 'no-cache, no-store, max-age=0' ``` This can then be applied as part of your Secure headers configuration. ```python secure_headers = Secure(cache=cache_control) ``` ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#cache-control) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) secure-1.0.1/docs/headers/content_security_policy.md000066400000000000000000000141061470442436000226520ustar00rootroot00000000000000# Content-Security-Policy Header ## Purpose The `Content-Security-Policy` (CSP) header helps mitigate cross-site scripting (XSS), data injection, and other attacks by specifying the sources from which content can be loaded. By restricting the sources for different types of content (scripts, styles, images, etc.), CSP provides an additional layer of security. ## Best Practices - **`default-src 'self'`**: Restricts content to the same origin by default. - **`object-src 'none'`**: Disables plugins such as Flash and Java applets. - **`script-src 'self'`**: Allows JavaScript execution only from your domain. - **`upgrade-insecure-requests`**: Ensures that any HTTP URLs are upgraded to HTTPS. ## Configuration in `secure.py` The `ContentSecurityPolicy` class in `secure.py` allows flexible configuration of CSP. You can add various directives for specific content types like `script-src`, `style-src`, `img-src`, etc., to enhance security. ### Example Configuration ```python secure_headers = Secure( csp=ContentSecurityPolicy() .default_src("'self'") .script_src("'self'") .style_src("'self'") .object_src("'none'") ) ``` ### Methods Available - **`default_src(*sources)`**: Specifies default content sources. - **`script_src(*sources)`**: Specifies valid JavaScript sources. - **`style_src(*sources)`**: Specifies valid CSS sources. - **`object_src(*sources)`**: Specifies valid plugin sources (e.g., ``, ``, ``). - **`upgrade_insecure_requests()`**: Automatically upgrades HTTP URLs to HTTPS. ## Example Usage To set up a `Content-Security-Policy` header that only allows content from the same origin and restricts the use of plugins: ```python csp = ContentSecurityPolicy() .default_src("'self'") .script_src("'self'") .object_src("'none'") print(csp.header_name) # Output: 'Content-Security-Policy' print(csp.header_value) # Output: "default-src 'self'; script-src 'self'; object-src 'none'" ``` This can then be applied as part of your Secure headers configuration. ```python secure_headers = Secure(csp=csp) ``` ## Using Nonce and `strict-dynamic` in Content-Security-Policy Content Security Policy (CSP) allows you to enhance the security of your web application by specifying the allowed sources of content. Using a nonce with the `strict-dynamic` directive improves protection against Cross-Site Scripting (XSS) attacks by dynamically allowing only scripts that are explicitly marked with a nonce. This is especially useful when you want to allow some inline scripts while ensuring only those scripts and their dynamically loaded dependencies are executed. ### Example: Using Nonce with `strict-dynamic` Here’s how to set a CSP with a nonce and `strict-dynamic` using `secure.py`: ```python import uuid from flask import Flask, Response from secure import ContentSecurityPolicy, Secure app = Flask(__name__) def generate_nonce(): # Create a unique nonce for each request return uuid.uuid4().hex secure_headers = Secure( csp=ContentSecurityPolicy() .default_src("'self'") .script_src(ContentSecurityPolicy().nonce(generate_nonce()), "'strict-dynamic'") .style_src("'self'") .object_src("'none'") ) @app.after_request def add_security_headers(response: Response): # Apply the security headers with a new nonce for each response nonce = generate_nonce() secure_headers.set_headers(response) # Ensure the nonce is passed in the CSP for inline scripts response.headers["Content-Security-Policy"] = response.headers[ "Content-Security-Policy" ].replace("'nonce-'", f"'nonce-{nonce}'") return response @app.route("/") def home(): # Example HTML with an inline script using the nonce nonce = generate_nonce() html = f""" Secure.py with CSP Hello, world! """ return Response(html, content_type="text/html") if __name__ == "__main__": app.run() ``` ### Example Output Headers This example sets the following HTTP headers on the response: ```http Content-Security-Policy: default-src 'self'; script-src 'nonce-' 'strict-dynamic'; style-src 'self'; object-src 'none' ``` ```html Secure.py with CSP Hello, world! ``` - **`default-src 'self'`**: Only content from the same origin is allowed by default. - **`script-src 'nonce-' 'strict-dynamic'`**: Only scripts with the nonce or dynamically loaded by trusted scripts are allowed. - **`style-src 'self'`**: Only CSS from the same origin is allowed. - **`object-src 'none'`**: The `` element is disabled for additional security. ### Why Use `strict-dynamic`? The `strict-dynamic` directive allows the CSP to trust dynamically created scripts as long as they are loaded by scripts with a nonce or from a trusted source. This reduces the need to explicitly list external sources in the CSP, improving security by ensuring only scripts with a nonce or trusted dynamic scripts are executed. For more details on `Content-Security-Policy` and the `nonce` attribute, refer to the following resources: - [MDN Web Docs: Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) - [OWASP Secure Headers Project: Content-Security-Policy](https://owasp.org/www-project-secure-headers/#content-security-policy) ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#content-security-policy) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) secure-1.0.1/docs/headers/cross_origin_embedder_policy.md000066400000000000000000000042231470442436000235770ustar00rootroot00000000000000# Cross-Origin-Embedder-Policy Header ## Purpose The `Cross-Origin-Embedder-Policy` (COEP) header prevents a document from loading any cross-origin resources that don’t explicitly grant permission. It works alongside the `Cross-Origin-Resource-Policy` (CORP) to enhance security, especially in modern applications dealing with cross-origin requests. ## Best Practices - **`require-corp`**: Only allow loading resources from the same origin or those explicitly permitting cross-origin access. This is the most secure setting. - **`unsafe-none`**: Permits loading cross-origin resources without explicit permission. Use this only when security constraints aren't a concern. ## Configuration in `secure.py` The `CrossOriginEmbedderPolicy` class in `secure.py` allows you to configure the COEP header with options like `require-corp` or `unsafe-none` to control resource loading policies. ### Example Configuration ```python secure_headers = Secure( coep=CrossOriginEmbedderPolicy().require_corp() ) ``` ### Methods Available - **`require_corp()`**: Ensures resources are loaded only from the same origin or from origins that grant explicit permission. - **`unsafe_none()`**: Disables the COEP policy, allowing cross-origin resources to be loaded without restriction. ## Example Usage To set up a `Cross-Origin-Embedder-Policy` header that requires cross-origin resources to explicitly permit being loaded: ```python coep = CrossOriginEmbedderPolicy().require_corp() print(coep.header_name) # Output: 'Cross-Origin-Embedder-Policy' print(coep.header_value) # Output: 'require-corp' ``` This can then be applied as part of your Secure headers configuration. ```python secure_headers = Secure(coep=coep) ``` ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#cross-origin-embedder-policy) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) secure-1.0.1/docs/headers/cross_origin_opener_policy.md000066400000000000000000000045631470442436000233270ustar00rootroot00000000000000# Cross-Origin-Opener-Policy Header ## Purpose The `Cross-Origin-Opener-Policy` (COOP) header isolates your browsing context from potentially untrusted contexts, preventing attackers from accessing your global object through popups and mitigating cross-origin attacks such as XS-Leaks. By setting this header, you protect against malicious cross-origin interactions that could compromise your application's security. ## Best Practices - **`same-origin`**: This is the most secure option, isolating your document from other origins. - **`same-origin-allow-popups`**: Allows popups while maintaining some level of isolation. - **`unsafe-none`**: Disables COOP, potentially exposing your application to cross-origin risks. Use this only if isolation is not required. ## Configuration in `secure.py` The `CrossOriginOpenerPolicy` class in `secure.py` allows you to configure the COOP header with options like `same-origin`, `same-origin-allow-popups`, or `unsafe-none` to control the behavior of popups and cross-origin contexts. ### Example Configuration ```python secure_headers = Secure( coop=CrossOriginOpenerPolicy().same_origin() ) ``` ### Methods Available - **`same_origin()`**: Isolates the browsing context to the same origin, preventing cross-origin documents from being loaded. - **`same_origin_allow_popups()`**: Retains references to popups or tabs that opt out of isolation. - **`unsafe_none()`**: Disables the COOP protection, allowing the document to be added to its opener’s browsing context group. ## Example Usage To set up a `Cross-Origin-Opener-Policy` header that isolates your application from cross-origin contexts: ```python coop = CrossOriginOpenerPolicy().same_origin() print(coop.header_name) # Output: 'Cross-Origin-Opener-Policy' print(coop.header_value) # Output: 'same-origin' ``` This can then be applied as part of your Secure headers configuration. ```python secure_headers = Secure(coop=coop) ``` ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#cross-origin-opener-policy) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) secure-1.0.1/docs/headers/custom_header.md000066400000000000000000000041441470442436000205150ustar00rootroot00000000000000# CustomHeader Class ## Purpose The `CustomHeader` class allows the creation and management of custom HTTP headers with arbitrary names and values. This is particularly useful for adding non-standard headers to HTTP responses or requests, such as headers specific to your application or infrastructure. ## Best Practices - Custom headers should follow the convention of using a prefix like `X-` (e.g., `X-Custom-Header`), although this is no longer a requirement as per the latest RFC. - Be cautious when adding custom headers to avoid potential conflicts or leaking sensitive information. ## Configuration in `secure.py` The `CustomHeader` class in `secure.py` provides flexibility for developers to define and set custom HTTP headers as needed. You can specify both the header name and value and update the value later if necessary. ### Example Configuration ```python custom_header = CustomHeader("X-Custom-Header", "CustomValue") ``` ### Methods Available - **`set(value)`**: Updates the value of the custom header. - **`header_value()`**: Retrieves the current value of the custom header. ## Example Usage To define a custom header and use it in a secure configuration: ```python custom_header = CustomHeader("X-Custom-Header", "CustomValue") print(custom_header.header_name) # Output: 'X-Custom-Header' print(custom_header.header_value) # Output: 'CustomValue' # Update the value custom_header.set("NewValue") print(custom_header.header_value) # Output: 'NewValue' ``` This can then be applied as part of your Secure headers configuration: ```python secure_headers = Secure(custom=[custom_header]) ``` ## **Resources** - [MDN Web Docs: HTTP Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) secure-1.0.1/docs/headers/permissions_policy.md000066400000000000000000000052371470442436000216310ustar00rootroot00000000000000# Permissions-Policy Header ## Purpose The `Permissions-Policy` header allows you to enable or disable browser features and APIs for your web applications. This header replaces the deprecated `Feature-Policy` header and provides fine-grained control over which features are allowed in your site, such as geolocation, camera access, or microphone use. ## Best Practices - Disable unnecessary features to reduce your site's attack surface and protect user privacy. - Allow features only for trusted sources or specific origins to avoid potential misuse. - Use a restrictive default policy, then selectively enable features as required. ## Configuration in `secure.py` The `PermissionsPolicy` class in `secure.py` allows you to configure the `Permissions-Policy` header with specific directives for controlling access to browser APIs and features. ### Example Configuration ```python secure_headers = Secure( permissions=PermissionsPolicy() .geolocation() .microphone() .camera() ) ``` ### Methods Available - **`add_directive(directive, *allowlist)`**: Add a custom directive with an optional allowlist of origins. - **`geolocation(*allowlist)`**: Control access to geolocation data. - **`camera(*allowlist)`**: Control access to the camera. - **`microphone(*allowlist)`**: Control access to the microphone. - **`usb(*allowlist)`**: Control access to USB devices. - More methods are available for other browser features, such as accelerometer, gyroscope, and more. ## Example Usage To set up a `Permissions-Policy` header that controls access to specific features: ```python permissions_policy = PermissionsPolicy() .geolocation() .camera() .microphone() print(permissions_policy.header_name) # Output: 'Permissions-Policy' print(permissions_policy.header_value) # Output: 'geolocation=(), camera=(), microphone=()' ``` This can then be applied as part of your Secure headers configuration. ```python secure_headers = Secure(permissions=permissions_policy) ``` ## **Resources** - [MDN Web Docs: Permissions-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy) - [OWASP Secure Headers Project: Permissions-Policy](https://owasp.org/www-project-secure-headers/#permissions-policy) ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#permissions-policy) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) secure-1.0.1/docs/headers/referrer_policy.md000066400000000000000000000055531470442436000210730ustar00rootroot00000000000000# Referrer-Policy Header ## Purpose The `Referrer-Policy` header controls how much referrer information is included with requests made from your website. This header helps protect user privacy by limiting the amount of data exposed via the `Referer` header, especially when navigating between different origins. ## Best Practices - **`strict-origin-when-cross-origin`**: This is a secure default, providing the full URL for same-origin requests and only the origin for cross-origin requests. - **`no-referrer`**: Use this option to completely suppress the `Referer` header in all requests, offering the most privacy. - **`no-referrer-when-downgrade`**: Prevents sending the referrer when transitioning from HTTPS to HTTP, protecting information from being leaked over unsecured connections. ## Configuration in `secure.py` The `ReferrerPolicy` class in `secure.py` allows you to configure the `Referrer-Policy` header with various directives depending on your site's security and privacy requirements. ### Example Configuration ```python secure_headers = Secure( referrer=ReferrerPolicy().strict_origin_when_cross_origin() ) ``` ### Methods Available - **`no_referrer()`**: No `Referer` header will be sent. - **`no_referrer_when_downgrade()`**: The `Referer` header will not be sent when navigating from HTTPS to HTTP. - **`origin()`**: The `Referer` header will contain only the origin of the URL. - **`same_origin()`**: The `Referer` header will be sent only for same-origin requests. - **`strict_origin_when_cross_origin()`**: The full URL is sent for same-origin requests, but only the origin for cross-origin requests. - **`unsafe_url()`**: The full URL will always be sent, even for cross-origin requests. This may expose sensitive information. ## Example Usage To set up a `Referrer-Policy` header that limits the exposure of referrer information: ```python referrer_policy = ReferrerPolicy().strict_origin_when_cross_origin() print(referrer_policy.header_name) # Output: 'Referrer-Policy' print(referrer_policy.header_value) # Output: 'strict-origin-when-cross-origin' ``` This can then be applied as part of your Secure headers configuration: ```python secure_headers = Secure(referrer=referrer_policy) ``` ## **Resources** - [MDN Web Docs: Referrer-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy) - [OWASP Secure Headers Project: Referrer-Policy](https://owasp.org/www-project-secure-headers/#referrer-policy) ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#referrer-policy) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) secure-1.0.1/docs/headers/server.md000066400000000000000000000047661470442436000172130ustar00rootroot00000000000000# Server Header ## Purpose The `Server` header provides information about the server software handling the request. By default, this header exposes the server's technology stack, which can increase the risk of targeted attacks. For enhanced security, it is recommended to obscure or remove this header to prevent unnecessary exposure of server details. ## Best Practices - **Set an empty value or custom string**: It's generally advisable to set the `Server` header to an empty value (`""`) or use a non-informative value to avoid revealing specific details about the server software. - **Avoid exposing server information**: Avoid leaving the default server response, which may expose sensitive version information. ## Configuration in `secure.py` The `Server` class in `secure.py` allows you to easily control the `Server` header value, with the default value set to an empty string to enhance security. ### Example Configuration ```python secure_headers = Secure( server=Server().set("") ) ``` ### Methods Available - **`set(value)`**: Set a custom value for the `Server` header. - **`clear()`**: Clear any custom value and revert the header to its default secure value (an empty string). ## Example Usage To set up the `Server` header and hide the server information: ```python server_header = Server().set("") print(server_header.header_name) # Output: 'Server' print(server_header.header_value) # Output: '' ``` This can then be applied as part of your Secure headers configuration: ```python secure_headers = Secure(server=server_header) ``` ### Special Considerations for Frameworks Some frameworks like Uvicorn automatically inject a `Server` header. If you're using Uvicorn and need to override or remove this header, refer to the [framework integration guide](../frameworks.md) for specific instructions on how to disable Uvicorn's default `Server` header. ## **Resources** - [MDN Web Docs: Server Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server) - [OWASP Secure Headers Project: Server Header](https://owasp.org/www-project-secure-headers/#server-header) ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#server-header) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) secure-1.0.1/docs/headers/strict_transport_security.md000066400000000000000000000055661470442436000232570ustar00rootroot00000000000000# Strict-Transport-Security (HSTS) Header ## Purpose The `Strict-Transport-Security` (HSTS) header ensures that the application communicates over HTTPS, preventing man-in-the-middle attacks by instructing the browser to automatically upgrade all HTTP connections to HTTPS. Additionally, this header helps protect your site from downgrade attacks, where an attacker might try to force a user to communicate over an insecure HTTP connection. ## Best Practices - **Set a long max-age**: A duration of one year (`31536000` seconds) is recommended to enforce HTTPS for an extended period. - **Include subdomains**: Use the `includeSubDomains` directive to apply the policy to all subdomains. - **Use the preload directive**: Opt into the HSTS preload list to ensure that browsers always load your site over HTTPS, even on the first visit. ## Configuration in `secure.py` The `StrictTransportSecurity` class in `secure.py` allows you to configure the `Strict-Transport-Security` (HSTS) header with options like `max-age`, `includeSubDomains`, and `preload`. ### Example Configuration ```python secure_headers = Secure( hsts=StrictTransportSecurity() .max_age(31536000) .include_subdomains() .preload() ) ``` ### Methods Available - **`max_age(seconds)`**: Set the maximum duration (in seconds) for which the browser should enforce the HTTPS-only policy. - **`include_subdomains()`**: Apply the HSTS policy to all subdomains of the domain. - **`preload()`**: Opt into the HSTS preload list, ensuring that all requests to your site are made over HTTPS, even on the first visit. ## Example Usage To set up a `Strict-Transport-Security` header with a one-year max age, including subdomains and opting into the HSTS preload list: ```python hsts_header = StrictTransportSecurity().max_age(31536000).include_subdomains().preload() print(hsts_header.header_name) # Output: 'Strict-Transport-Security' print(hsts_header.header_value) # Output: 'max-age=31536000; includeSubDomains; preload' ``` This can then be applied as part of your Secure headers configuration: ```python secure_headers = Secure(hsts=hsts_header) ``` ## **Resources** - [MDN Web Docs: Strict-Transport-Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) - [OWASP Secure Headers Project: HSTS](https://owasp.org/www-project-secure-headers/#http-strict-transport-security) - [HSTS Preload List](https://hstspreload.org/) ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#http-strict-transport-security) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) secure-1.0.1/docs/headers/x_content_type_options.md000066400000000000000000000045501470442436000225110ustar00rootroot00000000000000# X-Content-Type-Options Header ## Purpose The `X-Content-Type-Options` header prevents browsers from MIME-sniffing a response away from the declared `Content-Type`. This helps protect against certain types of attacks, such as cross-site scripting (XSS) and drive-by downloads, where an attacker tries to disguise a file's MIME type in order to trick the browser into executing malicious content. ## Best Practices - **Set to `nosniff`**: This is the recommended value, as it tells the browser to strictly follow the declared `Content-Type` and not attempt to guess or "sniff" the MIME type. This helps prevent MIME-based attacks. ## Configuration in `secure.py` The `XContentTypeOptions` class in `secure.py` allows you to easily configure the `X-Content-Type-Options` header. The default value is `nosniff`, which is the recommended setting. ### Example Configuration ```python secure_headers = Secure( xcto=XContentTypeOptions().nosniff() ) ``` ### Methods Available - **`nosniff()`**: Sets the `X-Content-Type-Options` header to `nosniff`, which prevents MIME-sniffing by browsers. - **`set(value)`**: Sets a custom value for the `X-Content-Type-Options` header. - **`clear()`**: Clears any custom value and reverts the header to its default value (`nosniff`). ## Example Usage To set up the `X-Content-Type-Options` header and prevent MIME-sniffing: ```python xcto_header = XContentTypeOptions().nosniff() print(xcto_header.header_name) # Output: 'X-Content-Type-Options' print(xcto_header.header_value) # Output: 'nosniff' ``` This can then be applied as part of your Secure headers configuration: ```python secure_headers = Secure(xcto=xcto_header) ``` ## **Resources** - [MDN Web Docs: X-Content-Type-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) - [OWASP Secure Headers Project: X-Content-Type-Options](https://owasp.org/www-project-secure-headers/#x-content-type-options) ## **Attribution** This library implements security recommendations from trusted sources: - [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) (licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)) - [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/#x-content-type-options) (licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)) secure-1.0.1/docs/headers/x_frame_options.md000066400000000000000000000045561470442436000210760ustar00rootroot00000000000000# X-Frame-Options Header ## Purpose The `X-Frame-Options` header helps protect your site from clickjacking attacks by specifying whether your web pages can be embedded in ``, `