Compare commits

...
1 Commits
Author SHA1 Message Date
poli0981andClaude Opus 5.5 c4c25ebb7f fix(guard): a scan-set member still loading or already gone is read again once before the guard refuses, and a refused re-scan of a game that has exited ends as its exit (beta.14 PR-4, D48)
Owner decision D48 (2026-10-05), from the crash-reporter question: the 30 s re-scan reads every process
in the game's tree; a member still being created (an engine's crash reporter as its game dies, any
helper started a moment before - EnumProcessModulesEx ERROR_PARTIAL_COPY) or gone between the snapshot
and the open (OpenProcess ERROR_INVALID_PARAMETER) refused the session as unreadable, ending it as a
safety unhook - which also ends a user-mode exception's trial for good.

Native (FrameLedger.Guard): Collected::kRetry, produced by EnumerateModules only for those two errors;
ACCESS_DENIED (a protected process) stays kFailed and is never retried. CheckModules runs one pass,
notes a kRetry and goes on (a finding anywhere still refuses at once), then Pause(kScanRetryPauseMs =
250) and a second pass over a FRESH scan set, where kRetry refuses as kProcessUnreadable and a gone
target leaves no set (kProcessTreeUnavailable). Sources::Pause seam (Sleep in SystemSources).
FindPresentationRuntime treats kRetry as "not yet". fl_prescan's chain ended in an implicit pass for
any new Collected value - it refuses anything but kOk now. fl-baseline-probe names the new value.

Managed: ExitScanRelabel - when the re-scan refused for ProcessUnreadable / ModuleScanFailed /
ProcessTreeUnavailable (never a finding) and the game itself has exited at conclusion, the session is
TargetExited (exit code decides normal/crashed), CaptureOutcome.ExitScanReason, notes
`scan_at_exit=<reason>` (CaptureNotes.ScanAtExit). Findings, live games and other checks unchanged.

Tests: ctest fl_guard [D48] (re-read clean; still unreadable refuses; exited member drops out; gone
target refuses; ACCESS_DENIED never retried; a finding refuses at once; a finding the re-read sees
refuses; [live]: a suspended process and a pid with no process answer kRetry against the real source),
CaptureSessionTests (relabel for the three reasons; live game, finding, driver failure unchanged),
SessionRecorderTests (the note and the exit status), CaptureNotesTests.

Docs: 19_SAFETY (check 1 amended; During a session), 04_CAPTURE, 14_TESTING, CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 01:46:35 +07:00
18 changed files with 438 additions and 29 deletions

No files matched your search

+7
View File
@@ -36,6 +36,13 @@ numeric core and does not move; the heading is the full version — corrected 20
### Fixed
- **A game that exited as FrameLedger's anti-cheat check ran could be recorded as "unhooked (safety)"** — and, under a
user-mode anti-cheat exception, end the exception's trial for good. The check reads every process in the game's
tree every 30 s; one that was just starting (an engine's crash reporter as its game dies, any helper the game launched
a moment before) or already gone could not be read, and the check refused. Such a process is now read once more a
quarter of a second later, and refused only if it is still unreadable (a protected process never gets the second
look). And when the check could not read and the game itself has exited, the session ends as that exit, normal or
crashed by its exit code. Anything the check *finds* is a refusal exactly as before (owner decision D48).
- **An installed copy never found an update unless you had changed its channel.** The update channel was *Stable* by
default and every FrameLedger release so far is a pre-release, so the check found nothing. The channel is now
*Automatic*: a pre-release looks for pre-releases and a release for releases; choosing *Stable* or *Beta* still decides.
+3 -1
View File
@@ -438,7 +438,9 @@ because a layer cannot leave a running game's loader chain.
- Normal: presenting PID exit code 0 — **and since beta.8 any exit code that is not an exception's** (End task and taskkill leave 1; a program's own error exit; Ctrl+C's `0xC000013A`), kept in `capture_notes` and said as what it is.
- `crashed`: ~~nonzero exit code~~ **an exception's exit code** (`ExitStatusMapper.IsExceptionCode`: NTSTATUS `0xC0000000–0xC0FFFFFF` but `0xC000013A`, `0xE06D7363` C++, `0xE0434352` .NET, `0x80000003` breakpoint), **or** an Application Error (1000) / WER (1001) event log record naming the exe within `[start, end + 30 s]`.
- `unhooked_safety`: the guard fired mid-session.
- `unhooked_safety`: the guard fired mid-session. *(Since beta.14, D48: a re-scan that refused only because it could not
read the game's tree, concluded after the game itself had exited, is the game's exit instead — `normal` or `crashed` by
its exit code — with `scan_at_exit=<reason>` in `capture_notes`; `19_SAFETY` §During a session.)*
- `degraded`: Overlay self-disabled after faults, or ring layout mismatch mid-session.
- `interrupted`: Agent died mid-session; recovered from `.partial` on next start.
- A **user stop** (FR-3.6; `StopSession` over the pipe, P3 PR-1b) is `normal`: the loop ends as `SessionEndReason.StoppedByUser` at its next tick, drains once more and finalizes; the target keeps running, unhooked from here. It is the session's own stop token, not the host's cancellation — the latter leaves a `.partial`.
+7
View File
@@ -16,6 +16,13 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
- **Absence-of-override test:** no code path may reach the injection primitive without a passing guard result. The mechanism previously described here — a `sealed` token type "only the guard can produce" — does not work and was disproved by compiling (`20_OPEN_QUESTIONS` §S8: C# accessibility flows inward, `CS0122`). The replacement is structural: the guard **owns the chokepoint** and calls the primitive itself, the primitive has internal linkage in the guard's own translation unit so no other TU has a symbol to call, and a build-time check asserts that nothing else references it. A token that escapes can be ignored; a symbol that does not exist cannot.
- Static pre-scan: a game directory containing `EasyAntiCheat/` renders `hook_enabled` un-settable; API-level attempt to set it is rejected — including via `SetWatchlist`, which no longer carries hooking state at all (`07_IPC` §The pipe is not a trust boundary). ~~**The toggle half needs persistence and is not built yet**~~ **built in P2/P3**: `SqliteGameConsentStore.RecordGuardBlockAsync` forces `hook_enabled = 0`, `AgentCommandHandler.SetHookEnabledAsync` re-runs the pre-scan and answers `Refused`, and `GameDetailViewModel` disables the toggle on a blocked row (corrected 2026-09-21; since 2026-09-22 a finding at a session's start or at the re-scan writes the same block — `CaptureSessionTests`); the scan itself is ctest `fl_prescan`, whose matrix is mostly fail-closed: a listing that FAILED, one that was TRUNCATED, a directory that could not be established, unusable rules, and a missing evidence source must each be *undetermined*, never clean. Two cases exist only to stop the rest passing vacuously — a genuinely clean directory must be **allowed**, and a name matching the wrong group (a directory named like a `files` entry) must **not** fire. One case removes a family from the rules and asserts the hit disappears, which is what proves there is a single matcher rather than a second one that happens to agree.
> **D48 (beta.14):** the module check's one re-read is held both ways in ctest `fl_guard` `[D48]` — a member still
> loading reads clean on the re-read (one pause, two snapshots); one still unreadable refuses; one that exited drops out of
> the fresh set; a target that exited refuses; `ACCESS_DENIED` is never retried; a finding refuses at once and a finding
> the re-read sees refuses — and against the real source (`[live]`: a process created suspended and a pid with no process
> answer `kRetry`). The managed half — a refused re-scan of a game that has exited ends as its exit, never for a finding —
> is `CaptureSessionTests` and `SessionRecorderTests`.
## Native unit tests (Catch2)
- **Ring buffer:** SPSC correctness under a hammering writer thread; seqlock torn-read detection; wrap and overwrite-oldest semantics; power-of-two capacity assumptions. Include the **one-full-lap case**: a reader stalled exactly `capacity` records must not validate a different frame as unchanged (this is what the never-reset `seq` counter defends, `07_IPC` §Protocol rules).
+22
View File
@@ -51,6 +51,19 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> handle rights above are confirmed sufficient for every target this call can
> legitimately reach.
>
> **Amended 2026-10-05 (owner decision D48, beta.14): one re-read, never a pass.** A member of the scan set that
> is still being created answers `ERROR_PARTIAL_COPY` (its loader has not built a module list), and one that exited
> between the snapshot and the open answers `ERROR_INVALID_PARAMETER`. Both refused the whole session — and at the
> 30 s re-scan an engine's crash reporter starting as its game died, or any helper started a moment before the scan,
> turned an ordinary exit into a "safety" unhook, which ends a user-mode exception's trial for good. Such a member
> (`Collected::kRetry`, `fl_guard.h`) is now read once more: the pass finishes (a finding in any member still refuses
> at once), waits `kScanRetryPauseMs` (250 ms), takes a **fresh** scan set and scans it whole. A member still unreadable
> then refuses `kProcessUnreadable`, as before; one that has gone is not in the new set; a target that has gone leaves
> no set, which refuses `kProcessTreeUnavailable`. **`ERROR_ACCESS_DENIED` — a protected process — is never retried**,
> and no other answer of any source is. The sentence above stands: every failure still means REFUSE; what changed is
> how many times "still loading" is asked before it counts as one. ctest `fl_guard` `[D48]` holds both directions,
> against fakes and against the real source (a process created suspended, a pid with no process).
>
> **Launch mode (2026-09-06, P1 item 2) does not weaken this.** `FlGuardedInjectWhenReady` polls
> the same enumeration to learn *when* the launched target has mapped a presentation runtime, and a
> failing enumeration there means "not yet" — the poll continues. That is not a pass: the poll
@@ -836,6 +849,15 @@ checked stays untrusted and refuses — that direction is deliberate.
Re-run **every pre-injection check** every 30 s, for **every Tier-1 session —
injected or layered**.
> **A refused re-scan of a game that has already exited is that exit (owner decision D48, beta.14).** When the re-scan
> refuses only because it could not read the game's tree (`ProcessUnreadable`, `ModuleScanFailed`,
> `ProcessTreeUnavailable` — never a finding) and the game itself has exited by the time the session concludes, the
> session ends as `TargetExited`, its exit code deciding normal or crashed, with `scan_at_exit=<reason>` in its notes
> (`Application.Capture.ExitScanRelabel`). The stop was still published to the Overlay — the game it would have stopped
> is gone. A finding, any refusal while the game still runs, and a refusal of another check (drivers, services, the
> pre-scan) are a safety unhook exactly as before. `CaptureSessionTests.AnUnreadableRescanOfAGameThatHasExited…` and
> its three refusing neighbours.
> **This said "both the module scan and the driver scan" until 2026-08-05, and
> the loop runs four checks, not two** (`20_OPEN_QUESTIONS` §S23-4).
> `FlGuardEvaluate` → `EvaluateImpl` runs `CheckDrivers`, `CheckServices`,
@@ -20,6 +20,13 @@ public sealed record CaptureOutcome
/// </summary>
public bool HookingTurnedOff { get; init; }
/// <summary>
/// D48(b), beta.14: the guard's "could not read" refusal at the last re-scan, when the session concluded as the game's
/// exit rather than a safety unhook because the game itself had already exited (<see cref="ExitScanRelabel"/>); null
/// otherwise. Written to the notes as <c>scan_at_exit=</c>.
/// </summary>
public AntiCheatRefusalReason? ExitScanReason { get; init; }
/// <summary>
/// D33 (owner decision 2026-09-26): the family the game's user-mode exception covered for this session — published to
/// the Overlay and named to the guard at the injection and at every re-scan — or null when none was in force. The
@@ -431,6 +431,9 @@ public sealed class CaptureSession(
// about the game at the 30 s re-scan turns its hooking off exactly as one at the start does (2026-09-22).
AntiCheatVerdict final = end == SessionEndReason.SafetyUnhook && supervisor.LastVerdict is { } fired ? fired : verdict;
bool turnedOff = end == SessionEndReason.SafetyUnhook && await TurnHookingOffAsync(observed, final, ct).ConfigureAwait(false);
// D48(b): a re-scan that could not read, concluded as the game's exit (ExitScanRelabel) — its reason goes in the notes.
AntiCheatRefusalReason? exitScan = end == SessionEndReason.TargetExited && supervisor.LastVerdict is { IsAllowed: false } last
&& ExitScanRelabel.Applies(last.Reason) ? last.Reason : null;
return new CaptureOutcome
{
@@ -440,6 +443,7 @@ public sealed class CaptureSession(
Reason = end,
Verdict = final,
HookingTurnedOff = turnedOff,
ExitScanReason = exitScan,
ExceptionFamily = toleratedFamily,
AttachRefusal = ShmAttachRefusal.Ok,
Records = state.Records,
@@ -555,7 +559,7 @@ public sealed class CaptureSession(
await FlushNativeLogAsync(sink, alive, end, ct).ConfigureAwait(false);
// The switch's stop is the user's, not the guard's: it ends the session as its own reason rather
// than as the safety refusal a false mayContinue would otherwise read as.
return state.KillSwitchStopped ? SessionEndReason.KillSwitchEngaged : Conclude(end, faulted, mayContinue);
return state.KillSwitchStopped ? SessionEndReason.KillSwitchEngaged : Conclude(end, faulted, mayContinue, supervisor.LastVerdict, alive.HasExited);
}
/// <summary>
@@ -738,14 +742,18 @@ public sealed class CaptureSession(
/// <see cref="SessionEndClassifier"/> cannot know that, because the mapping stores
/// one status for both stops.
/// </remarks>
private static SessionEndReason Conclude(SessionEndReason end, Exception? faulted, bool mayContinue)
/// <remarks>
/// D48(b), beta.14: a refusal that says only that the guard could not read, concluded after the game itself has exited
/// (read after the last drain), is the game's exit — <see cref="ExitScanRelabel"/>. A finding never is.
/// </remarks>
private static SessionEndReason Conclude(SessionEndReason end, Exception? faulted, bool mayContinue, AntiCheatVerdict? lastVerdict, bool targetExited)
{
if (faulted is not null)
{
return SessionEndReason.SupervisionFaulted;
}
return mayContinue ? end : SessionEndReason.SafetyUnhook;
return mayContinue ? end : ExitScanRelabel.EndOf(lastVerdict, targetExited);
}
/// <summary>
@@ -0,0 +1,29 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Domain.AntiCheat;
namespace FrameLedger.Application.Capture;
/// <summary>
/// Owner decision D48(b), beta.14. The guard's 30 s re-scan reads every process in the game's tree; one that is
/// starting (an engine's crash reporter, as its game dies) or gone could not be read, the scan refused, and the session
/// ended as a <see cref="SessionEndReason.SafetyUnhook"/> — a "safety" stop for a game that had simply exited, which also
/// ended a user-mode exception's trial for good. When the refusal says only that the guard COULD NOT READ and the game
/// itself has exited by the time the session concludes, the session ends as the game's exit
/// (<see cref="SessionEndReason.TargetExited"/>), its exit code deciding normal or crashed, and the scan's reason is kept
/// in the notes (<c>scan_at_exit=</c>). A finding — any anti-cheat the guard identified — is never relabelled, and neither
/// is a refusal while the game still runs.
/// </summary>
public static class ExitScanRelabel
{
/// <summary>The guard's "could not read" refusals of the module check (<c>fl_guard.cpp</c> check 1) — never a finding.</summary>
public static bool Applies(AntiCheatRefusalReason reason) =>
reason is AntiCheatRefusalReason.ProcessUnreadable or AntiCheatRefusalReason.ModuleScanFailed or AntiCheatRefusalReason.ProcessTreeUnavailable;
/// <summary>The end a refused re-scan concludes as: the game's exit when <see cref="Applies"/> and it has exited, else a safety unhook.</summary>
public static SessionEndReason EndOf(AntiCheatVerdict? lastVerdict, bool targetExited) =>
targetExited && lastVerdict is { IsAllowed: false } refused && Applies(refused.Reason)
? SessionEndReason.TargetExited
: SessionEndReason.SafetyUnhook;
}
@@ -40,6 +40,12 @@ public readonly record struct CaptureNotes(string? End, string? GuardReason, str
/// <summary>D33: the family the game's user-mode exception let through while the session was hooked (<c>ac-exception=</c>).</summary>
public string? AcExceptionFamily { get; init; }
/// <summary>
/// D48(b), beta.14: the guard's "could not read" answer at the last re-scan of a session that ended as the game's exit
/// (<c>scan_at_exit=</c>), or null.
/// </summary>
public string? ScanAtExit { get; init; }
public static CaptureNotes Parse(string? notes)
{
if (string.IsNullOrWhiteSpace(notes))
@@ -47,7 +53,7 @@ public readonly record struct CaptureNotes(string? End, string? GuardReason, str
return default;
}
string? end = null, reason = null, family = null, signal = null, acException = null;
string? end = null, reason = null, family = null, signal = null, acException = null, scanAtExit = null;
int? exitCode = null, launchError = null;
bool crashEvent = false;
foreach (string raw in notes.Split(';'))
@@ -77,6 +83,10 @@ public readonly record struct CaptureNotes(string? End, string? GuardReason, str
{
acException = Blank(part[_acExceptionPrefix.Length..]);
}
else if (part.StartsWith(_scanAtExitPrefix, StringComparison.Ordinal))
{
scanAtExit = Blank(part[_scanAtExitPrefix.Length..]);
}
}
return new CaptureNotes(end, reason, family, signal)
@@ -85,6 +95,7 @@ public readonly record struct CaptureNotes(string? End, string? GuardReason, str
CrashEvent = crashEvent,
LaunchError = launchError,
AcExceptionFamily = acException,
ScanAtExit = scanAtExit,
};
}
@@ -132,6 +143,8 @@ public readonly record struct CaptureNotes(string? End, string? GuardReason, str
private const string _acExceptionPrefix = "ac-exception=";
private const string _scanAtExitPrefix = "scan_at_exit=";
private static string Clean(string? s) => string.IsNullOrEmpty(s) ? string.Empty : s.Replace(';', ',');
private static string? Blank(string s) => s.Length > 0 ? s : null;
@@ -266,6 +266,13 @@ public sealed class SessionRecorder : ISessionRecorder
notes += "; " + CaptureNotes.AcExceptionSlot(excepted);
}
// D48(b), beta.14: the last re-scan could not read the game's tree as the game exited, and the session ended as
// that exit rather than as a safety unhook; what the scan said stays with the row.
if (o.ExitScanReason is { } scanAtExit)
{
notes += "; scan_at_exit=" + scanAtExit;
}
// The session that turned the game's hooking off says so in its notes (2026-09-22): the row's block names
// the finding, and the notes travel into every bug bundle.
if (o.HookingTurnedOff)
@@ -252,8 +252,18 @@ enum class Collected : std::uint8_t {
kOk = 0,
kFailed, // the call failed outright
kIncomplete, // partial result: e.g. WOW64 without LIST_MODULES_ALL
// EnumerateModules ONLY (owner decision D48, beta.14): a process still being created (ERROR_PARTIAL_COPY -- its
// loader has not finished) or gone between the scan set's snapshot and the open (ERROR_INVALID_PARAMETER). The
// module check reads the whole scan set once more, after kScanRetryPauseMs, and a second kRetry refuses as
// kProcessUnreadable -- so it is never a pass. ACCESS_DENIED (a protected process) is kFailed and is never retried.
// Every other consumer of Collected treats anything but kOk as a failure.
kRetry,
};
// How long the module check waits before its one re-read (D48). A process that was still loading has its modules
// well within it; one that has exited is out of the fresh snapshot.
inline constexpr std::uint32_t kScanRetryPauseMs = 250;
// Callbacks receive (context, name) for each item found. Returning false stops
// enumeration early — used when a match has already been found.
using NameSink = bool (*)(void* ctx, const char* name);
@@ -300,6 +310,10 @@ struct Sources {
// ancestors up to but excluding the first known platform launcher.
Collected (*EnumerateScanSet)(std::uint32_t targetPid, bool (*sink)(void*, std::uint32_t), void* ctx) = nullptr;
// The module check's one pause before it re-reads the scan set (D48). Null skips the pause: the re-read still
// happens, and still refuses what it still cannot read.
void (*Pause)(std::uint32_t ms) = nullptr;
// Whole rules file into a caller-owned buffer. Returns bytes written, or
// SIZE_MAX on any failure — unreadable, absent, or larger than the cap.
std::size_t (*ReadRulesFile)(char* buffer, std::size_t cap) = nullptr;
@@ -453,9 +467,9 @@ struct Sources {
// would make one of them untestable without disturbing the other.
// The real Windows implementations. Behaviour measured in spike-notes.md §1;
// notably EnumerateModules reports kFailed on ERROR_PARTIAL_COPY (a suspended
// target) and uses LIST_MODULES_ALL, without which a 32-bit target under-reports
// by more than half AS A SUCCESS.
// notably EnumerateModules reports kRetry (kFailed until D48, beta.14) on ERROR_PARTIAL_COPY (a suspended
// target, or one whose loader has not finished) and on a process already gone, and uses LIST_MODULES_ALL,
// without which a 32-bit target under-reports by more than half AS A SUCCESS.
[[nodiscard]] Sources SystemSources() noexcept;
// ---------------------------------------------------------------------------
@@ -388,14 +388,12 @@ Verdict LoadRules(const Sources& s, Rules& rules) 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");
}
// One pass of check 1 over a fresh scan set. `allowRetry` (D48): on the first pass a member that is still being
// created or already gone (Collected::kRetry) is noted in `retryWanted` and the pass goes on -- a finding in any other
// member still refuses at once; on the second pass the same answer refuses as kProcessUnreadable, exactly as an
// unreadable member always has. Anything but the four answers refuses too: no answer is a pass by omission.
Verdict ScanModulesOnce(const Sources& s, const Rules& rules, std::uint32_t targetPid, const Tolerance* tolerance,
ToleratedFinding& finding, bool allowRetry, bool& retryWanted) noexcept {
ScanSet set;
if (s.EnumerateScanSet(targetPid, &ScanSetSink, &set) != Collected::kOk || set.overflowed || set.count == 0) {
// An empty scan set is not "nothing to scan" — it is "we do not know
@@ -417,14 +415,19 @@ Verdict CheckModules(const Sources& s, const Rules& rules, std::uint32_t targetP
if (st.hit != nullptr) {
return Refuse(Reason::kBlockedModule, st.hit->name, st.signal);
}
// kFailed covers ERROR_ACCESS_DENIED on a protected target and
// ERROR_PARTIAL_COPY on a suspended one; kIncomplete covers a WOW64
// under-report. Both mean we did not see the whole picture, and the
// D48: a member still being created, or gone since the snapshot, is read again once from a fresh one.
if (c == Collected::kRetry && allowRetry) {
retryWanted = true;
continue;
}
// kFailed covers ERROR_ACCESS_DENIED on a protected target; kRetry here
// is a member that was still unreadable on the re-read; kIncomplete covers a WOW64
// under-report. Each means we did not see the whole picture, and the
// whole point of this guard is that a partial look is not a clean one.
if (c == Collected::kFailed) {
if (c == Collected::kFailed || c == Collected::kRetry) {
return Refuse(Reason::kProcessUnreadable, nullptr, "a process in the scan set could not be read");
}
if (c == Collected::kIncomplete) {
if (c != Collected::kOk) {
return Refuse(Reason::kModuleScanFailed, nullptr, "a module list came back incomplete");
}
if (st.sawSuspicious) {
@@ -451,6 +454,36 @@ Verdict CheckModules(const Sources& s, const Rules& rules, std::uint32_t targetP
return Allow();
}
// 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.
//
// D48 (owner decision, beta.14): a member that was still being created -- an engine's crash reporter started as its
// game died, a helper launched a moment before the 30 s re-scan -- or that exited between the snapshot and the read,
// refused the whole session as "unreadable" and ended it as a safety unhook. Such a member is read again ONCE: the pass
// finishes (a finding anywhere still refuses at once), pauses kScanRetryPauseMs, takes a FRESH scan set and scans it
// whole. A member still unreadable then refuses as before; one that is gone is not in the new set; a target that is
// gone makes the new set unavailable, which refuses. The re-read can only turn a refusal of "could not read" into a
// full read -- never into a pass that skipped anything.
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");
}
bool retryWanted = false;
const Verdict first = ScanModulesOnce(s, rules, targetPid, tolerance, finding, true, retryWanted);
if (!first.Allowed() || !retryWanted) {
return first;
}
if (s.Pause != nullptr) {
s.Pause(kScanRetryPauseMs);
}
finding = ToleratedFinding{}; // collected again from the pass that decides
bool again = false;
return ScanModulesOnce(s, rules, targetPid, tolerance, finding, false, again);
}
// Check 2 — machine-wide drivers. Independent of process identity, which is
// why it catches the case a module scan structurally cannot: a driver that
// gates the whole machine, loaded by a game we are not even looking at.
@@ -800,8 +833,9 @@ PresentationRuntime FindPresentationRuntime(const Sources& s, std::uint32_t pid)
if (s.EnumerateModules == nullptr) {
return PresentationRuntime::kNone;
}
RuntimeProbe p;
if (s.EnumerateModules(pid, &RuntimeSinkFn, &p) == Collected::kFailed) {
RuntimeProbe p;
const Collected c = s.EnumerateModules(pid, &RuntimeSinkFn, &p);
if (c == Collected::kFailed || c == Collected::kRetry) {
return PresentationRuntime::kNone; // still in its loader, or unreadable -- the full scan refuses the latter
}
if (p.vk) {
@@ -86,10 +86,18 @@ bool IsPlatformLauncher(const wchar_t* imageName) noexcept {
return false;
}
// The module check's one pause before its re-read (D48).
void PauseImpl(std::uint32_t ms) noexcept {
Sleep(ms);
}
Collected EnumerateModulesImpl(std::uint32_t pid, ModuleSink sink, void* ctx) noexcept {
HANDLE h = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_VM_READ, FALSE, pid);
if (h == nullptr) {
return Collected::kFailed; // ACCESS_DENIED on a protected target: cannot determine
// D48 (beta.14): ERROR_INVALID_PARAMETER is a pid with no process -- it exited between the scan set's snapshot
// and this open -- which the module check reads again from a fresh snapshot. ACCESS_DENIED on a protected
// target, and everything else: cannot determine, as ever.
return GetLastError() == ERROR_INVALID_PARAMETER ? Collected::kRetry : Collected::kFailed;
}
HMODULE mods[1024]{};
@@ -97,8 +105,11 @@ Collected EnumerateModulesImpl(std::uint32_t pid, ModuleSink sink, void* ctx) no
// LIST_MODULES_ALL, always. Measured: the default filter under-reports a
// 32-bit target by more than half and returns that as a success.
if (!EnumProcessModulesEx(h, mods, sizeof(mods), &needed, LIST_MODULES_ALL)) {
const DWORD err = GetLastError();
CloseHandle(h);
return Collected::kFailed; // includes ERROR_PARTIAL_COPY on a suspended target
// ERROR_PARTIAL_COPY: a process whose loader has not built its module list yet -- a child created moments ago,
// an engine's crash reporter starting as its game dies, a suspended target. Read again once (D48).
return err == ERROR_PARTIAL_COPY ? Collected::kRetry : Collected::kFailed;
}
const bool truncated = needed > sizeof(mods);
@@ -994,6 +1005,7 @@ Collected ModuleSignerOrganisationImpl(const wchar_t* modulePath, char* out, std
Sources SystemSources() noexcept {
Sources s;
s.EnumerateModules = &EnumerateModulesImpl;
s.Pause = &PauseImpl;
s.EnumerateDrivers = &EnumerateDriversImpl;
s.QueryService = &QueryServiceImpl;
s.EnumerateScanSet = &EnumerateScanSetImpl;
@@ -143,6 +143,12 @@ Verdict ScanWith(const Sources& s, const Rules& rules, const wchar_t* dir, const
return Refused(Reason::kPreScanFailed, nullptr,
"the game directory listing was truncated, unreadable, or crossed a reparse point");
}
// Any other answer refuses too (beta.14, with Collected::kRetry's arrival): this chain ended in an implicit pass,
// so a new value of the tri-state would have read as a clean walk.
if (c != Collected::kOk) {
return Refused(Reason::kPreScanFailed, nullptr,
"the game directory listing gave an answer the pre-scan does not know");
}
// 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;
+140 -1
View File
@@ -119,6 +119,10 @@ struct Fake {
int moduleCalls = 0;
std::map<std::uint32_t, Collected> moduleResultByPid;
Collected moduleResult = Collected::kOk;
// D48 (beta.14): a pid's answers call by call -- the first pass, then the re-read. Past its end the last one
// repeats.
std::map<std::uint32_t, std::vector<Collected>> moduleResultsInTurn;
std::map<std::uint32_t, int> moduleCallsByPid;
// Check 3's evidence. Defaults to a name no blocklist entry matches, so every
// pre-existing case keeps its meaning: check 3 runs, looks, and allows.
@@ -133,6 +137,13 @@ struct Fake {
std::vector<std::uint32_t> scanSet{1234};
Collected scanSetResult = Collected::kOk;
// D48: the fresh snapshot the re-read takes. Empty keeps `scanSet`; the result defaults to the first one's.
std::vector<std::uint32_t> scanSetAfterFirst;
Collected scanSetResultAfterFirst = Collected::kOk;
bool scanSetAfterFirstFails = false;
int scanSetCalls = 0;
int pauses = 0;
std::uint32_t lastPauseMs = 0;
// Check 4 — the static pre-scan. Entries are (name, isDirectory), because
// directories and files are matched against different blocklist groups and
@@ -227,6 +238,13 @@ Collected FakeEnumModules(std::uint32_t pid, ModuleSink sink, void* ctx) {
break;
}
}
const int turn = g.moduleCallsByPid[pid]++;
const auto tit = g.moduleResultsInTurn.find(pid);
if (tit != g.moduleResultsInTurn.end() && !tit->second.empty()) {
const std::size_t last = tit->second.size() - 1; // windows.h's min macro: no std::min here
const std::size_t at = static_cast<std::size_t>(turn) < last ? static_cast<std::size_t>(turn) : last;
return tit->second[at];
}
const auto rit = g.moduleResultByPid.find(pid);
return (rit != g.moduleResultByPid.end()) ? rit->second : g.moduleResult;
}
@@ -251,7 +269,12 @@ Collected FakeQueryService(const char* name, bool* present) {
}
Collected FakeEnumScanSet(std::uint32_t, bool (*sink)(void*, std::uint32_t), void* ctx) {
for (auto pid : g.scanSet) {
const bool later = g.scanSetCalls++ >= 1;
const auto& set = (later && !g.scanSetAfterFirst.empty()) ? g.scanSetAfterFirst : g.scanSet;
if (later && g.scanSetAfterFirstFails) {
return Collected::kFailed;
}
for (auto pid : set) {
if (!sink(ctx, pid)) {
break;
}
@@ -259,6 +282,11 @@ Collected FakeEnumScanSet(std::uint32_t, bool (*sink)(void*, std::uint32_t), voi
return g.scanSetResult;
}
void FakePause(std::uint32_t ms) {
++g.pauses;
g.lastPauseMs = ms;
}
Collected FakeImageDirectory(std::uint32_t, wchar_t* out, std::size_t cap) {
if (g.imageDirectoryResult != Collected::kOk) {
return g.imageDirectoryResult;
@@ -399,6 +427,7 @@ Sources FakeSources() {
s.EnumerateDrivers = &FakeEnumDrivers;
s.QueryService = &FakeQueryService;
s.EnumerateScanSet = &FakeEnumScanSet;
s.Pause = &FakePause;
s.ImageDirectory = &FakeImageDirectory;
s.ImageFileName = &FakeImageFileName;
s.EnumerateDirEntries = &FakeEnumDirEntries;
@@ -685,6 +714,116 @@ TEST_CASE("EVERY process in the scan set is scanned, not just the target", "[gua
}
}
// ===========================================================================
// D48 (owner decision, beta.14) — a member still being created, or gone, is read
// again ONCE, and the re-read can only turn "could not read" into a full read.
//
// The case it is for: an engine's crash reporter starting as its game dies, or any
// helper launched a moment before the 30 s re-scan, answered ERROR_PARTIAL_COPY
// (its loader had not built a module list) and the whole session ended as a
// safety unhook. What it must never do is pass something it did not read: the
// sections below spend most of their effort on that.
// ===========================================================================
TEST_CASE("D48 — a scan-set member still loading, or gone, is read again once", "[guard][failclosed][D48]") {
ResetFake();
g.scanSet = {1234, 1000, 4000}; // target first, its launcher, a child that is starting
SECTION("a member still loading reads clean on the re-read: one pause, two snapshots, allowed") {
g.moduleResultsInTurn[4000] = {Collected::kRetry, Collected::kOk};
CHECK(EvaluateWithSources(1234, FakeSources()).Allowed());
CHECK(g.pauses == 1);
CHECK(g.lastPauseMs == kScanRetryPauseMs);
CHECK(g.scanSetCalls == 2);
}
SECTION("a member that is still unreadable on the re-read refuses as unreadable") {
g.moduleResultsInTurn[4000] = {Collected::kRetry, Collected::kRetry};
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kProcessUnreadable);
CHECK(g.pauses == 1);
}
SECTION("a member that exited is not in the fresh snapshot, and the rest reads clean") {
g.moduleResultsInTurn[4000] = {Collected::kRetry};
g.scanSetAfterFirst = {1234, 1000};
CHECK(EvaluateWithSources(1234, FakeSources()).Allowed());
CHECK(g.moduleCallsByPid[4000] == 1);
}
SECTION("a target that is gone leaves no scan set to take, which refuses") {
g.moduleResultsInTurn[1234] = {Collected::kRetry};
g.scanSetAfterFirstFails = true;
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kProcessTreeUnavailable);
}
SECTION("ACCESS_DENIED -- a protected process -- is never retried") {
g.moduleResultByPid[4000] = Collected::kFailed;
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kProcessUnreadable);
CHECK(g.pauses == 0);
CHECK(g.scanSetCalls == 1);
}
SECTION("a finding in another member refuses at once, with no pause") {
g.moduleResultsInTurn[4000] = {Collected::kRetry, Collected::kOk};
g.modulesByPid[1000] = {"EasyAntiCheat_EOS.dll"};
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kBlockedModule);
CHECK(g.pauses == 0);
}
SECTION("a finding the re-read sees refuses") {
g.moduleResultsInTurn[4000] = {Collected::kRetry, Collected::kOk};
g.modulesByPid[1234] = {"kernel32.dll"};
g.modulesByPid[1000] = {"kernel32.dll"};
g.modulesLate = {"EasyAntiCheat_EOS.dll"};
g.moduleCallsBeforeLate = 3; // the first pass's three reads; the reporter shows its module on the re-read
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kBlockedModule);
CHECK(g.pauses == 1);
}
}
TEST_CASE("D48 — the real module source answers kRetry for a process still loading and for one that is gone",
"[guard][D48][live]") {
const Sources s = SystemSources();
REQUIRE(s.EnumerateModules != nullptr);
REQUIRE(s.Pause != nullptr);
auto none = [](void*, const char*, const wchar_t*) noexcept -> bool { return true; };
// A pid with no process behind it: the open fails with ERROR_INVALID_PARAMETER.
CHECK(s.EnumerateModules(0x7FFFFFFCu, none, nullptr) == Collected::kRetry);
// A process created suspended: its loader has not run, and the module list is a partial copy.
STARTUPINFOW si{};
PROCESS_INFORMATION pi{};
si.cb = sizeof(si);
wchar_t cmd[] = L"cmd.exe /c exit 0";
REQUIRE(CreateProcessW(nullptr, cmd, nullptr, nullptr, FALSE, CREATE_SUSPENDED | CREATE_NO_WINDOW, nullptr, nullptr,
&si, &pi));
const Collected suspended = s.EnumerateModules(pi.dwProcessId, none, nullptr);
TerminateProcess(pi.hProcess, 0);
CloseHandle(pi.hThread);
CloseHandle(pi.hProcess);
CHECK(suspended == Collected::kRetry);
// And a process this test may read whole is kOk, as ever.
CHECK(s.EnumerateModules(GetCurrentProcessId(), none, nullptr) == Collected::kOk);
}
// ===========================================================================
// §S18 — the guard refused ITSELF.
//
@@ -223,6 +223,8 @@ const char* CollectedName(fl::guard::Collected c) {
return "FAILED";
case fl::guard::Collected::kIncomplete:
return "INCOMPLETE";
case fl::guard::Collected::kRetry:
return "RETRY (still loading, or gone)";
}
return "?";
}
@@ -831,6 +831,74 @@ public sealed class CaptureSessionTests : IAsyncDisposable
(await store.FindAsync(_exe, TestContext.Current.CancellationToken)).HookEnabled.Should().BeFalse();
}
/// <summary>
/// D48(b), beta.14: the re-scan could not read the game's tree — an engine's crash reporter still starting as its game
/// died — and the game itself has exited. The session is the game's exit, not a safety unhook, and the scan's answer is
/// kept; nothing turns hooking off.
/// </summary>
[Theory]
[InlineData(AntiCheatRefusalReason.ProcessUnreadable)]
[InlineData(AntiCheatRefusalReason.ModuleScanFailed)]
[InlineData(AntiCheatRefusalReason.ProcessTreeUnavailable)]
public async Task AnUnreadableRescanOfAGameThatHasExitedEndsAsItsExit(AntiCheatRefusalReason couldNotRead)
{
var guard = new CountingGuard { EvaluateVerdict = AntiCheatVerdict.Refused(couldNotRead, string.Empty, "a process in the scan set could not be read") };
using var sink = new FakeSink();
using var alive = new FakeLiveness { HasExited = true, ExitCode = 3 };
IGameConsentStore store = await StoreWithAsync();
CaptureSession loop = Loop(store, guard, sink, alive, options: EndsOnItsOwn);
CaptureOutcome r = await loop.RunAsync(_exe, Fingerprint, "payload.dll", TestContext.Current.CancellationToken);
r.Reason.Should().Be(SessionEndReason.TargetExited, "the game had gone; its exit decides how the session ended");
r.ExitScanReason.Should().Be(couldNotRead);
r.HookingTurnedOff.Should().BeFalse("nothing was found");
(await store.FindAsync(_exe, TestContext.Current.CancellationToken)).HookEnabled.Should().BeTrue();
}
[Fact]
public async Task AnUnreadableRescanOfALiveGameIsStillASafetyUnhook()
{
var guard = new CountingGuard { EvaluateVerdict = AntiCheatVerdict.Refused(AntiCheatRefusalReason.ProcessUnreadable, string.Empty, "access is denied") };
using var sink = new FakeSink();
using var alive = new FakeLiveness { HasExited = false };
CaptureSession loop = Loop(await StoreWithAsync(), guard, sink, alive, options: EndsOnItsOwn);
CaptureOutcome r = await loop.RunAsync(_exe, Fingerprint, "payload.dll", TestContext.Current.CancellationToken);
r.Reason.Should().Be(SessionEndReason.SafetyUnhook, "a game still running that the guard cannot read is unhooked, as ever");
r.ExitScanReason.Should().BeNull();
}
[Fact]
public async Task AFindingOnAGameThatHasExitedIsStillASafetyUnhook()
{
var guard = new CountingGuard { EvaluateVerdict = AntiCheatVerdict.Refused(AntiCheatRefusalReason.BlockedModule, "BattlEye", "BEClient_x64.dll") };
using var sink = new FakeSink();
using var alive = new FakeLiveness { HasExited = true, ExitCode = 0 };
IGameConsentStore store = await StoreWithAsync();
CaptureSession loop = Loop(store, guard, sink, alive, options: EndsOnItsOwn);
CaptureOutcome r = await loop.RunAsync(_exe, Fingerprint, "payload.dll", TestContext.Current.CancellationToken);
r.Reason.Should().Be(SessionEndReason.SafetyUnhook, "a finding is never relabelled, whatever the game did next");
r.HookingTurnedOff.Should().BeTrue();
r.ExitScanReason.Should().BeNull();
}
[Fact]
public async Task ADriverScanFailureIsNotRelabelled()
{
var guard = new CountingGuard { EvaluateVerdict = AntiCheatVerdict.Refused(AntiCheatRefusalReason.DriverScanFailed, string.Empty, "driver list unreadable") };
using var sink = new FakeSink();
using var alive = new FakeLiveness { HasExited = true };
CaptureSession loop = Loop(await StoreWithAsync(), guard, sink, alive, options: EndsOnItsOwn);
CaptureOutcome r = await loop.RunAsync(_exe, Fingerprint, "payload.dll", TestContext.Current.CancellationToken);
r.Reason.Should().Be(SessionEndReason.SafetyUnhook, "only the module check's could-not-read answers concern the game's own tree");
}
[Fact]
public async Task AGuardThatThrowsStopsTheTickRatherThanBeingSwallowed()
{
@@ -25,6 +25,15 @@ public sealed class CaptureNotesTests
blocked.GuardSignal.Should().Be("AntiCheatDirectory|Easy Anti-Cheat|EasyAntiCheat", "the signal is the last slot and keeps its own bars");
}
[Fact]
public void TheScanAtExitSlotReadsBack()
{
// D48(b), beta.14: a session that ended as the game's exit though its last re-scan could not read the game's tree.
CaptureNotes n = CaptureNotes.Parse("end=TargetExited; exit_code=3; scan_at_exit=ProcessUnreadable");
(n.End, n.ExitCode, n.ScanAtExit).Should().Be(("TargetExited", 3, "ProcessUnreadable"));
CaptureNotes.Parse("end=TargetExited; exit_code=0").ScanAtExit.Should().BeNull();
}
[Fact]
public void TheRecorderWritesEverySlotAndNoSemicolonInsideOne()
{
@@ -82,7 +82,10 @@ public sealed class SessionRecorderTests : IAsyncDisposable
{
public AntiCheatVerdict Verdict { get; set; } = AntiCheatVerdict.Allowed();
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default) => ValueTask.FromResult(AntiCheatVerdict.Allowed());
/// <summary>What every re-scan answers (D48's tests): allowed unless a test says otherwise.</summary>
public AntiCheatVerdict Rescan { get; set; } = AntiCheatVerdict.Allowed();
public ValueTask<AntiCheatVerdict> EvaluateAsync(int targetPid, string? toleratedFamily, CancellationToken ct = default) => ValueTask.FromResult(Rescan);
public ValueTask<AntiCheatVerdict> GuardedInjectAsync(int targetPid, string payloadPath, string? toleratedFamily, CancellationToken ct = default) => ValueTask.FromResult(Verdict);
@@ -288,7 +291,8 @@ public sealed class SessionRecorderTests : IAsyncDisposable
}
private async Task<Harness> MakeAsync(bool consented = true, AntiCheatVerdict? verdict = null, int records = 3_000, FakeLiveness? liveness = null, bool poller = true,
bool clockStepsOnDrain = false, IDriverProfileSource? profiles = null, bool excepted = false, IDisplayProbe? display = null, ulong adapterLuid = 0)
bool clockStepsOnDrain = false, IDriverProfileSource? profiles = null, bool excepted = false, IDisplayProbe? display = null, ulong adapterLuid = 0,
AntiCheatVerdict? rescan = null)
{
_db ??= await LedgerDatabase.OpenAsync(Path.Combine(_dir, LedgerPaths.DatabaseFileName), ct: TestContext.Current.CancellationToken).ConfigureAwait(false);
var store = new SqliteGameConsentStore(_db);
@@ -308,7 +312,7 @@ public sealed class SessionRecorderTests : IAsyncDisposable
}
var clock = new SteppingClock();
var guard = new FakeGuard { Verdict = verdict ?? AntiCheatVerdict.Allowed() };
var guard = new FakeGuard { Verdict = verdict ?? AntiCheatVerdict.Allowed(), Rescan = rescan ?? AntiCheatVerdict.Allowed() };
var games = new FakeGameRepository();
var sessions = new FakeSessionRepository();
var partials = new FakePartialSessionStore();
@@ -565,6 +569,25 @@ public sealed class SessionRecorderTests : IAsyncDisposable
h.Games.Rows[_exe].HookEnabled.Should().BeFalse();
}
/// <summary>
/// D48(b), beta.14: the re-scan could not read the game's tree as the game exited — the session is that exit, its exit
/// code deciding normal or crashed, and the notes keep what the scan said.
/// </summary>
[Fact]
public async Task ARescanThatCouldNotReadAsTheGameExitedEndsAsItsExitWithTheScanInTheNotes()
{
using var exited = new FakeLiveness(exited: true, exitCode: 0);
Harness h = await MakeAsync(liveness: exited,
rescan: AntiCheatVerdict.Refused(AntiCheatRefusalReason.ProcessUnreadable, string.Empty, "a process in the scan set could not be read"));
RecordedSession r = await h.Recorder.RecordAsync(Request(), TestContext.Current.CancellationToken);
r.Outcome.Reason.Should().Be(SessionEndReason.TargetExited);
r.ExitStatus.Should().Be(ExitStatus.Normal, "a game that exited with 0 ended normally, whatever the last scan could read");
r.Row.CaptureNotes.Should().Contain("scan_at_exit=ProcessUnreadable");
CaptureNotes.Parse(r.Row.CaptureNotes).ScanAtExit.Should().Be("ProcessUnreadable");
}
[Fact]
public async Task AnEarlyCrashIsCountedAndTheSecondOneDisablesHooking()
{