Every Chromium child process a client spawns (renderer, GPU, the storage and
audio utilities) runs cef_subprocess.exe. It is one Framework target shared
by every project. The network service is the exception: it runs inside the
game process (see below). It ships next to the client DLL, and every launch puts a fresh copy
of it on players' machines. Antivirus engines therefore see it more than any
other file we ship, so this page covers what it does and the rules that keep
it from being flagged.
Framework::GUI::Manager initialises CEF with
settings.browser_subprocess_path pointing at cef_subprocess.exe in the
directory of the owning module (the injected client DLL), not the
process exe. The game process is the browser process; every child is a
cef_subprocess.exe. The sandbox is off (no_sandbox = true), which is what
makes a separate subprocess exe possible at all. See "Signing" for why the
sandboxed layout does not fit us.
The exe is three translation units:
| file | role |
|---|---|
gui/cef/subprocess_main.cpp |
entry point: parent watch, then CefExecuteProcess |
gui/cef/renderer_app.cpp |
RendererApp, the renderer side of the JS bindings (callEvent) and of the focus reports push-to-talk reads (InputFocus) |
gui/resources/scheme.cpp |
custom scheme registration |
Every process in a CEF instance must register the identical set of custom
schemes, which is why scheme.cpp is compiled into both the client and the
subprocess, and why the scheme name is framework-wide (see
local_resource_scheme.md). A project cannot have its own subprocess without
also having its own scheme set.
App::OnBeforeCommandLineProcessing enables Chromium's
NetworkServiceInProcess2 feature, so the network service (DNS, HTTP, TLS,
cookies, the disk cache) runs on threads of the browser process instead of in
a cef_subprocess.exe of its own. Two things single that helper out when it
is a process:
- It is the one unsandboxed child Chromium assigns to a kill-on-close job
(
sandbox/policy/win/sandbox_win.cc,LaunchWithoutSandbox, gated byUtilitySandboxedProcessLauncherDelegate::ShouldUnsandboxedRunInJob). A failed assignment terminates the child with exit code 1 before it runs a line, and nothing is logged in a release build (DPLOG). - It is the one helper that opens sockets, which is what security software judges an unsigned, windowless exe on.
Shipped builds have shown exactly that shape: the network service exits as it
launches and Chromium restarts it every 27 ms for the whole session
(Network service crashed or was terminated, restarting service. thousands
of times in cef.log), the menu stays blank, and the renderer and GPU
helpers run fine. The trigger is environmental and was never reproduced on a
developer machine: launching the same shipped build from a terminal, from
Explorer with the mark of the web (inside Explorer's BREAKAWAY_OK job), or
inside a synthetic job all worked. In-process there is nothing to launch,
kill or police, so the failure mode is gone whatever triggers it. The cost is
that a crash in the network stack now takes the game with it, which for a UI
that serves local resources is the right trade.
Manager::Init logs, at debug level, whether the game process runs inside a
job and that job's limit flags, so a report of the blank menu shows the
host's setup.
If the game dies without reaching CefShutdown (a crash, a kill from Task
Manager), Chromium's children are not reliably torn down. CEF still has no
built-in fix for this (chromiumembedded/cef#3614). The subprocess
therefore waits on the game process and calls ExitProcess(0) when it ends.
The browser process names itself. App::OnBeforeChildProcessLaunch appends
--fw-parent-pid=<pid> (kParentProcessSwitch in renderer_app.h) to every
child's command line. The child reads it with CefCommandLine, opens the
process with SYNCHRONIZE only, and waits on it from a thread.
The PID is deliberately not read from the process's own kernel block.
The helper used to resolve NtQueryInformationProcess through
GetProcAddress and read PROCESS_BASIC_INFORMATION::InheritedFromUniqueProcessId.
That combination, together with an unsigned, windowless exe launched by an
injected DLL, got the release build quarantined by Windows Defender as a
trojan.
Everything added to this exe is judged by heuristic scanners on a binary with no reputation. Keep it boring:
- Documented Win32 only. No
ntdllexports, noGetProcAddressfor system functions, no undocumented structures (PEB,TEB, theReserved*fields ofwinternl.h). - No process or memory access beyond
SYNCHRONIZEon the parent. Nothing that opens other processes, reads or writes their memory, enumerates processes or modules, or adjusts token privileges. - No anti-debug or anti-tamper. The client's string encryption and
/GR-are for the client DLL. Do not carry them over here; an obfuscated helper looks like a dropper. - Data reaches the child on its command line. If a child needs something
from the browser process, add a switch in
OnBeforeChildProcessLaunch. Never have the child discover it by inspecting the system. - No network, file or registry access of its own. Chromium does its own I/O; the helper's code should do none.
code/framework/CMakeLists.txt calls fw_set_binary_identity() on the
target, so the exe carries a VERSIONINFO with company MafiaHub, product
MafiaHub Framework, description MafiaHub Framework Web Helper, and the
version from the Framework VERSION file.
It carries the Framework's identity, not a project's, because every
project in a configure shares the one target. A second
fw_set_binary_identity(cef_subprocess ...) from a project would add a
second version resource and fail the link. A project that needs its own
branding on the helper needs its own target, and with it its own copy of the
scheme set (see above).
The linker's default manifest (asInvoker) is embedded; no custom manifest
is needed.
None of this replaces a code signature. That is the one thing that reliably keeps Defender and SmartScreen quiet.
- No signed prebuilt exists. The helper runs our
RendererAppand our scheme set, so nobody else's binary can stand in for it. The CEF binary distribution is unsigned as well:libcef.dll,chrome_elf.dll,bootstrap.exeandbootstrapc.exeinvendors/cef/.../Releaseall reportNotSigned. Signing is the embedder's job. - What to sign in a release:
cef_subprocess.exe,libcef.dll,chrome_elf.dlland the project's own launcher and client DLL, all with the same certificate. - The CEF bootstrap does not apply. Since M138 CEF ships
bootstrap.exe/bootstrapc.exefor sandboxed apps. They load the application as a DLL and requirechrome_elf.dllto be signed with the same certificate as the exe. Our client is injected into a game rather than loaded by a CEF exe, so the bootstrap layout has nowhere to go. We stay on the separate-subprocess layout, which rules out the sandbox.
- Get the detection name from Windows Security's protection history, or from
the Defender operational event log (events 1116/1117). A
!mlsuffix (e.g.Trojan:Win32/Wacatac.B!ml) is a machine-learning verdict on the binary's shape. A named signature is a match on specific bytes. - Submit the exact released file as a false positive at https://www.microsoft.com/wdsi/filesubmission, as "software developer". Definitions usually clear it within one to three days. This needs doing per release while the binaries are unsigned, since each build is a new hash.
- For an
!mlverdict, check the latest changes to the helper against the rules above before blaming the scanner.