Attention

This is the lite version of balooProxy. Instead of net/http it uses gofiber as to increase performance at the cost of features. This version only supports http/1(.1) and some custom firewall fields might not be supported

Features

TLS-Fingerprinting

TLS Fingerprinting opens a whole new world of possibilities to defend against malicious attacks.

On one hand you can use tls fingerprinting to whitelist specific fingerprints, take for example seo bots, blacklist unwanted fingerprints, like for example wordpress exploit crawlers, ratelimit attackers that use proxies to change their ips or just simply gain more information about a visitor

Staged DDoS-Mitigation

balooProxy comes with 3 distinct challenges, in order to defend against bots/ddos attacks effectively, whilst effecting an actual users experience as little as possible. In order to archive that, balooProxy starts with the "weakest" and least notable challenge and automatically changes them when it detects one of them is being bypassed

Cookie Challenge

The cookie challenge is completely invisible and supported by every webbrowser, aswell as most http libraries. It is an effective method to defend against simple ddos attacks

Invisible JS Challenge

The invisible js challenge allows you to reliably block slightly more advanced bots while impacting the user experience as little as possible

Custom Captcha

The custom captcha should be your last resort or be used to protect especially weak webpages.

DDoS Alerts

Always be informed when you are under attack of a (D)DoS attack with customisable discord alerts.

For more information on how to customise discord alerts refeer to

Lightweight

balooProxy tries to be as lightweight as possible, in order to run smoothly for everyone. Everything has its limits tho.

Cloudflare Mode

Not everyone can afford expensive servers, aswell as a global cdn and this is fine. That's why balooProxy supports being used along with cloudflare, although this comes at the cost of a few features, like tls fingerprinting.

Installation

Server Setup

To start, download the latest version of balooProxy balooProxy or compile it from source.

If you already have a config.json drag it in the same folder in your server as the main you downloaded/compiled. If you do not, simply start balooProxy by running ./main and answer the questions the proxy asks you. After you answered those questions stop the proxy with ctrl + c.

You can run the proxy as a service or inside of a screen. To run the proxy inside a screen on ubuntu/debian first run apt update. After that is done install screen by running apt install screen and follow its installation process. To start running the proxy inside of a screen run screen -S balooProxy. This will put you inside a screen, making sure the proxy keeps running even when you log out of ssh. Now just start the proxy inside the screen by running ./main (make sure the proxy isnt running anywhere else already) and quit the screen by pressing ctrl + a + d. You can always reopen the screen by running screen -d -r

DNS Setup

The proxy is now successfully running, however you still need to point your dns records to the proxy. To do so get the servers ip the proxy is currently running on. Go to your dns management and point the domain you want to proxy to the proxy ip via an A record, if the ip is an ipv4 or an AAAA record, if the ip is an ipv6. If you chose to use the proxy with Cloudflare, make sure the option "Proxy status" is set to "Proxied". If you chose not to use Cloudflare but are managing the dns via Cloudflare, make sure "Proxy status" is set to "DNS only". Also make sure no other records are pointing to your actual backend, since the proxy can otherwise be bypassed by attacking the backend directly, without first going through the proxy. After you did all of that wait ~10 minutes for the dns entry to register. You can check if your domain is successfully proxied by opening a new tab in the browser of your choice, opening dev tools, navigating to the network tab, opening your website, and searching for a "baloo-proxy" header in "Response Headers" of your request. If that exist, you successfully setup balooProxy

Configuration

---

The config.json allows you to change several features and values about balooProxy. There are three main fields, proxy, domains and rules.

Proxy

---

This field specifically allows you to change general settings about balooProxy

cloudflare ^Bool

If this field is set to true balooProxy will be in cloudflare mode. (NOTE: SSL/TLS encryption mode in your cloudflare settings has to be set to "Flexible". Enabeling this mode without using cloudflare will also not work. Additionally, some features, such as TLS-Fingerprinting will not work and always return "Cloudflare")

maxLogLength ^Int

This field sets the amount of logs entires shown in the ssh terminal

secret ^{Map[String]String}

This field allows you to set the secret keys for the cookie, js and captcha challenge. It is highly advised to change the default values using a tool to generate secure secrets

ratelimits ^{Map[String]Int}

This field allows you to set the different ratelimit values

requests: Amount of requests a single ip can send within 2 minutes

unknownFingerprint: Amount of requests a single unknown fingerprint can send within 2 minutes

challengeFailures: Amount of times a single ip can fail a challenge within 2 minutes

noRequestsSent: Amount of times a single ip can open a tcp connection without making http requests

Domains

---

This field specifically allows you to change settings for a specific domain

name ^String

The domains name (For example example.com)

scheme ^String

The scheme balooProxy should use to communicate with your backend (Can be http or https. Generally you should use http as it is faster and less cpu intensive)

backend ^String

Your backends ip (Note: You can specify ports by using the following format 1.1.1.1:8888)

certificate ^String

Path to your ssl certificate (For example server.crt or /certificates/example.com.crt)

key ^String

Path to your ssl private key (For example server.key or /keys/example.com.key)

webhook ^{Map[String]String}

This field allows you to customise/enable discord DDoS alert notifications. It should be noted, discord alerts only get sent when the stage is not locked aswell as only when the first stage is bypassed and when the attack ended.

url: The webhook url the alert should be sent to. Refer to Discords Introduction To Webhooks for more information.

name: The name your alert should have displayed above it in discord

avatar: Url to the profile picture your alert should have inside discord

attack_start_msg: The message the alert should send when your domain is first under attack. Notice: you can use placeholders, like {{domain.name}}, {{attack.start}}, {{attack.end}}, {{proxy.cpu}} and {{proxy.ram}} here

attack_end_msg: The message the alert should send when your domain is no longer under attack. Notice: you can use placeholders, like {{domain.name}}, {{attack.start}}, {{attack.end}}, {{proxy.cpu}} and {{proxy.ram}} here

Firewall Rules

---

Refer to Custom Firewall Rules

Terminal

Main Hud

---

The main hud shows you different information about your proxy

cpu

Shows you the current cpu usage of the server balooProxy is running on in percent

stage

Shows you the stage balooProxy is currently in

stage locked

Shows true if the stage was manually set and locked by using the stage command in the terminal

total

Shows the number of all incoming requests per second to balooProxy

bypassed

Shows the number of requests per second that passed balooProxy and have been forwarded to the backend

connections

Shows the current amount of open L4 connections to balooProxy

latest logs

Shows information about the last requests that passed balooProxy (The amount can be specified in config.json)

Commands

---

The terminal allows you to input commands which change the behaviour of balooProxy

help

The command help shows you a quick summary of all available commands. Type anything or press enter to exit it

stage

The command stage followed by a number will set the proxies stage to said number (Note: Setting the stage manually means the proxy will remain in that stage no matter what. Even if an attack is ongoing that bypasses this stage. Setting your stage to 0 will set the stage to 1 and enable automatic stage-switching again. Setting the stage to a number higher than 3 will result in all requests getting blocked)

domain

The command domain followed by the name of a domain allows you to switch between your domains

add

The command add prompts you with questions to add another domain to your proxy (Note: This can be done in the config.json aswell, however that currently requires your proxy to restart to apply the changes)

rtlogs

The command rtlogs enables "real time logs", meaning the terminal log will not, like usually, update every second with the latest logs but will instead instantly update, as soon as there is another request to log. Notice, this might require a lot of cpu when your proxy is getting attacked

reload

The command reload will cause the proxy to read the config.json again, aswell as reset some other generic settings, in order to apply changes from your config.json (NOTE: This is automatically executed every 5 hours)

Custom Firewall Rules

Thanks to gofilter balooProxy allows you to add your own firewall rules by using a ruleset engine based on wireguards display filter expressions

Fields

---

ip.src ^IP

Represents the clients ip address

ip.engine ^String

Represents the clients browser ("") if not applicable

ip.bot ^String

Represents the bots name ("") if not applicable

ip.fingerprint ^String

Represents the clients raw tls fingerprint

ip.http_requests ^Int

Represents the clients total forwarded http requests in the last 2 minutes

ip.challenge_requests ^Int

Represents the clients total attempts at solving a challenge in the last 2 minutes

http.host ^String

Represents the hostname of the current domain

http.version ^String

Represents the http version used by the client (either HTTP/1.1 or HTTP/2)

http.method ^String

Represents the http method used by the client (all capital)

http.query ^String

Represents the raw query string sent by the client

http.path ^String

Represents the path requested by the client (e.g. /pictures/dogs)

http.user_agent ^String

Represents the user-agent sent by the client (Important: will always be lowercase)

http.cookie ^String

Represents the cookie string sent by the client

http.headers ^{Map[String]String}

Represents the headers send by the client (Do not use!. Not production ready)

proxy.stage ^Int

Represents the stage the reverse proxy is currently in

proxy.cloudflare ^Bool

Returns true if the proxy is in cloudflare mode

proxy.stage_locked ^Bool

Returns true if the stage is locked to a specific stage

proxy.attack ^Bool

Returns true if the proxy is under attack

proxy.bypass_attack ^Bool

Returns true if the proxy is getting attacked by an attack that bypasses the current security measures

proxy.rps ^Int

Represents the number of currently incoming requests per second

proxy.rps_allowed ^Int

Represents the number of currently incoming requests per second forwarded to the backend

Comparison Operatos

---

Check if two values are identical

eq, ==

(http.path eq "/")

(http.path == "/")

Check if two values are not identical

ne, !=

(http.path ne "/")

(http.path != "/")

Check if the value to the left is bigger than the value to the right

gt, >

(proxy.rps gt 200)

(proxy.rps > 200)

Check if the value to the right is bigger than the value to the left

`lt