Improved readme with dedicated section on filters

README.md

@@ -11,24 +11,29 @@ A little HTTP proxy suitable to create tunnels for webhook endpoints protected b
 
 ## Rationale
 
-If you are doing security properly in your company it's very likely that most of your resources will be
+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 web based tools.
+or other tools with web based integrations.
 
-In such scenarios it becomes tricky to integrate external services (e.g. GitHub) with your internal tools
+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 commit
-on one of the projects your CI is building.
+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.
 
-This tool allows you to create a tunnel that can be used for routing web hooks requests through your
-security layer.
+Webhook-tunnel allows you to create an HTTP tunnel that can be used for routing web hooks requests through your security layers.
 
-This approach, of course, creates a connection channel from the outside to your internal infrastructure,
+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](#filters) to know more about this aspect.
+
+Here's an example configuration that demonstrates how the tunnel can be used:
+
 ![Example CI diagram](/images/ci-example.png)
 
+
 ## Install
 
 From npm:
@@ -95,6 +100,91 @@ Options:
 ```
 
 
+## Filters
+
+Webhook-tunnel supports a number of filters straight away.
+The currently supported filters are:
+
+  - [Ip ranges (CIDR)](#ip-ranges)
+  - [Request Path prefixes](#request-path)
+  - [Query string parameters](#query-string)
+  - [Header parameters](#header)
+  - [HTTP methods](#method)
+
+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:
+
+```bash
+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:
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "webhook-tunnel",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "A little HTTP proxy suitable to create tunnels for webhook endpoints protected behind a firewall or a VPN",
   "main": "src/index.js",
   "bin": {

src/filterRequest.js

@@ -2,7 +2,6 @@ const { parse } = require('url')
 const Netmask = require('netmask').Netmask
 
 const isInCidr = (remoteAddress) => (cidr) => {
-  console.log(cidr, remoteAddress)
   const range = new Netmask(cidr)
   return range.contains(remoteAddress)
 }