CF-Shield – An open source tool to protect any website with Cloudflare

CF-Shield is a Python script for detecting DDoS attacks and enabling security measures on Cloudflare automatically.

Then to run the script, you can use the following command:

or if it is not in your PATH, you can use the following command:

If this fails, you can try using git.

First, you will need to get your Cloudflare email, API token, zone ID, and account ID.

When running the script for the first time, it will ask you for your Cloudflare email, API token, zone ID, and account ID. More info on Setup.

The dependencies should be installed automatically. If not, you can install them manually by running python3 -m pip install -r requirements.txt.

To setup the script, you will need to run the script and follow the prompts. First run the commands on Installation. Here you have a list of what the script will ask you for and what you need to do. The prompts with default: are optional and will be set to the default value if you don't enter anything.

Here is an example of the setup, in diff format for better readability:

Please ignore the + and - signs, they are only for formatting. They are not part of the setup. You should not enter them.

What's the domain(s) you want to use? (default: all, e.g. "example.com,www.example.com" or "example.com")

This is the domain(s) you want to use. You can add multiple domains by separating them with a comma. The domains must be on the same Zone (meaning a single WAF rule can be applied to all of them).

If you want to use all domains in the zone, you can enter all.

If you change this after the inital setup, you will need to remove the rule from the dashboard and run the script again.

What's the email you used to sign up for Cloudflare? (e.g. [email protected])

This must be the email you used to sign up for Cloudflare. You can find it here.

Please create an API token and copy it here (e.g. aK-MaF3oyTrPDD8YoNBlvqo0ous7BOeSA7te84OR)

This is the API token you need to create. You can create it here. There is a guide here. You need to create a token with Zone WAF Write permissions. It should be 40 characters long and only contain letters, numbers and dashes.

Please copy the zone ID from the URL of your Cloudflare dashboard (e.g. 1b7c0e3d41f09ceb9cbcde6b0c7bc819)

This is the zone ID you need to copy from the URL of your Cloudflare dashboard. You can find it here. It should be 32 characters long and only contain letters and numbers.

Please copy the account ID from the URL of your Cloudflare dashboard (e.g. 6dead821d9eb4c42f8a8dda399651660)

The account ID can be found below the zone ID. It should not be the same as the zone ID. If you can't find it, there is more info here. It should be 32 characters long and only contain letters and numbers.

Please enter the CPU usage threshold in percentage (default: 80)

This is the CPU usage threshold you want to use. The script will enable the challenge rule if the CPU usage is greater than this threshold. It should be a number between 0 and 100. It is advised to set it to a value between 50 and 90 depending on your server's performance and average load.

What's the challenge type you want to use? (default: managed_challenge, options: managed_challenge, js_challenge, challenge)

This is the challenge type you want to use. You can choose between managed_challenge, js_challenge and challenge.

js_challenge is a challenge that uses JavaScript to detect bots. It is the fastest challenge type to load, but it is also not as effective as challenge or managed_challenge.

challenge is a challenge that uses a CAPTCHA to detect bots, it was the first challenge type to be released by Cloudflare. It is the most effective challenge type, but it is also the most resource intensive and slowest to load.

managed_challenge is the default challenge type. Cloudflare will choose to use js_challenge or challenge based on how likely it thinks the request is a bot.

Usually it is best to start with managed_challenge and then switch to challenge if the bots are still able to bypass the challenge.

If you change this after the inital setup, you will need to remove the rule from the dashboard and run the script again.

If you want to use a Discord webhook, please enter the webhook URL (default: None)

This is the Discord webhook URL you want to use. You can find a guide here. It should be a valid Discord webhook URL. You will get messages when the challenge is enabled or disabled.

If you don't want to use a Discord webhook, you can leave it blank.

If you want to use a custom message for the attack start, please enter the message (default: The CPU usage is too high, enabling challenge rule for example.com...)

This is the custom message you want to use when the CPU usage is too high.

If you don't want to use a custom message, you can leave it blank.

If you want to use a custom message for the attack end, please enter the message (default: The CPU usage is back to normal, disabling challenge rule for example.com...)

This is the custom message you want to use when the CPU usage is back to normal.

If you don't want to use a custom message, you can leave it blank.

If you want to use a custom message, please enter the message (default: The CPU usage is still too high, the challenge rule might not be working...)

This is the custom message you want to use when the CPU usage is still too high 10 seconds after the attack started.

If you don't want to use a custom message, you can leave it blank.

If you want to use a Telegram bot, please enter the bot token (default: None)

This is the Telegram bot token you want to use. You can find a guide here. It should be a valid Telegram bot token. You will get messages when the challenge is enabled or disabled. If you set a bot token, you will also need to set a chat ID.

If you don't want to get Telegram notifications, you can leave it blank.

Please enter the chat ID for the telegram bot (default: None)

This is the chat ID you want to use. You can find a guide here. It should be a valid Telegram chat ID. You will get messages when the challenge is enabled or disabled. If you set a bot token, you will also need to set a chat ID.

If you haven't set a bot token, you will not see this prompt.

If you want to use a custom message for the attack start, please enter the message (default: The CPU usage is too high, enabling challenge rule for example.com...)

This is the custom message you want to use when the CPU usage is too high.

If you don't want to use a custom message, you can leave it blank.

If you want to use a custom message for the attack end, please enter the message (default: The CPU usage is back to normal, disabling challenge rule for example.com...)

This is the custom message you want to use when the CPU usage is back to normal.

If you don't want to use a custom message, you can leave it blank.

If you want to use a custom message for when the CPU usage is too high 10 seconds after the attack started, please enter the message (default: The CPU usage is still too high, the challenge rule might not be working...)

This is the custom message you want to use when the CPU usage is still too high 10 seconds after the attack started.

If you don't want to use a custom message, you can leave it blank.

If you want to use a Slack webhook, please enter the webhook URL (default: None)

This is the Slack webhook URL you want to use. You can find a guide here. It should be a valid Slack webhook URL. You will get messages when the challenge is enabled or disabled.

If you don't want to use a Slack webhook, you can leave it blank.

If you want to use a custom message for the attack start, please enter the message (default: The CPU usage is too high, enabling challenge rule for example.com...)

This is the custom message you want to use when the CPU usage is too high.

If you don't want to use a custom message, you can leave it blank.

If you want to use a custom message for the attack end, please enter the message (default: The CPU usage is back to normal, disabling challenge rule for example.com...)

This is the custom message you want to use when the CPU usage is back to normal.

If you don't want to use a custom message, you can leave it blank.

If you want to use a custom message for when the CPU usage is too high 10 seconds after the attack started, please enter the message (default: The CPU usage is still too high, the challenge rule might not be working...)

This is the custom message you want to use when the CPU usage is still too high 10 seconds after the attack started.

If you don't want to use a custom message, you can leave it blank.

How many seconds do you want to wait before disabling the challenge rule? (default: auto eg. 30)

This is the delay in seconds you want to use before disabling the challenge rule. This is to avoid the rule to be disabled and enabled fast when the CPU lowers because of the challenge. It should be a number between 0 and infinity. But it is advised to set it to a value between 5 and 1800. You can also set it to "auto" and the script will choose the value dynamically.

Do you want to use averaged CPU monitoring? (default: yes)

Setting this to "yes" uses the last 10 values of the CPU to calculate the average CPU usage. This is to avoid the script to detect a CPU spike when there is no attack.

On the next setting you can configure the range of the averaged CPU monitoring to be something else than 10.

Please enter the range of the averaged CPU monitoring (default: 10)

This is the range of the averaged CPU monitoring. It should be a number between 2 and 120. It is advised to set it to a value between 5 and 30.

or if it is not in your PATH, you can use the following command:

Or if it doesn't work, you can install it using git. (See Installation) and then run the following command:

To modify the config after the inital setup, you can edit the .env file or use the setup argument like this (See Setup):

• Adding a way to add multiple domains.
• Making the challenge type customizable instead of managed_challenge.
• Discord webhook notifications.
• Adding a configurable delay before disabling the challenge rule.
• Telegram notifications.
• Full guide in the README.md.
• A way to use all domains in the zone.
• Slack notifications.
• Set disable delay automatically.
• Averaged CPU monitoring option.
• Customizable alert messages.
• Send an alert when the challenge rule does not make the CPU usage go down.
• Trigger based on network traffic.
• Placeholders on the custom alert messages.
• Add ntfy.sh notifications.
• Automated CPU spike detection option.
• Add ratelimit challenge.

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

GPL-3.0