项目作者: Kage

项目描述 :
Mojolicious plugin to set the remote address, connection scheme, and more from trusted upstream proxies
高级语言: Perl
项目地址: git://github.com/Kage/Mojolicious-Plugin-TrustedProxy.git
创建时间: 2019-05-28T08:55:07Z
项目社区:https://github.com/Kage/Mojolicious-Plugin-TrustedProxy

开源协议:Other

下载


Build Status
Coverage Status
Kwalitee status
Cpan license
Cpan version
GitHub tag
GitHub issues

NAME

Mojolicious::Plugin::TrustedProxy - Mojolicious plugin to set the remote
address, connection scheme, and more from trusted upstream proxies

VERSION

Version 0.05

SYNOPSIS

  1. use Mojolicious::Lite;
  2. plugin 'TrustedProxy' => {
  3. enabled => 1,
  4. ip_headers => ['x-forwarded-for', 'x-real-ip'],
  5. scheme_headers => ['x-forwarded-proto', 'x-ssl'],
  6. https_values => ['https', 'on', '1', 'true', 'enable', 'enabled'],
  7. parse_rfc7239 => 1,
  8. trusted_sources => ['127.0.0.0/8', '10.0.0.0/8'],
  9. hide_headers => 0,
  10. };
  11. # Example of how you could verify expected functionality
  12. get '/test' => sub {
  13. my $c = shift;
  14. $c->render(json => {
  15. 'tx.remote_address' => $c->tx->remote_address,
  16. 'tx.remote_proxy_address' => $c->tx->remote_proxy_address,
  17. 'req.url.base.scheme' => $c->req->url->base->scheme,
  18. 'req.url.base.host' => $c->req->url->base->host,
  19. 'is_trusted_source' => $c->is_trusted_source,
  20. 'is_trusted_source("1.1.1.1")' => $c->is_trusted_source('1.1.1.1'),
  21. });
  22. };
  23. app->start;

DESCRIPTION

:TrustedProxy">Mojolicious::Plugin::TrustedProxy modifies every Mojolicious request
transaction to override connecting user agent values only when the request
comes from trusted upstream sources. You can specify multiple request headers
where trusted upstream sources define the real user agent IP address or the
real connection scheme, or disable either, and can hide the headers from the
rest of the application if needed.

This plugin provides much of the same functionality as setting
MOJO_REVERSE_PROXY=1, but with more granular control over what headers to
use and what upstream sources can send them. This is especially useful if your
Mojolicious app is directly exposed to the internet, or if it sits behind
multiple upstream proxies. You should therefore ensure your application does
not enable the default Mojolicious reverse proxy handler when using this plugin.

This plugin supports parsing RFC 7239
compliant Forwarded headers, validates all IP addresses, and will
automatically convert RFC-4291 IPv4-to-IPv6 mapped values (useful for when your
Mojolicious listens on both IP versions). Please be aware that Forwarded
headers are only partially supported. More information is available in “BUGS”.

Debug logging can be enabled by setting the MOJO_TRUSTEDPROXY_DEBUG
environment variable. This plugin also adds a remote_proxy_address
attribute into Mojo::Transaction. If a remote IP address override header is
matched from a trusted upstream proxy, then tx->remote_proxy_address
will be set to the IP address of that proxy.

CONFIG

enabled

This allows you to load this plugin to access the helper functions
without automatically running the around_dispatch hook on each request.
Default is 1 (enabled).

ip_headers

List of zero, one, or many HTTP headers where the real user agent IP address
will be defined by the trusted upstream sources. The first matched header is
used. An empty value will disable this and keep the original scheme value.
Default is ['x-forwarded-for', 'x-real-ip'].

If a header is matched in the request, then tx->remote_address is set to
the value, and tx->remote_proxy_address is set to the IP address of the
upstream source.

scheme_headers

List of zero, one, or many HTTP headers where the real user agent connection
scheme will be defined by the trusted upstream sources. The first matched
header is used. An empty value will disable this and keep the original remote
address value. Default is ['x-forwarded-proto', 'x-ssl'].

This tests that the header value is “truthy” but does not contain the literal
barewords http, off, or false. If the header contains any other
“truthy” value, then req->url->base->scheme is set to https.

protocol_headers

Alias for “scheme_headers”.

https_values

List of values to consider as “truthy” when evaluating the headers in
“scheme_headers”. Default is
['https', 'on', '1', 'true', 'enable', 'enabled'].

parse_rfc7239

Enable support for parsing RFC 7239
compliant Forwarded HTTP headers. Default is 1 (enabled).

If a Forwarded header is matched, the following actions occur with the first
semicolon-delimited group of parameters found in the header value:

  • If the for parameter is found, then tx->remote_address is set to the
    first matching value.
  • If the by parameter is found, then tx->remote_proxy_address is set
    to the first matching value, otherwise it is set to the IP address of the
    upstream source.
  • If the proto parameter is found, then req->url->base->scheme is set
    to the first matching value.
  • If the host parameter is found, then req->url->base->host is set to
    the first matching value.

Note! If enabled, the headers defined in “ip_headers” and
“scheme_headers” will be overridden by any corresponding values found in
the Forwarded header.

parse_forwarded

Alias for “parse_rfc7239”.

trusted_sources

List of one or more IP addresses or CIDR classes that are trusted upstream
sources. (Warning! An empty value will trust from all IPv4 sources!) Default
is ['127.0.0.0/8', '10.0.0.0/8'].

Supports all IP, CIDR, and range definition types from :Lite">Net::CIDR::Lite.

hide_headers

Hide all headers defined in “ip_headers”, “scheme_headers”, and
Forwarded from the rest of the application when coming from trusted upstream
sources. Default is 0 (disabled).

HELPERS

is_trusted_source

  1. # From Controller context
  2. sub get_page {
  3. my $c = shift;
  4. if ($c->is_trusted_source || $c->is_trusted_source('1.2.3.4')) {
  5. ...
  6. }
  7. }

Validate if an IP address is in the “trusted_sources” list. If no argument is
provided, then this helper will first check tx->remote_proxy_address
then tx->remote_address. Returns 1 if in the “trusted_sources”
list, 0 if not, or undef if the IP address is invalid.

process_ip_headers

  1. # From Controller context
  2. sub get_page {
  3. my $c = shift;
  4. my $matched_header = $c->process_ip_headers(1);
  5. }

Finds the first matching header from “ip_headers” and sets
tx->remote_address to the value (if a valid IP address), sets
tx->remote_proxy_address to the IP address of the upstream proxy, and
returns a hash of the name and value of the matched header. Otherwise returns
0 if no match is found.

If any “truthy” value is passed as a parameter to this helper, it will first
run the “is_trusted_source” helper (no arguments passed) and will return
undef if it returns a false value.

WARNING! Calling this helper when “enabled” is set to true will likely
produce unexpected results.

process_scheme_headers

  1. # From Controller context
  2. sub get_page {
  3. my $c = shift;
  4. my $matched_header = $c->process_scheme_headers(1);
  5. }

Finds the first matching header from “scheme_headers” and sets
req->url->base->scheme to https if the header value matches any
defined in “https_values”, and returns a hash of the name and value of the
matched header. Otherwise returns 0 if no match is found.

If any “truthy” value is passed as a parameter to this helper, it will first
run the “is_trusted_source” helper (no arguments passed) and will return
undef if it returns a false value.

WARNING! Calling this helper when “enabled” is set to true will likely
produce unexpected results.

process_protocol_headers

Alias for “process_scheme_headers”.

process_rfc7239_header

  1. # From Controller context
  2. sub get_page {
  3. my $c = shift;
  4. my @matched_params = $c->process_rfc7239_header(1);
  5. }

Process an RFC 7239 (“Forwarded”) HTTP header if found. See “parse_rfc7239”
for more details. If the “Forwarded” header is found, this helper will return
an array of hashes of the matched RFC 7239 parameters and values, or 0 if no
matches are found.

If any “truthy” value is passed as a parameter to this helper, it will first
run the “is_trusted_source” helper (no arguments passed) and will return
undef if it returns a false value.

WARNING! Calling this helper when “enabled” is set to true will likely
produce unexpected results.

process_forwarded_header

Alias for “process_rfc7239_header”.

hide_upstream_headers

  1. # From Controller context
  2. sub get_page {
  3. my $c = shift;
  4. $c->hide_headers(1);
  5. }

Remove all headers defined in “ip_headers”, “scheme_headers”, and
Forwarded from the request.

If any “truthy” value is passed as a parameter to this helper, it will first
run the “is_trusted_source” helper (no arguments passed) and will return
undef if it returns a false value.

CDN AND CLOUD SUPPORT

:TrustedProxy">Mojolicious::Plugin::TrustedProxy is compatible with assumedly all
third-party content delivery networks and cloud providers. Below is an
incomplete list of some of the most well-known providers and the recommended
config values to use for them.

Akamai

  • ip_headers

    Set “ip_headers” to ['true-client-ip'] (unless you set this to a different
    value) and enable True Client IP in the origin server behavior for your site
    property. Akamai also supports ['x-forwarded-for'], which is enabled by
    default in :TrustedProxy">Mojolicious::Plugin::TrustedProxy.

  • scheme_headers

    There is no known way to pass this by default with Akamai. It may be possible
    to pass a custom header via a combination of a Site Property variable and a
    custom behavior that injects an outgoing request header based on that variable,
    but this has not been tested or confirmed.

  • trusted_sources

    This is only possible if you have the
    Site Shield
    product from Akamai. If so, set “trusted_sources” to the complete list of
    IPs provided in your Site Shield map.

AWS

  • ip_headers

    The AWS Elastic Load Balancer uses ['x-forwarded-for'], which is enabled by
    default in :TrustedProxy">Mojolicious::Plugin::TrustedProxy.

  • scheme_headers

    The AWS Elastic Load Balancer uses ['x-forwarded-proto'], which is enabled
    by default in :TrustedProxy">Mojolicious::Plugin::TrustedProxy.

  • trusted_sources

    Depending on your setup, this could be one of the 172.x.x.x IP addresses
    or ranges within your Virtual Private Cloud, the IP address(es) of your Elastic
    or Application Load Balancer, or could be the public IP ranges for your AWS
    region. Go to
    https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html for an
    updated list of AWS’s IPv4 and IPv6 CIDR ranges.

Cloudflare

  • ip_headers

    Set “ip_headers” to ['cf-connecting-ip'], or ['true-client-ip'] if
    using an enterprise plan. Cloudflare also supports ['x-forwarded-for'],
    which is enabled by default in :TrustedProxy">Mojolicious::Plugin::TrustedProxy.

  • scheme_headers

    Cloudflare uses the x-forwarded-proto header, which is enabled by default
    in :TrustedProxy">Mojolicious::Plugin::TrustedProxy.

  • trusted_sources

    Go to https://www.cloudflare.com/ips/ for an updated list of Cloudflare’s
    IPv4 and IPv6 CIDR ranges.

SECURITY

Caution should be taken that you set only the “CONFIG” values necessary for
your application in a most-common-first order, and that your upstream proxies
remove any headers you do not want passed through to your application.

For example, if you use Cloudflare and set “ip_headers” to
['x-real-ip', 'cf-connecting-ip'] and did not configure Cloudflare to
remove x-real-ip headers from requests, an attacker could use this trick
your application into using whatever IP he or she defines due to being passed
through your trusted proxy and the x-real-ip header being the first to be
evaluated.

AUTHOR

Kage

BUGS

Please report any bugs or feature requests on Github:
https://github.com/Kage/Mojolicious-Plugin-TrustedProxy

  • Hostnames not supported

    Excluding the host parameter of RFC 7239, this plugin does not currently
    support hostnames or hostname resolution and there are no plans to implement
    this. If you have a use case that requires this, please feel free to submit a
    pull request.

  • HTTP ‘Forwarded’ only partially supported

    Only partial support for RFC 7239 is currently implemented, but this should
    work with most common use cases. The full specification allows for complex
    structures and quoting that is difficult to implement safely. Full RFC support
    is expected to be implemented soon.

SEE ALSO

:RemoteAddr">Mojolicious::Plugin::RemoteAddr, :ClientIP::Pluggable">Mojolicious::Plugin::ClientIP::Pluggable,
Mojolicious, Mojolicious::Guides, http://mojolicio.us.

COPYRIGHT

MIT License

Copyright (c) 2019 Kage

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.