🧠 Xerxes — Bot Traffic Reality Controller

What Xerxes Is

Xerxes is a traffic control system for bots and automated agents.

It does not simply block bots. Instead, it detects bot-like behavior, classifies incoming requests, decides how each request should be handled, and controls what the requester is allowed to see.

Xerxes is not a firewall.
It is a system that determines what each visitor is allowed to perceive.

Core Concept

Traditional systems follow this pattern:

Bot → Block

Xerxes follows this pattern:

Bot → Observe → Classify → Decide → Respond

Blocking is easy. Controlling perception is powerful.

Perception Control Layer

Xerxes is designed not just to block, but to control what automated systems experience.

Request → Classified → Routed → Controlled Response

• Serve alternate content to bots
• Provide null or decoy data
• Redirect high-risk actors
• Shape crawler perception intentionally

This transforms Xerxes from a defensive system into an active intelligence layer.

System Architecture

Internet → WAF → Xerxes → Response

Key Features in v0.1.1-dev

• Bot Detection Engine with user-agent analysis, classification scoring, and pattern matching.
• Live Request Handling through detect.php for real-time classification and optional logging.
• Rate Limiting at the PHP Layer to protect allowed traffic that makes it past the WAF.
• Control Panel with token-protected access and no WordPress dependency.
• SQLite Storage so the system remains portable and self-contained.
• Payload System Foundation for future controlled responses and deception routing.

Dashboard Preview (Next Evolution)

This represents the upcoming visual intelligence layer. Current build prepares the data pipeline.

Directory Structure

/xerxes/
│
├── index.php              → Control panel (login protected)
├── detect.php             → Live detection endpoint
├── payload_router.php     → Payload handling (future expansion)
│
├── /includes/
│   ├── db.php
│   ├── analytics.php
│
├── /data/
│   ├── xerxes.sqlite
│   ├── parse_state.json
│
├── /payloads/
│   ├── botpot.json
│   ├── empty-feed.xml
│   ├── null.html
│
├── config.php             → Core configuration (sensitive)

Installation

1. Upload the /xerxes/ directory into your site root, such as /public_html/xerxes/.
2. Add one simple Xerxes-safe block to the top of the main site .htaccess.
3. Set proper file permissions.
4. Access the control panel and change the default token.

Main .htaccess Block

RewriteEngine On

# Xerxes safe zone
RewriteCond %{REQUEST_URI} ^/xerxes/ [NC]
RewriteRule ^ - [L]

Permissions

chmod 755 xerxes/
chmod 644 *.php
chmod 755 data/

Access

http://yourdomain.com/xerxes/

Authentication

The control panel uses a token stored in config.php. This token must be changed before the system is exposed publicly.

'auth' => [
    'token' => 'change-me-now-xerxes-dev-token',
    'session_key' => 'xerxes_auth',
],

Security Notes

Protect sensitive files. Even if PHP is configured correctly, deny direct access explicitly.

<FilesMatch "^(config\.php|.*\.sqlite)$">
    Require all denied
</FilesMatch>

• Do not expose config.php.
• Do not expose SQLite database files.
• Do not expose internal include files if avoidable.

Testing

Basic Detection Test

curl -A "Mozilla/5.0" http://yourdomain.com/xerxes/detect.php

Bot Simulation

curl -A "Googlebot/2.1 (+http://www.google.com/bot.html)" http://yourdomain.com/xerxes/detect.php

Safe Load Test

for i in {1..50}; do
  curl -s -A "TestBot$i" http://yourdomain.com/xerxes/detect.php &
  ((i % 10 == 0)) && wait
done
wait

Use browser-like UAs when testing through environments with aggressive WAF rules. Curl with default UA may be blocked before Xerxes ever sees the request.

Known Behavior

Current Limitations

• No advanced long-term behavioral scoring yet.
• No adaptive response engine yet.
• Payload routing exists as a foundation, not a fully evolved deception layer.
• The user interface is intentionally minimal.
• Visualization and dashboard analytics remain limited in this locked dev build.

Configuration

Core runtime values are stored in config.php.

'runtime' => [
    'enabled' => true,
    'log_live_hits' => true,
    'rate_limit' => true,
    'rate_window' => 1,
    'rate_hits' => 5,
    'force_full_detection' => false,
    'debug' => false,
]

These settings allow live request logging, basic internal rate limiting, and future expansion into deeper behavior analysis.

Behavior Scoring Engine

Xerxes now introduces a scoring system that evaluates each request based on behavioral indicators instead of relying solely on static signatures.

Score Range:
0   → Likely Human
1–3 → Suspicious
4–6 → Automated / Scripted
7+  → Aggressive / Bot / Scanner

Design Philosophy

Recommended Workflow

1. Install Xerxes in /xerxes/.
2. Add the minimal main .htaccess block.
3. Test with a browser-like UA and with controlled bot UAs.
4. Observe behavior before adding complexity.
5. Expand rules gradually.
6. Keep the main .htaccess clean and avoid scattered edits.

Future Evolution

Final State of This Locked Build

• Working bot detection system
• Stable installation model
• Layered protection architecture
• Portable deployment approach
• Clean foundation for future expansion

Xerxes is not designed to stop bots.
It is designed to let them in,
study them,
and decide what version of reality they experience.

Change Log (Evolution Tracking)