Templarbit

Templarbit Resources

Welcome to the Templarbit developer resources. You'll find comprehensive guides and documentation to help you start securing your applications and websites with Templarbit as quickly as possible. Let's jump right in!

Get Started

Behind Load Balancers

It's common to run your application behind a Load Balancer to distribute the ingress traffic across multiple instances. The Templarbit Agents supports both L4 (TCP) and L7 (HTTP/HTTPS) Load Balancers, but needs help discovering the real IP address of the connecting client.

L7 HTTP/HTTPS Load Balancers

Check the manual of your Load Balancer

Only trust headers that are set, updated or managed by your Load Balancer. An attacker's request can include fake headers which need to be sanitized.

If the Templarbit Agent is running behind one or more (reverse) proxies, it needs help discovering the real client IP. Make sure to configure the Templarbit Agent with the following settings depending on your setup.

This is necessary because an attacker can easily manipulate request headers, and thereby potentially pretend to come from a different IP address.

--trust-proxy-ips string

Comma separated list of trusted proxy IP addresses

--trust-x-real-ip-header

Trust contents of X-Real-IP header

--trust-forwarded-header

Trust contents of Forwarded header

--trust-x-forwarded-for-header

Trust contents of X-Forwarded-For header

Example configurations

If your Load Balancer takes care of the real IP detection and then forwards a X-Real-IP header, you can trust this header by using the --trust-x-real-ip-header configuration:

templarbit-agent --trust-x-real-ip-header

If your Load Balancer sets or updates the Forwarded or X-Forwarded-For header, we can instruct the Templarbit Agent to use those headers but the --trust-proxy-ips has to be configured as well. The following setup considers client IPs from the Forwarded and X-Forwarded-For headers. Unfortunately the format of X-Forwarded-For can differ, depending on your Load Balancer. The commonly accepted practice for the X-Forwarded-For header is to read all given IPs from right to left and take the first unknown (meaning not trusted) public IP. The Templarbit Agent will ignore any private IPs found in the headers.

templarbit-agent --trust-proxy-ips "10.0.0.5, 10.0.0.6" --trust-forwarded-header --trust-x-forwarded-for-header

Additionally, if you use multiple proxies in front of your application, make sure that the chain of trusted headers is set up correctly.

L4 TCP Load Balancers

The Templarbit Agent works behind TCP Load Balancers, but needs help discovering the real client IP. Most TCP Load Balancers support the PROXY protocol. Templarbit understands the PROXY protocol version 1. You will have to manually allow the usage of the PROXY protocol.

--trust-tcp-proxy-protocol

Trust TCP PROXY protocol

Verify configuration

You can start the Templarbit Agent with --debug-client-ips, make HTTP requests and then follow the logs. Example output:

2018/09/06 21:29:48 proxy.go:130: Debug: Client IP: 74.115.209.58
2018/09/06 21:29:52 proxy.go:130: Debug: Client IP: 86.89.142.9

Please remove the flag in production.