CORSlib#

CORSlib is framework- and protocol-agnostic library that emits CORS headers on web server side based on defined rules. Policies are applied per request but may be used with arbitrary granularity.

Since it’s framework-agnostic, the only thing it can do is to generate preflight and regular response headers related to CORS. It’s up to the user to write specific handler for OPTIONS request and respond appropriately, including generated headers. Header structures returned from library functions are generic Python objects like dicts, strings and numbers so it may be necessary to adapt resolution result to specific application / framework headers structure or handling method.

CORS Security#

This library strives to be as secure as it’s possible within CORS specification and will not generate insecure headers even if requested to do so. To achieve that, some basic precautions are observed:

  • no origin reflection - Allow-Origin header value is taken from rule definition and never reflected from request Origin value unless policy resolves with exact match from non-exact rule (PATH or REGEX);

  • strict credentials handling - library will not allow credentialed requests if resolved rule allows traffic from everywhere (Allow-Origin resolves to * or null origin);

  • matched Allow-Origin headers dict always include Vary header value - when policy resolves Allow-Origin with exact origin match, generated headers include value for Vary header, note according to HTTP spec it may be a list of separated values so it may need to be merged with any existing value as generated by application / framework;

CORSlib includes extensive range of well tested rule validators based on OWASP WSTG to prevent common security lapses coming from CORS misconfiguration.

Warning

In general, while this library provides regex-based rules, it’s best to first try with other rule kinds because no matter how much testing, regular expressions can easily turn into a footgun. It’s simply not possible to test all scenarios, so only the most common are being validated and tested.

Please don’t take web security lighthearted.

By default generated headers provide relaxed security appropriate for development yet still within CORS specification. The default access model allows open web safe operation, similar to pre-CORS browser mode. This way additional security may be gradually added as requirements arise.

Note

CORS is tailored towards Javascript running in the web browsers. It works only as much as agent (web browser) wants to cooperate. Therefore it can not be treated as web API security measure in cases when requests may come from sources other than web browsers. Non-browser client may even send requests without Origin header effectively making CORS a moot. If your API will be exposed to wide web use appropriate security measures like server-side client validation, API gateways and so on.

Utilities#

CORSlib provides validation tool based on well-established CORS scanner. With this validator it is possible to assess rule security before it gets exposed to wide web. Please use it before going to production.

Guides#

API documentation#

Indices and tables#