BlackSession browser multi-identità con Electron e React

Samueleex

Vi presento il mio nuovo progetto BlackSession, questo è un browser nato per gestire più account su una stessa piattaforma. Se ad esempio dobbiamo gestire più account come: lavoro, personale, cliente ecc... richiederebbe normalmente browser separati o profili manuali.

{BlackSession LOGO}

BlackSession risolve questo problema dato che ogni profilo è assegnato ad una finestra completamente isolata, con cookie, local storage e sessioni in comune, tutto dentro una singola finestra.
I browser mainstream hanno i "profili" ma li trattano come finestre separate con overhead elevato. L'obiettivo di BlackSession è diverso cioè rendere il context switching immediato tramite tab colorate per profilo, proxy dedicati per ogni profilo e zero sovrapposizione di sessioni. Il tutto con un'interfaccia minimalista avendo come punto di forza la leggerezza.

Screenshot BlackSession Browser

Premesse prima di partire

Vediamo prima dei concetti fondamentali prima di leggere l'architettura del browser.
Electron è un framework open source che permette di creare applicazioni desktop native usando HTML, CSS, JavaScript. Combina due motori: Chromium per il rendering dell'interfaccia e Node.js per l'accesso al sistema operativo. Quindi come risultato avremo un'app che sembra un programma nativo ma è scritta interamente in JavaScript/TypeScript. Ad esempio VS Code, Figma e Discord sono tutti basati su Electron.

Main process e renderer process Electron divide l'applicazione in due processi separati.
main process = backend quindi accesso a Node.js e alle API di sistema, gestisce le finestre e i file.
renderer = frontend quindi HTML/CSS/React, non ha accesso diretto al filesystem o alle API native.

IPC (Inter-Process Communication) Dato che i due processi sono isolati questi comunicano tramite IPC in modo asincrono. Il renderer chiama funzioni esposte tramite un preload script (un bridge sicuro) e il main risponde. In BlackSession ogni azione UI come aprire un tab, cambiare proxy, navigare a un URL è una chiamata IPC.

ESM (ECMAScript Modules) è un sistema di moduli standard di JavaScript basato su import ed export. Quindi come CommonJS (require) ma evoluto. Nel codice ho incluso "type": "module" in package.json per abilitarlo in tutto il progetto (anche per main process di Electron).

Iniziamo!
Lo stack tecnologico è incentrato su WebContentsView successore di BrowserView presente nelle versioni più recenti di Electron. Ogni tab è una view separata inclusa sulla finestra principale e dimensionata dinamicamente al resize:

// electron/main.ts
function resizeView(view: WebContentsView) {
  const { width, height } = mainWindow.getBounds();
  view.setBounds({ x: 0, y: 60, width, height: height - 60 });
}

// throttle CPU/memoria per i tab in background
function setTabActive(view: WebContentsView, active: boolean) {
  view.webContents.setBackgroundThrottling(!active);
  view.webContents.setAudioMuted(!active);
}

Il vero isolamento si basa sulle session di Electron con partizioni persistenti. Ogni profilo ottiene la propria partizione persist:<profileId>, quindi Electron lo gestisce quasi come una sandbox separata su disco: cookie, cache, IndexedDB tutto separato.

Architettura:

Main process: tab e gestione sessioni - Gestisce WebContentsView, proxy, IPC
Renderer process: React + Tailwind UI - title bar, tab bar, address bar, modali
Preload bridge: contextBridge API - IPC type-safe tra renderer e main
Session store: persist:<profileId> - Isolamento completo per profilo

Altro punto di forza per BlackSession è che ogni profilo può avere un proxy dedicato (HTTP, HTTPS, SOCKS5):

Questo viene applicato a livello di session prima che la tab carichi qualsiasi risorsa. Le credenziali sono memorizzate in una Map indicizzata per partizione e iniettate tramite app.on('login'):

// proxy in session prima di caricare
async function applyProxy(partition: string, proxy?: ProxyConfig) {
  const s = session.fromPartition(partition);
  if (!proxy?.enabled || !proxy.host || !proxy.port) {
    await s.setProxy({ proxyRules: '' });
    return;
  }
  await s.setProxy({
    proxyRules: `${proxy.type}://${proxy.host}:${proxy.port}`
  });
  if (proxy.username && proxy.password) {
    proxyCredentials.set(partition, {
      username: proxy.username,
      password: proxy.password,
    });
  }
}

// auto auth per proxy che richiedono credenziali
app.on('login', (event, webContents, _details, authInfo, callback) => {
  if (!authInfo.isProxy) return;
  const partition = wcPartitionMap.get(webContents.id);
  const creds = proxyCredentials.get(partition);
  if (creds) {
    event.preventDefault();
    callback(creds.username, creds.password);
  }
});

N.B. le credenziali sono indicizzate per nome di partizione (stringa) ma non per riferimento all'oggetto Session. Questo evita di lasciare dati inutili quando le session vengono ricreate tra restart.

La scelta di usare vite-plugin-electron mi ha permesso di avere un unico processo di build per entrambi i target (renderer e main) con hot-reload durante lo sviluppo (cioè poter fare modifiche al codice con il programma avviato). Il main process è scritto in TypeScript con type: "module" e compilato in ESM. Combo un po' caotica perché bisogna fare attenzione a __filename e __dirname che non disponibili nativamente in ESM (risolti con fileURLToPath(import.meta.url)).

Stack:

Build con Vite 8 + electron-builder: Windows (NSIS) Linux (deb, tar.gz)
UI React 19 + Tailwind 4: JIT, nessun file CSS generato a build

In ambito di gestione crash e cleanup di risorse ogni WebContentsView registra listener per render-process-gone e unresponsive, con alert dedicato. Alla chiusura del tab o della finestra, destroyTab() rimuove la view, chiama webContents.destroy() e pulisce entrambe le map ausiliarie per evitare memory leak:

function destroyTab(tab: Tab) {
  wcPartitionMap.delete(tab.view.webContents.id);
  try { mainWindow?.contentView.removeChildView(tab.view); } catch (_) {}
  try {
    tab.view.webContents.stop();
    tab.view.webContents.destroy();
  } catch (_) {}
  tabs.delete(tab.id);
}

Il context menu è nativo! Al posto di implementare un menu contestuale in HTML (che non si integra con l'OS) quindi ci sarebbe problemi di compatibilità spesso e volentieri, ho sfruttato electron.Menu con scelte basate sull'elemento selezionato: taglia/copia/incolla se il focus è su un campo editabile, copia/apri-in-nuova-scheda se si è su un link. L'evento open-url-in-new-tab viene inviato dal main al renderer via IPC che apre il tab nel profilo corretto.
Oltre a questo il browser presenta diversi shortcuts interessati come ctrl +/- per lo zoom e ctrl t che apre la finestra dei profili creati dall'utente.

Utilizzo risorse: Google Chrome vs Blacksession (idling)

(Testato su Win 11)
Utilizzo risorse Google Chrome vs Blacksession

Garantisco che questo browser è in continua fase di aggiornamento e dimostra che con Electron è assolutamente fattibile avere accesso alle API di sistema senza alcun problema (avendo come punto di forza il fattore cross platform). La separazione tra main e renderer con un bridge IPC tipizzato mi ha portato a scrivere il progetto in circa 700 righe di codice, incredibile per le funzioni che attualmente sono disponibili!
Architettura completa.
Il browser è scaricabile nel sito ufficiale: blacksession.org

Avete idee per futuri aggiornamenti?

Samueleex

Update V 1.0.1

Aggiunta di un Fingerprint randomizzato, file creati/modificati:

electron/fingerprint.ts (Nuovo file) Modulo completo di generazione fingerprint
electron/main.ts (integrazione) injection automatica ad ogni dom-ready
electron/preload.ts API getFingerprint() esposta al renderer
src/App.tsx Badge FP nella barra indirizzi + tooltip con dettagli

Come funziona? Ogni containerId genera un fingerprint unico ma coerente (stesso profilo = stessa identità spoofata anche tra tab diversi) e lo script viene iniettato ad ogni navigazione (dom-ready) prima degli script di pagina.

API spoofate:

Canvas: toDataURL/toBlob
WebGL: Vendor, renderer, parametri GPU randomizzati
AudioContext: Variazione DynamicsCompressor
DOMRect: piccolo noise su getBoundingClientRect/getClientRects
Navigator: CPU cores, memoria, touch, platform, lingue
Screen: Risoluzione, color depth, pixel ratio
Timezone: Fuso orario randomizzato
WebDriver: navigator.webdriver = false

Aggiunta la possibilità di impostare uno User Agent per singolo profilo. Ho aggiunto il campo userAgentall'interfaccia Profile, modificato ProxyModal in ProfileSettingsModalaggiungendo un campo di input che permette all'utente di inserirlo (lasciando vuoto si usa quello di default di Electron).
Aggiornata la callback di salvataggio saveProfileSettingse addTabin modo da passare questo parametro al momento della creazione del tab.

Risolto Bug dei link che aprivano finestre Electron separate. C'era un grosso problema, target="_blank" e window.open() creavano un nuovo BrowserWindow con l'header Electron di default. Ho quindi optato per setWindowOpenHandler su ogni WebContentsView, in questo modo intercetta la richiesta, la blocca e invia l'URL al renderer che lo apre come nuova tab nello stesso profilo.

BLACKSESSION.ORG

Samueleex

Update V 1.0.2

Fix eseguiti:

Niente più require() dinamico

Prima

click: () => { require('electron').clipboard.writeText(url); }

Dopo

import { clipboard } from 'electron';
// ...
click: () => { clipboard.writeText(url); }

Richiamare require() dentro una callback è incoerente in un modulo ESM e potrebbe comportarsi in modo imprevedibile a seconda dell'ambiente di bundling. La soluzione è banale cioè portare l'import in cima al file come tutti gli altri moduli Electron.

Rimuovere solo il listener giusto:

Prima

ipcRenderer.removeAllListeners('profile-selected');
ipcRenderer.on('profile-selected', handler);
return () => ipcRenderer.removeAllListeners('profile-selected');

Dopo:

ipcRenderer.on('profile-selected', handler);
return () => ipcRenderer.removeListener('profile-selected', handler);

removeAllListeners è molto pericoloso dato che rimuove tutti i listener registrati su quel canale non solo il tuo. Se in futuro un altro modulo si agganciasse allo stesso evento verrebbe eliminato senza errori.

ID profilo con crypto.randomUUID()

Prima

const id = `${name.toLowerCase().replace(/\s+/g, '-')}-${Date.now()}`;

Dopo

const tabId = crypto.randomUUID();

Il vecchio ID usava il nome del profilo inserito dall'utente che finiva direttamente come argomento di session.fromPartition(). Il regex rimuoveva solo gli spazi, mentre caratteri come .., \0 o separatori di path restavano e in alcuni casi potrebbero creare problemi.

Samueleex

Update V 1.0.3

ProxyChain (catena SOCKS)

electron/proxyChain.ts

Per ogni profilo viene aperto un server TCP locale su 127.0.0.1 con porta casuale (listen(0)).
Il server comunica SOCKS5 verso Electron (quindi session.setProxy come per un SOCKS5 normale).
Per ogni connessione client:
- gestisce handshake SOCKS5 (greeting + CONNECT);
- dopo il CONNECT rimuove il listener data e fa pipe tra client e socket remoto (altrimenti i byte del tunnel verrebbero letti di nuovo come SOCKS e la connessione si romperebbe).
La catena reale è costruita con socks (SocksClient.createConnectionChain): hop multipli solo SOCKS4/SOCK5, in sequenza Tu - hop1 - hop2 - … webserver.
Avvio / stop (main): handler proxy-chain-start / proxy-chain-stop nel main:

Start: startProxyChain verso applyProxysulla partition del profilo verso socks5://127.0.0.1:<porta> e reload di tutte le tab di quel profilo.
NB: in create-tab se esiste una catena per quel containerId, non si usa il proxy salvato nel profilo ma si forza sempre SOCKS5.

  const chainPort = getChainPort(containerId);
  const rotState = rotatingProxyState.get(containerId);
  let effectiveProxy: ProxyConfig | undefined = proxy;
  if (chainPort) {
    effectiveProxy = { enabled: true, type: 'socks5', host: '127.0.0.1', port: String(chainPort) };
  } else if (rotState && rotState.proxies.length > 0) {
    const activeIndex = rotState.currentIndex === 0 ? rotState.proxies.length - 1 : rotState.currentIndex - 1;
    effectiveProxy = rotState.proxies[activeIndex];
  }

Proxy rotativi

Stato nel main: tre Map per profilo:
- rotatingProxyTimersporta a setInterval che chiama il cambio proxy
- rotatingProxyStatecioè { proxies: ProxyConfig[], currentIndex: number }
- rotatingProxySwapBusyper evitare swap strani.
Start (rotating-proxy-start):
- stopRotatingProxypulisce timer e stato precedente.
- Imposta stato con currentIndex: 0.
applyNextProxy: applica proxies[currentIndex], poi fa currentIndex = (currentIndex + 1) % length e reloadProfileTabs.
Quindi l’indice in stato indica il prossimo proxy da applicare e il proxy attualmente in uso è quello indietro di uno. Da cui deriva la formula in create-tab sopra. (con caso speciale currentIndex === 0 dopo il wrap per ultimo hop).
Timer: ogni intervalMinutesripete applyNextProxy.
Stop: cancella timer/stato e opzionalmente ripristina restoreProxy(il proxy base del profilo).
Blocco aggiornamenti manuali: update-proxy non fa nulla se c’è una catena attiva oppure un timer rotazione attivo per quel profilo così le impostazioni salvate nel renderer non sovrascrivono chain/rotation.

ipcMain.handle('update-proxy', async (_e, { containerId, proxy }: { containerId: string; proxy: ProxyConfig }) => {
  // If a chain or rotating proxy is active, don't let the profile proxy config override it.
  if (getChainPort(containerId) !== null) return;
  if (rotatingProxyTimers.has(containerId)) return;
  await applyProxy(`persist:${containerId}`, proxy);
});

NB: ProxyChain batte sempre la rotazione se getChainPortè true non si entra nel ramo rotazione.

Bookmarks per profilo

Qui la logica è solo nel renderer + persistenza localStorage, non nel main process per i dati.

ipcMain.on('show-bookmarks-overflow-menu', (_e, payload: unknown) => {
  ...
  Menu.buildFromTemplate(template).popup({ window: win, x: Math.round(p.anchor.x), y: Math.round(p.anchor.y) });
});

Il preload inoltra bookmark-overflow-action al React (open per la navigazione sulla tab attiva; remove per aggiornare lo stato profilo e il useEffect salva di nuovo su localStorage).

Nota: proxy chain / rotazione non influenzano i bookmark: sono canali indipendenti (rete nel main, preferiti nel renderer legati all’id profilo).

BLACKSESSION.ORG

Samueleex

Update V 1.0.4

Miglioramento fingerprint randomizzato:

User-Agent / Client hints: Chrome reale + platform version diversa
Canvas / ClientRects: Rumore seeded unico
WebGL: Coppia vendor/renderer coerente (NVIDIA/AMD/Intel)
Schermo: risoluzione logica + DPR + taskbar
Font diversi
Audio: Bias su Oscillator / OfflineAudioContext
Navigator hardwareConcurrency, deviceMemory, timezone US, ecc.

Aggiunta "Company Mode"

Modalità che trasforma il PC admin in un vero e proprio server locale, quando attivata gli altri PC nella rete lo trovano automaticamente e si collegano senza configurazioni.
L’admin può gestire tutto (profili e proxy) mentre i client possono solo visualizzare e avviare i profili.
Il sistema è sicuro (token per le modifiche) e continua a funzionare anche offline grazie alla cache dei client.
Questa funzione permette quindi di avere un PC admin che crea i profili da Company Mode ON e annota l’URL LAN, in questo caso http://192.168.1.10:7471. Gli altri PC connessi alla stessa rete saranno i PC client che con Find server on LAN, poi clic sul server: apri i profili (nessuna creazione/modifica/eliminazione).
Se l’admin si spegne: Use last cached profiles per usare l’ultima copia salvata.

Ruolo Admin: Toggle “Company Mode ON”, server Express su IP LAN:7471, mDNS blacksession.tcp, CRUD profili/proxy dal pannello
Ruolo Client: “Find server on LAN”, un click per connettersi, profili sola lettura + avvio tab (cache locale se l’admin è offline).

API (LAN):

GET /profiles pubblico (anche client)
POST /profiles, PUT /profiles/:id, DELETE /profiles/:id richiedono Authorization: Bearer <token>
PUT /profiles/:id/proxy, DELETE /profiles/:id/proxy idem

Il token admin viene generato all’avvio del server e salvato nello stato locale dell’admin.

Samueleex

Update V 1.0.5 latest release

Aggiunta gestione permessi:

File aggiunti:

electron/sitePermissions.ts Store JSON per profilo in userData/site-permissions/
electron/permissionHandlers.ts Handler Electron (setPermissionRequestHandler, setPermissionCheckHandler, setDevicePermissionHandler)
src/components/PermissionPrompt.tsx Dialog richiesta permesso
src/components/SitePermissionsModal.tsx Pannello gestione completa

Gestisce le autorizzazioni quando un sito le richiede:

GPS (geolocalizzazione)
Fotocamera / microfono
Notifiche, appunti, MIDI, schermo intero
Condivisione schermo, USB/HID/serial e altre autorizzazioni Chromium supportate

Le opzioni sono:

Consenti sempre: salvato per quel sito + profilo
Consenti questa volta: solo per la sessione corrente
Blocca: rifiuta la richiesta

NB:

Dispositivi USB/HID/serial: l'opzione compare al primo tentativo ma dopo “Consenti” l’utente deve ripetere l’azione sul sito (limite Electron).
I permessi si applicano ai nuovi tab del profilo, i tab già aperti usano la sessione già configurata.

BlackSession permessi

DOWNLOAD BLACKSESSION

Samueleex

BlackSessionOS

Finalmente è uscito BlackSessionOS! Non è più un semplice browser o un'app Electron, ora è una distro Linux minimal basata su Debian 12 (Bookworm) a 64-bit, al momento pensata solo per utilizzo live, quindi progettata per avviarsi direttamente in RAM da chiavetta USB o VM in modalità zero trace (senza lasciare dati persistenti sul disco dell'host).

Questa distro è stata pensata come una Ephemeral Containerized Workstation, in pratica la shell dell'OS è integrata con l'interfaccia di BlackSession e ogni sessione viene isolata all'interno di container Linux dedicati. Invece "ephemeral" proprio perché allo spegnimento dell'ambiente i dati spariscono.

Architettura generale

Sequenza boot e avvio in utente Kiosk

L'intero flusso di boot è stato pensato per togliere qualsiasi desktop environment (KDE, GNOME, XFCE), riducendo al minimo l'overhead di RAM e CPU.
Il supporto (usb o iso) viene avviato tramite Syslinux (suite di bootloader leggeri) su macchine BIOS legacy o GRUB EFI su sistemi UEFI.
I paramentri passati al kernel sono: boot=live components quiet splash edd=off noedd.
L'immagine compressa filesystem.squashfs viene decompressa e montata come unione in sola lettura insieme a un layer scrivibile in RAM (tmpfs).
Non viene utilizzato alcuna grafica (come gdm o LightDM). Il login automatico è gestito da un override di Systemd, in grosso modo:

[Service]
ExecStart=
ExecStart=-/sbin/agetty --autologin blacksession --noclear %I $TERM

Dopo il login su tty1, il file .profile dell'utente blacksession comunica con il terminale e lancia il server X:

if [ -z "$DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then
    exec startx -- -nocursor
fi

C'è un file .xinitrc che avvia la sessione di openbox, un window manager molto minimal ( circa 10mb di RAM) configurato in autostart per lanciare lo script che poi andrà ad orchestare:

# /home/blacksession/.config/openbox/autostart
/usr/local/bin/blacksession-start &

Problema Docker su OverlayFS e il Loopback ext4

Uno dei problemi più complessi che abbia risolto nella creazione di BlackSessionOS è stato proprio l'unire Debian e Docker Engine.

Il vero problema è stato che nei sistemi operativi live il file system root / è montato tramite OverlayFS (squashfs + tmpfs). Quando Docker si avvia su un filesystem che è già un OverlayFS, il kernel Linux impedisce la creazione di un secondo layer OverlayFS annidato (overlay-on-overlay).
Questo porta a:

Docker ricade in automatico sul driver di storage vfs.
Il driver vfs non condivide i layer e copia l'intero filesystem per ogni container in RAM.
Il caricamento delle immagini di BlackSession (₈₀₀ MB compresse) portava quindi ad un'espansione di diversi gb nella ram, saturandola istantaneamente e causando il crash del sistema per out of memory con errore ENOSPC.

La soluzione è stata la creazione di blacksession-docker-storage!
Non è altro che un servizio Systemd dedicato che si attiva prima di Docker (Before=docker.service):

[Unit]
Description=BlackSession: prepare overlay2-capable storage for Docker
After=local-fs.target systemd-modules-load.service
Before=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/sbin/blacksession-docker-storage

Questo script esegue della logica a basso livello che consiste nel:

Rilevare la ram fisica disponibile da /proc/meminfo e calcolare un budget dedicato (fino a 8gb) lasciando 1,5gb per il sistema base.

RAM_MB=$(awk '/^MemTotal:/ {print int($2/1024)}' /proc/meminfo)
BUDGET_MB=$(( RAM_MB - 1536 ))
[ "$BUDGET_MB" -gt 8192 ] && BUDGET_MB=8192

Creare un punto di montaggio tmpfs isolato in /run/blacksession
Allocare docker-storage.img che consuma RAM solo per i blocchi effettivamente scritti:
truncate -s "${BUDGET_MB}M" /run/blacksession/docker-storage.img
Lo formatta come filesystem nativo ext4 senza root per massimizzare lo spazio:
mkfs.ext4 -F -q -m 0 /run/blacksession/docker-storage.img
Lo monta in loopback su /var/lib/docker:
mount -o loop,noatime /run/blacksession/docker-storage.img /var/lib/docker

Configura /etc/docker/daemon.json imponendo il driver ad alte prestazioni overlay2:

{
  "storage-driver": "overlay2",
  "data-root": "/var/lib/docker"
}

In questo modo il sistema si avvia senza problemi!

Avvio non bloccante e precaricamento delle immagini con flock

All'avvio dell'OS, il launcher blacksession-start gestisce l'inizializzazione (che in questo caso si svolge in parallelo):

# start Docker background non bloccante
sudo systemctl start --no-block docker

# start ui Electron
cd /opt/blacksession
ELECTRON_BIN="./node_modules/electron/dist/electron"
FLAGS="--no-sandbox --disable-gpu --disable-dev-shm-usage --disable-software-rasterizer"
exec "$ELECTRON_BIN" . $FLAGS >> "$LOG_FILE" 2>&1

Mentre l'interfaccia utente di BlackSession appare a schermo (evitando schermate nere o attese inutili) un sub-process in background monitora la disponibilità del socket (di Docker) e fa un "depacchettamento" delle immagini precompilate (browser.tar.gz e terminal.tar.gz).
Oltre a ciò, per impedire race condition (ad esempio l'utente che apre un tab prima che il preloader abbia terminato la decompressione), sia lo script di boot che il processo Electron usano un lock molto solido:
sudo flock -w 600 /var/lock/blacksession-image-load.lock -c "gunzip -c '$img' | docker load"
Questo significa che se il precaricatore ha già finito il caricamento, Electron rileva l'immagine all'istante senza decomprimerla una seconda volta.

Tab isolation e architettura container

Nell'OS ogni singola scheda non è un semplice renderer locale ma un intero ambiente Linux containerizzato e isolato via Docker (o gVisor runsc se disponibile nel kernel):

Container Browser

Headless display: Xvfb crea il framebuffer grafico virtuale :99 con profondità colore 24bit.
Window management trasparente: Fluxbox viene configurato tramite i file apps e init per rimuovere tutte le barre del titolo e forzare fullscreen.
Patch NDI su noVNC: Il file /usr/share/novnc/vnc.html viene modificato via sed in fase di build del container per nascondere in modo nativo la barra di stato e gli elementi di controllo VNC:
RUN sed -i 's|</head>|<style>#noVNC_control_bar, #noVNC_status, #noVNC_status_bar { display: none !important; }</style></head>|' /usr/share/novnc/vnc.html

Controllo navigazione via CDP relay

Dato che Chromium gira all'interno del container isolato, Electron non ha accesso diretto al suo DOM o al ciclo di navigazione.

Ho fatto in modo che all'interno del container socat inoltra le connessioni esterne da :9223 alla porta interna :9222 (di Chromium):
socat TCP-LISTEN:9223,fork,reuseaddr TCP:127.0.0.1:9222 &
Electron interroga in modo periodico l'endpoint http://127.0.0.1:{debugPort}/json con una variabile in main.ts estraendo in tempo reale:
- L'url effettivo della pagina dopo redirect
- Il titolo del documento
- Lo stato di loading
Quando l'utente inserisce un nuovo URL nella barra degli indirizzi Electron esegue navigate.py che apre una sessione WebSocketverso il target CDP del container e invia il comando JSON-RPC:
{ "id": 1, "method": "Page.navigate", "params": { "url": "https://..." } }

Terminal mode e i suoi container

Le caratteristiche dei terminali sono:

Debian Bookworm con suite di networking (nmap, netcat, curl, wget, proxychains4), compiler (build-essential, python3, nodejs 20), tools (tmux, htop, vim, nano) e utente blacksession abilitato a sudo senza password.
Accesso web ad alte prestazioni: ttyd (compilato in C con supporto WebSocket e WebAssembly) espone la console su porta allocata dinamicamente sull'host.
scambio file istantaneo: Il volume Docker blacksession_vol_<profileId> viene montato assieme nel container browser e nel container terminal. La directory di download di Chromium è collegata via symlink a /shared/downloads quindi qualsiasi file scaricato dal browser è immediatamente accessibile dalla riga di comando del terminale.
Toggle Dinamico CLI / GUI con un tasto si può passare al volo da terminale alla GUI grafica con finestra Xterm (noVNC su :6080).

Monitoraggio hardware a basso livello con systemStats.ts

Sulla barra in alto a destra integrata in BlackSessionOS ha la capacità di dialogare con i file virtuali del kernel Linux per visualizzare metriche (CPU e RAM) e gestire l'hardware:

// memoria reale ignorando la cache di pagina dello SquashFS
const txt = await fs.readFile('/proc/meminfo', 'utf8');
const total = extractKb(txt, 'MemTotal');
const avail = extractKb(txt, 'MemAvailable');
const usedPct = Math.round(((total - avail) / total) * 100);

In questa barra è presente il calcolo per la percentuale di carico della CPU, ottenuta analizzando il delta dei jiffies (user, nice, system, idle, irq) tra due chiamate successive a os.cpus().
Il Wi-Fi Manager con nmcli, che esegue scansioni e connessioni alle reti Wi-Fi richiamando nmcli tramite execFile con array di parametri (eliminando il rischio di command injection causato da caratteri speciali negli SSID o password).
Il controllo del menu spegnimento funziona richiamando i comandi ACPI di Systemd (systemctl poweroff e systemctl reboot) e per quanto riguarda l'audio, il volume master si regola tramite amixer (ALSA) o pactl (PulseAudio).

Toolchain dell'ISO (build-iso.sh)

La generazione dell'immagine bootable .iso sfrutta il framework ufficiale live-build di Debian configurato all'interno dello script build-iso.sh.

lb config \
    --apt apt \
    --apt-indices false \
    --apt-recommends false \
    --architectures amd64 \
    --bootloader "syslinux,grub-efi" \
    --bootappend-live "boot=live components quiet splash edd=off noedd" \
    --binary-images iso-hybrid \
    --distribution bookworm \
    --parent-archive-areas "main contrib non-free non-free-firmware" \
    --archive-areas "main contrib non-free non-free-firmware" \
    --linux-packages "linux-image" \
    --system live \
    --win32-loader false

Le fasi di compilazione sono:

Bootstrap del chroot: debootstrap scarica ed installa i pacchetti di Debian 12 Bookworm (Kernel, firmware Wi-Fi non-free Realtek/Intel, Xorg, Openbox, Docker.io, Node.js, librerie GTK3 e NetworkManager).
Copia l'applicazione compilata (dist/ e dist-electron/), i manifest dei container (docker/) e installa le dipendenze di produzione Node.js (npm install --omit=dev).
Esporta le immagini blacksession-browser:latest e blacksession-terminal:latest in archivi .tar.gz compressi in /opt/blacksession/preloaded-images/.
mksquashfs comprime il chroot e xorriso genera il file immagine live-image-amd64.hybrid.iso compatibile sia con dischi ottici che con drive USB (dd/Ventoy/Rufus).

Tutorial installazione

Per installare BlackSessionOS, dopo aver scaricato l'ISO dobbiamo formattare una chiavetta USB in modo che sia avviabile. In questo caso ho utilizzato Rufus, selezionate lo schema di partizione su GPT e il sistema di destinazione su UEFI. In seguito clicca sul pulsante "Avvia", confermate le richieste a schermo e attendete. Una volta formattata l'unità, avviatela dal boot menu del PC e il sistema operativo si avvierà!

Fondatori