corslib package#

Submodules#

corslib.policy module#

exception corslib.policy.InsecureRule(message: str, *, rule: str, rule_type: str, description: Optional[str] = None)#: Bases: corslib.policy.RuleError

exception corslib.policy.PolicyError#: Bases: ValueError

exception corslib.policy.RuleError#: Bases: ValueError

class corslib.policy.OriginRule(rule: str, kind: corslib.policy.RuleKind = RuleKind.STR)#

Bases: object

A rule for origin check.

Rule consists of string representing rule and kind (default is STR). Matching is done in allow_origin() method that matches origin specification from HTTP request against rule using appropriate procedure for selected kind.

Variables

rule (str) – rule specification as string
kind (RuleKind) – kind of rule, determines matching against origin specification provided in request headers

allow_origin(request_origin: str) → Optional[str]#

Match origin spec from request against rule.

The matching is done using method specified in kind. If kind is STR then rule value is returned. In any other case returned is the spec from request (if matches) or None (if not) with exception of null origin which can be specified only by STR rule to match.

Parameters: request_origin (str) – origin spec from request
Returns: allowed origin spec or None
Return type: Optional[str]

kind: corslib.policy.RuleKind = 'str'#

rule: str#

class corslib.policy.Policy(name: str, allow_credentials: bool = False, allow_origin: Optional[Sequence[corslib.policy.OriginRule]] = None, allow_headers: Optional[Sequence[str]] = None, allow_methods: Optional[Sequence[str]] = None, expose_headers: Optional[Sequence[str]] = None, max_age: Optional[int] = None)#

Bases: object

Policy to be applied to incoming requests.

All arguments except name are optional. The default behaviour is to allow all traffic from 3rd party but limited to “web safe” parameters (methods, headers, credentials).

Variables

name (str) – name of the rule
allow_credentials (bool) – allow credentialed requests, default is to not allow
allow_origin (Optional[Sequence[OriginRule]]) – optional sequence of OriginRule objects that will be checked to match client-provided origin in request headers
allow_headers (Optional[Sequence[str]]) – optional sequence of allowed HTTP request headers
allow_methods (Optional[Sequence[str]]) – optional sequence of allowed HTTP methods
expose_headers (Optional[Sequence[str]]) – optional sequence of HTTP headers that may be accessed in client code
max_age (Optional[int]) – optional number of seconds that response may be cached by client

access_control_allow_credentials(request_credentials: bool, allow_origin: str) → Mapping[str, str]#

Generate Access-Control-Allow-Credentials header entry.

If request is to be denied or credentials has not been requested then this method returns empty dict. This happens also when rule allows credentials but origin resolves to * or null.

Parameters

request_credentials (bool) – indicates response to credentialed request
allow_origin (str) – calculated allowed origin

Returns

Access-Control-Allow-Credentials header entry or empty dict

Return type

Mapping[str, str]

access_control_allow_headers(request_headers: Optional[str]) → Mapping[str, str]#

Generate Access-Control-Allow-Headers header entry.

If no specific headers are requested then this method returns empty dict, which usually means “default safe headers”.

If policy does not specify allowed headers then all headers are allowed. This is implemented by reflecting requested headers.

Parameters: request_headers (Optional[str]) – value of Access-Control-Request-Headers header from preflight request
Returns: Access-Control-Allow-Headers entry as dict or empty dict
Return type: Mapping[str, str]

access_control_allow_methods(request_method: Optional[str]) → Mapping[str, str]#

Generate Access-Control-Allow-Methods header entry.

If no specific method is requested then this method returns empty dict, which usually means “default methods” (GET, HEAD, POST).

If policy does not specify allowed methods then requested method is reflected but only if it’s in a list of simple methods. Otherwise list of simple methods is returned.

Parameters: request_method (Optional[str]) – value of Access-Control-Request-Method header from preflight request
Returns: Access-Control-Allow-Methods entry or empty dict
Return type: Mapping[str, str]

access_control_allow_origin(origin: str) → Mapping[str, str]#

Generate Access-Control-Allow-Origin header entry.

Additionally if value is not * or null then Vary header value is also included in resulting dict.

Parameters: origin (str) – value of the Origin header
Returns: Access-Control-Allow-Origin header entry, and optionally also Vary header entry
Return type: Mapping[str, str]

preflight_response_headers(origin: str, *, strict: bool = False, request_credentials: bool = False, request_method: Optional[str] = None, request_headers: Optional[str] = None) → Mapping[str, Union[str, int]]#

Generate preflight response headers.

This method takes value of Origin header from request and a flag if request will be “credentialed”, that is it will include cookies and/or authentication HTTP header.

Returned value is also generic dict. If multiple values are returned for any key, they are returned as list so the result needs to be adapted to framework/library specific implementation of HTTP headers structure.

Parameters

origin (str) – value of the Origin request header
strict (bool, optional) – flag if strict security has to be applied, effectively treating null origin as *, defaults to False
request_credentials (bool, optional) – indicates response to credentialed request, defaults to False
request_method (str, optional) – requested HTTP method, defaults to None
request_headers (str, optional) – requested HTTP headers, defaults to None

Returns

generated header values as Python dict

Return type

Mapping[str, Union[str, int]]

response_headers(origin: str, *, strict: bool = False, request_credentials: bool = False) → Mapping[str, str]#

Generate regular response headers.

Parameters

origin (str) – value of the Origin request header
strict (bool, optional) – flag if strict security has to be applied, effectively treating null origin as *, defaults to False
request_credentials (bool, optional) – indicates response to credentialed request, defaults to False

Returns

generated header values as Python dict

Return type

Mapping[str, str]

ACCESS_CONTROL_ALLOW_CREDENTIALS: ClassVar[str] = 'Access-Control-Allow-Credentials'#

ACCESS_CONTROL_ALLOW_HEADERS: ClassVar[str] = 'Access-Control-Allow-Headers'#

ACCESS_CONTROL_ALLOW_METHODS: ClassVar[str] = 'Access-Control-Allow-Methods'#

ACCESS_CONTROL_ALLOW_ORIGIN: ClassVar[str] = 'Access-Control-Allow-Origin'#

ACCESS_CONTROL_MAX_AGE: ClassVar[str] = 'Access-Control-Max-Age'#

SAFELIST_CONTENT_TYPE = ['application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain']#

SAFELIST_HEADERS = ['accept', 'accept-language', 'content-language', 'content-type']#

SIMPLE_METHODS = ['GET', 'POST', 'HEAD']#

allow_credentials: bool = False#

allow_headers: Optional[Sequence[str]] = None#

allow_methods: Optional[Sequence[str]] = None#

allow_origin: Optional[Sequence[corslib.policy.OriginRule]] = None#

expose_headers: Optional[Sequence[str]] = None#

max_age: Optional[int] = None#

name: str#

class corslib.policy.RuleKind(value)#

Bases: enum.Enum

Enumeration of supported rule kinds.

str kind of rule should be used if the rule describes exact host name or allows all hosts (*); also this is the only rule that allows to support special null origin
path kind uses filename pattern matching provided by fnmatch, this allows for example to match whole subdomains (http://*.mydomain.com) or partial names (http://myapp-prod-??.mydomain.com)
regex allows matching against arbitrary regular expressions supported by Python re module

PATH = 'path'#

REGEX = 'regex'#

STR = 'str'#

corslib.utils module#

corslib.utils.is_request_credentialed(headers: Union[Mapping[str, Any], Sequence[str]]) → bool#

Utility function that checks if headers indicate credentialed request.

This is done only by inspecting header fields so it does not takes SSL client certificate authentication into account. The argument may be either headers dictionary-like object or a sequence of headers field names.

Parameters: headers (Union[Mapping[str, Any], Sequence[str]]) – header fields
Returns: flag indicating credentialed status
Return type: bool

corslib package#

Submodules#

corslib.policy module#

corslib.utils module#

Module contents#