ehwrj/README.md

# Ehwrj

Ehwrj is a clean-room War Thunder live map companion for Windows.

It reads War Thunder's local map service at `http://127.0.0.1:8111`, renders a desktop map view, and can show a click-through always-on-top overlay. The code is newly written and intentionally excludes the malicious behavior found in the analyzed sample.

## Analyzed Malware File

This repository does not contain the original malicious sample. The notes below summarize the static analysis used to separate the benign WT Live Map behavior from the malicious loader/clipper behavior.

Analysis date: 2026-06-02  
Analysis method: static analysis only; the sample was not executed.

| File | SHA-256 | Assessment |
| --- | --- | --- |
| `WTLiveMap.exe` | `4dbbc21d9c2ed70dde046a2f737ee4173da807d43d5b3a6acfe447864ed6d643` | Native x64 Win32/C++ executable containing RCDATA 101 and 102. |
| `WTLiveMap.zip` | `429e07a27e7896f75a901a1df3cd6560b43de33986920f1f22013ef155541b4c` | ZIP package containing the same suspicious executable. |
| `resource_101.bin` | `00732b0bbc1740ebe88745424c88ab840b381475837e5e02e937a29e66df3909` | Benign WT Live Map UI/WebView-style resource. |
| `resource_102.bin` | `03547c81562a065bcb08defa638866c8c1c79343d78b8df7a8a7e0cb827242d7` | Resource-less loader/clipper variant with the same malicious capability class as the outer EXE. |

Key findings:

- RCDATA 101 matches the non-virus WT Live Map behavior: it references `Warthunder LiveMap`, `map_info.json`, `map_obj.json`, `map.img`, `aces.exe`, WebView messaging, and loopback access to `127.0.0.1:8111`.
- RCDATA 102 is not byte-identical to the outer `WTLiveMap.exe`, but it shares the suspicious import profile, hidden string structure, Windows Update disguise strings, clipboard API strings, and cryptocurrency address replacement logic.
- The malicious path monitors clipboard text and replaces BTC, ETH, SOL, TRX, XRP, DOGE, LTC, and BCH wallet addresses with attacker-controlled addresses.
- Persistence is disguised as Windows Update. The analyzed code builds paths similar to `%TEMP%\WindowsUpdateModule\SystemUpdateService.exe` and creates a startup shortcut named `WindowsSystemUpdate.lnk`.
- `SHGetSpecialFolderPathW(CSIDL_STARTUP)`, Shell Link COM use, `Global\WinSysUpdateMutexV11`, and resource update APIs were observed in the malicious loader path.
- A ZIP repackaging path uses hidden PowerShell command construction, extracts a ZIP, locates an inner EXE, reinvokes itself with `--merge-env`, injects RCDATA 101/102, and recreates the ZIP.
- No external C2 server, IP, domain, or upload path was confirmed in static analysis. The confirmed monetization path is clipboard-based cryptocurrency address replacement.

## What It Implements

- Local War Thunder API polling:
  - `/map_info.json`
  - `/map_obj.json`
  - `/map.img`
- Optional local telemetry/message polling when available:
  - `/state`
  - `/hudmsg`
  - `/gamechat`
- Main map preview with aircraft/object markers
- Transparent click-through overlay
- Configurable overlay size, position, zoom, minimap, Mach labels, and spot radar
- Overlay controls for aircraft scale, minimum Mach filters, radar spread, vertical scale/offset, arrow size, opacity, label colors, font sizes, distance, Mach, and closure speed labels
- English/Korean UI language selection
- Settings persisted under `%LOCALAPPDATA%\Ehwrj\settings.json`
- Windows build from Linux using .NET 8 and Avalonia targeting `win-x64`

## Explicitly Not Implemented

The analyzed binary contained malicious behavior. Ehwrj does not implement:

- Clipboard monitoring or cryptocurrency address replacement
- Windows Update disguise or startup persistence
- ZIP/EXE infection or resource injection
- Hidden mutex-based malware lifecycle control
- Any external C2, exfiltration, or remote upload path

## Build

From Ubuntu:

```bash
cd ehwrj
scripts/bootstrap-ubuntu.sh
```

The bootstrap script installs missing Ubuntu packages for .NET 8 and the safety scanner, then runs restore, build, tests, the safety scan, tool smoke checks, and Windows x64 publish.

If the dependencies are already installed:

```bash
dotnet restore ehwrj/Ehwrj.sln
dotnet build ehwrj/Ehwrj.sln -c Release
dotnet run --project ehwrj/tests/Ehwrj.Tests/Ehwrj.Tests.csproj -c Release
dotnet publish ehwrj/src/Ehwrj.App/Ehwrj.App.csproj -c Release -r win-x64 --self-contained true \
  -p:PublishSingleFile=false
```

Or from inside the `ehwrj` folder:

```bash
scripts/publish-win-x64.sh
```

The output EXE will be under:

```text
ehwrj/src/Ehwrj.App/bin/Release/net8.0/win-x64/publish/
```

The portable release ZIP is written to:

```text
ehwrj/artifacts/ehwrj-win-x64.zip
```

## Runtime

Run War Thunder first, then start Ehwrj on Windows. The app expects the game to expose the local map API on `127.0.0.1:8111`.

The current coordinate and speed estimates are intentionally conservative because War Thunder's local API shape can vary by mode and vehicle. Use real `map_info.json` and `map_obj.json` captures to tune projection and spot radar math for a specific game mode.

## Local API Stub

For UI development without War Thunder, run the deterministic local API stub:

```bash
cd ehwrj
scripts/run-local-api-stub.sh
```

It serves:

- `http://127.0.0.1:8111/map_info.json`
- `http://127.0.0.1:8111/map_obj.json`
- `http://127.0.0.1:8111/map.img`
- `http://127.0.0.1:8111/state`
- `http://127.0.0.1:8111/hudmsg`
- `http://127.0.0.1:8111/gamechat`

Use another port for endpoint testing:

```bash
scripts/run-local-api-stub.sh 18111
```

## Capturing Real Local API Data

When War Thunder is running on Windows, capture the local API into a fixture directory:

```bash
cd ehwrj
scripts/capture-local-api.sh captures/my-session
```

The capture tool saves:

- `map_info.json`
- `map_obj.json`
- `map.img`
- `state.json` when `/state` is available
- `hudmsg.json` when `/hudmsg` is available
- `gamechat.json` when `/gamechat` is available
- `capture-report.txt` with parser coverage, raw object field frequency, unknown object samples, replay readiness, and tuning warnings

Validate an existing capture:

```bash
scripts/validate-capture.sh captures/my-session
```

Use the report to tune real game-mode support. The most useful sections are `Object field coverage`, `Unknown object samples`, and `State field names`; they show which raw War Thunder fields are present and where object classification or telemetry parsing needs adjustment.

Replay a capture through the local API stub:

```bash
scripts/run-local-api-stub.sh 8111 captures/my-session
```

## New Code Structure

```text
Directory.Build.props
  shared compiler, analyzer, and Windows-targeting settings
docs/
  architecture and feature parity notes
scripts/
  Ubuntu bootstrap, safety scan, capture, publish, and packaging helpers
src/Ehwrj.App/
  Avalonia desktop UI and overlay host
src/Ehwrj.App/Models/
  UI settings, localization text, endpoint health, and render snapshots
src/Ehwrj.App/Services/
  polling adapter and settings store
src/Ehwrj.App/Rendering/
  main map and overlay drawing surfaces
src/Ehwrj.App/ViewModels/
  app state and UI commands
src/Ehwrj.App/Infrastructure/
  minimal Win32 interop for click-through overlay styles
src/Ehwrj.Core/
  loopback API parsing, map models, telemetry models, tracking, and projection logic
src/Ehwrj.Core/Models/
  War Thunder map object, map info, flight state, battle message, and motion tracker types
src/Ehwrj.Core/Services/
  local WT API client, process probe, loopback guard, and capture fixture analyzer
src/Ehwrj.Core/Geometry/
  viewport, projected point, and coordinate projection math
tools/Ehwrj.Tools.LocalApiStub/
  deterministic local map API server and capture replay helper
tools/Ehwrj.Tools.Capture/
  local API fixture capture and validation tool
tests/Ehwrj.Tests/
  lightweight parser, projection, localization, settings, and safety checks
artifacts/ehwrj-win-x64/
  committed portable Windows x64 build output, including Ehwrj.exe and checksums
```

## CI

The repository includes a GitHub Actions workflow that restores, checks formatting, builds with warnings as errors, runs the lightweight tests, publishes a Windows x64 artifact, and uploads it as `ehwrj-win-x64`.

## Feature Parity

See [docs/feature-matrix.md](docs/feature-matrix.md) for the benign WT Live Map feature parity status and remaining data gaps.