Skip to content
🍹 Nginx DDoS mitigation project
Branch: master
Clone or download
Latest commit a6c21b3 Aug 14, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates Aug 12, 2019
Kumo Added SecurityLevel May 25, 2019
images Create KumoOG.png Aug 14, 2019
.gitattributes Initial commit Apr 30, 2019
.gitignore Initial commit Apr 30, 2019
Kumo.sln Initial commit Apr 30, 2019
LICENSE Create LICENSE Aug 10, 2019 Update Aug 12, 2019

Kumo small logo Kumo - DDoS mitigation

Kumo is a project started in order to provide a free, open-sourced and reliable solution in DDoS mitigation.

While creating Kumo I was thinking about it as a better alternative to fail2ban software. fail2ban is great in blocking abusing users at a small scale but when there are thousands of requests per seconds it starts to struggle quite a lot with CPU spiking to 90%-98% and basically killing the server. Kumo in the same scenario can keep the CPU usage around 1%-5% and it has some nice bonus features like enabling Under Attack Mode in Cloudflare.

πŸ”΄ Requirements

  • .NET Core 2.2
  • Cloudflare
  • Linux server
  • Nginx

πŸ‘¨β€πŸ’» How it works

A basic infographic to better visualise what's going on under the hood.
Please keep in mind that this is a very simplified example.

Kumo infographic

🎑 Features

  • Lightweight & fast
  • Supports both IPv4 and IPv6
  • Mitigates both Layer7 (HTTP) DoS and DDoS attacks
  • Enables Cloudflare Under Attack Mode when massive DDoS is detected (optional)

🏁 Installation

  1. Install .NET Core 2.2 on your machine
  2. Download latest Kumo release and unzip it
  3. Make sure you are fine with where Kumo files are located (you won't be able to move it without full reinstallation)
  4. Open Kumo installation directory (so you can see Kumo.dll etc. files after executing ls command)
  5. Make file executable using sudo chmod +x command
  6. And then execute it with sudo ./
  7. Configure Kumo by editing config.json file (documentation)
  8. Configure Nginx to work with Kumo (tutorial)
  9. Test your configuration with dotnet Kumo.dll command (Ctrl+C to exit)
  10. Start service by running sudo systemctl start kumo

Looking for uninstallation instructions? Click here.

πŸ”§ Configuring Nginx

  1. First of all make sure that the nginx -s reload command is working properly
  2. Edit the Nginx configuration nginx.conf file and add the following line include /etc/nginx/snippets/kumo.conf; (path must be the same as NginxBlockSnippetFile from Kumo config.json file)
  3. Double-check that you have configured Nginx rate limiting properly and that you are getting user's real ip from the Cloudflare header (latest Cloudflare IP ranges)

πŸ“¬ Contact

β˜• Support me

  • Bitcoin: 35n1y9iHePKsVTobs4FJEkbfnBg2NtVbJW
  • Ethereum: 0xc69C7FC9Ce691c95f38798506EfdBB8d14005B67

πŸ› οΈ Documentation

  • CloudflareEmail
    Your cloudlfare account email address

  • CloudflareApiKey
    Your cloudlfare account global API key
    Tutorial - how to find it

  • CloudflareUnderAttackMode
    Enable Cloudflare's Under Attack Mode when massive attack is detected

  • CloudflareModeDefault
    Default security level (switch to it after Under Attack Mode expires) (to use only with CloudflareUnderAttackMode)

  • CloudflareManageZones
    List of zones/websites where Under Attack Mode should be enabled (to use only with CloudflareUnderAttackMode)
    Tutorial - how to find it

Example configuration:

"CloudflareManageZones": [
  "85295678901234567890123456783270" // <-- last one doesn't have a ','
  • BlockNote
    Comment to set in Cloudflare block rule and Nginx block .conf file

  • WatcherTargetFile
    Full path to Nginx error.log file

  • WatcherCheckSleep
    Check for error.log file changes every X milliseconds (2 seconds = 2000)

  • AbuseExpirationTime
    Time after which abuse counter resets to zero (value in seconds, 5 minutes = 300)

  • BlockExpirationTime
    Time after which IP is removed from the blacklist (value in seconds, 3 hours = 10800)

  • BlocksToUnderAttack
    Amount of blocks required in single tick to enable Under Attack Mode (1 tick = WatcherCheckSleep milliseconds) (to use only with CloudflareUnderAttackMode)

  • UnderAttackExpirationTicks
    Ticks after which Under Attack Mode is disabled (1 tick = WatcherCheckSleep milliseconds) (to use only with CloudflareUnderAttackMode)

  • AbusesToBlock
    How many abuses are required to add IP to the blacklist

  • AbusesToBlockUnderAttack
    How many abuses are required to add IP to the blacklist while Under Attack Mode is enabled (to use only with CloudflareUnderAttackMode)

  • NginxBlockSnippetFile
    Full path where Nginx block .conf file will be created

πŸ€” How to find your Cloudflare API key

  1. Login to your Cloudflare account
  2. Go to My Profile
  3. Switch tab to API Tokens and scroll down to API Keys section
  4. Click View button next to Global API Key

Cloudflare API key

❓ How to find your Cloudflare zone ID

  1. Login to your Cloudflare account
  2. Go to overview of your website
  3. Scroll down to API section

Cloudflare zone ID

πŸ‘‹ Uninstallation

  1. Stop and disable Kumo service by executing sudo systemctl stop kumo && sudo systemctl disable kumo
  2. Remove service file with sudo rm /lib/systemd/system/kumo.service
  3. Now you can safely delete all Kumo files

πŸ“ƒ License

Robot vector created by

You can’t perform that action at this time.