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.
- rcdebug/__init__.py +7 -0
- rcdebug/cli.py +475 -0
- rcdebug/client_bridge.py +776 -0
- rcdebug/data/flaws_120000.txt +4 -0
- rcdebug/data/luau_debugger_pack_120.json +1202 -0
- rcdebug/debugger_pack.py +115 -0
- rcdebug/exporter.py +135 -0
- rcdebug/flaw_catalog.py +650 -0
- rcdebug/github_harvester.py +181 -0
- rcdebug/learner.py +745 -0
- rcdebug/luau_payload.py +505 -0
- rcdebug/mcp_inspector.py +796 -0
- rcdebug/models.py +146 -0
- rcdebug/terminal.py +161 -0
- rcdebug-1.0.0.dist-info/METADATA +171 -0
- rcdebug-1.0.0.dist-info/RECORD +20 -0
- rcdebug-1.0.0.dist-info/WHEEL +5 -0
- rcdebug-1.0.0.dist-info/entry_points.txt +2 -0
- rcdebug-1.0.0.dist-info/licenses/LICENSE +21 -0
- rcdebug-1.0.0.dist-info/top_level.txt +1 -0
rcdebug/flaw_catalog.py
ADDED
|
@@ -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
|