Immution - Bot Protection for LAMP Stack

immution

JavaScript-free bot protection for LAMP stack

IN TESTING PHASE

An open-source solution to block malicious bots by analyzing server log files, without client-side JavaScript. No additional software required - only Python 3 and PHP 8 standard libraries.

NO JAVASCRIPT REQUIRED • NO EXTERNAL DEPENDENCIES

What is Immution?

Immution is an open-source software designed to protect LAMP (Linux, Apache, MySQL, PHP) stack websites from malicious bots and automated attacks. Unlike other solutions, Immution works entirely server-side by analyzing log files, requiring no JavaScript execution on the client side.

Real-time Analysis

Monitors Apache access logs as requests happen with multi-site support and auto-discovery of log files.

Zero Dependencies

Only requires Python 3 and PHP 8 standard libraries. No additional software installation needed.

Advanced Optimization

Features like sharded locks, write buffering, lazy writes, and bloom filters for maximum performance.

Memory-Mapped Ban Checks

PHP performs O(1) lookups against a memory-mapped banned IP table for ultra-fast blocking.

Performance Optimizations

Immution includes advanced optimizations that require no additional software - only Python 3 and PHP 8 standard libraries:

Optimization	Description	Improvement
Sharded Locks	Divide cache into 16 shards with separate locks to reduce contention	2-4x throughput
Write Buffering	Buffer writes in memory and flush periodically (every 50 updates or 2 seconds)	10x fewer disk writes
Lazy Writes	Only write when score changes by ≥5 points or ban status changes	5x fewer writes for legitimate traffic
Bloom Filter	Track "clean" IPs to skip file reads for legitimate traffic	50% fewer file reads
Memory-Mapped Bans	PHP reads directly from mmap file - O(1) lookup without JSON parsing	100x faster ban checks

Expected Performance Metrics

Disk Writes

Original: 1000/sec

Optimized: 50-100/sec

Improvement: 10-20x fewer writes

Ban Check Latency

Original: ~2ms

Optimized: ~0.02ms

Improvement: 100x faster

Cache Contention

Original: High

Optimized: Low

Improvement: 4x throughput

# Example: Memory-mapped banned IP table (Python + PHP)
# File structure (512KB):
# ┌─────────────────────────────────────────┐
# │ Entry 0: [4B checksum][4B timestamp]    │
# │ Entry 1: [4B checksum][4B timestamp]    │
# │ ...                                     │
# │ Entry 65535: [4B checksum][4B timestamp]│
# └─────────────────────────────────────────┘

# PHP lookup (O(1)):
$idx = md5_hash($ip) % 65536;
$entry = substr($mmap, $idx * 8, 8);
$is_banned = (checksum_matches($entry, $ip));

How It Works

Architecture Overview

┌─────────────────┐
│  Apache Logs    │──── tail -f ────▶┌─────────────────┐
│  (multi-site)   │     (threads)    │  Python Daemon  │
└─────────────────┘                  │    (immution)   │
                                     └────────┬────────┘
                                              │
                                              ▼
                                     ┌─────────────────┐
                                     │   /dev/shm/     │
                                     │    immution/    │
                                     │   {ip}.txt      │
                                     └────────┬────────┘
                                              │
┌─────────────────┐                           │
│  HTTP Request   │                           │
└────────┬────────┘                           │
         │                                    │
         ▼                                    ▼
┌─────────────────┐      reads       ┌─────────────────┐
│    gate.php     │◀─────────────────│   IP Data File  │
│ (auto_prepend)  │                  │   score, banned │
└────────┬────────┘                  └─────────────────┘
         │
         ├── banned=true ──▶ Log to CSV + Show 403 + exit()
         │
         └── banned=false ─▶ Continue to PHP script

Detection Criteria

Scoring Events

404 Error: +2 points (increases with frequency)
Suspicious Path: +6 points
Missing User-Agent: +8 points
Known Bot User-Agent: +12 points
Soft Request Burst (>25 req/10s): +10 points
Hard Request Burst (>60 req/10s): +25 points

System Parameters

Ban Threshold: ≥ 50 points
Score Decay: Half-life of 20 minutes
TTL: 1 hour of inactivity
Multi-site: Single daemon handles all sites
Languages: Ban pages in English & Italian

Installation & Configuration

Quick Installation

# Download and run the installer
sudo bash install.sh

# The installer will:
# 1. Copy files to /opt/immution/
# 2. Create and enable the systemd service
# 3. Configure log rotation
# 4. Install Apache configuration

Manual PHP Configuration

# Add to Apache PHP configuration
sudo nano /etc/php/8.x/apache2/php.ini

# Add this line:
auto_prepend_file = /opt/immution/gate.php

# Restart Apache:
sudo systemctl restart apache2

Useful Commands

Monitoring

sudo systemctl status immution
sudo journalctl -u immution -f
tail -f /var/log/immution/blocked.csv
ls -la /dev/shm/immution/

Maintenance

# Count blocks today
grep "$(date +%Y-%m-%d)" /var/log/immution/blocked.csv | wc -l
# Top 10 blocked IPs
cut -d',' -f2 /var/log/immution/blocked.csv | sort | uniq -c | sort -rn | head -10
# Unblock a specific IP
sudo rm /dev/shm/immution/1.2.3.4.txt

GitHub Repository Coming Soon

The Immution project is currently in testing phase. The source code will be publicly available on GitHub shortly.

Check back soon for access to the repository, documentation, and installation instructions.

Repository will be available at: github.com/immution

Project Status

Current Phase: Testing & Performance Optimization

Next Release: Public GitHub repository with full source code

License: MIT License - Open Source

Requirements: Python 3 + PHP 8 (standard libraries only)

File Structure

/opt/immution/
├── immution.py              # Main Python daemon
├── gate.php                 # PHP gate (auto_prepend)
├── gate-404.php             # Multilingual 404 page
├── config.json              # Configuration (optional)
└── immution_optimized.py    # Performance-optimized version

/dev/shm/immution/           # IP data in RAM (fast)
├── 1.2.3.4.txt              # Data for each tracked IP
├── 5.6.7.8.txt
└── banned.mmap              # Memory-mapped ban table

/var/log/immution/           # Block logs
└── blocked.csv              # CSV log of all blocks

/etc/apache2/conf-available/
└── immution-apache.conf     # Apache configuration

/etc/systemd/system/
└── immution.service         # Systemd service unit