Secweb: Security Middlewares for FastAPI and Starlette

Common errors

• ModuleNotFoundError: No module named 'Secweb'

  cause The `secweb` package is not installed in the current Python environment or the environment is not active.
  fix Ensure `secweb` is installed by running `pip install secweb` and that you are using the correct Python environment where it was installed.

• KeyError: 'Some-Policy-Key-That-DoesNotExist'

  cause An invalid key was used in the `Option` dictionary passed to `SecWeb`, possibly due to a typo or a deprecated parameter name.
  fix Verify the `Option` dictionary keys against the official Secweb documentation or source code for your specific version to ensure they are correct and up-to-date.

• Security headers are not being applied or are incorrect in the response.

  cause This can be caused by the order of middlewares in your FastAPI/Starlette application, where another middleware might be overwriting Secweb's headers. Alternatively, a misconfiguration in the `Option` dictionary might prevent headers from being set as expected.
  fix Ensure `SecWeb(app=app)` is called early in your application's setup, typically right after initializing `FastAPI()` or `Starlette()`, to give it precedence over other middlewares. Double-check your `Option` dictionary for typos or incorrect values.

Warnings

• breaking Secweb now requires Python 3.9 or higher. Older Python versions will not be supported with recent releases.
  Fix: Upgrade your Python environment to 3.9 or later. Consider using a virtual environment (e.g., `python3.9 -m venv .venv`).
• gotcha When initializing `SecWeb(app=app)`, all 16 security headers are enabled by default with their preset values. Users expecting a minimal set of headers or custom policies must explicitly define them using the `Option` parameter.
  Fix: To customize or disable specific headers, pass an `Option` dictionary to `SecWeb` with boolean flags or policy definitions (e.g., `SecWeb(app=app, Option={'Content-Security-Policy': {'default-src': "'self'"}})`).
• gotcha Using individual middleware classes (e.g., `ContentSecurityPolicy`) instead of the combined `SecWeb` class will only activate those specific headers. Other security headers will remain deactivated unless explicitly added.
  Fix: Decide whether you need a comprehensive set of default headers (`SecWeb`) or fine-grained control over a few specific ones. If using individual middlewares, ensure all necessary security headers are separately configured.
• gotcha Some `Option` dictionary parameter keys for specific headers (e.g., `COEP`, `COOP`, `CORP`, `Referrer`) have changed across versions. While the library claims backward compatibility, existing configurations might need updates to reflect new key names or structures.
  Fix: Consult the latest Secweb documentation or GitHub README for the correct `Option` dictionary structure and key names for each security header in your installed version.

Install

• pip install secweb Install latest version

Imports

• SecWeb

  from Secweb import SecWeb

  Main class that includes all security middlewares bundled together.
• ContentSecurityPolicy

  from Secweb import ContentSecurityPolicy

  Example of importing a single, specific security middleware.

Quickstart

This quickstart demonstrates how to integrate `Secweb` with a FastAPI application. By initializing `SecWeb` with your FastAPI app, all default security headers are automatically applied, enhancing the application's security posture. To test, run the app and inspect the HTTP response headers.

import uvicorn
from fastapi import FastAPI
from Secweb import SecWeb

app = FastAPI()

# Initialize SecWeb to apply all default security headers.
# Custom options can be passed via the 'Option' dictionary parameter.
SecWeb(app=app)

@app.get("/")
async def read_root():
    return {"message": "Hello, secured World!"}

# To run this example:
# 1. Save as a Python file (e.g., main.py)
# 2. Run from your terminal: uvicorn main:app --reload
# Check browser developer tools for applied security headers.