Building a Custom DDoS Protection Engine with Nginx and Python

How I Created a DDoS Protection Engine

Wilfrid Okorie developed a custom DDoS protection engine for an HNG14 DevOps task to secure a live Nextcloud server. The system identifies anomalies using z-scores and enforces blocks via host-level iptables.

Why This Matters

While high-level security tools like Fail2Ban are standard, building a custom engine reveals the technical necessity of integrating log parsing with system-level firewall controls. This project demonstrates the reality of containerized security where tools must bypass standard isolation using NET_ADMIN capabilities and host networking to effectively protect the underlying infrastructure from distributed denial-of-service attempts.

Key Insights

• Nginx JSON logging with the escape=json directive prevents special characters from breaking downstream log parsers (Source: Wilfrid Okorie, 2026).
• Baseline calculation involves a 30-minute rolling history to maintain accurate mean and standard deviation metrics for traffic anomaly detection.
• Docker containers require network_mode: host and cap_add: NET_ADMIN to modify the host machine’s iptables rules for effective IP banning.
• Real IP forwarding via the X-Forwarded-For header is essential to prevent the detector from incorrectly identifying the internal proxy IP as the attacker.
• Automated backoff levels in the unbanner thread ensure that repeat offenders face escalating ban durations based on their history in the audit log.

Working Examples

Configuring Nginx to output access logs in a structured JSON format for the detector daemon.

log_format json_log escape=json '{' '"source_ip":"$remote_addr",' '"timestamp":"$time_iso8601",' '"method":"$request_method",' '"path":"$request_uri",' '"status":$status,' '"response_size":$body_bytes_sent' '}'; access_log /var/log/nginx/hng-access.log json_log;

Docker Compose snippet showing the necessary privileges and networking mode for the detector to manage host firewalls.

detector: build: context: ./detector dockerfile: Dockerfile restart: unless-stopped network_mode: host volumes: - HNG-nginx-logs:/var/log/nginx:ro cap_add: - NET_ADMIN

Practical Applications

• Nextcloud Instance Security: Implementing real-time IP blocking on AWS EC2 nodes to protect sensitive file storage from brute-force or flooding attempts. Pitfall: Failing to allow port 5000 in the local UFW firewall can prevent access to the monitoring dashboard even if cloud security groups are correct.
• Automated Incident Alerting: Integrating Slack webhooks to notify SRE teams of active z-score violations and automated ban actions. Pitfall: Committing Slack webhook URLs directly to public repositories exposes the alert system to external manipulation.

References:

• https://dev.to/wilfridk/how-i-created-a-ddos-protection-engine-3kfg