webhook-tunnel

A little HTTP proxy suitable to create tunnels for webhook endpoints protected behind a firewall or a VPN

Rationale

If you are doing security properly in your company, it's very likely that most of your resources will be protected behind a firewall or a VPN, including things like Continuous Integration pipelines (e.g. Jenkins) or other tools with web based integrations.

In such scenarios, it becomes tricky to integrate external services (e.g. GitHub) with your internal tools through web hooks.

For example, it becomes hard to allow GitHub to notify your secured CI instance that there's a new push on one of the projects that your CI is building.

Webhook-tunnel allows you to create an HTTP tunnel that can be used for routing web hooks requests through your security layers.

This approach creates a connection channel from the outside to your internal infrastructure, so be sure to limit the access to the tunnel as much as you can.

To increase the security level of the tunnel, Webhook-tunnel can be configured to apply a number of diffent filters over the HTTP requests and block them from getting into the internal network. Consult the section filters to know more about this aspect.

Here's an example configuration that demonstrates how the tunnel can be used:

Install

From npm:

npm install --global webhook-tunnel

(this requires npm and Node.js version >= 8)

Or you can simply download one of the binaries available in the Releases section.

Note: the compiled executable contains a full-blown version of the Node.js runtime embedded in it. So use this version only if you want to run the tunnel in an environment that does not have a supported version of Node.js already installed.

Execute

To execute the proxy in your server:

webhook-tunnel <target>

Where target is the full URL where every request will be proxied to.

E.g.

webhook-tunnel http://myprivatejenkins.tld/somepath/

By default the server will be bound to 0.0.0.0:12345.

Command line options

This is the full list of supported command line options:

Options:
  --help               Show help                                       [boolean]
  --bind-address, -a   The bind address of the server
                                                   [string] [default: "0.0.0.0"]
  --port, -p           The port on which the server will be listening to
                                                       [number] [default: 12345]
  --expect-cidr, -C    Rejects the request if it is not coming from one of the
                       specified IP ranges (CIDRs)                       [array]
  --expect-path, -P    Rejects the request if it is not addressed to one of the
                       specified path prefixes                           [array]
  --expect-query, -Q   Rejects the request if it doesn't contain any of
                       specified query parameters with a matching value (e.g.
                       token=1234)                                       [array]
  --expect-header, -H  Rejects the request if it doesn't contain any of
                       specified headers with a matching value (e.g.
                       x-token=1234)                                     [array]
  --expect-method, -M  Rejects the request if it is not using one of the
                       specified methods (e.g. `GET`)                    [array]
  --log-level, -l      Logging level (one of 'fatal', 'error', 'warn', 'info',
                       'debug', 'trace' or 'silent')  [string] [default: "info"]
  --version            Show version number                             [boolean]

Filters

Webhook-tunnel supports a number of filters straight away. The currently supported filters are:

• Ip ranges (CIDR)
• Request Path prefixes
• Query string parameters
• Header parameters
• HTTP methods

By default every filter is disabled, so every request can cross the tunnel. For every filter you can specify one or more rules. As soon as you have a rule for a filter, No request can pass the tunnel unless the request matches the rule.

We can recap the internal flow with the following statements:

1. if no filter is used (no rules in every filter), every request can cross the tunnel
2. if you have a rule under a filter, every request is blacklisted, unless it matches the rule
3. if you have a filter with more than one rule, then at least one rule per every filter should be matched to allow the request to cross the tunnel.

IP Ranges

If you want to accept requests that come only from a selected list of IPs you can run the tunnel with the option --expect-cidr. This option allows you to add a rule under the CIDR filter. You can create multiple rules by using the option multiple times.

Example:

webhook-tunnel http://somedonain.tld --expect-cidr 22.23.24.25/22 --expect-cidr 120.25.25.25/22

This way the tunnel will accept only requests coming from 22.23.24.25/22 or 120.25.25.25/22.

Request path

You can restrict the requests being tunneled by path prefix with the option --expect-path. By default all the paths are accepted but you can add one or more path rules as in the following example:

webhook-tunnel http://somedonain.tld --expect-path /path1 --expect-path /path2

With this configuration requests with a prefix path of /path1 and /path2 (e.g. /path1/producs or /path123) will be allowed, while all the other requests will be rejected.

Query string

You can restrict the requests being tunneled by query parameters with the option --expect-query. This option accepts arguments in the form key=value. You can specify multiple --expect-query options and the request will be tunneled only if at least one of the rules is matched.

E.g.

webhook-tunnel http://somedonain.tld --expect-query token=xyz --expect-query auth=admin

With this configuration requests with a query string like ?token=xyz or ?auth=admin will be allowed, while all the other requests will be rejected.

Header

Headers filters behave exactly like query string, except that headers are used for the match. To specify headers rules you have to use the --expect-header option.

Method

You can restrict the requests by HTTP method (get, post, patch, etc.).

To set the method rules you have to use the --expect-method option. You can specify the option multiple times and the request will be tunneled only if at least one of the rules is matched.

E.g.

webhook-tunnel http://somedonain.tld --expect-method get --expect-method post

Will accept only post or get requests.

Contributing

Everyone is very welcome to contribute to this project. You can contribute just by submitting bugs or suggesting improvements by opening an issue on GitHub.

License

Licensed under MIT License. © Luciano Mammino.