Guardian

Guardian — отдельный Windows user-mode supervisor. Electron не запускает javaw.exe напрямую: он формирует policy из уже проверенных manifests и передаёт её Guardian. Guardian повторно проверяет доверенные данные, создаёт Java-процесс в приостановленном состоянии, применяет Windows mitigations, помещает процесс в Job Object и только затем разрешает выполнение.

Запуск вручную

wraithbound-guardian.exe `
  --policy "C:\path\guardian-policy.json" `
  -- `
  --username Player `
  --uuid 0123456789abcdef0123456789abcdef `
  --accessToken session-token

Аргументы policy хранят постоянные JVM/classpath параметры. Всё после -- добавляется только в память процесса. Launcher использует эту часть для username, UUID и access token.

Policy, создаваемая лаунчером

{
  "schemaVersion": 1,
  "root": "C:\\Users\\Player\\AppData\\Roaming\\Wraithbound\\storage",
  "executable": "runtimes/java-21-win32-x64/bin/javaw.exe",
  "executableSha256": "64-hex-characters",
  "arguments": [
    "-XX:+DisableAttachMechanism",
    "-Xms1024M",
    "-Xmx4096M",
    "-cp",
    "absolute;classpath;entries",
    "net.minecraft.client.main.Main"
  ],
  "workingDirectory": "common/Create",
  "protectedFiles": [],
  "allowedModules": [],
  "scanIntervalMs": 250,
  "integrityIntervalMs": 60000,
  "strictMitigations": true,
  "requireJobObject": true,
  "blockJavaAgents": true
}

Общий root равен storage, а не каталогу одной сборки. Благодаря этому одна policy одновременно охватывает:

Java в storage/runtimes/{runtimeId};
JAR, mods и natives в storage/common/{profile.dir}.

Поля policy

Поле	Назначение
`schemaVersion`	Версия контракта; сейчас только `1`
`root`	Абсолютный общий корень доверенных ресурсов
`executable`	Безопасный относительный путь к `javaw.exe`
`executableSha256`	Hash executable из runtime manifest
`arguments`	Несекретные JVM/classpath/mainClass arguments
`workingDirectory`	Относительный каталог клиента
`protectedFiles`	Неизменяемые файлы из `updateVerify` и весь Java runtime с size/hash
`allowedModules`	Разрешённые несистемные DLL из manifests
`scanIntervalMs`	Интервал проверки загруженных модулей, 100–10000 мс
`integrityIntervalMs`	Интервал повторного hash-контроля, 1 с–1 час
`strictMitigations`	Включить совместимые process mitigations
`requireJobObject`	Отказаться от запуска, если Job Object недоступен
`blockJavaAgents`	Запретить Attach API и Java instrumentation

Проверка пути и файла

Guardian принимает только относительные пути с /. Запрещены:

абсолютные пути и drive prefix;
..;
обратные слеши;
символические ссылки/reparse chain;
дублирующиеся пути без учёта регистра.

Перед запуском javaw.exe проверяется по размеру и SHA-256. Protected files проверяются до старта и повторно во время работы игры. Manifest-файлы с типом configuration не входят в runtime-policy: Scanner восстанавливает их перед запуском, но моды могут штатно менять такие файлы во время инициализации.

Контроль DLL

Guardian перечисляет модули процесса через ToolHelp API. Разрешены:

сам Java executable;
DLL внутри Windows System32;
DLL, явно перечисленные в allowedModules и совпавшие по hash.

Лаунчер строит allowedModules из .dll файлов client/runtime manifests. Неизвестная сторонняя DLL считается нарушением и завершает всё дерево игры. Во время старта Java список DLL быстро меняется, и Windows может временно вернуть ERROR_BAD_LENGTH или ERROR_PARTIAL_COPY. Guardian повторяет снимок внутри ограниченного окна и один раз отправляет guardianWarning. Успешный снимок сбрасывает счётчик; неизвестная DLL по-прежнему вызывает немедленное нарушение, а восемь последовательных нестабильных циклов завершают процесс.

Все штатные LWJGL/JVM natives должны входить в manifest. Иначе Guardian корректно воспримет их как неизвестный модуль и остановит Minecraft.

Защита JVM

Guardian удаляет из окружения:

_JAVA_OPTIONS
JAVA_TOOL_OPTIONS
JDK_JAVA_OPTIONS
CLASSPATH

При blockJavaAgents = true запрещены:

-javaagent:
-agentlib:
-agentpath:
-Xrun
-Xbootclasspath
-XX:+StartAttachListener
-XX:-DisableAttachMechanism
-XX:+EnableDynamicAgentLoading
-Djdk.attach.allowAttachSelf=true

Guardian сам добавляет -XX:+DisableAttachMechanism. Custom Wraithbound authlib не является agent: она должна лежать в проверенном classpath сборки. Поэтому запрет instrumentation не мешает штатной авторизации Minecraft. Файлы только из update восстанавливаются перед запуском, но не входят в периодический protectedFiles: игра может штатно менять, например, servers.dat. Конфигурации из updateVerify также проверяются Scanner перед стартом, но исключаются из runtime-защиты по manifest kind configuration. JAR, библиотеки, natives, моды и весь Java runtime остаются защищёнными.

Job Object и остановка

Job Object создаётся с режимом kill-on-close. Если пользователь нажал «Остановить», Guardian завершился или Electron аварийно закрыл его handle, Windows завершает всё дерево Minecraft, включая дочерние процессы.

События stderr

{"type":"guardianStarted","processId":1234,"strictMitigations":true}
{"type":"guardianWarning","message":"..."}
{"type":"guardianViolation","processId":1234,"category":"module","message":"..."}
{"type":"fatal","message":"..."}

Launcher переносит warning/violation/fatal в отдельную debug console без вывода access token.

Итог stdout

{
  "schemaVersion": 1,
  "status": "exited",
  "processId": 1234,
  "exitCode": 0
}

Exit codes Guardian

Код Guardian	Значение
`0`	Minecraft завершился, Guardian не обнаружил нарушение
`1`	Ошибка policy, пути, Windows API или запуска процесса
`10`	Нарушение целостности/неразрешённый модуль; процесс завершён

exitCode внутри итогового JSON — код самого процесса Minecraft.

Граница защиты

Guardian повышает стоимость user-mode DLL injection, подмены JAR/native и Attach API, но не является kernel anti-cheat. Администратор системы или kernel driver принципиально находятся выше его доверительной границы. На сервере всё равно нужны поведенческие проверки и валидация игрового протокола.

Контракты и сборка

Модули

Запуск вручную

Policy, создаваемая лаунчером

Поля policy

Проверка пути и файла

Контроль DLL

Защита JVM

Job Object и остановка

События stderr

Итог stdout

Exit codes Guardian

Граница защиты

​Запуск вручную

​Policy, создаваемая лаунчером

​Поля policy

​Проверка пути и файла

​Контроль DLL

​Защита JVM

​Job Object и остановка

​События stderr

​Итог stdout

​Exit codes Guardian

​Граница защиты

Запуск вручную

Policy, создаваемая лаунчером

Поля policy

Проверка пути и файла

Контроль DLL

Защита JVM

Job Object и остановка

События stderr

Итог stdout

Exit codes Guardian

Граница защиты