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

PoW JS Challenge

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

• Difficulty 5: ~3.100 Seconds
• Difficulty 4: ~0.247 Seconds
• Difficulty 3: ~0.244 Seconds
• Difficulty 2: ~0.215 Seconds
• Difficulty 1: ~0.212 Seconds

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.

Running

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

Docker Setup

To use balooProxy with Docker, start by executing the ./main file to generate a config.json. Next, build the Docker image by running docker build -t baloo-proxy . in the same folder as the main file. Once the build is complete, run the Docker image using docker run -d -p 80:80 -p 443:443 -t baloo-proxy. To access the terminal of the Docker image, use docker attach CONTAINERID. The container ID can be obtained by running docker ps. To detach from the terminal, press Ctrl + p + q. To stop the container, run docker stop CONTAINERID. To remove the container, use docker rm CONTAINERID, and to remove the image, run docker rmi baloo-proxy.

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