Skip to main content

Starlette middleware implementing Double Submit Cookie technique to mitigate CSRF

Project description

Starlette CSRF Middleware

Starlette middleware implementing Double Submit Cookie technique to mitigate CSRF.

build codecov PyPI version Downloads

How it works?

  1. The user makes a first request with a method considered safe (by default GET, HEAD, OPTIONS, TRACE).
  2. It receives in response a cookie (named by default csrftoken) which contains a secret value.
  3. When the user wants to make an unsafe request, the server expects them to send the same secret value in a header (named by default x-csrftoken).
  4. The middleware will then compare the secret value provided in the cookie and the header.
    • If they match, the request is processed.
    • Otherwise, a 403 Forbidden error response is given.

This mechanism is necessary if you rely on cookie authentication in a browser. You can have more information about CSRF and Double Submit Cookie in the OWASP Cheat Sheet Series.

Installation

pip install starlette-csrf

Usage with Starlette

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette_csrf import CSRFMiddleware

routes = ...

middleware = [
    Middleware(CSRFMiddleware, secret="__CHANGE_ME__")
]

app = Starlette(routes=routes, middleware=middleware)

Usage with FastAPI

from fastapi import FastAPI
from starlette_csrf import CSRFMiddleware

app = FastAPI()

app.add_middleware(CSRFMiddleware, secret="__CHANGE_ME__")

Arguments

  • secret (str): Secret to sign the CSRF token value. Be sure to choose a strong passphrase and keep it SECRET.
  • required_urls (Optional[List[re.Pattern]] - None): List of URL regexes that the CSRF check should always be enforced, no matter the method or the cookies present.
  • exempt_urls (Optional[List[re.Pattern]] - None): List of URL regexes that the CSRF check should be skipped on. Useful if you have any APIs that you know do not need CSRF protection.
  • sensitive_cookies (Set[str] - None): Set of cookie names that should trigger the CSRF check if they are present in the request. Useful if you have other authentication methods that don't rely on cookies and don't need CSRF enforcement. If this parameter is None, the default, CSRF is always enforced.
  • safe_methods (Set[str] - {"GET", "HEAD", "OPTIONS", "TRACE"}): HTTP methods considered safe which don't need CSRF protection.
  • cookie_name (str - csrftoken): Name of the cookie.
  • cookie_path str - /): Cookie path.
  • cookie_domain (Optional[str] - None): Cookie domain. If your frontend and API lives in different sub-domains, be sure to set this argument with your root domain to allow your frontend sub-domain to read the cookie on the JavaScript side.
  • cookie_secure (bool - False): Whether to only send the cookie to the server via SSL request.
  • cookie_samesite (str - lax): Samesite strategy of the cookie.
  • header_name (str - x-csrftoken): Name of the header where you should set the CSRF token.

Customize error response

By default, a plain text response with the status code 403 is returned when the CSRF verification is failing. You can customize it by overloading the middleware class and implementing the _get_error_response method. It accepts in argument the original Request object and expects a Response. For example:

from starlette.requests import Request
from starlette.responses import JSONResponse, Response
from starlette_csrf import CSRFMiddleware

class CustomResponseCSRFMiddleware(CSRFMiddleware):
    def _get_error_response(self, request: Request) -> Response:
        return JSONResponse(
            content={"code": "CSRF_ERROR"}, status_code=403
        )

Development

Setup environment

We use Hatch to manage the development environment and production build. Ensure it's installed on your system.

Run unit tests

You can run all the tests with:

hatch run test

Format the code

Execute the following command to apply linting and check typing:

hatch run lint

License

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

starlette_csrf-3.0.0.tar.gz (8.4 kB view details)

Uploaded Source

Built Distribution

starlette_csrf-3.0.0-py3-none-any.whl (6.2 kB view details)

Uploaded Python 3

File details

Details for the file starlette_csrf-3.0.0.tar.gz.

File metadata

  • Download URL: starlette_csrf-3.0.0.tar.gz
  • Upload date:
  • Size: 8.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-httpx/0.24.1

File hashes

Hashes for starlette_csrf-3.0.0.tar.gz
Algorithm Hash digest
SHA256 7afaca8c72cc3c726e5942778af53454607ca3e653fd86cd75ee35d8cd1cfa77
MD5 46e50ceeb4e8dfdc47013f1e0044cf04
BLAKE2b-256 0f7c53c57b4cd76c9a4493a8525d34a76d7e4bbe0ff957de1c53f30241aa757a

See more details on using hashes here.

File details

Details for the file starlette_csrf-3.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for starlette_csrf-3.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 aac29b366e83621d3fc56be690866e16f3c56df91ab5e184b77950540a4e2761
MD5 e823181f10d63fb7da52cf9ed025426c
BLAKE2b-256 b9836641e4fdcf33b1cc614a74ecabe5835236a1b2564bf6735db7e35d788795

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page