balooProxy is designed to be as minimalistic as possible. It can be run effectively on extremely cheap servers (which is not to say it has infinite performance. Worse servers will have less performance).

If you find anything that can be improved in the source code, feel free to let me know and/or open a pull request/issue.

balooProxy has 3 different stages in order to automatically mitigate DDoS attacks. When your website is under attack and the stage is not locked to a specific stage, balooProxy will automatically engage the next stage once your configured threshold has been hit and disengage it once it deems the attack to be over.

This stage is the default stage and always on. It will challenge visitors with an invisible cookie challenge which is invisible to browsers and can be passed by most good bots. If you want to whitelist specific requests from this challenge use domain specific custom firewall rules for that.

This stage will be engaged if you manually set it or stage 1 gets bypassed. It will present every visitor with an invisible javascript challenge. Browsers will not be able to see it, however automated requests, good or bad, will most likely not pass it autmatically. Use domain specific custom firewall rules in order to whitelist good bots from this challenge.

This stage will be engaged when both stage 1 and stage 2 have been bypassed. It will present every visitor with a text based captcha. This will stop almost every attack but can also be annoying to users. Use domain specific custom firewall rules in order to whitelist requests.

balooProxy gives you the ability to configure your own firewall rules in the config.json in order to make balooProxy even more effective at blocking unwanted requests specifically for your website(s) and/or whitelist certain requests. For more information refer to Custom Firewall Rules.

balooProxy automatically fingerprints every request passively using tls fingerprints. This allows you to block or whitelist certain tls fingerprints to make your custom firewal rules even harder to bypass and only allow good and wanted visitors/bots.

balooProxy can globaly ratelimit spamming IPs, aswell as tls fingerprints. BalooProxy gives you the option to block spamming IPs or IPs that failed challenges multiple times for 2 minutes. It also gives you the ability to ratelimit unknown tls fingerprints. All of these thresholds can be configured in the config.json (Note: These ratelimits are global. If your proxy proxies multiple domains, a ratelimited IP/Fingerprint will be banned for 2 minutes on all of them).

balooProxy can automatically send alerts to a discord webhook whenever your website is getting attacked by a bypassing attack aswell as more detailed alerts after your website is no longer getting attacked that include a graph showing total and allowed requests over time.

You can use balooProxy behind cloudflare in order to hide your IPv4 address (Note: Some features might not work in cloudflare mode. Refer to Installation).

You can change almost every setting about balooProxy in your config.json.

In order to install balooProxy you need the config.json aswell as the compiled version of balooProxy.

The config.json allows you to change several features and values about balooProxy. There are three main fields, proxy, domains and rules. Example configurations can be found in the config.json.

This field specifically allows you to change general settings about balooProxy.

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").

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

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.

This field allows you to set the different ratelimit values. (Note: These ratelimits are global and not ment to be used for individual sites. These ratelimits are supposed to protect your proxy from wasting cpu on spamming requests).

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.

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

The domains name (For example example.com)

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)

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

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

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

This field allows you to modify your alert webhooks. Every time a domain is attacked by an attack that bypasses at least stage 1, balooProxy will send a discord webhook alert. Once when your domain comes under attack and a more detailed alert with a graph after the attack is over.

url: The url the alert will be sent to (Leave empty if you don't want webhook alerts)

name: Webhook name

avatar: Url to webhook profile picture

attack_start_msg: Message that should be displayed when the website is getting attacked (Note: {{domain.name}} will get replaced with your domain name. For example "The website {{domain.name}} is under attack" will display as "The website example.com is under attack").

attack_stop_msg: Message that should be displayed when the website is no longer getting attacked (Note: {{domain.name}} will be replaced with your domain name here aswell)

Allows you to configure custom firewall rules for every domain. For more information refer to Custom Firewall Rules

Allows you to configure the threshold of allowed requests per second at which balooProxy should consider stage 1 to be bypassed and switch to stage 2 (JS Challenge)

Allows you to configure the threshold of allowed requests per second at which balooProxy should consider stage 2 to be bypassed and switch to stage 3 (Captcha)

If the number of allowed requests per second is lower than this one and if disableRawStage3 is also true, balooProxy disables stage 3 and engages stage 2

If the number of total requests per second is lower than this one and if disableBypassStage3 is also true, balooProxy disables stage 3 and engages stage 2

If the number of allowed requests per second is lower than this one and if disableRawStage2 is also true, balooProxy disables stage 2 and engages stage 1

If the number of total requests per second is lower than this one and if disableBypassStage2 is also true, balooProxy disables stage 2 and engages stage 1

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

Represents the clients ip address

Represents the clients browser ("") if not applicable

Represents the bots name ("") if not applicable

Represents the clients raw tls fingerprint

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

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

Represents the hostname of the current domain

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

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

Represents the raw query string sent by the client

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

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

Represents the cookie string sent by the client

Represents the headers send by the client in Map format as a string

Represents the stage the reverse proxy is currently in

Returns true if the proxy is in cloudflare mode

Returns true if the stage is locked to a specific stage

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

Represents the number of currently incoming requests per second

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

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, <

(proxy.rps lt 10)

(proxy.rps < 10)

Check if value to the left is bigger or equal to the value to the right

ge, >=

(proxy.rps_bypassed ge 50)

(proxy.rps_bypassed >= 50)

Check if value to the right is bigger or equal to the value to the left

le, <=

(proxy.rps_bypassed le 50)

(proxy.rps_bypassed <= 50)

Require both comparisons to return true

and, &&

(http.path eq "/" and http.query eq "")

(http.path eq "/" && http.query eq "")

Require either one of the comparisons to return true

or, ||

(http.path eq "/" or http.query eq "/alternative")

(http.path eq "/" || http.query eq "/alternative")

Require comparison to return false to be true

not, !

!(http.path eq "/" and http.query eq "")

not(http.path eq "/" && http.query eq "")

Returns true if field contains value

contains

(http.user_agent contains "chrome")

Returns true if field matches a regex expression

matches

(http.header matches "(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*\W)")

Firewall rules are build in the config.json and have the following structure

"rules": [
        {
            "expression": "(http.path eq \"/captcha\")",
            "action": "3"
        },
        {
            "expression": "(http.path eq \"/curl\" and ip.bot eq \"Curl\")",
            "action": "0"
        }
    ]

Every individual has to have the expression and action field.

Rules are priorities from top to bottom in the config.json. A role has priority over every rule coming after it in the json.

(Note: As will later be described, some rules will stop balooProxy from checking for other matching rules. This is why it is recommended to have rules with higher action values be higher in the json aswell.)

The resulting action to a rule is decided based on the "susLv", which is a scale from 0-3 how suspicious/malicious the request is. The susLv itself starts of at the current stage balooProxy is in. This is normally 1 but might change to 2 and 3 depending on how many bypassing requests balooProxy currently experiences.

Each number has its own reaction.

The request is whitelisted and will not be challenged in any form

The request will be challenged with a simple cookie challenge which will be passed automatically by most good bots

The request will be challenged with a javascript challenge which will stop most bots, including good once

The request will be challenged with a visual captcha. The user will have to input text he sees on a picture. Will stop most malicious requests aswell as good bots

Every request with a susLv of 4 or higher will be blocked

You can set a rules action to be a specific action by setting it's action to a specific number

(Note: If a rule matches a request and sets the action to a specific number balooProxy will not check for other matching rules. Hence you should usually give rules with a higher action value a lower priority value aswell).

{
    "expression": "(http.host contains \":\")",
    "action": "3"
}

In this example, the rule checks whether or not the request is made by a socket and if so, challenges the request with a captcha. (Note: With balooProxy 1.0 the current domain management system doesnt allow port specifications if they have not been specified in the config.json, making this rule useless at the moment)

You can also set actions more dynamically by using a + in front of the action value. This will tell balooProxy that you want to increase the current susLv of the request by the amount specified after the +.

(Note: actions that use a + do not stop balooProxy from checking if further rules match, if the rule matches. This allows you to stack multiple checks ontop of each other and set reactions more dynamically and react less aggressively when not attacked)

{
    "expression": "(http.engine eq \"\")",
    "action": "+1"
}

In this example, the rule checks whether or not the request is made by a known browser. If not, the susLv gets raised by 1.

Similar to using + can also set a - in front of the action value. This will tell balooProxy that you want to decrease the current susLv of the request by the amount specified after the -.

{
    "expression": "(proxy.stage eq 3 and http.useragent contains \"windows\")",
    "action": "-1"
}

In this example, the rule checks whether or not the request is made by a Windows useragent when the stage is 3 and decreases the susLv by one, making it not show a captcha for Windows users but also not skipping rules that might come after this rule

{
    "expression": "(proxy.stage eq 1)",
    "action": "-1"
}

This rule will disable stage 1 for every request but still keep the auto mitigation active, aswell as allow other rules that might follow after it or were in front of it, to still be considered

{
    "expression": "((ip.engine eq \"Firefox\" and http.user_agent contains \"chrome\") or (ip.engine eq \"Chromium\" and http.user_agent contains \"firefox\"))",
    "action": "3"
}

This rule checks if the useragent missmatches the browser engine associated with the tls fingerprint. If so, the request gets presented with a captcha.

{
    "expression": "(http.path eq \"/curl\" and ip.bot eq \"Curl\")",
    "action": "0"
},
{
    "expression": "(http.path eq \"/curl\")",
    "action": "4"
}

This rule-chain only allows Curl to make requests to the path /curl

The main hud shows you different information about your proxy

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

Shows you the domain name you are currently inspecting

Shows you the stage balooProxy is currently in

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

Shows the number of all incoming requests per second to balooProxy

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

Shows the current amount of open L4 connections to balooProxy

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

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

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)

The command domain followed by a domain name will make the proxy display the statistics of said domain. Other changes, such as the stage command will also now apply to this domain. Only typing "domain" followed by nothing else will list the available domains currently loaded in balooProxy. By default the proxy starts on the first domain in your config.json