API¶
Setup¶
-
coroutine
aiohttp_remotes.
setup
(app, *tools)¶ Setup tools provided by the module.
A tool is class instance from described below list, the functon registers provided tools into aiohttp application app, e.g.:
from aiohttp_remotes import BasicAuth, Secure, setup app = web.Application() await setup(app, Secure(), BasicAuth("user", "password", "realm"))
Order of tools is important: in the example redirect to HTTPS is performed before credentials check, thus login/password is sent via SSL encrypted connection.
AllowedHosts¶
-
class
aiohttp_remotes.
AllowedHosts
(allowed_hosts=('*', ), *, white_paths_())¶ Restrict a list of host/domain names that this aiohttp application can serve. This is a security measure to prevent HTTP Host header attacks, which are possible even under many seemingly-safe web server configurations.
Parameters: - allowed_hosts – an iterable of allowed client IP
addresses.
'*'
is a wildcard for accepting any host. - white_paths – an iterable of white paths, see White paths for details.
- allowed_hosts – an iterable of allowed client IP
addresses.
BasicAuth¶
-
class
aiohttp_remotes.
BasicAuth
(username, password, realm, * white_paths=())¶ Protect web application by basic auth authorization.
Parameters: - username (str) – user name
- password (str) – password
- realm (str) – realm
- white_paths – an iterable of white paths, see White paths for details.
CloudFlare¶
-
class
aiohttp_remotes.
Cloudflare
(client=None)¶ Make sure that web application is protected by CloudFlare.
The tools should be used with
XForwardedStrict
orXForwardedRelaxed
to setup HTTP scheme, host and remote properly.Parameters: client – aiohttp.ClientSession
instance for performing HTTP requests to CloudFlare configuration resources.The class creates a temporary client if
None
is provided.
Forwarded¶
-
class
aiohttp_remotes.
ForwardedRelaxed
(num=1)¶ Modify
scheme
,host
,remote
attributes giving the values from numForwarded
HTTP header record (last one by default).The tools is useful for getting real client IP, scheme (HTTPS or HTTP) and HOST if aiohttp application is deployed behind Reverse Proxy like NGINX.
The class does not perform any security check, use it with caution.
-
class
aiohttp_remotes.
ForwardedStrict
(trusted, *, white_paths=())¶ Process
Forwarded
HTTP header and modify correspondingscheme
,host
,remote
attributes in strong secure mode.Restrict access (return 400 Bad Request) if reverse proxy addresses are not match provided configuration.
Parameters: - trusted – a list of trusted reverse proxies, see Trusted hosts for details.
- white_paths – an iterable of white paths, see White paths for details.
Secure¶
-
class
aiohttp_remotes.
Secure
(*, redirect=True, redirect_url=None, white_paths=())¶ Ensure that web application is handled by HTTPS (SSL/TLS) only, redirect plain HTTP to HTTPS automatically.
Parameters: - redirect (bool) – do redirection instead of returning 400 Bad Request.
- redirect_url – redirection URL, the same usr as requested non-secure HTTP if not specified.
- white_paths – an iterable of white paths, see White paths for details.
X-Forwarded¶
-
class
aiohttp_remotes.
XForwardedRelaxed
(num=1)¶ Modify
scheme
,host
,remote
attributes giving the values from numX-Forwarded-*
HTTP headers (last record by default).The tools is useful for getting real client IP, scheme (HTTPS or HTTP) and HOST if aiohttp application is deployed behind Reverse Proxy like NGINX.
The class does not perform any security check, use it with caution.
-
class
aiohttp_remotes.
XForwardedStrict
(trusted, *, white_paths=())¶ Process
X-Forwarded-*
HTTP headers and modify correspondingscheme
,host
,remote
attributes in strong secure mode.Restrict access (return 400 Bad Request) if reverse proxy addresses are not match provided configuration.
Parameters: - trusted – a list of trusted reverse proxies, see Trusted hosts for details.
- white_paths – an iterable of white paths, see White paths for details.
Trusted hosts¶
trusted parameter is a sequence of trusted hosts or networks.
The format is list of items, where every item describes a reverse proxy.
Item can be:
- A list of IP addresses or networks, every element is:
- IP address is IPv4 or IPv6 in form accepted by
ipaddress.ip_address()
. - Network is IPv4 or IPv6 network in form accepted by
ipaddress.ip_network()
.
- IP address is IPv4 or IPv6 in form accepted by
- Ellipsis
...
The check is performed against Forwarded
or X-Forwarded-*
HTTP headers.
The leftmost item in the list describes reverse proxy closest to web application’s host.
IP address or network is specified by strict checking, ...
is
the placeholder for skip checking (should be rightmost element).
In practice ellipsis is secure if used with CloudFlare
only. Cloudflare
checks corresponding proxy against a list of
CloudFlare proxy networks provided by the service at configuration
stage.