Compare commits

...
Author SHA1 Message Date
poli0981andClaude Opus 5.5 f06ff2a1bd feat(guard): the native half of the user-mode exception - the guard tolerates one named user-mode family and keeps scanning, and the Overlay learns it before its loader detour exists (D33)
Owner decision D33 (2026-09-26, beta.9 PR-1 of 4): a per-game exception for anti-cheat
that is user-mode throughout, bound to evidence (>= 2 successful Tier-1 sessions), chosen
with CLAUDE.md rule 2 and D22 quoted back. This PR is the part the guard and the Overlay
own; nothing asks for it yet (NativeAntiCheatGuard passes no family), so every game is
judged exactly as in beta.8. The Agent's half is PR-2, the App's and the legal text PR-3.

- ABI: FlGuardEvaluate, FlGuardedInject, FlGuardedInjectWhenReady and FlStaticPreScanGame
  take `const char* toleratedFamilies` - family NAMES, never evidence; nullptr/"" is
  today's behaviour. No new entry point, and nothing of the withdrawn bypass comes back.
- fl::guard::FamilyIsUserModeOnly / ResolveTolerance / MatchNameTolerating: the guard
  itself decides which names it honours - a family with no drivers or services entry and
  no .sys among its files, in the floor AND the rules file (the floor cannot shrink, so
  data can make a family kernel-level and never the reverse). At most 8 names.
- Tolerant scans keep scanning past a tolerated hit (module sink, CheckModules, the tree
  walk), so a second family, a suspicious module or a .sys further in still refuses - the
  load-order fail-open S22(b) closed for the exemption. A .sys is refused whichever family
  matched it. Title lists, drivers, services, the fuzzy tier, scan failures,
  TargetUnreadable, WOW64 and the kill switch are untouched; the Vulkan branch evaluates
  strictly (the layer's self-scan goes inert on any anti-cheat module).
- kAllowedUserModeException = 28 (the slot the withdrawn bypass left): an allow that names
  the family and signal it let through. Managed: AntiCheatRefusalReason
  .AllowedUnderUserModeException, AntiCheatVerdict.RanUnderException / AllowedUnderException;
  IsFindingAboutTheGame stays false for it; Refused() cannot carry either allow.
- fl_tolerance.h: Local\FrameLedger.Tolerate.<pid>, FlTolerance (16 + 8 x 64 = 528 B), the
  Agent's channel to the Overlay BEFORE injection (the ring is the Overlay's, created after
  its detour would need the answer). Mirrored as Shared.FlTolerance / ToleranceLayout and
  held by ShmLayoutMirrorTests through fl-layout-dump.
- Overlay: InitThread reads the mapping once, before InstallLoaderHook, resolves each name
  against its own compiled floor and honours only a user-mode family (a 64-bit mask over the
  floor's module families, logged as TOLERANCE). Hook_LoadLibraryExW tests one bit before
  the early stop.
- NativeAntiCheatGuard: the parameter crosses as NUL-terminated UTF-8 byte[] (CA2101 rejects
  [MarshalAs(LPUTF8Str)] string), the shape FlGuardCheckRules already used.

Overhead: the present path is unchanged - no per-frame hook body was edited. The loader
detour gains one acquire load of a uint64, a shift and a compare on the floor-match branch
only (a branch taken approximately never); the mapping is read once on the init thread.

Tests: guard_test [D33] (6 cases, 73 assertions): the user-mode matrix, ResolveTolerance,
the allow and its family/signal, everything outside the family still refusing (EAC named,
BattlEye after NEP2, a suspicious module, vgk.sys, vgc, a title list, the Aniimo shape with
NEPKernel.sys, an incomplete walk, an unreadable process), the pre-scan answering as the
chokepoint does, and an integration case: a decoy NEP2.dll loaded 2.5 s after injection
does not stop the Overlay when the mapping names NetEase Yidun, and does when it names
Easy Anti-Cheat. AntiCheatVerdictTests, ShmLayoutMirrorTests, ReasonTextTests follow the
new reason.

Docs: CLAUDE.md rule 2 (amendment D33), 19_SAFETY (new section The user-mode exception,
cross-references), 17_HOOK_ENGINE (the detour note, overhead), 07_IPC (section D, the
tolerance mapping), HANDOFF (the beta.9 train: decision, evidence, traps), CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 03:20:17 +07:00
25 changed files with 1109 additions and 110 deletions

No files matched your search

+11 -1
View File
@@ -27,7 +27,17 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
## [Unreleased]
_Nothing yet — entries continue here after `0.1.0-beta.8`._
### Added
- **Groundwork for the user-mode anti-cheat exception** (owner decision D33, 2026-09-26; the option, the list and the
disclosure arrive later in this train). The guard can now be asked to let ONE named anti-cheat family through, and
grants it only for a family whose every signal — in the built-in floor and in the rules file — is user-mode: no
driver, no service, no `.sys` (on today's rules NetEase Yidun, AhnLab HackShield, Anybrain and FredaikisAntiCheat).
It still runs every check and keeps scanning past what it let through, so a second anti-cheat, a kernel driver in
the game's folder, a title list, a driver or service on the machine, or a scan that could not finish still refuses;
a pass that let something through says so and names it. The injected Overlay learns the same family before it
starts watching the game's module loads, so a late-loading module of that family does not stop it and any other
anti-cheat still does. Nothing asks for any of this yet: every game is judged exactly as in beta.8.
## [0.1.0-beta.8] - 2026-09-25
+1
View File
@@ -16,6 +16,7 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
> **Amended 2026-09-22 (owner decision): the override of 2026-09-21 is withdrawn, and the sentence above is the rule again.** For one day (releases `0.1.0-beta.3` and `beta.4`) a per-game override existed. The owner withdrew it: no entry point, no message, no column (schema 0008 drops 0007's five), no string. Do not add one in any form.
>
> **A finding turns the game's hooking off** (`19_SAFETY` §What a finding does to the game). An anti-cheat named in the game itself — its process, its title lists, its folder — is written to the row exactly as the pre-scan always wrote it (`hook_enabled = 0`, `hook_blocked_reason`, `hook_prescan_state = 'blocked'`), and since 2026-09-22 also when the guard finds it at a session's start or at the 30 s re-scan (`AntiCheatVerdict.IsFindingAboutTheGame`). A machine-wide driver or service refuses that session only. The notice, the game's page, the session's notes and the Agent's log all say it happened. Nothing clears the block, as before.
> **Amended 2026-09-26 (owner decision D33): one narrow, evidence-bound exception.** Asked with the 2026-09-22 withdrawal and this rule quoted back, the owner chose a per-game exception for anti-cheat that is **user-mode throughout** — a Settings option off by default, then the user ticks each eligible game through a versioned disclosure (bans are possible and can arrive days later). Eligible only when every finding about the game is `BlockedModule` / `AntiCheatFile` / `AntiCheatDirectory` of ONE family whose floor-and-file footprint has no driver, service or `.sys` (`fl::guard::FamilyIsUserModeOnly` — the GUARD decides, from a family NAME the caller passes), no `.sys` is anywhere in the install tree, no title list names the game, and the ledger holds ≥ 2 successful Tier-1 sessions of it. Drivers, services, title lists, the `.sys` rule, the fuzzy tier, scan failures, `TargetUnreadable`, 32-bit, the kill switch and Vulkan are never excepted. The guard runs every check and keeps scanning past the tolerated family (`kAllowedUserModeException`, reason 28); the Overlay learns the family from `Local\FrameLedger.Tolerate.<pid>` before its loader detour exists. A new finding, a crash / safety unhook / floor stop under it, or an executable change ends it; the block is never cleared. **No other form of override is to be added** (`19_SAFETY` §The user-mode exception).
3. **Never implement evasion.** No manual mapping, no PE header erasure, no thread hiding, no signature obfuscation, no unlinking from the PEB module list. Injection uses documented `LoadLibraryW`. The DLL keeps its real name, real exports, and version info. A performance tool must be *visible* to anti-cheat, not hidden from it. Any PR that makes FrameLedger harder to detect is rejected on principle.
4. **Never read or write game memory outside our own hooks.** We read arguments passed to APIs we hooked and COM/handle objects we legitimately own. No pattern scanning for game internals, no reading player/entity state, no writing to game memory. Ever.
5. **The hook must never crash the game.** Every hook body: SEH-guarded, allocation-free, lock-free, no logging, no exceptions crossing the boundary. On repeated faults, self-disable (`17_HOOK_ENGINE` §Fault policy).
+22
View File
@@ -260,6 +260,28 @@ same class of bug as record drift.
Agent is inert from the beginning rather than enjoying a grace window.
- If `unhookRequested` is set, the Overlay disables hooks within one frame and sets `status = unhooked`. This path must be the fastest, most-tested code in the DLL: it is the safety stop.
## D — the tolerance mapping (`Local\FrameLedger.Tolerate.<pid>`), D33 (2026-09-26)
Agent → Overlay, once, BEFORE the injection it concerns: the anti-cheat family NAMES a game's user-mode exception
covers (`19_SAFETY` §The user-mode exception). It cannot live in A + B: the Overlay creates that mapping on init and the
Agent opens it afterwards, while the Overlay's loader detour must know the tolerance from the moment it exists.
```cpp
struct FlTolerance { // fl_tolerance.h; 16 + 8 x 64 = 528 B, no padding
uint32_t magic; // @0 FL_TOLERANCE_MAGIC ("FLTL")
uint32_t version; // @4 FL_TOLERANCE_VERSION (1)
uint32_t count; // @8 names used, <= 8
uint32_t reserved; // @12 zero
char families[8][64]; // @16 NUL-terminated ASCII family names
};
```
Created by the Agent for the game's pid, current user only, held for the session; read once by the Overlay's
`InitThread` before `InstallLoaderHook`, which resolves every name against its own compiled floor and honours only a
user-mode family. Absent, malformed or naming anything else: nothing is tolerated. Mirrored as `FlTolerance` /
`ToleranceLayout` in `FrameLedger.Shared` and held to the native layout by `ShmLayoutMirrorTests` through
`fl-layout-dump`. *(Built in beta.9 PR-1: the Overlay reads it; the Agent writes it from PR-2.)*
## C — command pipe (`\\.\pipe\FrameLedger.v2`)
Unchanged in spirit from v1, bumped to `v2` for the new message set.
+10
View File
@@ -57,6 +57,16 @@ The injected DLL. Its whole job: install hooks, write 64-byte records into a rin
> them and the loader does not list them. Body under `FL_HOOK_GUARD`, no allocation, no lock, no
> logging (rule 5). Exercised by `hook-harness --load-after-ms N PATH` (up to four), against the real
> Overlay in a real target, both jobs.
>
> **D33 (2026-09-26): one family may be tolerated.** Before `InstallLoaderHook`, `InitThread` reads
> `Local\FrameLedger.Tolerate.<pid>` once (`fl_tolerance.h`; absent = nothing tolerated, the ordinary case),
> resolves each name against its OWN compiled floor, honours only a family whose whole footprint there is
> user-mode (`fl::guard::FamilyIsUserModeOnly`) and keeps a 64-bit mask over the floor's module families. The
> detour's only change is one bit test before (b): a tolerated family's module loading late is not an early stop.
> **Overhead:** one relaxed-acquire `uint64` load, a shift and a compare, on the floor-match branch alone — a branch
> that fires approximately never — and nothing on the present path; the tolerance is read on the init thread, not in
> a hook body (and logged there as `TOLERANCE`). ctest `fl_guard` `[D33]` loads a decoy `NEP2.dll` 2.5 s in: the
> Overlay keeps recording when the mapping names NetEase Yidun, and stops when it names Easy Anti-Cheat.
4. Install present hooks for what exists (below).
5. Install feature hooks (upscaler / RT / PSO) lazily — the first time their module appears.
6. Publish `status = ready` in the handshake block.
+63 -3
View File
@@ -18,7 +18,7 @@ These are permanently out of scope. A PR implementing any of them is rejected re
- Hiding, renaming, or randomizing the DLL, its exports, or its shared-memory object names
- Thread hiding (`NtSetInformationThread`/`ThreadHideFromDebugger`) or debugger-evasion tricks
- Signature-breaking obfuscation/packing of our own binaries
- Any "bypass" setting, "stealth mode", or documentation explaining how to defeat the guard below. *(The first two words left this line on 2026-09-21 and returned on 2026-09-22 — §What a finding does to the game.)*
- Any "bypass" setting, "stealth mode", or documentation explaining how to defeat the guard below. *(The first two words left this line on 2026-09-21 and returned on 2026-09-22 — §What a finding does to the game. The one exception the owner has granted since, D33 on 2026-09-26, is not a bypass: the guard still runs every check and decides itself which family is user-mode — §The user-mode exception.)*
- Reading or writing game memory outside the arguments of APIs we hooked
- Kernel drivers of our own
@@ -394,7 +394,7 @@ the injection primitive, not a fifth question about the title.
- **Absent** is still `kInjectionFailed`, not `kPayloadNotOurs`. A damaged install
and a misuse of the ABI are different problems and must not share a reason.
> **There is no override.** ~~There is one, since 2026-09-21, and it is none of the things this paragraph named~~ *(one day; withdrawn 2026-09-22)*: still no hidden setting, no config-file flag, no CLI switch, no "advanced users" escape hatch, no global form. If a user disagrees with a specific entry, the path is still a GitHub issue against the rules file, reviewed in public. What exists is below.
> **There is no override.** ~~There is one, since 2026-09-21, and it is none of the things this paragraph named~~ *(one day; withdrawn 2026-09-22)*: still no hidden setting, no config-file flag, no CLI switch, no "advanced users" escape hatch, no global form. If a user disagrees with a specific entry, the path is still a GitHub issue against the rules file, reviewed in public. What exists is below — and since 2026-09-26 (D33), one narrow, evidence-bound exception for anti-cheat that is user-mode throughout, which lets a named family through while every check still runs (§The user-mode exception).
### What a finding does to the game — owner decision 2026-09-22
@@ -455,7 +455,8 @@ card is back with the finding under its disabled switch. The finding itself is o
**What clears it.** Nothing, as before: the block outlives *Change executable* and a re-import (§A game already enabled
can become blocked later). The owner asked for hooking to be turned off when anti-cheat is detected, not for a second
switch.
switch. *(Still true under D33: an exception is a separate layer over the block, never a clearing of it — §The user-mode
exception.)*
**D21 stands as a fact.** A process an anti-cheat driver protects is `SessionEndReason.TargetUnreadable` (2026-09-21:
every candidate of that name exists and none can be opened; ELDEN RING under Easy Anti-Cheat on the owner's machine).
@@ -467,6 +468,65 @@ still finds the injection primitives in exactly that file and the evasion primit
to four methods (`NoSecondMatcherTests`). `FloorFamilies` is untouched.
### The user-mode exception — owner decision 2026-09-26 (D33)
**Why it exists.** The beta.8 library sweep turned hooking off for *GIRLS' FRONTLINE 2: EXILIUM* on a documented,
unmeasured rule — NetEase Yidun, `AntiCheatFile NEP2.dll` — after FrameLedger had measured that game hooked (three
normal Tier-1 sessions in the owner's ledger, 474,143 frames). The owner asked for a way to keep measuring a game like
that, and chose, against the rule this document had kept since 2026-09-22 and with that rule quoted back to them, **an
exception the user grants per game, bound to evidence, and only for anti-cheat that is user-mode throughout.** The
reasons D22 withdrew the override are answered one by one: it "did nothing where it was wanted" — an exception is only
offered where FrameLedger has already measured the game hooked; it "only exposed the user to the risk its own disclosure
described" — that risk stands, and the disclosure says so, including that a ban can arrive days later and that FrameLedger
cannot know.
**What may be excepted — all of it must hold:**
- every finding about the game is `BlockedModule`, `AntiCheatFile` or `AntiCheatDirectory` of **one** family;
- that family's whole footprint is user-mode — no `drivers` entry, no `services` entry and no `*.sys` among its `files`, in
the compiled floor or the rules file (`fl::guard::FamilyIsUserModeOnly`). The floor cannot be shrunk, so data can make a
family kernel-level and never the reverse. On today's data that leaves NetEase Yidun, AhnLab HackShield, Anybrain and
FredaikisAntiCheat; Easy Anti-Cheat, BattlEye, ACE, NetEase Anti-Cheat, mihoyo protect, Vanguard, Ricochet and every
other family carry a driver or a service and are never excepted;
- no `*.sys` anywhere in the install tree — the kernel-driver rule (D30) is never excepted, whichever family a driver
belongs to (so *Aniimo*, which unpacks `NEPKernel.sys` beside `NEP2.dll` on its first run, stays blocked);
- the game is on no title list (`BlockedExecutable`, `BlockedStoreId` — the notorious titles are there by design);
- the ledger holds **at least two successful Tier-1 sessions** of the game: hooked, frames recorded, `exit_status = normal`
(which since beta.8 includes End task's exit code 1 and a user's stop), never crashed, never unhooked for safety.
**Never excepted, whatever the user ticked:** a machine-wide `BlockedDriver` or `BlockedService`, the fuzzy tier
(`SuspiciousUnsigned`), a scan that could not look or finish, unusable rules, `TargetUnreadable` (D21), a 32-bit target,
the kill switch, and a Vulkan target (the implicit layer's own self-scan stays strict).
**How the guard takes it.** The four evaluating ABI entries carry `toleratedFamilies` — a NAME, never evidence
(`fl_guard_abi.h`). The guard resolves it against its own rules (`ResolveTolerance`), keeps only a user-mode family,
runs every check, lets that family's modules, files and folders through **and keeps scanning past them**, so a second
family, a suspicious module or a `.sys` further in still refuses. A pass that let something through is
`kAllowedUserModeException` (reason 28, the slot the withdrawn bypass left) with the family and the signal; the session it
starts is marked with them.
**How the Overlay takes it.** The Overlay stops observing when a floor module loads after injection, so the Agent
publishes the exception's family names in `Local\FrameLedger.Tolerate.<pid>` (`fl_tolerance.h`) before it asks the guard
to inject, and the Overlay's init thread reads them once, before its loader detour exists — resolving each against its
own compiled floor and honouring only a user-mode family. A mapping that names anything else tolerates nothing, and the
Agent's 30 s re-scan keeps judging every other signal.
**What ends it.** A new finding outside the excepted family at any of the four moments above writes the block as before
and revokes the exception; a session under it that crashes, is unhooked for safety or is stopped by the Overlay's
in-process floor stop revokes it; an executable change ends it with the consent it shared a fingerprint with; turning
the option off suspends every exception. **The block itself is never cleared** — the exception is a separate layer over
it, and the finding stays on the game's page (FR-2.2).
**What it is not.** Not a bypass of a live refusal, not a global switch (a Settings option off by default enables the list,
and the user ticks each game), not reachable from the command line, and not evasion: the DLL stays `LoadLibraryW`-loaded,
named and visible (rule 3). `InjectViaLoadLibrary` still has internal linkage in `fl_guard.cpp`; `tools/chokepoint-check.ps1`
is unchanged.
*Built in beta.9 PR-1: the guard's tolerance and the Overlay's channel, with nothing yet asking for either
(`NativeAntiCheatGuard` passes none). The Agent's eligibility, gate and records follow in PR-2; the option, the list,
the disclosure and the legal text in PR-3.*
### The floor data cannot remove
**There was a local bypass, and this paragraph is the reason it no longer works
+34
View File
@@ -1640,6 +1640,40 @@ only be refused, never the finding (FR-2.2).
64-bit build of the same game under *Change executable* can be hooked; the sweep's turn-off uses
`hook_autodisabled_reason`, which the page does not offer to undo while the file is still 32-bit.
## 2026-09-26 — the beta.9 train: the user-mode exception (D33)
*Status is `CHANGELOG.md` `[Unreleased]` (then `[0.1.0-beta.9]`); this is what no other file carries. The approved plan
is four PRs: PR-1 the guard's tolerance and the Overlay's channel, PR-2 the Agent (eligibility, gate, records, schema
0014, IPC), PR-3 the App, strings, docs and legal text, PR-4 the release.*
**Decision (D33, owner, 2026-09-26, asked with rule 2 and D22 quoted back).** The beta.8 sweep turned hooking off for
GIRLS' FRONTLINE 2: EXILIUM (NetEase Yidun, `AntiCheatFile NEP2.dll`, a documented and unmeasured rule) after it had
been measured hooked; the owner asked for an exception list for user-mode anti-cheat games measured at Tier 1 before.
Chosen, all four options as recommended: **evidence-bound, per game** (a Settings option off by default, then the user
ticks each eligible game); **≥ 2 successful Tier-1 sessions**; **Aniimo stays blocked** (it unpacks `NEPKernel.sys` beside
`NEP2.dll` — the D30 `.sys` rule is never excepted); **the legal text changes** (Disclaimer §2A 2.7, EULA 1.3, the
accuracy block, SECURITY.md, FR-2.3; Privacy stays 2.4). Eligibility, what is never excepted and every lapse are in
`19_SAFETY` §The user-mode exception; the rule-2 amendment is in CLAUDE.md.
**Evidence it rests on (read from a COPY of the owner's ledger and their logs, 2026-09-26).** GF2: three normal Tier-1
sessions under the current entry (474,143 frames; three more from 2026-09-21 went with a removed entry), no `.sys` in
its tree. Aniimo: one Tier-1 session stored `crashed` (End task before beta.8, no exit code kept). A randomly named
kernel driver (`lyoxztfx.sys`) was installed on 2026-09-21 at 15:38 and is gone now, service and file, by something
the logs cannot name — the residual the disclosure states: a driver outside the game folder that no rule names is
invisible to every check.
**Traps met on the way:**
- **The ring cannot carry anything the Overlay needs before its detour is armed** — the Overlay creates it. Hence the
separate `Local\FrameLedger.Tolerate.<pid>` mapping the Agent creates BEFORE the injection (`fl_tolerance.h`).
- **A tolerant scan must keep scanning.** Every sink that used to stop at the first hit returns `true` on a tolerated
one, or a second family / a `.sys` further in would pass: the same load-order fail-open §S22(b) closed for the
exemption.
- **A prefix value of a user-mode family can match a `.sys`**; the tolerant file sink refuses any `.sys` itself.
- **CA2101 rejects `[MarshalAs(LPUTF8Str)] string`** on a P/Invoke; the tolerance crosses as NUL-terminated UTF-8
`byte[]`, the shape `FlGuardCheckRules` already used.
- **The Vulkan branch evaluates strictly**: the layer's self-scan goes inert on any anti-cheat module, so an exception
there could only buy a session that measures nothing.
## Owner-only — no PR can close these
1. **§S23-2 — branch protection.** `Rules / validate` is not a required status check on
@@ -207,6 +207,19 @@ public enum AntiCheatRefusalReason
/// </summary>
KillSwitchEngaged = 27,
// Value 28 was AllowedUnderUserBypass for one day (2026-09-21) and was withdrawn with the bypass on 2026-09-22. It
// was the last value, so nothing is renumbered; the native enum dropped it in the same change (GuardMirrorTests).
// Value 28 was AllowedUnderUserBypass for one day (2026-09-21) and was withdrawn with the bypass on 2026-09-22.
/// <summary>
/// D33 (owner decision 2026-09-26): every check ran and passed, and the only findings belonged to the ONE anti-cheat
/// family the game's user-mode exception names — a family whose whole footprint, floor and file, is user-mode, which
/// the native guard decides itself. <see cref="AntiCheatVerdict.Family"/> and <see cref="AntiCheatVerdict.Signal"/>
/// carry what was let through, so the session it starts is marked with it.
/// </summary>
/// <remarks>
/// An allow — the Overlay is in the target — and never the withdrawn bypass that once held this value: nothing
/// here injected past a refusal. A driver or service on the machine, a title list, a <c>.sys</c> in the tree, the
/// fuzzy tier, a scan that could not finish and any other family all refuse under an exception exactly as without
/// one (<c>19_SAFETY</c> §The user-mode exception).
/// </remarks>
AllowedUnderUserModeException = 28,
}
@@ -45,10 +45,17 @@ public readonly record struct AntiCheatVerdict
public string Signal { get; }
/// <summary>
/// True only when a real evaluation happened AND every check passed.
/// A default-constructed verdict is never allowed.
/// True only when a real evaluation happened AND every check passed — plainly, or under the game's user-mode
/// exception (D33, <see cref="RanUnderException"/>). A default-constructed verdict is never allowed.
/// </summary>
public bool IsAllowed => _evaluated && Reason == AntiCheatRefusalReason.Allow;
public bool IsAllowed => _evaluated
&& Reason is AntiCheatRefusalReason.Allow or AntiCheatRefusalReason.AllowedUnderUserModeException;
/// <summary>
/// D33: allowed because the only findings were the excepted family's; <see cref="Family"/> and <see cref="Signal"/>
/// say what was let through. The session is marked with them.
/// </summary>
public bool RanUnderException => _evaluated && Reason == AntiCheatRefusalReason.AllowedUnderUserModeException;
/// <summary>
/// A refusal. The default-constructed value is deliberately a refusal too:
@@ -69,14 +76,21 @@ public readonly record struct AntiCheatVerdict
or AntiCheatRefusalReason.AntiCheatFile;
public static AntiCheatVerdict Refused(AntiCheatRefusalReason reason, string family, string signal) =>
reason == AntiCheatRefusalReason.Allow
? throw new ArgumentOutOfRangeException(nameof(reason), "Refused() cannot carry Allow.")
reason is AntiCheatRefusalReason.Allow or AntiCheatRefusalReason.AllowedUnderUserModeException
? throw new ArgumentOutOfRangeException(nameof(reason), "Refused() cannot carry an allow.")
: new AntiCheatVerdict(reason, family, signal);
/// <summary>Every check passed.</summary>
public static AntiCheatVerdict Allowed() =>
new(AntiCheatRefusalReason.Allow, string.Empty, string.Empty);
/// <summary>D33: every check passed, and the only findings were the excepted family's — this one, through this signal.</summary>
public static AntiCheatVerdict AllowedUnderException(string family, string signal)
{
ArgumentException.ThrowIfNullOrWhiteSpace(family);
return new(AntiCheatRefusalReason.AllowedUnderUserModeException, family, signal ?? string.Empty);
}
/// <summary>
/// Build from the native ABI's reason code. An unrecognised code refuses:
/// it means the managed mirror has drifted from <c>fl::guard::Reason</c>,
@@ -59,22 +59,28 @@ public sealed class NativeAntiCheatGuard : IAntiCheatGuard
// resolver were ever removed the fallback would still not probe the
// application directory. CA5393 rejects ApplicationDirectory for exactly
// the reason this comment exists.
// `toleratedFamilies` (D33): newline-separated family NAMES as NUL-terminated UTF-8 bytes (the byte[] shape
// FlGuardCheckRules takes, so no string crosses as ANSI), null for none — the one thing a caller may add, resolved
// and bounded by the guard itself (fl_guard_abi.h). Null until the Agent's exception passes one.
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl)]
private static extern void FlGuardEvaluate(uint targetPid, out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
private static extern void FlGuardedInject(uint targetPid, string dllPath, out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
private static extern void FlGuardedInjectWhenReady(uint targetPid, string dllPath, uint timeoutMs,
private static extern void FlGuardEvaluate(uint targetPid, byte[]? toleratedFamilies,
out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
private static extern void FlStaticPreScanGame(string exePath, out FlGuardResult result);
private static extern void FlGuardedInject(uint targetPid, string dllPath,
byte[]? toleratedFamilies, out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
private static extern void FlGuardedInjectWhenReady(uint targetPid, string dllPath, uint timeoutMs,
byte[]? toleratedFamilies, out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
private static extern void FlStaticPreScanGame(string exePath,
byte[]? toleratedFamilies, out FlGuardResult result);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_guardDll, CallingConvention = CallingConvention.Cdecl)]
@@ -109,7 +115,7 @@ public sealed class NativeAntiCheatGuard : IAntiCheatGuard
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, CancellationToken ct = default) =>
RunAsync(() =>
{
FlGuardEvaluate(checked((uint)targetPid), out FlGuardResult r);
FlGuardEvaluate(checked((uint)targetPid), null, out FlGuardResult r);
return AntiCheatVerdict.FromNative(r.Reason, r.Family, r.Signal);
}, ct);
@@ -120,7 +126,7 @@ public sealed class NativeAntiCheatGuard : IAntiCheatGuard
ArgumentException.ThrowIfNullOrWhiteSpace(payloadPath);
return RunAsync(() =>
{
FlGuardedInject(checked((uint)targetPid), payloadPath, out FlGuardResult r);
FlGuardedInject(checked((uint)targetPid), payloadPath, null, out FlGuardResult r);
return AntiCheatVerdict.FromNative(r.Reason, r.Family, r.Signal);
}, ct);
}
@@ -133,7 +139,7 @@ public sealed class NativeAntiCheatGuard : IAntiCheatGuard
ArgumentOutOfRangeException.ThrowIfNegative(timeoutMs);
return RunAsync(() =>
{
FlGuardedInjectWhenReady(checked((uint)targetPid), payloadPath, checked((uint)timeoutMs),
FlGuardedInjectWhenReady(checked((uint)targetPid), payloadPath, checked((uint)timeoutMs), null,
out FlGuardResult r);
return AntiCheatVerdict.FromNative(r.Reason, r.Family, r.Signal);
}, ct);
@@ -145,7 +151,7 @@ public sealed class NativeAntiCheatGuard : IAntiCheatGuard
ArgumentException.ThrowIfNullOrWhiteSpace(executablePath);
return RunAsync(() =>
{
FlStaticPreScanGame(executablePath, out FlGuardResult r);
FlStaticPreScanGame(executablePath, null, out FlGuardResult r);
return AntiCheatVerdict.FromNative(r.Reason, r.Family, r.Signal);
}, ct);
}
+42
View File
@@ -755,3 +755,45 @@ public unsafe struct FlFrameRecord
/// </summary>
public uint SwapchainId;
}
/// <summary>
/// D33 (owner decision 2026-09-26) — <c>fl_tolerance.h</c>: the families the injected Overlay may see load without
/// stopping, under a game's user-mode exception. Written by the Agent into <c>Local\FrameLedger.Tolerate.&lt;pid&gt;</c>
/// BEFORE it asks the guard to inject, read once by the Overlay's init thread before its loader detour exists. NAMES,
/// never indices: the Overlay resolves them against its own compiled floor and honours only a user-mode family.
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public unsafe struct FlTolerance
{
/// <summary><see cref="ToleranceLayout.Magic"/>.</summary>
public uint Magic;
/// <summary><see cref="ToleranceLayout.Version"/>.</summary>
public uint Version;
/// <summary>Names used, at most <see cref="ToleranceLayout.MaxFamilies"/>.</summary>
public uint Count;
/// <summary>Must be zero.</summary>
public uint Reserved;
/// <summary><see cref="ToleranceLayout.MaxFamilies"/> NUL-terminated ASCII names, <see cref="ToleranceLayout.NameLen"/> bytes each.</summary>
public fixed byte Families[512];
}
/// <summary>The constants of <c>fl_tolerance.h</c>. Drift is caught by the mirror test.</summary>
public static class ToleranceLayout
{
/// <summary>"FLTL", little-endian.</summary>
public const uint Magic = 0x4C544C46u;
public const uint Version = 1u;
public const int MaxFamilies = 8;
public const int NameLen = 64;
/// <summary>The mapping's name for a game process — <c>MakeToleranceName</c>.</summary>
public static string MappingName(int pid) =>
"Local\\FrameLedger.Tolerate." + pid.ToString(System.Globalization.CultureInfo.InvariantCulture);
}
@@ -139,6 +139,108 @@ struct Rules {
std::size_t trustedSignerCount = 0;
};
// ---------------------------------------------------------------------------
// D33 (owner decision 2026-09-26) — the user-mode exception
// ---------------------------------------------------------------------------
//
// A user may except ONE game from the findings of ONE anti-cheat family, and only a family whose whole known footprint
// is user-mode (19_SAFETY §The user-mode exception). A caller can NAME a family (the ABI's `toleratedFamilies`) and
// nothing more: which families a name reaches, and whether that family is user-mode, are the guard's own answers from
// the rules it is evaluating with. A name that fails here is tolerated nowhere — fail closed.
// ASCII case-insensitive equality. Inline so the Overlay, which compiles no fl_ac_rules.cpp, resolves its tolerance
// against the compiled floor with the same comparison the guard uses.
[[nodiscard]] inline bool AsciiIEquals(const char* a, const char* b) noexcept {
if (a == nullptr || b == nullptr) {
return false;
}
for (;; ++a, ++b) {
char ca = *a;
char cb = *b;
if (ca >= 'A' && ca <= 'Z') {
ca = static_cast<char>(ca - 'A' + 'a');
}
if (cb >= 'A' && cb <= 'Z') {
cb = static_cast<char>(cb - 'A' + 'a');
}
if (ca != cb) {
return false;
}
if (ca == '\0') {
return true;
}
}
}
// True for a value ending in ".sys", ASCII case-insensitively.
[[nodiscard]] inline bool EndsWithSysSuffix(const char* value) noexcept {
if (value == nullptr) {
return false;
}
std::size_t n = 0;
while (value[n] != '\0') {
++n;
}
return n > 4 && AsciiIEquals(value + n - 4, ".sys");
}
// True iff `familyName` names at least one of `families` and EVERY entry naming it sits in a user-mode group —
// modules, directories, files — with no `*.sys` value. A family with a `drivers` or `services` entry anywhere (the
// floor or the file), or a kernel driver among its files, is kernel-level and never tolerable. A name no family carries
// — a title-list family such as Valve VAC, or the kernel-driver code rule's family — is false. The floor cannot be
// shrunk by data, so a rules file can make a family kernel-level (add a driver) and never the reverse.
[[nodiscard]] inline bool FamilyIsUserModeOnly(const Family* families, std::size_t count,
const char* familyName) noexcept {
if (families == nullptr || familyName == nullptr || familyName[0] == '\0') {
return false;
}
bool named = false;
for (std::size_t i = 0; i < count; ++i) {
const Family& f = families[i];
if (!AsciiIEquals(f.name, familyName)) {
continue;
}
named = true;
if (f.group == Group::kDrivers || f.group == Group::kServices) {
return false;
}
if (f.group == Group::kFiles) {
for (std::size_t v = 0; v < f.valueCount; ++v) {
if (EndsWithSysSuffix(f.values[v])) {
return false;
}
}
}
}
return named;
}
[[nodiscard]] inline bool FamilyIsUserModeOnly(const Rules& rules, const char* familyName) noexcept {
return FamilyIsUserModeOnly(rules.families, rules.familyCount, familyName);
}
// How many names one exception list may carry. v1 grants one family per game; the room is for a later version, and a
// longer list is read up to this many names — tolerating fewer is the safe direction.
inline constexpr std::size_t kMaxToleratedFamilies = 8;
// The families one evaluation tolerates, resolved against the rules it evaluates with: `family[i]` covers
// `rules.families[i]`. Value-initialised, it tolerates nothing.
struct Tolerance {
bool family[kMaxFamilies] = {};
bool any = false;
};
// `toleratedFamilies` is newline-separated family names; null or empty tolerates nothing. A name is honoured only when
// FamilyIsUserModeOnly(rules, name) — and then for every entry of that family, in every user-mode group. Unknown and
// kernel-level names, and a name longer than kMaxFamilyNameLen - 1, are ignored: they widen nothing.
void ResolveTolerance(const Rules& rules, const char* toleratedFamilies, Tolerance& out) noexcept;
// MatchName that never returns a family the tolerance covers. When `tolerated` is non-null it receives the first
// covered family that matched `observed` (and is left untouched when none did), so a caller can record what it let
// through while a non-covered family matching the same name still refuses.
[[nodiscard]] const Family* MatchNameTolerating(const Rules& rules, Group group, const char* observed,
const Tolerance& tolerance, const Family** tolerated) noexcept;
// Returns `r` to the state of a value-initialised `Rules{}` WITHOUT materialising one.
//
// `r = Rules{}` builds a ~530 KB temporary on the stack before copying it, and ParseRules runs inside the Vulkan
@@ -183,9 +183,20 @@ enum class Reason : std::uint8_t {
kKillSwitchEngaged,
// Value 28 was kAllowedUnderUserBypass, the one day the guard had an override (2026-09-21, withdrawn by the owner
// on 2026-09-22 before any release carried it past beta.4). It was the LAST enumerator, so removing it renumbers
// nothing; the managed mirror dropped it in the same change and GuardMirrorTests holds the two counts equal. A
// refusal is a refusal again: there is no entry point that injects past one.
// on 2026-09-22 before any release carried it past beta.4). It was the LAST enumerator, so removing it renumbered
// nothing, and a refusal stayed a refusal: there is no entry point that injects past one.
//
// D33 (owner decision 2026-09-26) reuses the slot for something narrower, and it is not that override back. The
// guard ran EVERY check; the only findings it saw were of the one family the caller named, and that family's whole
// footprint — floor and file — is user-mode (FamilyIsUserModeOnly: no driver, no service, no `.sys`). Everything
// else still refused as it always does: a driver or service on the machine, a title list, a `.sys` anywhere in the
// tree, the fuzzy tier, a scan that could not finish, another family. The verdict carries the tolerated family and
// the signal, so the session it starts is marked with them (19_SAFETY §The user-mode exception).
//
// Allowed() is true for it — the DLL is loaded, which is what Allowed() has meant since kInjectionFailed existed —
// and it is produced ONLY as EvaluateImpl's final answer, never by a sub-check, so the `!Allowed()` chains between
// checks read exactly as before.
kAllowedUserModeException,
// NOT A REASON. The count, so appending above it updates the exported
// FlGuardReasonCount by construction.
@@ -207,7 +218,20 @@ struct Verdict {
char family[64] = {}; // e.g. "Easy Anti-Cheat"
char signal[260] = {}; // e.g. "EasyAntiCheat_EOS.dll"
[[nodiscard]] bool Allowed() const noexcept { return reason == Reason::kAllow; }
// kAllowedUserModeException too (D33): every check ran, and the only findings belonged to the one user-mode family
// the caller's exception names. See the enumerator.
[[nodiscard]] bool Allowed() const noexcept {
return reason == Reason::kAllow || reason == Reason::kAllowedUserModeException;
}
};
// D33 — the first finding a tolerated family produced during one evaluation (a module in the scan set, or a file or
// folder in the install tree). When nothing else refuses, it becomes the kAllowedUserModeException verdict's family and
// signal, so the session is marked with what was let through.
struct ToleratedFinding {
bool seen = false;
char family[64] = {};
char signal[260] = {};
};
// The literal default must be a refusal, not an allow. Asserted rather than
@@ -450,7 +474,12 @@ struct Sources {
// While the injection primitive was a stub, a caller passing all-clean fakes
// was a theoretical hole; the moment injection became real it would have been
// a way into a game process that never consulted a single genuine signal.
[[nodiscard]] Verdict GuardedInject(std::uint32_t targetPid, const wchar_t* dllPath) noexcept;
//
// `toleratedFamilies` (D33) is the one thing a caller may add, and it is a NAME, not evidence: newline-separated
// anti-cheat families the user's exception covers for this game, resolved against the rules by ResolveTolerance, which
// honours only a family whose whole footprint is user-mode. Null or empty is the guard exactly as before.
[[nodiscard]] Verdict GuardedInject(std::uint32_t targetPid, const wchar_t* dllPath,
const char* toleratedFamilies = nullptr) noexcept;
// LAUNCH MODE. Poll `targetPid` -- every 50 ms, up to `timeoutMs` -- until it has
// mapped a presentation runtime (dxgi.dll with d3d11.dll or d3d12.dll, or
@@ -461,19 +490,24 @@ struct Sources {
// exits first, or never maps a runtime inside the budget, is refused with
// kLaunchTargetExited / kLaunchNoPresentationRuntime and nothing is injected.
// 04_CAPTURE §Launch mode; 20_OPEN_QUESTIONS §S1 / §S13(c).
[[nodiscard]] Verdict GuardedInjectWhenReady(std::uint32_t targetPid, const wchar_t* dllPath,
std::uint32_t timeoutMs) noexcept;
//
// A Vulkan target is evaluated WITHOUT the tolerance (D33): the implicit layer runs its own module self-scan and goes
// inert on any anti-cheat module, so an exception could not reach it and must not be spent on it.
[[nodiscard]] Verdict GuardedInjectWhenReady(std::uint32_t targetPid, const wchar_t* dllPath, std::uint32_t timeoutMs,
const char* toleratedFamilies = nullptr) noexcept;
// Evaluate the guard WITHOUT injecting. Exists for the 30 s in-session re-scan
// (19_SAFETY §During a session), which must reach a verdict on a process it is
// already inside and has nothing to inject. Deliberately cannot be used to
// pre-authorise an injection: it takes no dll path and returns no token, so the
// only way to act on a pass is to call GuardedInject, which re-collects.
[[nodiscard]] Verdict Evaluate(std::uint32_t targetPid) noexcept;
[[nodiscard]] Verdict Evaluate(std::uint32_t targetPid, const char* toleratedFamilies = nullptr) noexcept;
// There were two more entry points here for one day (GuardedInjectAcknowledged and its WhenReady twin, the user's
// bypass of 2026-09-21). Withdrawn 2026-09-22: the guard has no entry that injects past its own refusal, and a
// finding about the game turns that game's hooking off instead (19_SAFETY §What a finding does to the game).
// finding about the game turns that game's hooking off instead (19_SAFETY §What a finding does to the game). D33's
// `toleratedFamilies` is not that entry: it narrows what counts as a finding for one user-mode family, and the guard
// still runs, and refuses on, everything else.
#ifdef FL_GUARD_TESTABLE
// ---------------------------------------------------------------------------
@@ -487,11 +521,13 @@ struct Sources {
// cannot be exercised is an input whose failure path is unverified. So the seam
// exists — and is unavailable to anything a user runs.
// ---------------------------------------------------------------------------
[[nodiscard]] Verdict EvaluateWithSources(std::uint32_t targetPid, const Sources& sources) noexcept;
[[nodiscard]] Verdict GuardedInjectWithSources(std::uint32_t targetPid, const wchar_t* dllPath,
const Sources& sources) noexcept;
[[nodiscard]] Verdict EvaluateWithSources(std::uint32_t targetPid, const Sources& sources,
const char* toleratedFamilies = nullptr) noexcept;
[[nodiscard]] Verdict GuardedInjectWithSources(std::uint32_t targetPid, const wchar_t* dllPath, const Sources& sources,
const char* toleratedFamilies = nullptr) noexcept;
[[nodiscard]] Verdict GuardedInjectWhenReadyWithSources(std::uint32_t targetPid, const wchar_t* dllPath,
std::uint32_t timeoutMs, const Sources& sources) noexcept;
std::uint32_t timeoutMs, const Sources& sources,
const char* toleratedFamilies = nullptr) noexcept;
#endif
// Human-readable reason, for logs and for mapping to resx keys.
@@ -46,14 +46,23 @@ struct FlGuardResult {
char signal[260]; // e.g. "EasyAntiCheat_EOS.dll"
};
// `toleratedFamilies` — D33 (owner decision 2026-09-26), on the four evaluating entries below. The user's exception
// for ONE game, by NAME: newline-separated anti-cheat families (UTF-8), null or "" for none. It is not evidence and
// it is not a switch: the guard still collects everything itself and runs every check, resolves the names against
// its own rules, honours only a family whose whole footprint is user-mode (no driver, no service, no `.sys`), and
// then lets that family's modules, files and folders through while every other finding refuses as before. A pass
// that let something through answers AllowedUnderUserModeException with the family and the signal, never Allow.
// It is not the withdrawn bypass either (below): nothing here injects past a refusal the guard made.
// Run every pre-injection check against `targetPid`. No injection.
// Used for the 30 s in-session re-scan (19_SAFETY §During a session).
FL_GUARD_ABI void FlGuardEvaluate(std::uint32_t targetPid, FlGuardResult* out);
FL_GUARD_ABI void FlGuardEvaluate(std::uint32_t targetPid, const char* toleratedFamilies, FlGuardResult* out);
// Run every check and, only on a pass, inject `dllPath` via documented
// LoadLibraryW. There is no variant that skips the checks, and no way to hand
// in evidence — the guard collects its own.
FL_GUARD_ABI void FlGuardedInject(std::uint32_t targetPid, const wchar_t* dllPath, FlGuardResult* out);
FL_GUARD_ABI void FlGuardedInject(std::uint32_t targetPid, const wchar_t* dllPath, const char* toleratedFamilies,
FlGuardResult* out);
// LAUNCH MODE (P1 item 2). Wait -- polling every 50 ms, up to `timeoutMs` -- until
// `targetPid` has mapped a presentation runtime, then run every check and inject
@@ -63,8 +72,9 @@ FL_GUARD_ABI void FlGuardedInject(std::uint32_t targetPid, const wchar_t* dllPat
// runtime inside the budget, answers LaunchTargetExited / LaunchNoPresentationRuntime
// with nothing injected. The caller launches and holds the process; this never
// creates or terminates one (04_CAPTURE §Launch mode, 20_OPEN_QUESTIONS §S1).
// A Vulkan target is evaluated without `toleratedFamilies`: the layer's own self-scan would go inert anyway.
FL_GUARD_ABI void FlGuardedInjectWhenReady(std::uint32_t targetPid, const wchar_t* dllPath, std::uint32_t timeoutMs,
FlGuardResult* out);
const char* toleratedFamilies, FlGuardResult* out);
// FlGuardedInjectAcknowledged, FlGuardedInjectWhenReadyAcknowledged and FlGuardIsJudgement were exported for one day
// (2026-09-21, the user's bypass) and withdrawn on 2026-09-22. The ABI has no entry that injects past a refusal.
@@ -82,7 +92,11 @@ FL_GUARD_ABI void FlGuardedInjectWhenReady(std::uint32_t targetPid, const wchar_
// It reports through FlGuardResult rather than an outcome enum of its own, so there is ONE reason table and ONE
// mirror surface: kAllow means clean; BlockedExecutable, BlockedStoreId, AntiCheatDirectory and AntiCheatFile name
// what was found; PreScanFailed or a Rules* reason means the scan could not reach an answer.
FL_GUARD_ABI void FlStaticPreScanGame(const wchar_t* exePath, FlGuardResult* out);
//
// With `toleratedFamilies`, AllowedUnderUserModeException means "this game passes checks 3 and 4 under its
// exception" — the question the Agent asks before it offers or keeps one (a `.sys` in the tree, a title list or
// another family still refuses).
FL_GUARD_ABI void FlStaticPreScanGame(const wchar_t* exePath, const char* toleratedFamilies, FlGuardResult* out);
// Stable name for a reason code. The managed mirror test compares these against
// its own enum, so this is a contract and not a debugging aid.
@@ -101,7 +101,13 @@ inline constexpr const char* kKernelDriverInTreeFamily = "Kernel driver in the g
// unverified (fl_guard.h rule 3). It grants nothing: it opens no process with
// injection rights, reaches no injection primitive, and returns a Verdict its
// only caller already had to reach anyway.
[[nodiscard]] Verdict CheckStaticPreScan(const Sources& s, const Rules& rules, std::uint32_t targetPid) noexcept;
//
// D33: with a `tolerance`, a file or folder of a tolerated family is recorded in `finding` and the walk goes on, so a
// kernel driver, another family or an unfinished walk further in still refuses. A `.sys` is never tolerated, whatever
// family names it. Without one (null), the check is exactly what it was.
[[nodiscard]] Verdict CheckStaticPreScan(const Sources& s, const Rules& rules, std::uint32_t targetPid,
const Tolerance* tolerance = nullptr,
ToleratedFinding* finding = nullptr) noexcept;
// Check 3's store half over an install root: the store identity it carries (Sources::StoreIdentity) against
// `blockedStoreIds`. An install with no store identity is NOT refused — "not a store title" is an answer, and
@@ -125,12 +131,17 @@ inline constexpr const char* kKernelDriverInTreeFamily = "Kernel driver in the g
//
// Loads the rules itself and uses SystemSources(), so a caller cannot choose the evidence — the same reason Evaluate
// and GuardedInject take no Sources.
[[nodiscard]] Verdict StaticPreScanGame(const wchar_t* exePath) noexcept;
//
// `toleratedFamilies` (D33), exactly as GuardedInject takes it: the verdict is kAllowedUserModeException when the only
// findings belonged to a tolerated user-mode family, which is how the Agent tells "this game would pass under its
// exception" from "it would not" without a second matcher.
[[nodiscard]] Verdict StaticPreScanGame(const wchar_t* exePath, const char* toleratedFamilies = nullptr) noexcept;
#ifdef FL_GUARD_TESTABLE
// TEST-ONLY, exactly as fl_guard.h defines the term: compiled out of everything
// that ships, and only src/native/tests may define the macro.
[[nodiscard]] Verdict StaticPreScanGameWithSources(const wchar_t* exePath, const Sources& sources) noexcept;
[[nodiscard]] Verdict StaticPreScanGameWithSources(const wchar_t* exePath, const Sources& sources,
const char* toleratedFamilies = nullptr) noexcept;
#endif
} // namespace fl::guard
@@ -617,13 +617,11 @@ ParseResult ParseRules(const char* json, std::size_t length, Rules& out) noexcep
return ParseResult::kOk;
}
const Family* MatchName(const Rules& rules, Group group, const char* observed) noexcept {
if (observed == nullptr || observed[0] == '\0') {
return nullptr;
}
namespace {
// Drivers arrive as native paths (\SystemRoot\system32\drivers\vgk.sys);
// match on the leaf.
// Drivers arrive as native paths (\SystemRoot\system32\drivers\vgk.sys); every group matches on the leaf of that, and
// the other groups' names are leaves already.
const char* MatchLeaf(Group group, const char* observed) noexcept {
const char* leaf = observed;
if (group == Group::kDrivers) {
for (const char* p = observed; *p != '\0'; ++p) {
@@ -632,18 +630,89 @@ const Family* MatchName(const Rules& rules, Group group, const char* observed) n
}
}
}
return leaf;
}
bool FamilyMatches(const Family& f, const char* leaf) noexcept {
for (std::size_t v = 0; v < f.valueCount; ++v) {
const bool hit = (f.match == MatchKind::kPrefix) ? IStartsWith(leaf, f.values[v]) : IEquals(leaf, f.values[v]);
if (hit) {
return true;
}
}
return false;
}
} // namespace
const Family* MatchName(const Rules& rules, Group group, const char* observed) noexcept {
if (observed == nullptr || observed[0] == '\0') {
return nullptr;
}
const char* leaf = MatchLeaf(group, observed);
for (std::size_t i = 0; i < rules.familyCount; ++i) {
const Family& f = rules.families[i];
if (f.group != group) {
if (f.group == group && FamilyMatches(f, leaf)) {
return &f;
}
}
return nullptr;
}
void ResolveTolerance(const Rules& rules, const char* toleratedFamilies, Tolerance& out) noexcept {
// In place, like ResetRules: a Tolerance is small, but nothing here needs a temporary to be correct.
std::memset(&out, 0, sizeof(out));
if (toleratedFamilies == nullptr) {
return;
}
const char* p = toleratedFamilies;
std::size_t names = 0;
while (*p != '\0' && names < kMaxToleratedFamilies) {
char name[kMaxFamilyNameLen] = {};
std::size_t n = 0;
bool tooLong = false;
for (; *p != '\0' && *p != '\n' && *p != '\r'; ++p) {
if (n + 1 < sizeof(name)) {
name[n++] = *p;
} else {
tooLong = true;
}
}
while (*p == '\n' || *p == '\r') {
++p;
}
if (n == 0 || tooLong) {
continue; // a name we could not hold whole is not a name we may honour
}
++names;
if (!FamilyIsUserModeOnly(rules, name)) {
continue; // kernel-level or unknown: tolerated nowhere, whoever asked
}
for (std::size_t i = 0; i < rules.familyCount; ++i) {
if (IEquals(rules.families[i].name, name)) {
out.family[i] = true;
out.any = true;
}
}
}
}
const Family* MatchNameTolerating(const Rules& rules, Group group, const char* observed, const Tolerance& tolerance,
const Family** tolerated) noexcept {
if (observed == nullptr || observed[0] == '\0') {
return nullptr;
}
const char* leaf = MatchLeaf(group, observed);
for (std::size_t i = 0; i < rules.familyCount; ++i) {
const Family& f = rules.families[i];
if (f.group != group || !FamilyMatches(f, leaf)) {
continue;
}
for (std::size_t v = 0; v < f.valueCount; ++v) {
const bool hit =
(f.match == MatchKind::kPrefix) ? IStartsWith(leaf, f.values[v]) : IEquals(leaf, f.values[v]);
if (hit) {
return &f;
}
if (!tolerance.family[i]) {
return &f; // a family the exception does not cover refuses, even when a covered one matched first
}
if (tolerated != nullptr && *tolerated == nullptr) {
*tolerated = &f;
}
}
return nullptr;
@@ -204,6 +204,11 @@ struct MatchState {
// Null sources, or the target's own process, mean nothing is ever exempt.
const Sources* sources = nullptr;
bool isTarget = false;
// D33 — the exception's families, and the first module of theirs this process let through.
const Tolerance* tolerance = nullptr;
const Family* tolerated = nullptr;
char toleratedSignal[260] = {};
};
// Drivers and any other flat name list. The module scan does NOT come through
@@ -280,11 +285,25 @@ bool ModuleSinkFn(void* ctx, const char* name, const wchar_t* modulePath) noexce
if (st == nullptr || st->rules == nullptr || name == nullptr) {
return false;
}
if (const Family* f = MatchName(*st->rules, Group::kModules, name)) {
const Family* tolerated = nullptr;
const Family* f = st->tolerance != nullptr
? MatchNameTolerating(*st->rules, Group::kModules, name, *st->tolerance, &tolerated)
: MatchName(*st->rules, Group::kModules, name);
if (f != nullptr) {
st->hit = f;
strncpy_s(st->signal, name, _TRUNCATE);
return false; // stop: one hit is enough to refuse
}
// D33: a module the exception's family names is identified, recorded and KEPT LOOKING PAST - the same keep-looking
// the exemption and the trusted signer below follow, for the same load-order reason: a module of another family, or
// a suspicious one, loaded after it must still refuse. An identified module is not judged by the fuzzy tier.
if (tolerated != nullptr) {
if (st->tolerated == nullptr) {
st->tolerated = tolerated;
strncpy_s(st->toleratedSignal, name, _TRUNCATE);
}
return true;
}
if (st->sawSuspicious || !HasSuspiciousFragment(*st->rules, name)) {
return true;
}
@@ -366,8 +385,10 @@ Verdict LoadRules(const Sources& s, Rules& rules) noexcept {
}
}
// Check 1 — modules, across the §S16 scan set.
Verdict CheckModules(const Sources& s, const Rules& rules, std::uint32_t targetPid) noexcept {
// Check 1 — modules, across the §S16 scan set. With a `tolerance` (D33), a module of a tolerated family is recorded in
// `finding` rather than refused; everything else refuses exactly as without one.
Verdict CheckModules(const Sources& s, const Rules& rules, std::uint32_t targetPid, const Tolerance* tolerance,
ToleratedFinding& finding) noexcept {
if (s.EnumerateScanSet == nullptr || s.EnumerateModules == nullptr) {
return Refuse(Reason::kProcessTreeUnavailable, nullptr, "no process source");
}
@@ -387,6 +408,7 @@ Verdict CheckModules(const Sources& s, const Rules& rules, std::uint32_t targetP
// would read as configuration.
st.sources = &s;
st.isTarget = (set.pids[i] == targetPid);
st.tolerance = tolerance;
const Collected c = s.EnumerateModules(set.pids[i], &ModuleSinkFn, &st);
if (st.hit != nullptr) {
@@ -416,6 +438,12 @@ Verdict CheckModules(const Sources& s, const Rules& rules, std::uint32_t targetP
// depend on where the HOST lived (§S22(b)).
return Refuse(Reason::kSuspiciousUnsigned, "unknown", st.suspicious);
}
// This process was read whole and only the exception's family was in it (D33).
if (st.tolerated != nullptr && !finding.seen) {
finding.seen = true;
strncpy_s(finding.family, st.tolerated->name, _TRUNCATE);
strncpy_s(finding.signal, st.toleratedSignal, _TRUNCATE);
}
}
return Allow();
}
@@ -528,6 +556,8 @@ const char* ReasonName(Reason r) noexcept {
return "TargetIsVulkanLayered";
case Reason::kKillSwitchEngaged:
return "KillSwitchEngaged";
case Reason::kAllowedUserModeException:
return "AllowedUnderUserModeException";
case Reason::kCount:
break; // not a reason; falls through to the guard below
}
@@ -588,7 +618,7 @@ Verdict CheckBlockedExecutable(const Sources& s, const Rules& rules, std::uint32
return Allow();
}
Verdict EvaluateImpl(std::uint32_t targetPid, const Sources& sources) noexcept {
Verdict EvaluateImpl(std::uint32_t targetPid, const Sources& sources, const char* toleratedFamilies) noexcept {
// Static so the 1 MiB of rules storage inside LoadRules is not duplicated
// on the stack. Cleared on every call: a stale blocklist from a previous
// evaluation would be a gate answering about the wrong data.
@@ -598,6 +628,14 @@ Verdict EvaluateImpl(std::uint32_t targetPid, const Sources& sources) noexcept {
if (Verdict v = LoadRules(sources, rules); !v.Allowed()) {
return v;
}
// D33: the exception's families, resolved against THESE rules - only a family whose whole footprint is user-mode
// survives ResolveTolerance, whatever the caller named. It reaches check 1 and check 4, the only two whose findings
// can be user-mode; drivers, services and both title lists never see it.
Tolerance tolerance;
ResolveTolerance(rules, toleratedFamilies, tolerance);
const Tolerance* tolerating = tolerance.any ? &tolerance : nullptr;
ToleratedFinding finding;
// Drivers first. It is machine-wide, it is the cheapest, and it is the one
// that refuses for ALL titles rather than just this one (19_SAFETY item 2).
if (Verdict v = CheckDrivers(sources, rules); !v.Allowed()) {
@@ -606,7 +644,7 @@ Verdict EvaluateImpl(std::uint32_t targetPid, const Sources& sources) noexcept {
if (Verdict v = CheckServices(sources, rules); !v.Allowed()) {
return v;
}
if (Verdict v = CheckModules(sources, rules, targetPid); !v.Allowed()) {
if (Verdict v = CheckModules(sources, rules, targetPid, tolerating, finding); !v.Allowed()) {
return v;
}
// Check 3, at last. Cheap -- one OpenProcess and a string compare -- and it
@@ -629,17 +667,23 @@ Verdict EvaluateImpl(std::uint32_t targetPid, const Sources& sources) noexcept {
//
// Last of the four because it is the only one that touches the filesystem;
// the three cheaper checks have already had their say.
if (Verdict v = CheckStaticPreScan(sources, rules, targetPid); !v.Allowed()) {
if (Verdict v = CheckStaticPreScan(sources, rules, targetPid, tolerating, &finding); !v.Allowed()) {
return v;
}
// Every check ran and passed. When the only findings were the exception's, say so, with what was let through: the
// session this starts is marked with it (19_SAFETY §The user-mode exception).
if (finding.seen) {
return Refuse(Reason::kAllowedUserModeException, finding.family, finding.signal);
}
return Allow();
}
// A refusal returns here, and there is no argument that changes that (the `acknowledged` flag of 2026-09-21 was
// withdrawn on 2026-09-22 with the bypass it served). Everything below -- the payload's existence, the payload's
// identity, the primitive, the bitness answer -- runs only for a target the full evaluation allowed.
Verdict GuardedInjectImpl(std::uint32_t targetPid, const wchar_t* dllPath, const Sources& sources) noexcept {
const Verdict v = EvaluateImpl(targetPid, sources);
Verdict GuardedInjectImpl(std::uint32_t targetPid, const wchar_t* dllPath, const Sources& sources,
const char* toleratedFamilies) noexcept {
const Verdict v = EvaluateImpl(targetPid, sources, toleratedFamilies);
if (!v.Allowed()) {
return v;
}
@@ -764,7 +808,7 @@ PresentationRuntime FindPresentationRuntime(const Sources& s, std::uint32_t pid)
}
Verdict GuardedInjectWhenReadyImpl(std::uint32_t targetPid, const wchar_t* dllPath, std::uint32_t timeoutMs,
const Sources& sources) noexcept {
const Sources& sources, const char* toleratedFamilies) noexcept {
// SYNCHRONIZE only: this handle exists to notice an exit and for nothing else.
HANDLE proc = OpenProcess(SYNCHRONIZE, FALSE, targetPid);
if (proc == nullptr) {
@@ -796,13 +840,15 @@ Verdict GuardedInjectWhenReadyImpl(std::uint32_t targetPid, const wchar_t* dllPa
}
}
if (runtime == PresentationRuntime::kD3dOrOpenGl) {
v = GuardedInjectImpl(targetPid, dllPath, sources);
v = GuardedInjectImpl(targetPid, dllPath, sources, toleratedFamilies);
break;
}
if (runtime == PresentationRuntime::kVulkan) {
// The FULL guard still runs -- a Vulkan title with anti-cheat is refused
// by name exactly as a D3D one is -- and on a pass nothing is injected.
v = EvaluateImpl(targetPid, sources);
// WITHOUT the exception (D33): the layer's own self-scan goes inert on any anti-cheat module, so a
// tolerated family could only buy a session that measures nothing.
v = EvaluateImpl(targetPid, sources, nullptr);
if (v.Allowed()) {
v = Refuse(Reason::kTargetIsVulkanLayered, nullptr,
"the guard passed; the target presents through Vulkan, where the implicit layer is the "
@@ -832,30 +878,32 @@ Verdict GuardedInjectWhenReadyImpl(std::uint32_t targetPid, const wchar_t* dllPa
} // namespace
Verdict Evaluate(std::uint32_t targetPid) noexcept {
return EvaluateImpl(targetPid, SystemSources());
Verdict Evaluate(std::uint32_t targetPid, const char* toleratedFamilies) noexcept {
return EvaluateImpl(targetPid, SystemSources(), toleratedFamilies);
}
Verdict GuardedInjectWhenReady(std::uint32_t targetPid, const wchar_t* dllPath, std::uint32_t timeoutMs) noexcept {
return GuardedInjectWhenReadyImpl(targetPid, dllPath, timeoutMs, SystemSources());
Verdict GuardedInjectWhenReady(std::uint32_t targetPid, const wchar_t* dllPath, std::uint32_t timeoutMs,
const char* toleratedFamilies) noexcept {
return GuardedInjectWhenReadyImpl(targetPid, dllPath, timeoutMs, SystemSources(), toleratedFamilies);
}
Verdict GuardedInject(std::uint32_t targetPid, const wchar_t* dllPath) noexcept {
return GuardedInjectImpl(targetPid, dllPath, SystemSources());
Verdict GuardedInject(std::uint32_t targetPid, const wchar_t* dllPath, const char* toleratedFamilies) noexcept {
return GuardedInjectImpl(targetPid, dllPath, SystemSources(), toleratedFamilies);
}
#ifdef FL_GUARD_TESTABLE
Verdict EvaluateWithSources(std::uint32_t targetPid, const Sources& sources) noexcept {
return EvaluateImpl(targetPid, sources);
Verdict EvaluateWithSources(std::uint32_t targetPid, const Sources& sources, const char* toleratedFamilies) noexcept {
return EvaluateImpl(targetPid, sources, toleratedFamilies);
}
Verdict GuardedInjectWithSources(std::uint32_t targetPid, const wchar_t* dllPath, const Sources& sources) noexcept {
return GuardedInjectImpl(targetPid, dllPath, sources);
Verdict GuardedInjectWithSources(std::uint32_t targetPid, const wchar_t* dllPath, const Sources& sources,
const char* toleratedFamilies) noexcept {
return GuardedInjectImpl(targetPid, dllPath, sources, toleratedFamilies);
}
Verdict GuardedInjectWhenReadyWithSources(std::uint32_t targetPid, const wchar_t* dllPath, std::uint32_t timeoutMs,
const Sources& sources) noexcept {
return GuardedInjectWhenReadyImpl(targetPid, dllPath, timeoutMs, sources);
const Sources& sources, const char* toleratedFamilies) noexcept {
return GuardedInjectWhenReadyImpl(targetPid, dllPath, timeoutMs, sources, toleratedFamilies);
}
#endif
@@ -26,33 +26,34 @@ bool Usable(FlGuardResult* out) noexcept {
extern "C" {
void FlGuardEvaluate(std::uint32_t targetPid, FlGuardResult* out) {
void FlGuardEvaluate(std::uint32_t targetPid, const char* toleratedFamilies, FlGuardResult* out) {
if (!Usable(out)) {
return;
}
Fill(out, fl::guard::Evaluate(targetPid));
Fill(out, fl::guard::Evaluate(targetPid, toleratedFamilies));
}
void FlGuardedInject(std::uint32_t targetPid, const wchar_t* dllPath, FlGuardResult* out) {
void FlGuardedInject(std::uint32_t targetPid, const wchar_t* dllPath, const char* toleratedFamilies,
FlGuardResult* out) {
if (!Usable(out)) {
return;
}
Fill(out, fl::guard::GuardedInject(targetPid, dllPath));
Fill(out, fl::guard::GuardedInject(targetPid, dllPath, toleratedFamilies));
}
void FlGuardedInjectWhenReady(std::uint32_t targetPid, const wchar_t* dllPath, std::uint32_t timeoutMs,
FlGuardResult* out) {
const char* toleratedFamilies, FlGuardResult* out) {
if (!Usable(out)) {
return;
}
Fill(out, fl::guard::GuardedInjectWhenReady(targetPid, dllPath, timeoutMs));
Fill(out, fl::guard::GuardedInjectWhenReady(targetPid, dllPath, timeoutMs, toleratedFamilies));
}
void FlStaticPreScanGame(const wchar_t* exePath, FlGuardResult* out) {
void FlStaticPreScanGame(const wchar_t* exePath, const char* toleratedFamilies, FlGuardResult* out) {
if (!Usable(out)) {
return;
}
Fill(out, fl::guard::StaticPreScanGame(exePath));
Fill(out, fl::guard::StaticPreScanGame(exePath, toleratedFamilies));
}
const char* FlGuardReasonName(std::int32_t reason) {
@@ -46,6 +46,11 @@ struct ScanState {
const char* driverRuleHit = nullptr; // kKernelDriverInTreeFamily once the code rule fired
bool hitWasDirectory = false;
char signal[260] = {};
// D33: the exception's families, and the first entry of theirs the walk let through.
const Tolerance* tolerance = nullptr;
const Family* tolerated = nullptr;
char toleratedSignal[260] = {};
};
bool EntrySink(void* ctx, const char* name, bool isDirectory) noexcept {
@@ -62,7 +67,26 @@ bool EntrySink(void* ctx, const char* name, bool isDirectory) noexcept {
// and `x3.xem` as a file are separate signals, and collapsing them would let
// a data edit move one gate into the other without anything noticing.
const Group group = isDirectory ? Group::kDirectories : Group::kFiles;
const Family* f = MatchName(*st->rules, group, name);
const Family* tolerated = nullptr;
const Family* f = st->tolerance != nullptr
? MatchNameTolerating(*st->rules, group, name, *st->tolerance, &tolerated)
: MatchName(*st->rules, group, name);
// D33. A KERNEL DRIVER IS NEVER TOLERATED, whichever family names it: FamilyIsUserModeOnly already refuses a family
// whose own values carry a `.sys`, and this closes the one way left - a prefix value of a user-mode family that
// happens to match a driver's file name. That driver refuses under the family, exactly as without an exception.
if (f == nullptr && tolerated != nullptr && !isDirectory && IsKernelDriverName(name)) {
f = tolerated;
}
if (f == nullptr && tolerated != nullptr) {
// Let through, recorded, and the walk goes ON: a kernel driver, another family or an unfinished listing
// further in must still refuse. The walk is bounded by kMaxPreScanEntries either way (a refusal).
if (st->tolerated == nullptr) {
st->tolerated = tolerated;
strncpy_s(st->toleratedSignal, sizeof(st->toleratedSignal), name, _TRUNCATE);
}
return true;
}
if (f != nullptr) {
st->hit = f;
st->hitWasDirectory = isDirectory;
@@ -80,7 +104,8 @@ bool EntrySink(void* ctx, const char* name, bool isDirectory) noexcept {
return true;
}
Verdict ScanWith(const Sources& s, const Rules& rules, const wchar_t* dir) noexcept {
Verdict ScanWith(const Sources& s, const Rules& rules, const wchar_t* dir, const Tolerance* tolerance,
ToleratedFinding* finding) noexcept {
if (s.EnumerateDirEntries == nullptr) {
return Refused(Reason::kPreScanFailed, nullptr, "no directory source");
}
@@ -90,6 +115,7 @@ Verdict ScanWith(const Sources& s, const Rules& rules, const wchar_t* dir) noexc
ScanState st;
st.rules = &rules;
st.tolerance = tolerance;
const Collected c = s.EnumerateDirEntries(dir, &EntrySink, &st);
@@ -114,6 +140,12 @@ Verdict ScanWith(const Sources& s, const Rules& rules, const wchar_t* dir) noexc
return Refused(Reason::kPreScanFailed, nullptr,
"the game directory listing was truncated, unreadable, or crossed a reparse point");
}
// The whole tree was seen and only the exception's family was in it: the caller turns the record into the verdict.
if (st.tolerated != nullptr && finding != nullptr && !finding->seen) {
finding->seen = true;
strncpy_s(finding->family, sizeof(finding->family), st.tolerated->name, _TRUNCATE);
strncpy_s(finding->signal, sizeof(finding->signal), st.toleratedSignal, _TRUNCATE);
}
return Passed();
}
@@ -148,8 +180,14 @@ Verdict LoadPreScanRules(const Sources& s, Rules& rules) noexcept {
}
}
// D33's verdict: every check passed and the only findings were the exception's. Built here and in fl_guard.cpp from
// the same record, and nowhere else.
Verdict ToleratedVerdict(const ToleratedFinding& finding) noexcept {
return Refused(Reason::kAllowedUserModeException, finding.family, finding.signal);
}
// The advisory pre-scan over whichever Sources the caller may hold (production: SystemSources, and nothing else).
Verdict PreScanGameWith(const wchar_t* exePath, const Sources& s) noexcept {
Verdict PreScanGameWith(const wchar_t* exePath, const Sources& s, const char* toleratedFamilies) noexcept {
if (exePath == nullptr || exePath[0] == L'\0') {
return Refused(Reason::kPreScanFailed, nullptr, "no executable to scan");
}
@@ -193,11 +231,18 @@ Verdict PreScanGameWith(const wchar_t* exePath, const Sources& s) noexcept {
return Refused(Reason::kBlockedExecutable, hit->family, leaf);
}
// Check 3's store half, then check 4 — both over the install root.
// Check 3's store half, then check 4 — both over the install root. Title lists are never tolerated (D33): only
// check 4 takes the exception, and only for a user-mode family.
if (Verdict v = CheckStoreIdentity(s, rules, root); !v.Allowed()) {
return v;
}
return ScanWith(s, rules, root);
Tolerance tolerance;
ResolveTolerance(rules, toleratedFamilies, tolerance);
ToleratedFinding finding;
if (Verdict v = ScanWith(s, rules, root, tolerance.any ? &tolerance : nullptr, &finding); !v.Allowed()) {
return v;
}
return finding.seen ? ToleratedVerdict(finding) : Passed();
}
} // namespace
@@ -269,7 +314,8 @@ bool ResolveInstallRoot(const wchar_t* exeDir, wchar_t* out, std::size_t cap) no
return true;
}
Verdict CheckStaticPreScan(const Sources& s, const Rules& rules, std::uint32_t targetPid) noexcept {
Verdict CheckStaticPreScan(const Sources& s, const Rules& rules, std::uint32_t targetPid, const Tolerance* tolerance,
ToleratedFinding* finding) noexcept {
if (s.ImageDirectory == nullptr) {
return Refused(Reason::kPreScanFailed, nullptr, "no image-path source");
}
@@ -280,7 +326,7 @@ Verdict CheckStaticPreScan(const Sources& s, const Rules& rules, std::uint32_t t
// 19_SAFETY has no "three of four checks passed" state.
return Refused(Reason::kPreScanFailed, nullptr, "could not establish the target's directory");
}
return ScanWith(s, rules, dir);
return ScanWith(s, rules, dir, tolerance, finding);
}
Verdict CheckStoreIdentity(const Sources& s, const Rules& rules, const wchar_t* installRoot) noexcept {
@@ -322,13 +368,14 @@ Verdict CheckBlockedStoreId(const Sources& s, const Rules& rules, std::uint32_t
return CheckStoreIdentity(s, rules, root);
}
Verdict StaticPreScanGame(const wchar_t* exePath) noexcept {
return PreScanGameWith(exePath, SystemSources());
Verdict StaticPreScanGame(const wchar_t* exePath, const char* toleratedFamilies) noexcept {
return PreScanGameWith(exePath, SystemSources(), toleratedFamilies);
}
#ifdef FL_GUARD_TESTABLE
Verdict StaticPreScanGameWithSources(const wchar_t* exePath, const Sources& sources) noexcept {
return PreScanGameWith(exePath, sources);
Verdict StaticPreScanGameWithSources(const wchar_t* exePath, const Sources& sources,
const char* toleratedFamilies) noexcept {
return PreScanGameWith(exePath, sources, toleratedFamilies);
}
#endif
+81 -1
View File
@@ -53,6 +53,7 @@
#include <fl_shm_host.h>
#include <fl_sl_inputs.h>
#include <fl_sl_seen.h>
#include <fl_tolerance.h>
#include <knownfolders.h>
#include <MinHook.h>
#include <shlobj_core.h>
@@ -139,6 +140,7 @@ enum FlLogCode : uint32_t {
kLogUnhookDeclined,
kLogLoaderDetour,
kLogSupervisionLost,
kLogTolerance,
};
const char* LogCodeName(uint32_t code) noexcept {
@@ -163,6 +165,8 @@ const char* LogCodeName(uint32_t code) noexcept {
return "LOADER_DETOUR";
case kLogSupervisionLost:
return "SUPERVISION_LOST";
case kLogTolerance:
return "TOLERANCE";
default:
return "?";
}
@@ -735,6 +739,10 @@ void StopObserving(uint32_t reason) noexcept {
// path reads it first): 0 = none; else 1-based index among the floor's MODULE
// families in rules order.
std::atomic<uint32_t> g_earlyStopFamily{0};
// D33: floor MODULE families (bit index-1, the same 1-based index as g_earlyStopFamily) whose late load does NOT stop
// observing, because the user's exception for this game covers them and the guard let them through. Written once by
// ReadTolerance on the init thread BEFORE the detour exists; read by the detour. Zero without an exception.
std::atomic<uint64_t> g_toleratedFloorModules{0};
void PublishLoaderWords() noexcept;
// Defined with the OpenGL hook below; the watchdog installs it lazily.
bool InstallOpenGlHook() noexcept;
@@ -1163,6 +1171,73 @@ uint32_t MatchesFloorModule(const wchar_t* base) noexcept {
return 0;
}
// How many MODULE families the compiled floor carries: the tolerance mask has one bit per family, so it must fit.
constexpr uint32_t FloorModuleFamilyCount() noexcept {
uint32_t n = 0;
for (const fl::guard::Family& f : fl::guard::generated::kFloorFamilies) {
if (f.group == fl::guard::Group::kModules) {
++n;
}
}
return n;
}
static_assert(FloorModuleFamilyCount() <= 64, "g_toleratedFloorModules has one bit per floor module family");
bool IsToleratedFloorModule(uint32_t family) noexcept {
return family != 0u && family <= 64u &&
(g_toleratedFloorModules.load(std::memory_order_acquire) & (uint64_t{1} << (family - 1u))) != 0u;
}
// D33 — the Agent's tolerance for this process, read ONCE from Local\FrameLedger.Tolerate.<pid> (fl_tolerance.h) on
// the init thread, before InstallLoaderHook. Every name is checked against THIS binary's compiled floor: it must name
// a floor family whose whole footprint is user-mode, or it tolerates nothing — the Overlay never takes the mapping's
// word for what is safe. Anything unexpected (no mapping, a bad magic or version, a count out of range, a name with
// no terminator) leaves the mask at zero, which is the Overlay exactly as it was before D33.
void ReadTolerance() noexcept {
wchar_t name[96]{};
if (!MakeToleranceName(name, 96, GetCurrentProcessId())) {
return;
}
HANDLE mapping = OpenFileMappingW(FILE_MAP_READ, FALSE, name);
if (mapping == nullptr) {
return; // no exception for this game: the ordinary case
}
const void* view = MapViewOfFile(mapping, FILE_MAP_READ, 0, 0, sizeof(FlTolerance));
uint64_t mask = 0;
uint32_t names = 0;
if (view != nullptr) {
FlTolerance t{};
std::memcpy(&t, view, sizeof(t)); // one copy, then nothing of the mapping is read again
UnmapViewOfFile(view);
if (t.magic == FL_TOLERANCE_MAGIC && t.version == FL_TOLERANCE_VERSION &&
t.count <= FL_TOLERANCE_MAX_FAMILIES) {
for (uint32_t i = 0; i < t.count; ++i) {
char* family = t.families[i];
if (std::memchr(family, '\0', FL_TOLERANCE_NAME_LEN) == nullptr ||
!fl::guard::FamilyIsUserModeOnly(
fl::guard::generated::kFloorFamilies,
sizeof(fl::guard::generated::kFloorFamilies) / sizeof(fl::guard::Family), family)) {
continue;
}
++names;
uint32_t index = 0;
for (const fl::guard::Family& f : fl::guard::generated::kFloorFamilies) {
if (f.group != fl::guard::Group::kModules) {
continue;
}
++index;
if (fl::guard::AsciiIEquals(f.name, family)) {
mask |= uint64_t{1} << (index - 1u);
}
}
}
}
}
CloseHandle(mapping);
g_toleratedFloorModules.store(mask, std::memory_order_release);
LogNote(kLogTolerance, "Local\\FrameLedger.Tolerate.<pid>", names, mask);
}
// Does the inventory or the census name this module? A load of one of these is
// what the watchdog installs or counts on its next tick, so it is what wakes it.
bool ModuleIsInventoried(const wchar_t* base) noexcept {
@@ -1199,10 +1274,13 @@ HMODULE WINAPI Hook_LoadLibraryExW(LPCWSTR name, HANDLE file, DWORD flags) noexc
if (GetModuleFileNameW(h, path, MAX_PATH) != 0) {
const wchar_t* base = BaseNameOf(path);
const uint32_t family = MatchesFloorModule(base);
if (family != 0u) {
if (family != 0u && !IsToleratedFloorModule(family)) {
uint32_t none = 0;
g_earlyStopFamily.compare_exchange_strong(none, family, std::memory_order_acq_rel);
WakeWatchdog();
} else if (family != 0u) {
// D33: the family the user's exception covers loaded late. The guard let it through at injection
// and the Agent's 30 s re-scan keeps judging everything else; nothing to stop here.
} else if (ModuleIsInventoried(base) || _wcsicmp(base, L"opengl32.dll") == 0) {
uint32_t cur = g_loaderSignals.load(std::memory_order_relaxed);
while ((cur & kLoaderCountMask) < kLoaderCountMask &&
@@ -3100,6 +3178,8 @@ DWORD WINAPI InitThread(LPVOID) noexcept {
// the thread that waits on it. Then the LoadLibrary detour -- non-fatal: without
// it the 1 Hz tick and the host's scan are the backstops, and bit 15 says so.
g_watchdogWake = CreateEventW(nullptr, FALSE, FALSE, nullptr);
// D33: the exception's families, if the Agent published any for this pid, BEFORE the detour can see a load.
ReadTolerance();
InstallLoaderHook();
PublishLoaderWords();
// An OpenGL title has opengl32 mapped before we arrive; the watchdog retries
@@ -0,0 +1,52 @@
// D33 (owner decision 2026-09-26) — which anti-cheat families the injected Overlay may see load WITHOUT stopping.
//
// The Overlay stops observing when a module the compiled floor names loads after injection (its
// kernelbase!LoadLibraryExW detour, dllmain.cpp). Under a user's exception for one game (19_SAFETY §The user-mode
// exception) the guard lets that game's one user-mode family through, and the Overlay must know which, or the exception
// does nothing the moment the family's module loads late. The ring cannot carry it: the Overlay CREATES the ring
// (fl_shm_host.h) and the Agent opens it afterwards, so nothing the Agent writes there exists before the detour is
// armed.
//
// So the Agent creates this small mapping BEFORE it asks the guard to inject, holds it for the session, and the
// Overlay's init thread reads it ONCE, before it installs the detour. It carries NAMES, never indices: the Overlay
// resolves each against its own compiled floor and honours only a family whose whole footprint there is user-mode
// (fl::guard::FamilyIsUserModeOnly), so a mapping that named a kernel-level family — by mistake or by anyone else
// who can create objects in this session — tolerates nothing. It only ever narrows the in-process stop for families
// the guard itself would tolerate; the Agent's 30 s re-scan still refuses everything else.
//
// Absent mapping = no tolerance: every game without an exception, and every game before D33, behaves exactly as before.
//
// Mirrored in FrameLedger.Shared (ShmLayout.cs, FlTolerance) and held to it by ShmLayoutMirrorTests through
// tools/fl-layout-dump, as every struct that crosses the native/managed line is.
#ifndef FRAMELEDGER_FL_TOLERANCE_H
#define FRAMELEDGER_FL_TOLERANCE_H
#include <cstddef>
#include <cstdint>
#include <cwchar>
// "FLTL", little-endian: a mapping whose first word is not this was not written by the Agent for this purpose.
inline constexpr std::uint32_t FL_TOLERANCE_MAGIC = 0x4C544C46u;
inline constexpr std::uint32_t FL_TOLERANCE_VERSION = 1u;
inline constexpr std::uint32_t FL_TOLERANCE_MAX_FAMILIES = 8u; // fl::guard::kMaxToleratedFamilies
inline constexpr std::uint32_t FL_TOLERANCE_NAME_LEN = 64u; // fl::guard::kMaxFamilyNameLen
struct FlTolerance {
std::uint32_t magic; // @0 FL_TOLERANCE_MAGIC
std::uint32_t version; // @4 FL_TOLERANCE_VERSION
std::uint32_t count; // @8 names used, <= FL_TOLERANCE_MAX_FAMILIES
std::uint32_t reserved; // @12 must be zero
char families[FL_TOLERANCE_MAX_FAMILIES][FL_TOLERANCE_NAME_LEN]; // @16 NUL-terminated ASCII names
};
static_assert(offsetof(FlTolerance, families) == 16, "FlTolerance: the names start at 16");
static_assert(sizeof(FlTolerance) == 16 + FL_TOLERANCE_MAX_FAMILIES * FL_TOLERANCE_NAME_LEN,
"FlTolerance: no implicit padding");
// Local\FrameLedger.Tolerate.<pid> — the pid the Overlay is loaded into, i.e. the game's.
inline bool MakeToleranceName(wchar_t* out, std::size_t cap, unsigned long pid) noexcept {
return _snwprintf_s(out, cap, _TRUNCATE, L"Local\\FrameLedger.Tolerate.%lu", pid) >= 0;
}
#endif // FRAMELEDGER_FL_TOLERANCE_H
+264
View File
@@ -1342,6 +1342,7 @@ TEST_CASE(
// to, which is the only part of this suite that has a live Overlay to inspect.
#include <fl_ring.h>
#include <fl_shm.h>
#include <fl_tolerance.h>
// The compiled floor, so the early-stop case computes the family index the Overlay
// publishes from the same table rather than asserting a literal.
#include <fl_ac_floor.generated.h>
@@ -5236,3 +5237,266 @@ TEST_CASE("the harness log sweep removes this run's harness logs and nothing els
CHECK(parsed == "C:\\x\\hook-harness.exe");
CHECK_FALSE(fl::testing::OverlayLogImage("# a stale log planted by guard_test\r\n", parsed));
}
// ===========================================================================
// D33 (owner decision 2026-09-26) -- the user-mode exception. A caller may NAME a family; the guard decides whether
// that family is user-mode, runs every check anyway, lets only that family's modules, files and folders through, and
// refuses everything else exactly as before. 19_SAFETY §The user-mode exception.
//
// These cases lean on the compiled FLOOR, which every parse merges in: it carries NetEase Yidun as modules + files
// `NEP2.dll` (user-mode only) and Easy Anti-Cheat with drivers and services (kernel-level), whatever the test's own
// rules file says -- which is also the production shape, and the reason a file cannot make EAC tolerable.
// ===========================================================================
namespace {
constexpr const char* kYidun = "NetEase Yidun";
Rules& ParsedGoodRules() {
static Rules rules;
ResetRules(rules);
const std::string json = GoodRulesJson();
REQUIRE(ParseRules(json.data(), json.size(), rules) == ParseResult::kOk);
return rules;
}
std::string RulesWithExtra(const char* group, const char* entry) {
std::string json = GoodRulesJson();
const std::string needle = std::string("\"") + group + "\": [";
const std::size_t at = json.find(needle);
REQUIRE(at != std::string::npos);
json.insert(at + needle.size(), std::string(entry) + ", ");
return json;
}
} // namespace
TEST_CASE("D33 -- a family is user-mode only when no driver, service or .sys names it anywhere", "[guard][D33]") {
const Rules& rules = ParsedGoodRules();
CHECK(FamilyIsUserModeOnly(rules, kYidun));
CHECK(FamilyIsUserModeOnly(rules, "netease YIDUN")); // the comparison the guard uses everywhere
CHECK_FALSE(FamilyIsUserModeOnly(rules, "Easy Anti-Cheat")); // drivers and services in the floor
CHECK_FALSE(FamilyIsUserModeOnly(rules, "Riot Vanguard")); // a driver and a service
CHECK_FALSE(FamilyIsUserModeOnly(rules, "Valve VAC")); // a title list, not a family entry
CHECK_FALSE(FamilyIsUserModeOnly(rules, kKernelDriverInTreeFamily));
CHECK_FALSE(FamilyIsUserModeOnly(rules, "No Such Family"));
CHECK_FALSE(FamilyIsUserModeOnly(rules, ""));
CHECK_FALSE(FamilyIsUserModeOnly(rules, nullptr));
// DATA CAN MAKE A FAMILY KERNEL-LEVEL, and never the reverse: the floor cannot be shrunk.
for (const auto& [group, entry] : std::vector<std::pair<const char*, const char*>>{
{"drivers", R"({ "family": "NetEase Yidun", "match": "exact", "values": ["NEPKernel.sys"] })"},
{"services", R"({ "family": "NetEase Yidun", "values": ["NEPService"] })"},
{"files", R"({ "family": "NetEase Yidun", "values": ["NEPKernel.sys"] })"},
}) {
static Rules rules2;
ResetRules(rules2);
const std::string json = RulesWithExtra(group, entry);
REQUIRE(ParseRules(json.data(), json.size(), rules2) == ParseResult::kOk);
INFO(group);
CHECK_FALSE(FamilyIsUserModeOnly(rules2, kYidun));
}
}
TEST_CASE("D33 -- ResolveTolerance honours only user-mode names, and at most kMaxToleratedFamilies of them",
"[guard][D33]") {
const Rules& rules = ParsedGoodRules();
Tolerance t;
ResolveTolerance(rules, nullptr, t);
CHECK_FALSE(t.any);
ResolveTolerance(rules, "", t);
CHECK_FALSE(t.any);
ResolveTolerance(rules, "Easy Anti-Cheat", t);
CHECK_FALSE(t.any); // kernel-level: tolerated nowhere, whoever asked
ResolveTolerance(rules, "No Such Family\r\nNetEase Yidun\n", t);
CHECK(t.any);
// Every entry of the family is covered, in both of its groups, and nothing else is.
std::size_t covered = 0;
for (std::size_t i = 0; i < rules.familyCount; ++i) {
if (t.family[i]) {
CHECK(AsciiIEquals(rules.families[i].name, kYidun));
++covered;
}
}
CHECK(covered >= 2);
// A ninth name is not read: tolerating fewer is the safe direction.
std::string eight;
for (int i = 0; i < 8; ++i) {
eight += "No Such Family\n";
}
ResolveTolerance(rules, (eight + kYidun).c_str(), t);
CHECK_FALSE(t.any);
}
TEST_CASE("D33 -- a module of the excepted family is let through, and the verdict says so", "[guard][D33]") {
ResetFake();
g.modules = {"kernel32.dll", "NEP2.dll", "d3d12.dll"};
const Verdict strict = EvaluateWithSources(1234, FakeSources());
CHECK(strict.reason == Reason::kBlockedModule);
CHECK(std::string(strict.family) == kYidun);
const Verdict v = EvaluateWithSources(1234, FakeSources(), kYidun);
INFO(ReasonName(v.reason) << " " << v.family << " " << v.signal);
CHECK(v.reason == Reason::kAllowedUserModeException);
CHECK(v.Allowed());
CHECK(std::string(v.family) == kYidun);
CHECK(std::string(v.signal) == "NEP2.dll");
CHECK(std::string(ReasonName(v.reason)) == "AllowedUnderUserModeException");
// A game with nothing to except is an ordinary Allow, not an exception.
ResetFake();
g.modules = {"kernel32.dll"};
CHECK(EvaluateWithSources(1234, FakeSources(), kYidun).reason == Reason::kAllow);
}
TEST_CASE("D33 -- everything outside the excepted family still refuses", "[guard][D33][failclosed]") {
SECTION("a kernel-level family named as the exception is not tolerated") {
ResetFake();
g.modules = {"EasyAntiCheat_EOS.dll"};
CHECK(EvaluateWithSources(1234, FakeSources(), "Easy Anti-Cheat").reason == Reason::kBlockedModule);
}
SECTION("another family's module loaded AFTER the tolerated one refuses: the scan kept looking") {
ResetFake();
g.modules = {"NEP2.dll", "BEClient_x64.dll"};
const Verdict v = EvaluateWithSources(1234, FakeSources(), kYidun);
CHECK(v.reason == Reason::kBlockedModule);
CHECK(std::string(v.family) == "BattlEye");
}
SECTION("a suspicious module loaded after it still refuses") {
ResetFake();
g.modules = {"NEP2.dll", "SomeAntiCheatSdk.dll"};
CHECK(EvaluateWithSources(1234, FakeSources(), kYidun).reason == Reason::kSuspiciousUnsigned);
}
SECTION("a machine-wide driver refuses") {
ResetFake();
g.modules = {"NEP2.dll"};
g.drivers = {"\\SystemRoot\\system32\\drivers\\vgk.sys"};
CHECK(EvaluateWithSources(1234, FakeSources(), kYidun).reason == Reason::kBlockedDriver);
}
SECTION("a running service refuses") {
ResetFake();
g.modules = {"NEP2.dll"};
g.presentServices = {"vgc"};
CHECK(EvaluateWithSources(1234, FakeSources(), kYidun).reason == Reason::kBlockedService);
}
SECTION("a title list refuses") {
ResetFake();
g.rulesJson = RulesWithBlockedExecutable();
g.modules = {"NEP2.dll"};
g.imageFileName = "ranked.exe";
CHECK(EvaluateWithSources(1234, FakeSources(), kYidun).reason == Reason::kBlockedExecutable);
}
SECTION("a kernel driver anywhere in the install tree refuses -- the Aniimo shape") {
ResetFake();
g.modules = {"NEP2.dll"};
g.dirEntries = {{"NEP2.dll", false}, {"Aniimo_Data", true}, {"NEPKernel.sys", false}};
const Verdict v = EvaluateWithSources(1234, FakeSources(), kYidun);
CHECK(v.reason == Reason::kAntiCheatFile);
CHECK(std::string(v.family) == kKernelDriverInTreeFamily);
CHECK(std::string(v.signal) == "NEPKernel.sys");
}
SECTION("a walk that could not finish refuses, even after the tolerated file") {
ResetFake();
g.dirEntries = {{"NEP2.dll", false}};
g.dirEntriesResult = Collected::kIncomplete;
CHECK(EvaluateWithSources(1234, FakeSources(), kYidun).reason == Reason::kPreScanFailed);
}
SECTION("an unreadable process refuses") {
ResetFake();
g.modules = {"NEP2.dll"};
g.moduleResult = Collected::kFailed;
CHECK(EvaluateWithSources(1234, FakeSources(), kYidun).reason == Reason::kProcessUnreadable);
}
}
TEST_CASE("D33 -- the advisory pre-scan answers the same question the chokepoint does", "[guard][D33][prescan]") {
// The GF2 shape: the family's file beside the executable and nothing else.
ResetFake();
g.dirEntries = {{"GF2_Exilium.exe", false}, {"NEP2.dll", false}, {"GF2_Exilium_Data", true}};
const wchar_t* exe = LR"(D:\SteamLibrary\steamapps\common\GIRLS' FRONTLINE 2 EXILIUM\GF2_Exilium.exe)";
const Verdict strict = StaticPreScanGameWithSources(exe, FakeSources());
CHECK(strict.reason == Reason::kAntiCheatFile);
CHECK(std::string(strict.family) == kYidun);
const Verdict v = StaticPreScanGameWithSources(exe, FakeSources(), kYidun);
CHECK(v.reason == Reason::kAllowedUserModeException);
CHECK(std::string(v.signal) == "NEP2.dll");
// The Aniimo shape refuses under the same exception.
g.dirEntries.push_back({"NEPKernel.sys", false});
const Verdict aniimo = StaticPreScanGameWithSources(exe, FakeSources(), kYidun);
CHECK(aniimo.reason == Reason::kAntiCheatFile);
CHECK(std::string(aniimo.family) == kKernelDriverInTreeFamily);
}
TEST_CASE("D33 -- the excepted family's module loading late does not stop the Overlay; any other family still does",
"[guard][inject][shm][loader][D33]") {
// The Overlay's half. A decoy named `NEP2.dll` (NetEase Yidun's module, an exact floor match) loads 2.5 s after
// injection. With the Agent's tolerance mapping naming the family, the Overlay keeps recording; with it naming a
// kernel-level family instead, the Overlay's own FamilyIsUserModeOnly refuses the name and the decoy stops it.
wchar_t temp[MAX_PATH]{};
REQUIRE(GetTempPathW(MAX_PATH, temp) != 0);
const std::wstring dir = std::wstring(temp) + L"fl-d33-" + std::to_wstring(GetCurrentProcessId());
CreateDirectoryW(dir.c_str(), nullptr);
const std::wstring decoy = dir + L"\\NEP2.dll";
REQUIRE(CopyFileW(FL_STUB_SL_COMMON, decoy.c_str(), FALSE));
for (const char* named : {kYidun, "Easy Anti-Cheat"}) {
const bool tolerated = std::strcmp(named, kYidun) == 0;
INFO("tolerance names " << named);
Child child;
std::wstring args = L"--real --hold-presenting 14 --load-after-ms 2500 \"" + decoy + L"\"";
REQUIRE(StartHarness(child, args));
// The mapping exists BEFORE the injection, as the Agent creates it.
wchar_t name[96]{};
REQUIRE(MakeToleranceName(name, 96, child.pi.dwProcessId));
HANDLE mapping =
CreateFileMappingW(INVALID_HANDLE_VALUE, nullptr, PAGE_READWRITE, 0, sizeof(FlTolerance), name);
REQUIRE(mapping != nullptr);
void* view = MapViewOfFile(mapping, FILE_MAP_WRITE, 0, 0, sizeof(FlTolerance));
REQUIRE(view != nullptr);
FlTolerance t{};
t.magic = FL_TOLERANCE_MAGIC;
t.version = FL_TOLERANCE_VERSION;
t.count = 1;
strcpy_s(t.families[0], named);
std::memcpy(view, &t, sizeof(t));
UnmapViewOfFile(view);
ResetFake();
g.modules = {"kernel32.dll"};
g.scanSet = {child.pi.dwProcessId};
REQUIRE(GuardedInjectWithSources(child.pi.dwProcessId, FL_OVERLAY_DLL, FakeSources()).Allowed());
MappedRing r;
REQUIRE(OpenRingFor(child.pi.dwProcessId, r));
// Past the late load (2.5 s), with the supervision clock kept alive throughout.
for (int i = 0; i < 50; ++i) {
++r.ctl->guardTicks;
Sleep(100);
}
if (tolerated) {
const std::uint64_t mid = r.st->writeIndex;
for (int i = 0; i < 10; ++i) {
++r.ctl->guardTicks;
Sleep(100);
}
CHECK(r.st->status == fl::FL_STATUS_READY);
CHECK(r.st->earlyStopFamily == 0u);
CHECK(r.st->writeIndex > mid); // still recording after the family's module arrived
} else {
CHECK(r.st->status == fl::FL_STATUS_STOPPED_BLOCKLISTED);
CHECK(r.st->earlyStopFamily != 0u);
}
CloseHandle(mapping);
} // each child is gone before its module file is deleted
DeleteFileW(decoy.c_str());
RemoveDirectoryW(dir.c_str());
}
+12
View File
@@ -20,6 +20,7 @@
#include <cstddef>
#include <cstdio>
#include <fl_shm.h>
#include <fl_tolerance.h>
using namespace fl;
@@ -36,6 +37,9 @@ int main() {
std::printf(" \"layoutVersion\": %u,\n", FL_SHM_LAYOUT_VERSION);
std::printf(" \"regions\": { \"handshake\": %u, \"writer\": %u, \"control\": %u, \"ring\": %u },\n",
FL_SHM_HANDSHAKE_OFFSET, FL_SHM_WRITER_OFFSET, FL_SHM_CONTROL_OFFSET, FL_SHM_RING_OFFSET);
// D33: the tolerance mapping (fl_tolerance.h) the Agent writes before an injection under a user-mode exception.
std::printf(" \"tolerance\": { \"magic\": %u, \"version\": %u, \"maxFamilies\": %u, \"nameLen\": %u },\n",
FL_TOLERANCE_MAGIC, FL_TOLERANCE_VERSION, FL_TOLERANCE_MAX_FAMILIES, FL_TOLERANCE_NAME_LEN);
std::printf(" \"structs\": {\n");
std::printf(" \"FlShmHandshake\": { \"size\": %zu, \"fields\": [\n", sizeof(FlShmHandshake));
@@ -108,6 +112,14 @@ int main() {
Field("reserved", offsetof(FlFrameRecord, reserved), sizeof(uint8_t) * 3);
Field("seq", offsetof(FlFrameRecord, seq), sizeof(uint32_t));
Field("swapchainId", offsetof(FlFrameRecord, swapchainId), sizeof(uint32_t), true);
std::printf(" ] },\n");
std::printf(" \"FlTolerance\": { \"size\": %zu, \"fields\": [\n", sizeof(FlTolerance));
Field("magic", offsetof(FlTolerance, magic), sizeof(uint32_t));
Field("version", offsetof(FlTolerance, version), sizeof(uint32_t));
Field("count", offsetof(FlTolerance, count), sizeof(uint32_t));
Field("reserved", offsetof(FlTolerance, reserved), sizeof(uint32_t));
Field("families", offsetof(FlTolerance, families), sizeof(FlTolerance::families), true);
std::printf(" ] }\n");
std::printf(" }\n}\n");
@@ -53,8 +53,10 @@ public sealed class ReasonTextTests
{
foreach (AntiCheatRefusalReason reason in Enum.GetValues<AntiCheatRefusalReason>())
{
// The findings name their family, and the kill switch always carries its own label and end reason.
if (reason is AntiCheatRefusalReason.Allow or AntiCheatRefusalReason.BlockedModule or AntiCheatRefusalReason.BlockedDriver
// The findings name their family, the two allows are never said as a refusal (D33's names its family too), and
// the kill switch always carries its own label and end reason.
if (reason is AntiCheatRefusalReason.Allow or AntiCheatRefusalReason.AllowedUnderUserModeException
or AntiCheatRefusalReason.BlockedModule or AntiCheatRefusalReason.BlockedDriver
or AntiCheatRefusalReason.BlockedService or AntiCheatRefusalReason.BlockedExecutable or AntiCheatRefusalReason.BlockedStoreId
or AntiCheatRefusalReason.AntiCheatDirectory or AntiCheatRefusalReason.AntiCheatFile or AntiCheatRefusalReason.KillSwitchEngaged)
{
@@ -14,14 +14,19 @@ public sealed class AntiCheatVerdictTests
default(AntiCheatVerdict).IsAllowed.Should().BeFalse();
}
/// <summary>
/// The two allows are the only permitting values: a plain pass, and since D33 (2026-09-26) a pass whose only findings
/// were the excepted user-mode family's. Every other reason refuses.
/// </summary>
[Fact]
public void Allowed_IsTheOnlyPermittingValue()
public void OnlyTheTwoAllowsPermit()
{
AntiCheatVerdict.Allowed().IsAllowed.Should().BeTrue();
AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll").IsAllowed.Should().BeTrue();
foreach (AntiCheatRefusalReason reason in Enum.GetValues<AntiCheatRefusalReason>())
{
if (reason == AntiCheatRefusalReason.Allow)
if (reason is AntiCheatRefusalReason.Allow or AntiCheatRefusalReason.AllowedUnderUserModeException)
{
continue;
}
@@ -30,14 +35,41 @@ public sealed class AntiCheatVerdictTests
}
}
[Fact]
public void Refused_CannotCarryAllow()
[Theory]
[InlineData(AntiCheatRefusalReason.Allow)]
[InlineData(AntiCheatRefusalReason.AllowedUnderUserModeException)]
public void Refused_CannotCarryAnAllow(AntiCheatRefusalReason allow)
{
// Making the contradiction unrepresentable rather than merely untested.
Action act = () => AntiCheatVerdict.Refused(AntiCheatRefusalReason.Allow, "fam", "sig");
Action act = () => AntiCheatVerdict.Refused(allow, "fam", "sig");
act.Should().Throw<ArgumentOutOfRangeException>();
}
/// <summary>
/// D33: an allow under the user-mode exception names what it let through, so the session it starts can be marked
/// with it, and is never a finding that turns the game's hooking off.
/// </summary>
[Fact]
public void AnExceptionAllowNamesWhatItLetThrough()
{
AntiCheatVerdict v = AntiCheatVerdict.AllowedUnderException("NetEase Yidun", "NEP2.dll");
v.RanUnderException.Should().BeTrue();
v.Family.Should().Be("NetEase Yidun");
v.Signal.Should().Be("NEP2.dll");
v.IsFindingAboutTheGame.Should().BeFalse("what an exception let through is not a finding that turns hooking off");
AntiCheatVerdict native = AntiCheatVerdict.FromNative((int)AntiCheatRefusalReason.AllowedUnderUserModeException, "NetEase Yidun", "NEP2.dll");
native.IsAllowed.Should().BeTrue();
native.RanUnderException.Should().BeTrue();
native.Family.Should().Be("NetEase Yidun", "the native answer keeps the family, unlike a plain allow");
AntiCheatVerdict.Allowed().RanUnderException.Should().BeFalse();
default(AntiCheatVerdict).RanUnderException.Should().BeFalse();
Action nameless = () => AntiCheatVerdict.AllowedUnderException(" ", "NEP2.dll");
nameless.Should().Throw<ArgumentException>("an exception that names no family let nothing through that anyone can see");
}
[Fact]
public void FromNative_MapsEveryKnownReason()
{
@@ -65,7 +65,7 @@ public sealed class ShmLayoutMirrorTests
return element;
}
private static void AssertMirror<T>(string nativeName)
private static void AssertMirror<T>(string nativeName, int size = 64, string shape = "one cache line in fl_shm.h")
where T : struct
{
JsonElement native = StructOf(nativeName);
@@ -74,7 +74,7 @@ public sealed class ShmLayoutMirrorTests
// actually lays out and therefore what a memory-mapped read sees. They can differ, and only the
// second one is the property the reader depends on.
int nativeSize = native.GetProperty("size").GetInt32();
nativeSize.Should().Be(64, $"{nativeName} is one cache line in fl_shm.h");
nativeSize.Should().Be(size, $"{nativeName} is {shape}");
Marshal.SizeOf<T>().Should().Be(nativeSize, $"{typeof(T).Name} marshalled size must match {nativeName}");
Unsafe.SizeOf<T>().Should().Be(nativeSize, $"{typeof(T).Name} runtime size must match {nativeName}");
@@ -198,6 +198,22 @@ public sealed class ShmLayoutMirrorTests
[Fact]
public void TheFrameRecordMirrorMatches() => AssertMirror<FlFrameRecord>("FlFrameRecord");
/// <summary>D33: the tolerance mapping the Agent writes before an injection under a user-mode exception.</summary>
[Fact]
public void TheToleranceMirrorMatches() =>
AssertMirror<FlTolerance>("FlTolerance", 528, "a 16-byte header and eight 64-byte names in fl_tolerance.h");
[Fact]
public void TheToleranceConstantsMatch()
{
JsonElement tolerance = _nativeLayout.Value.GetProperty("tolerance");
tolerance.GetProperty("magic").GetUInt32().Should().Be(ToleranceLayout.Magic);
tolerance.GetProperty("version").GetUInt32().Should().Be(ToleranceLayout.Version);
tolerance.GetProperty("maxFamilies").GetInt32().Should().Be(ToleranceLayout.MaxFamilies);
tolerance.GetProperty("nameLen").GetInt32().Should().Be(ToleranceLayout.NameLen);
(ToleranceLayout.MaxFamilies * ToleranceLayout.NameLen).Should().Be(512, "FlTolerance.Families is a fixed 512-byte buffer");
}
[Fact]
public void EveryNativeFieldIsMirrored()
{
@@ -211,6 +227,7 @@ public sealed class ShmLayoutMirrorTests
("FlWriterState", typeof(FlWriterState)),
("FlControlBlock", typeof(FlControlBlock)),
("FlFrameRecord", typeof(FlFrameRecord)),
("FlTolerance", typeof(FlTolerance)),
];
foreach ((string nativeName, Type managed) in pairs)