docs: add project readme

README.md

@@ -0,0 +1,300 @@
+# Eris
+
+This is a sophisticated HTTP tarpit and honeypot stream designed to protect,
+delay, block and dare I say _troll_ malicious scanners and vulnerability probes
+while protecting **legitimate** web traffic.
+
+## How Does It Work?
+
+Eris works by sitting in front of your web server, intercepting all incoming
+HTTP requests and:
+
+- **Allowing** legitimate requests to pass through to your actual web server
+- **Trapping and delaying** malicious requests using a tarpit technique
+- **Blocking** repeat offenders at the firewall level (goodbye fail2ban)
+
+### Process Flow
+
+1. Eris receives all incoming HTTP requests
+2. It analyzes each request against its list of trap patterns
+3. Legitimate requests are proxied directly to your backend server
+4. Suspicious requests are tarpitted:
+   - Response is sent painfully slowly, byte-by-byte with random delays
+   - Deceptive content is generated to waste attacker time
+   - Connections are held open for extended periods to consume attacker
+     resources
+5. Repeat offenders are automatically blocked at the firewall level
+
+## Why Use Eris?
+
+Traditional web application firewalls simply block malicious requests, which
+immediately alerts attackers they've been detected. Eris takes a deceptive
+approach:
+
+- Wastes attacker time and resources on fake responses
+- Collects data about attack patterns and techniques
+- Reduces server load by handling malicious traffic efficiently
+- Provides valuable metrics and insights about attack traffic
+
+## Key Features
+
+The design I had in mind was minimal, but more features crept in while I was
+fixing things on to go. More features to come as I see fit.
+
+- **Low-overhead tarpit**: Delays responses to suspicious requests byte-by-byte
+  with random delays
+- **Markov chain response generation**: Creates realistic-looking fake responses
+  to deceive attackers (success my vary depending on how sophisticated the
+  attackers are)
+- **Firewall integration**: Automatically blocks repeat offenders using nftables
+  (iptables is legacy, and not supported)
+- **Customizable response scripts**: Using Lua scripting to generate deceptive
+  responses
+- **Prometheus metrics**: Tracks and exposes honeypot activity
+
+## Installation
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/notashelf/eris
+cd eris
+
+# Build the binary
+cargo build --release
+
+# Create necessary directories
+mkdir -p ~/.local/share/eris/data
+mkdir -p ~/.local/share/eris/corpora
+mkdir -p ~/.local/share/eris/scripts
+```
+
+### Pre-built Binaries
+
+Pre-built binaries are not yet available.
+
+## Deployment Architecture
+
+### Static Sites
+
+For static sites served by Nginx, the proper setup is to place Eris in front of
+Nginx. Here is a graph of how it's meant to be configured:
+
+```
+Internet → [Eris (port 80)] → [Nginx (local port)]
+```
+
+You will want to configure Eris to listen on port 80 (or 443 for SSL) and
+forward legitimate traffic to Nginx running on a local port:
+
+```bash
+# Run Eris on port 80, forwarding legitimate requests to Nginx on port 8080
+eris --listen-addr 0.0.0.0:80 --backend-addr 127.0.0.1:8080
+```
+
+Then, configure Nginx to serve your static site on the local port:
+
+```nginx
+server {
+    # XXX: Nginx listens on local port only and it is
+    # not exposed to internet
+    listen 127.0.0.1:8080;
+    server_name example.com;
+
+    root /var/www/example.com; # your site's source
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ =404;
+    }
+}
+```
+
+With the setup above, several things will happen (in this order):
+
+1. All traffic hits Eris first (on port 80)
+2. Eris inspects each request against its trap patterns
+3. Malicious requests get tarpitted by Eris
+4. Legitimate requests get proxied to Nginx on port 8080
+5. Nginx serves your static content as usual
+
+## HTTPS Support
+
+For HTTPS, you have two options:
+
+### Option 1: Terminate SSL at Eris
+
+```bash
+# SSL termination at Eris (requires cert files)
+eris --listen-addr 0.0.0.0:443 --backend-addr 127.0.0.1:8080 --ssl-cert /path/to/cert.pem --ssl-key /path/to/key.pem
+```
+
+### Option 2: Use a separate SSL terminator
+
+```
+Internet → [SSL Terminator (port 443)] → [Eris (local port)] → [Nginx (local port)]
+```
+
+You can use Nginx, HAProxy, or Caddy as the SSL terminator, forwarding decrypted
+traffic to Eris.
+
+## Configuration
+
+### Command Line Options
+
+```
+USAGE:
+    eris [OPTIONS]
+
+OPTIONS:
+    --listen-addr <ADDR>         Address to listen on [default: 0.0.0.0:8888]
+    --metrics-port <PORT>        Port for Prometheus metrics [default: 9100]
+    --backend-addr <ADDR>        Address of backend server [default: 127.0.0.1:80]
+    --min-delay <MS>             Minimum delay between tarpit bytes in ms [default: 1000]
+    --max-delay <MS>             Maximum delay between tarpit bytes in ms [default: 15000]
+    --max-tarpit-time <SEC>      Maximum time to hold a tarpit connection in seconds [default: 600]
+    --block-threshold <COUNT>    Block IPs after this many hits [default: 3]
+    --base-dir <PATH>            Base directory for all files (optional)
+    --config-file <FILE>         JSON configuration file (optional)
+    --log-level <LEVEL>          Log level (debug, info, warn, error) [default: info]
+```
+
+### JSON Configuration File
+
+For more complex configurations, use a JSON configuration file:
+
+```json
+{
+  "listen_addr": "0.0.0.0:8888",
+  "metrics_port": 9100,
+  "backend_addr": "127.0.0.1:80",
+  "min_delay": 1000,
+  "max_delay": 15000,
+  "max_tarpit_time": 600,
+  "block_threshold": 3,
+  "trap_patterns": [
+    "/vendor/phpunit",
+    "eval-stdin.php",
+    "/wp-admin",
+    "/wp-login.php",
+    "/xmlrpc.php",
+    "/phpMyAdmin",
+    "/solr/",
+    "/.env",
+    "/config",
+    "/api/",
+    "/actuator/"
+  ],
+  "whitelist_networks": [
+    "192.168.0.0/16",
+    "10.0.0.0/8",
+    "172.16.0.0/12",
+    "127.0.0.0/8"
+  ],
+  "markov_corpora_dir": "./corpora",
+  "lua_scripts_dir": "./scripts",
+  "data_dir": "./data"
+}
+```
+
+## Extending and Customizing
+
+### Adding Trap Patterns
+
+Edit your configuration file to add additional trap patterns:
+
+```json
+"trap_patterns": [
+  "/vendor/phpunit",
+  "eval-stdin.php",
+  "/wp-admin",
+  "/wp-login.php",
+  "/xmlrpc.php",
+  "/phpMyAdmin",
+  "/solr/",
+  "/.env",
+  "/config",
+  "/api/",
+  "/actuator/",
+  "/wp-content/debug.log",
+  "/cgi-bin/",
+  "/admin/"
+]
+```
+
+### Custom Response Generation with Lua
+
+> [!WARNING]
+> The Lua API is experimental, and might be subject to change. Breaking changes
+> will be
+
+Create Lua scripts in your `lua_scripts_dir` to customize response generation:
+
+```lua
+-- honeypot.lua
+function generate_honeytoken(token)
+    local token_types = {"API_KEY", "AUTH_TOKEN", "SESSION_ID", "SECRET_KEY"}
+    local prefix = token_types[math.random(#token_types)]
+    local suffix = string.format("%08x", math.random(0xffffff))
+    return prefix .. "_" .. token .. "_" .. suffix
+end
+
+function enhance_response(text, response_type, path, token)
+    local result = text
+    local honeytoken = generate_honeytoken(token)
+
+    if response_type == "php_exploit" then
+        result = result .. "\n<?php /* Debug mode enabled */ ?>"
+        result = result .. "\n<!-- DEBUG TOKEN: " .. honeytoken .. " -->"
+    elseif response_type == "wordpress" then
+        result = result .. "\n<!-- WordPress debug: DB_PASSWORD='" .. honeytoken .. "' -->"
+    elseif response_type == "api" then
+        result = '{"error":"Unauthorized","message":"Invalid credentials",'
+        result = result .. '"debug_token":"' .. honeytoken .. '"}'
+    else
+        result = result .. "\n<!-- Server: Apache/2.4.41 PHP/7.4.3 -->"
+        result = result .. "\n<!-- Debug: " .. honeytoken .. " -->"
+    end
+
+    return result
+end
+```
+
+### Custom Markov Response Corpus
+
+Create text files in your `markov_corpora_dir` to provide custom text for
+response generation:
+
+- `generic.txt` - Default responses
+- `php_exploit.txt` - PHP-specific error messages
+- `wordpress.txt` - WordPress-style responses
+- `api.txt` - API error messages
+
+## Metrics and Monitoring
+
+Eris exposes Prometheus metrics on the configured metrics port (default: 9100):
+
+- `eris_hits_total` - Total number of hits to honeypot paths
+- `eris_blocked_ips` - Number of IPs permanently blocked
+- `eris_active_connections` - Number of currently active connections in tarpit
+- `eris_path_hits_total` - Hits by path
+- `eris_ua_hits_total` - Hits by user agent
+
+View current status at: `http://your-server:9100/status`
+
+## Additional Security Considerations
+
+Internally, Eris is designed with security and maximum performance in mind.
+Additionally you might want to consider:
+
+- Running Eris as a non-privileged user
+- Placing Eris behind a CDN or DDoS protection service for high-traffic sites
+- Regularly reviewing logs to identify new attack patterns (and keeping verbose
+  NGINX logs)
+- Hiding the metrics endpoint from public access
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for
+details.