rcdebug 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,650 @@
1
+ """
2
+ Sub-10ms 120,000-Flaw Intelligence Catalog (flaws_120000.txt + ~/.rcdebug/index_cache.bin).
3
+
4
+ Uses a marshal-backed byte-offset & inverted-posting-list binary cache plus mmap
5
+ seek-reads so cold/warm CLI startups bypass parsing 120,000 lines into Python dicts.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import marshal
11
+ import mmap
12
+ import re
13
+ from dataclasses import dataclass
14
+ from functools import lru_cache
15
+ from pathlib import Path
16
+ from typing import Iterator, Pattern
17
+
18
+ from .debugger_pack import get_debugger_pack
19
+ from .learner import AdaptiveLearner, FlawBrain, extract_game_tokens
20
+ from .models import Finding, normalize_severity
21
+
22
+ FLAWS_TXT_PATH = Path(__file__).resolve().parent / "data" / "flaws_120000.txt"
23
+ INDEX_CACHE_PATH = Path.home() / ".rcdebug" / "index_cache.bin"
24
+ EXPECTED_FLAW_COUNT = 120000
25
+ _CACHE_VERSION = 2
26
+
27
+
28
+ @dataclass(frozen=True, slots=True)
29
+ class FlawSignature:
30
+ code: str
31
+ severity: str
32
+ category: str
33
+ domain: str
34
+ title: str
35
+ keywords: tuple[str, ...]
36
+ flaw: str
37
+ abuse: str
38
+ fix: str
39
+ rank: int = 999999
40
+ code_example: str = ""
41
+
42
+
43
+ @dataclass(frozen=True, slots=True)
44
+ class StaticCodeRule:
45
+ code: str
46
+ severity: str
47
+ category: str
48
+ title: str
49
+ literal_hint: str
50
+ pattern: Pattern[str]
51
+ anti_pattern: Pattern[str] | None
52
+ flaw: str
53
+ abuse: str
54
+ fix: str
55
+ rank: int = 100
56
+ code_example: str = ""
57
+
58
+
59
+ STATIC_CODE_RULES: tuple[StaticCodeRule, ...] = (
60
+ StaticCodeRule(
61
+ code="RCD-S001",
62
+ severity="CRITICAL",
63
+ category="StaticScriptAudit",
64
+ title="Dynamic Code Execution via loadstring()",
65
+ literal_hint="loadstring",
66
+ pattern=re.compile(r"\bloadstring\s*\("),
67
+ anti_pattern=None,
68
+ flaw="Script invokes loadstring() to dynamically compile and execute arbitrary Luau strings.",
69
+ abuse="If any remote argument, DataStore entry, or free-model payload reaches loadstring(), attackers achieve full server RCE.",
70
+ fix="Disable ServerScriptService.LoadStringEnabled and replace dynamic execution with a static function lookup table.",
71
+ rank=1,
72
+ code_example="local Handlers = { Heal = function(plr) ... end }\nlocal fn = Handlers[action]\nif fn then fn(player) end",
73
+ ),
74
+ StaticCodeRule(
75
+ code="RCD-S002",
76
+ severity="CRITICAL",
77
+ category="HttpSecurity",
78
+ title="Hardcoded Discord Webhook URL in Script",
79
+ literal_hint="webhooks/",
80
+ pattern=re.compile(r"https?://(?:ptb\.|canary\.)?discord(?:app)?\.com/api/webhooks/", re.IGNORECASE),
81
+ anti_pattern=None,
82
+ flaw="Script embeds a raw Discord webhook URL directly in source code.",
83
+ abuse="Attackers can extract exposed shared URLs or trigger remote-backed actions to spam/delete the webhook or forge audit logs.",
84
+ fix="Store credentials in HttpService:GetSecret() and throttle outbound webhook dispatches server-side.",
85
+ rank=2,
86
+ code_example='local secret = HttpService:GetSecret("AUDIT_WEBHOOK")',
87
+ ),
88
+ StaticCodeRule(
89
+ code="RCD-S003",
90
+ severity="WARN",
91
+ category="HttpSecurity",
92
+ title="Unwrapped or Unthrottled Outbound HttpService Call",
93
+ literal_hint="HttpService",
94
+ pattern=re.compile(r"HttpService\s*:\s*(?:PostAsync|GetAsync|RequestAsync)\s*\("),
95
+ anti_pattern=re.compile(r"\bpcall\s*\("),
96
+ flaw="Script calls HttpService network methods without an enclosing pcall() or visible rate-limit guard.",
97
+ abuse="Malicious players triggering HTTP-backed actions can exhaust the 500 req/min HttpService budget or cause unhandled script crashes.",
98
+ fix="Wrap all HttpService calls in pcall(), enforce per-player/server request queues, and never interpolate client input into URLs.",
99
+ rank=25010,
100
+ code_example="local ok, res = pcall(function() return HttpService:RequestAsync(opts) end)",
101
+ ),
102
+ StaticCodeRule(
103
+ code="RCD-S004",
104
+ severity="CRITICAL",
105
+ category="DataStoreSecurity",
106
+ title="Non-Atomic DataStore SetAsync() Without UpdateAsync()",
107
+ literal_hint="SetAsync",
108
+ pattern=re.compile(r":\s*SetAsync\s*\("),
109
+ anti_pattern=re.compile(r":\s*UpdateAsync\s*\("),
110
+ flaw="Script writes player progression using SetAsync() instead of atomic UpdateAsync() transforms.",
111
+ abuse="Concurrent server saves, cross-server teleports, or rapid trade/drop requests cause classic DataStore item duplication or rollback.",
112
+ fix="Use DataStore:UpdateAsync() with session locking (or ProfileStore/ProfileService) for all currency and inventory persistence.",
113
+ rank=3,
114
+ code_example="store:UpdateAsync(key, function(old)\n old = old or { Cash = 0 }\n old.Cash += delta\n return old\nend)",
115
+ ),
116
+ StaticCodeRule(
117
+ code="RCD-S005",
118
+ severity="CRITICAL",
119
+ category="MarketplaceSecurity",
120
+ title="ProcessReceipt Handler Missing PurchaseId Idempotency Check",
121
+ literal_hint="ProcessReceipt",
122
+ pattern=re.compile(r"MarketplaceService\.ProcessReceipt\s*="),
123
+ anti_pattern=re.compile(r"PurchaseId|Enum\.ProductPurchaseDecision\.PurchaseGranted"),
124
+ flaw="MarketplaceService.ProcessReceipt callback lacks visible PurchaseId deduplication or explicit PurchaseGranted handling.",
125
+ abuse="Players can trigger duplicate developer product grants on rejoin or leave receipts unacknowledged across sessions.",
126
+ fix="Record receiptInfo.PurchaseId atomically via UpdateAsync() before returning Enum.ProductPurchaseDecision.PurchaseGranted.",
127
+ rank=4,
128
+ code_example="if table.find(profile.ProcessedReceipts, receipt.PurchaseId) then\n return Enum.ProductPurchaseDecision.PurchaseGranted\nend",
129
+ ),
130
+ StaticCodeRule(
131
+ code="RCD-S006",
132
+ severity="CRITICAL",
133
+ category="PromptSecurity",
134
+ title="ProximityPrompt.Triggered Without Server Distance Check",
135
+ literal_hint="Triggered",
136
+ pattern=re.compile(r"\.Triggered\s*:\s*Connect\s*\("),
137
+ anti_pattern=re.compile(r"Magnitude|MaxActivationDistance|DistanceFromCharacter"),
138
+ flaw="ProximityPrompt.Triggered handler trusts client prompt activation without verifying character distance on the server.",
139
+ abuse="Exploiters manipulating local character position or replication timing can fire prompts from across the map or through walls.",
140
+ fix="Verify player.Character PrimaryPart distance to the prompt's parent BasePart (<= prompt.MaxActivationDistance + tolerance) on the server.",
141
+ rank=5,
142
+ code_example="local root = player.Character and player.Character.PrimaryPart\nif not root or (root.Position - promptPart.Position).Magnitude > prompt.MaxActivationDistance + 4 then return end",
143
+ ),
144
+ StaticCodeRule(
145
+ code="RCD-S007",
146
+ severity="WARN",
147
+ category="PhysicsSecurity",
148
+ title="BasePart.Touched Handler Missing Player/Cooldown Guard",
149
+ literal_hint="Touched",
150
+ pattern=re.compile(r"\.Touched\s*:\s*Connect\s*\("),
151
+ anti_pattern=re.compile(r"GetPlayerFromCharacter|debounce|cooldown|os\.clock"),
152
+ flaw="Touched connection processes hits without checking GetPlayerFromCharacter or enforcing a per-player debounce.",
153
+ abuse="Clients with network ownership over their character or unanchored parts can spam Touched events 60+ times per second.",
154
+ fix="Validate Players:GetPlayerFromCharacter(hit.Parent) and apply a per-player cooldown before awarding damage, coins, or teleports.",
155
+ rank=25020,
156
+ code_example="local plr = Players:GetPlayerFromCharacter(hit.Parent)\nif not plr or isDebounced(plr) then return end",
157
+ ),
158
+ StaticCodeRule(
159
+ code="RCD-S008",
160
+ severity="CRITICAL",
161
+ category="TeleportSecurity",
162
+ title="TeleportService Call With Unvalidated TeleportData or PlaceId",
163
+ literal_hint="Teleport",
164
+ pattern=re.compile(r"TeleportService\s*:\s*(?:Teleport|TeleportAsync|TeleportToPlaceInstance)\s*\("),
165
+ anti_pattern=re.compile(r"ALLOWED_PLACES|MemoryStoreService|DataStore"),
166
+ flaw="Script invokes TeleportService without validating target PlaceIds or signing cross-server state.",
167
+ abuse="If teleport options or TeleportData come from client-accessible sources, attackers can spoof carried stats/inventory on arrival.",
168
+ fix="Never trust GetLocalPlayerTeleportData() on the server; pass authoritative cross-server state via MemoryStoreService or DataStoreService.",
169
+ rank=6,
170
+ ),
171
+ StaticCodeRule(
172
+ code="RCD-S009",
173
+ severity="WARN",
174
+ category="TextFiltering",
175
+ title="User-Supplied Text Displayed Without TextService Filtering",
176
+ literal_hint=".Text",
177
+ pattern=re.compile(r"\.Text\s*=\s*(?:msg|message|text|input|name|bio|petName|title)\b", re.IGNORECASE),
178
+ anti_pattern=re.compile(r"FilterStringAsync|TextService|TextChatService"),
179
+ flaw="User-supplied string appears to be assigned directly to a UI/SurfaceGui Text property without TextService filtering.",
180
+ abuse="Players can broadcast unfiltered profanity, PII, or moderation-violating text to other players, risking game moderation action.",
181
+ fix="Always pass user-authored text through TextService:FilterStringAsync() on the server before replicating to other clients.",
182
+ rank=25030,
183
+ ),
184
+ StaticCodeRule(
185
+ code="RCD-S010",
186
+ severity="WARN",
187
+ category="MemoryLeak",
188
+ title="Unbounded Connection or Instance Creation Without Cleanup",
189
+ literal_hint="Instance.new",
190
+ pattern=re.compile(r"Instance\.new\s*\(\s*[\"'](?:Part|MeshPart|Model|Sound|ParticleEmitter)[\"']"),
191
+ anti_pattern=re.compile(r"Debris\s*:\s*AddItem|:Destroy\s*\("),
192
+ flaw="Script dynamically instantiates Workspace/FX objects without visible Debris:AddItem() or :Destroy() lifecycle cleanup.",
193
+ abuse="Repeated combat, projectile, or VFX spawns leak instances until server memory saturates and physics degrades.",
194
+ fix="Register temporary instances with Debris:AddItem(obj, lifetime) or reuse objects via an instance pool.",
195
+ rank=25040,
196
+ code_example='game:GetService("Debris"):AddItem(fxInstance, 2.5)',
197
+ ),
198
+ StaticCodeRule(
199
+ code="RCD-S011",
200
+ severity="CRITICAL",
201
+ category="ServerSecurity",
202
+ title="Legacy Require by Numeric Asset ID (Potential Backdoor Surface)",
203
+ literal_hint="require",
204
+ pattern=re.compile(r"\brequire\s*\(\s*\d{6,}\s*\)"),
205
+ anti_pattern=None,
206
+ flaw="Script calls require(<numeric_asset_id>) to load external closed-source ModuleScripts at runtime.",
207
+ abuse="External asset modules can be updated independently by third parties to inject server backdoors, remote shells, or data exfiltration.",
208
+ fix="Replace numeric asset require() calls with audited local ModuleScripts inside ServerScriptService or ReplicatedStorage.",
209
+ rank=7,
210
+ ),
211
+ StaticCodeRule(
212
+ code="RCD-S012",
213
+ severity="CRITICAL",
214
+ category="CombatSecurity",
215
+ title="Server Accepts Client-Supplied Damage or Target Health Value",
216
+ literal_hint="Humanoid",
217
+ pattern=re.compile(r"Humanoid\s*(?::\s*TakeDamage|\.Health\s*[-+]?=)\s*\(?\s*(?:dmg|damage|amount|heal|val)\b", re.IGNORECASE),
218
+ anti_pattern=re.compile(r"WEAPON_STATS|MAX_DAMAGE|math\.clamp"),
219
+ flaw="Server damage/healing calculation applies a variable directly without looking up authoritative weapon stats or clamping.",
220
+ abuse="If the parameter originates from a RemoteEvent, attackers can pass 1e9 to insta-kill any player/boss or negative values to heal/godmode.",
221
+ fix="Look up damage server-side from weapon/ability IDs, validate range/LoS/cooldowns, and reject NaN or negative numbers.",
222
+ rank=8,
223
+ ),
224
+ )
225
+
226
+ _TOKEN_SPLIT_RE = re.compile(r"[a-z0-9]+")
227
+ _CAMEL_SUB_RE = re.compile(r"[A-Z]?[a-z]+|[A-Z]+(?=[A-Z][a-z]|\b)|\d+")
228
+
229
+
230
+ @lru_cache(maxsize=16384)
231
+ def _split_camel_cached(raw_leaf: str) -> frozenset[str]:
232
+ out: set[str] = set(_TOKEN_SPLIT_RE.findall(raw_leaf.lower()))
233
+ for part in re.split(r"[^A-Za-z0-9]+", raw_leaf):
234
+ if not part:
235
+ continue
236
+ for sub in _CAMEL_SUB_RE.findall(part):
237
+ out.add(sub.lower())
238
+ return frozenset(out)
239
+
240
+
241
+ def _parse_flaw_line(raw_line: str) -> FlawSignature:
242
+ line = raw_line.rstrip("\r\n")
243
+ parts = line.split("|", 9)
244
+ if len(parts) < 9:
245
+ raise ValueError(f"Malformed flaw record: {line[:80]}")
246
+ code, sev, cat, domain, kw_csv, title, flaw, abuse, fix = parts[:9]
247
+ rank = int(parts[9]) if len(parts) == 10 and parts[9].isdigit() else 999999
248
+ keywords = tuple(k.strip().lower() for k in kw_csv.split(",") if k.strip())
249
+ return FlawSignature(
250
+ code=code,
251
+ severity=sev,
252
+ category=cat,
253
+ domain=domain,
254
+ title=title,
255
+ keywords=keywords,
256
+ flaw=flaw,
257
+ abuse=abuse,
258
+ fix=fix,
259
+ rank=rank,
260
+ )
261
+
262
+
263
+ def _build_or_load_index(
264
+ txt_path: Path = FLAWS_TXT_PATH,
265
+ cache_path: Path = INDEX_CACHE_PATH,
266
+ ) -> tuple[list[int], dict[str, list[int]], dict[str, list[int]]]:
267
+ """
268
+ Loads pre-built byte-offset & inverted-posting-list index from `cache_path`
269
+ if `txt_path` (size, mtime_ns) matches; otherwise builds and writes it once.
270
+ """
271
+ if not txt_path.exists():
272
+ raise FileNotFoundError(f"Flaw database file not found: {txt_path}")
273
+
274
+ st = txt_path.stat()
275
+ sig_key = (st.st_size, st.st_mtime_ns)
276
+
277
+ if cache_path.exists():
278
+ try:
279
+ with cache_path.open("rb") as cfh:
280
+ payload = marshal.load(cfh)
281
+ if (
282
+ isinstance(payload, dict)
283
+ and payload.get("v") == _CACHE_VERSION
284
+ and payload.get("size") == sig_key[0]
285
+ and payload.get("mtime_ns") == sig_key[1]
286
+ and len(payload.get("offsets", ())) == EXPECTED_FLAW_COUNT
287
+ ):
288
+ return (
289
+ payload["offsets"],
290
+ payload["primary_kw_index"],
291
+ payload["keyword_index"],
292
+ )
293
+ except Exception:
294
+ pass
295
+
296
+ offsets: list[int] = []
297
+ primary_kw_index: dict[str, list[int]] = {}
298
+ keyword_index: dict[str, list[int]] = {}
299
+
300
+ with txt_path.open("rb") as fh:
301
+ idx = 0
302
+ while True:
303
+ pos = fh.tell()
304
+ raw = fh.readline()
305
+ if not raw:
306
+ break
307
+ if not raw.strip():
308
+ continue
309
+ offsets.append(pos)
310
+ line = raw.decode("utf-8", errors="replace").rstrip("\r\n")
311
+ parts = line.split("|", 5)
312
+ if len(parts) >= 5:
313
+ kws = [k.strip().lower() for k in parts[4].split(",") if k.strip()]
314
+ if kws:
315
+ primary_kw_index.setdefault(kws[0], []).append(idx)
316
+ for kw in kws:
317
+ keyword_index.setdefault(kw, []).append(idx)
318
+ idx += 1
319
+
320
+ if len(offsets) != EXPECTED_FLAW_COUNT:
321
+ raise ValueError(
322
+ f"Expected {EXPECTED_FLAW_COUNT} flaws in {txt_path}, found {len(offsets)}"
323
+ )
324
+
325
+ try:
326
+ cache_path.parent.mkdir(parents=True, exist_ok=True)
327
+ with cache_path.open("wb") as cfh:
328
+ marshal.dump(
329
+ {
330
+ "v": _CACHE_VERSION,
331
+ "size": sig_key[0],
332
+ "mtime_ns": sig_key[1],
333
+ "offsets": offsets,
334
+ "primary_kw_index": primary_kw_index,
335
+ "keyword_index": keyword_index,
336
+ },
337
+ cfh,
338
+ )
339
+ except OSError:
340
+ pass
341
+
342
+ return offsets, primary_kw_index, keyword_index
343
+
344
+
345
+ class FlawCatalog:
346
+ """
347
+ Sub-10ms indexed storage for 120,000 Roblox flaw signatures.
348
+ Seek-reads only matched records from flaws_120000.txt via mmap/offset table.
349
+ """
350
+
351
+ def __init__(
352
+ self,
353
+ txt_path: Path = FLAWS_TXT_PATH,
354
+ cache_path: Path = INDEX_CACHE_PATH,
355
+ static_rules: tuple[StaticCodeRule, ...] = STATIC_CODE_RULES,
356
+ learner: AdaptiveLearner | None = None,
357
+ brain: FlawBrain | None = None,
358
+ ) -> None:
359
+ self.txt_path = txt_path
360
+ self.cache_path = cache_path
361
+ self.static_rules = static_rules
362
+ self.learner = learner or AdaptiveLearner()
363
+ self.brain = brain or FlawBrain()
364
+
365
+ offsets, primary_kw_index, keyword_index = _build_or_load_index(txt_path, cache_path)
366
+ self._offsets = offsets
367
+ self._primary_kw_index = primary_kw_index
368
+ self._keyword_index = keyword_index
369
+ self._record_cache: dict[int, FlawSignature] = {}
370
+ self._match_cache: dict[tuple[str, str, int], list[FlawSignature]] = {}
371
+
372
+ # Open read-only mmap handle for sub-millisecond seek-reads
373
+ self._fh = txt_path.open("rb")
374
+ self._mm = mmap.mmap(self._fh.fileno(), 0, access=mmap.ACCESS_READ)
375
+
376
+ def close(self) -> None:
377
+ mm = getattr(self, "_mm", None)
378
+ if mm is not None:
379
+ try:
380
+ mm.close()
381
+ except Exception:
382
+ pass
383
+ self._mm = None # type: ignore[assignment]
384
+ fh = getattr(self, "_fh", None)
385
+ if fh is not None:
386
+ try:
387
+ fh.close()
388
+ except Exception:
389
+ pass
390
+ self._fh = None # type: ignore[assignment]
391
+
392
+ def __del__(self) -> None:
393
+ self.close()
394
+
395
+ def _read_record(self, idx: int) -> FlawSignature:
396
+ cached = self._record_cache.get(idx)
397
+ if cached is not None:
398
+ return cached
399
+ offset = self._offsets[idx]
400
+ self._mm.seek(offset)
401
+ raw_line = self._mm.readline().decode("utf-8", errors="replace")
402
+ sig = _parse_flaw_line(raw_line)
403
+ if len(self._record_cache) >= 8192:
404
+ self._record_cache.clear()
405
+ self._record_cache[idx] = sig
406
+ return sig
407
+
408
+ def iter_signatures(self) -> Iterator[FlawSignature]:
409
+ """Streams all 120,000 signatures sequentially without holding all in RAM."""
410
+ with self.txt_path.open("r", encoding="utf-8") as fh:
411
+ for raw_line in fh:
412
+ if raw_line.strip():
413
+ yield _parse_flaw_line(raw_line)
414
+
415
+ def has_primary_keyword(self, token: str) -> bool:
416
+ return token.lower() in self._primary_kw_index
417
+
418
+ def count(self) -> int:
419
+ return len(self._offsets)
420
+
421
+ def signature_count(self) -> int:
422
+ return len(self._offsets)
423
+
424
+ def static_rule_count(self) -> int:
425
+ return len(self.static_rules)
426
+
427
+ def get(self, code: str) -> FlawSignature | None:
428
+ m = re.match(r"^RCD-(\d+)$", code.strip().upper())
429
+ if not m:
430
+ return None
431
+ idx = int(m.group(1)) - 1
432
+ if 0 <= idx < len(self._offsets):
433
+ return self._read_record(idx)
434
+ return None
435
+
436
+ def match_name(
437
+ self,
438
+ identifier: str,
439
+ container_hint: str = "",
440
+ limit: int = 5,
441
+ ) -> list[FlawSignature]:
442
+ """
443
+ O(1)-per-token lookup matching an instance name or path against 120,000
444
+ indexed signatures, returning top matches sorted by relevance & rank.
445
+ """
446
+ cache_key = (identifier, container_hint, limit)
447
+ cached = self._match_cache.get(cache_key)
448
+ if cached is not None:
449
+ return cached
450
+
451
+ generic_kws = {"remote", "bindable", "tool", "attribute", "valuebase", "replication", "streaming"}
452
+ lower_id = identifier.lower()
453
+ raw_leaf = container_hint.split(".")[-1] if "." in container_hint else identifier
454
+ leaf = raw_leaf.lower()
455
+ tokens = set(_TOKEN_SPLIT_RE.findall(lower_id))
456
+ leaf_tokens = _split_camel_cached(raw_leaf)
457
+ candidate_scores: dict[int, int] = {}
458
+
459
+ for primary_kw, idxs in self._primary_kw_index.items():
460
+ in_leaf_exact = primary_kw in leaf_tokens
461
+ in_leaf_sub = (not in_leaf_exact) and len(primary_kw) >= 5 and primary_kw in leaf and primary_kw != "emote"
462
+ in_full = primary_kw in tokens
463
+ if not (in_leaf_exact or in_leaf_sub or in_full):
464
+ continue
465
+
466
+ if primary_kw in generic_kws:
467
+ weight = 2
468
+ elif in_leaf_exact:
469
+ weight = 22
470
+ elif in_leaf_sub:
471
+ weight = 12
472
+ else:
473
+ weight = 10
474
+
475
+ for idx in idxs:
476
+ candidate_scores[idx] = candidate_scores.get(idx, 0) + weight
477
+
478
+ if not candidate_scores:
479
+ return []
480
+
481
+ hint_lower = container_hint.lower()
482
+ if hint_lower:
483
+ for hint_tok in _TOKEN_SPLIT_RE.findall(hint_lower):
484
+ for idx in self._keyword_index.get(hint_tok, ()):
485
+ if idx in candidate_scores:
486
+ candidate_scores[idx] += 4
487
+
488
+ # Boost historically reinforced catalog codes
489
+ hits_map = self.learner.catalog_hits
490
+ if hits_map:
491
+ for idx in list(candidate_scores.keys()):
492
+ code = f"RCD-{idx + 1:06d}"
493
+ hit_count = hits_map.get(code, 0)
494
+ if hit_count > 0:
495
+ candidate_scores[idx] += min(6, hit_count)
496
+
497
+ # Rank by (-score, idx) where idx == rank - 1 (CRITICAL first -> lowest last)
498
+ ranked = sorted(candidate_scores.items(), key=lambda kv: (-kv[1], kv[0]))
499
+ result = [self._read_record(idx) for idx, _ in ranked[:limit]]
500
+ if len(self._match_cache) >= 4096:
501
+ self._match_cache.clear()
502
+ self._match_cache[cache_key] = result
503
+ return result
504
+
505
+ def search(self, query: str, limit: int = 25) -> list[FlawSignature]:
506
+ tokens = _TOKEN_SPLIT_RE.findall(query.lower())
507
+ if not tokens:
508
+ return [self._read_record(i) for i in range(min(limit, len(self._offsets)))]
509
+
510
+ counts: dict[int, int] = {}
511
+ for tok in tokens:
512
+ for idx in self._keyword_index.get(tok, ()):
513
+ counts[idx] = counts.get(idx, 0) + 1
514
+ if tok not in self._keyword_index and len(tok) >= 3:
515
+ for kw, idxs in self._keyword_index.items():
516
+ if tok in kw:
517
+ for idx in idxs:
518
+ counts[idx] = counts.get(idx, 0) + 1
519
+
520
+ ranked = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
521
+ return [self._read_record(idx) for idx, _ in ranked[:limit]]
522
+
523
+ def match_source(self, script_path: str, source: str) -> list[Finding]:
524
+ """Runs all precompiled static Luau rules using a fast literal pre-filter."""
525
+ findings: list[Finding] = []
526
+ for rule in self.static_rules:
527
+ if rule.literal_hint and rule.literal_hint not in source:
528
+ continue
529
+ if not rule.pattern.search(source):
530
+ continue
531
+ if rule.anti_pattern is not None and rule.anti_pattern.search(source):
532
+ continue
533
+ findings.append(
534
+ Finding(
535
+ severity=rule.severity,
536
+ category=rule.category,
537
+ title=f"[{rule.code}] {rule.title}",
538
+ path=script_path,
539
+ flaw=rule.flaw,
540
+ abuse=rule.abuse,
541
+ fix=rule.fix,
542
+ code_example=rule.code_example,
543
+ rank=rule.rank,
544
+ metadata={"rule_code": rule.code},
545
+ )
546
+ )
547
+ return findings
548
+
549
+ def enrich_finding(self, finding: Finding) -> Finding:
550
+ """
551
+ Matches a runtime/client finding against the 120,000 catalog signatures,
552
+ learned custom game tokens, and FlawBrain statistical inference.
553
+ """
554
+ learned_hit = None
555
+ learned_tok_name = None
556
+ for tok in extract_game_tokens(f"{finding.path} {finding.title}"):
557
+ if tok in self.learner.learned_tokens:
558
+ learned_hit = self.learner.learned_tokens[tok]
559
+ learned_tok_name = tok
560
+ break
561
+
562
+ matches = self.match_name(
563
+ f"{finding.title} {finding.path}",
564
+ container_hint=finding.path,
565
+ limit=3,
566
+ )
567
+ generic_kws = {"remote", "bindable", "tool", "attribute", "valuebase", "replication", "streaming"}
568
+ strong_catalog_match = bool(
569
+ matches and matches[0].keywords and matches[0].keywords[0] not in generic_kws
570
+ )
571
+
572
+ if strong_catalog_match:
573
+ top = matches[0]
574
+ finding.metadata["catalog_code"] = top.code
575
+ finding.metadata["domain"] = top.domain
576
+ finding.metadata["matched_codes"] = [m.code for m in matches]
577
+ finding.rank = top.rank
578
+
579
+ if not finding.flaw or finding.flaw.startswith("Detected via Roblox Client Console"):
580
+ finding.flaw = top.flaw
581
+ if not finding.abuse or finding.abuse.startswith("Client-exposed state, remote"):
582
+ finding.abuse = top.abuse
583
+ if not finding.fix or finding.fix.startswith("Enforce server-authoritative validation"):
584
+ finding.fix = top.fix
585
+
586
+ if not finding.title.startswith("[RCD-") and not finding.title.startswith("[LEARNED:"):
587
+ finding.title = f"[{top.code}] {finding.title}"
588
+
589
+ if finding.severity == "INFO" and normalize_severity(top.severity) == "CRITICAL":
590
+ finding.severity = "WARN"
591
+ return finding
592
+
593
+ if learned_hit is not None and learned_tok_name is not None:
594
+ finding.metadata["learned_token"] = learned_tok_name
595
+ finding.metadata["domain"] = learned_hit.get("domain", "Learned")
596
+ if not finding.flaw:
597
+ finding.flaw = str(learned_hit.get("flaw", ""))
598
+ if not finding.abuse:
599
+ finding.abuse = str(learned_hit.get("abuse", ""))
600
+ if not finding.fix:
601
+ finding.fix = str(learned_hit.get("fix", ""))
602
+ sev_rank = {"INFO": 1, "WARN": 2, "CRITICAL": 3}
603
+ learned_sev = normalize_severity(str(learned_hit.get("severity", "INFO")))
604
+ if sev_rank.get(learned_sev, 1) > sev_rank.get(finding.severity, 1):
605
+ finding.severity = learned_sev
606
+ if not finding.title.startswith("[LEARNED:") and not finding.title.startswith("[RCD-"):
607
+ finding.title = f"[LEARNED:{learned_tok_name}] {finding.title}"
608
+ return finding
609
+
610
+ if matches:
611
+ top = matches[0]
612
+ finding.metadata["catalog_code"] = top.code
613
+ finding.metadata["domain"] = top.domain
614
+ finding.metadata["matched_codes"] = [m.code for m in matches]
615
+ finding.rank = top.rank
616
+ if not finding.title.startswith("[RCD-"):
617
+ finding.title = f"[{top.code}] {finding.title}"
618
+ self.brain.ingest_flaw_record(
619
+ domain=top.domain,
620
+ severity=finding.severity,
621
+ text=f"{finding.title} {finding.path} {finding.flaw}",
622
+ fix=finding.fix,
623
+ )
624
+ return finding
625
+
626
+ pred = self.brain.predict(f"{finding.title} {finding.path} {finding.flaw} {finding.abuse}")
627
+ if pred is not None:
628
+ pred_domain, pred_sev, pred_fix = pred
629
+ finding.metadata["inferred_domain"] = pred_domain
630
+ finding.metadata.setdefault("domain", pred_domain)
631
+ if not finding.fix:
632
+ finding.fix = pred_fix
633
+ if finding.severity == "INFO" and pred_sev in ("WARN", "CRITICAL"):
634
+ finding.severity = "WARN"
635
+
636
+ self.brain.ingest_flaw_record(
637
+ domain=str(finding.metadata.get("domain", finding.category)),
638
+ severity=finding.severity,
639
+ text=f"{finding.title} {finding.path} {finding.flaw}",
640
+ fix=finding.fix,
641
+ )
642
+ return finding
643
+
644
+
645
+ @lru_cache(maxsize=1)
646
+ def get_catalog() -> FlawCatalog:
647
+ """Returns the cached singleton FlawCatalog instance with trained FlawBrain."""
648
+ cat = FlawCatalog(txt_path=FLAWS_TXT_PATH, cache_path=INDEX_CACHE_PATH, static_rules=STATIC_CODE_RULES)
649
+ cat.brain.train_from_corpus(cat, pack=get_debugger_pack())
650
+ return cat