Beginner’s Guide: Building a DDoS Detection Tool

    Have you ever heard of a Distributed Denial of Service attack (DDoS attack)? It’s when too many requests hit a website at once, making it crash or slow down. Think of it like hundreds of people rushing into a shop at the same time — the shop can’t handle it. Our tool is like a security guard for your server. It watches traffic, learns what “normal” looks like, spots suspicious spikes, and automatically blocks bad visitors.

  Why this matters:

  • Keeps websites online during attacks.
  • Alerts admins in real time (via Slack).
  • Provides transparency with logs and dashboards.
   Project Diagram:


    What’s inside the Project

Here’s what each folder and file does:

·       detector/ = This is the brain of the tool.

o   main.py = Starts the whole system.

o   monitor.py - Watches incoming traffic.

o   detector.py - Decides if traffic looks normal or dangerous.

o   baseline.py - Learns what “normal” traffic looks like.

o   sliding_window.py - Keeps track of recent activity.

o   blocker.py - Blocks bad IP addresses using firewall rules.

o   unbanner.py - Unblocks IPs after some time.

o   notifier.py - Sends alerts to Slack.

o   dashboard.py - Shows a simple web dashboard with graphs.

o   config.example.yml - A sample settings file (you make your own config.yml)

o   requirements.txt - List of Python packages you need.

    ·  nginx/ = Contains nginx.conf, which is a web server setup file. NGINX helps handle  traffic.

    ·  docs/ = Contains architecture.png, a diagram showing how everything connects.

         Other files:

·        Dockerfile - Instructions to build the app in Docker.

·        docker-compose.yml - Runs multiple services (detector + nginx) together.

·        .gitignore and .dockerignore - Tell Git/Docker which files to ignore.

·        audit.log - Shows what happened (like bans/unbans).

·        README.md - Documentation.

 

    How the Sliding Window Works

    Think of the sliding window as a moving box of time. Instead of looking at all traffic forever, we only look at the last 60 seconds (or whatever window size you set).

  • Every new request goes into the box.
  • Old requests slide out once they’re older than 60 seconds.
  • This way, we always analyze recent activity.

How the Baseline Learns from Traffic

The baseline is like the tool’s memory of normal behavior:

 

·        It watches traffic over time (say 30 minutes).

·        It calculates the average requests per second and the standard deviation (how much traffic usually varies).

·      These numbers become the “normal baseline.”

So if your site usually gets 100 requests/minute, the baseline learns that. If suddenly you get 500 requests/minute, the detector knows something is wrong.

How the Detection Logic Makes a Decision

The detector combines the sliding window and baseline to decide if traffic is dangerous:

·        Z‑score check: If traffic is way above the baseline average (e.g., 3 standard deviations higher), it’s suspicious.

·        Spike factor: If traffic is more than 5× the mean, it’s flagged.

·        Per‑IP threshold: If one IP sends too many requests in 60 seconds, it’s banned.

·        Global threshold: If total requests in 60 seconds exceed a limit, alert is sent.

·        Error multiplier: If error rates (404/500) spike, thresholds tighten.

 

This layered logic reduces false alarms and catches real attacks.

How iptables Blocks an IP

When the detector decides an IP is bad, it calls the blocker. The blocker uses iptables, which is a firewall built into Linux.

This way, attackers are locked out automatically, and honest users can keep browsing.

 How You Can Build This Project.

     Step 1: Install Docker

    On Ubuntu/Debian:

    sudo apt-get update

  sudo apt-get install docker.io docker-compose -y

    Check versions:

    docker --version

    docker-compose --version

    Step 2: Project Setup

Create a folder hng-project with this structure: and create all the folders and files mentioned  earlier and write out all the codes inside.

    Step 3: Dockerfile and docker-compose.yml

Create the Dockerfile and the docker-compose.yml to set up docker

    Step 4: Build & Run

    docker-compose down -v

    docker-compose up -d --build

    Check logs:

    docker logs -f hng-detector

    Step 5: Verify Blocking

  1. Simulate traffic:

bash

ab -n 100 -c 10 http://localhost:8080/

  1. Detector flags IP = Blocker inserts DROP rule.
  2. Verify on host:

sudo iptables -L INPUT -v -n

You should see DROP rules with packet counters increasing.

    Step 5: Dashboard

    Visit:

    http://localhost:8081

See banned IPs, offense counts, and durations.

    Wrap Up

  • Detector watches logs.
  • Blocker enforces bans via iptables.
  • Dashboard shows results.
  • Docker Compose orchestrates everything.

 

 

This project teaches you:

 

·        How to monitor traffic with Python.

·        How to block/unblock IPs with firewall rules.

·        How to send alerts to Slack.

·        How to containerize apps with Docker.

·        How to document projects with diagrams and screenshots.

It’s a beginner-friendly way to learn about cybersecurity, Python, and DevOps all in one

  HERE IS A LINK TO MY GITHUB REPOSITORY INCASE YOU NEED TO CHECK OUT ANY CODES AND FEEL FREE TO CLONE: https://github.com/Godwin-Techie/DDOS-Detection-Tool.git

Erharuyi Godwin

Comments

Post a Comment