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/client_bridge.py
ADDED
|
@@ -0,0 +1,776 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Client Runtime Bridge (rcdebug --client):
|
|
3
|
+
- Local HTTP & WebSocket listener on 127.0.0.1:8765
|
|
4
|
+
- Auto-copies Luau diagnostic & telemetry snippet to macOS clipboard via pbcopy
|
|
5
|
+
- Processes runtime security findings, Remote Traffic Profiler data, and 10s Instance/Memory Diffs
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import base64
|
|
11
|
+
import hashlib
|
|
12
|
+
import json
|
|
13
|
+
import re
|
|
14
|
+
import struct
|
|
15
|
+
import threading
|
|
16
|
+
import time
|
|
17
|
+
from datetime import datetime
|
|
18
|
+
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
from urllib.request import Request, urlopen
|
|
21
|
+
|
|
22
|
+
from .exporter import export_markdown_report
|
|
23
|
+
from .flaw_catalog import get_catalog
|
|
24
|
+
from .luau_payload import build_luau_bridge_script
|
|
25
|
+
from .models import AuditSession, Finding, MemorySnapshot, RemoteTrafficStat
|
|
26
|
+
from .terminal import (
|
|
27
|
+
BOLD,
|
|
28
|
+
CYAN,
|
|
29
|
+
DIM,
|
|
30
|
+
GREEN,
|
|
31
|
+
MAGENTA,
|
|
32
|
+
RED,
|
|
33
|
+
RESET,
|
|
34
|
+
WHITE,
|
|
35
|
+
YELLOW,
|
|
36
|
+
copy_to_clipboard,
|
|
37
|
+
normalize_filter_label,
|
|
38
|
+
print_banner,
|
|
39
|
+
print_finding,
|
|
40
|
+
print_memory_diff,
|
|
41
|
+
print_remote_traffic_update,
|
|
42
|
+
print_session_summary,
|
|
43
|
+
)
|
|
44
|
+
|
|
45
|
+
WS_MAGIC_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class RuntimeBridgeServer(ThreadingHTTPServer):
|
|
49
|
+
allow_reuse_address = True
|
|
50
|
+
|
|
51
|
+
def __init__(
|
|
52
|
+
self,
|
|
53
|
+
server_address: tuple[str, int],
|
|
54
|
+
handler_class: type[BaseHTTPRequestHandler],
|
|
55
|
+
session: AuditSession,
|
|
56
|
+
filter_level: str | None = None,
|
|
57
|
+
) -> None:
|
|
58
|
+
self.session = session
|
|
59
|
+
self.filter_level = filter_level
|
|
60
|
+
self.lock = threading.Lock()
|
|
61
|
+
try:
|
|
62
|
+
super().__init__(server_address, handler_class)
|
|
63
|
+
except Exception:
|
|
64
|
+
try:
|
|
65
|
+
self.server_close()
|
|
66
|
+
except Exception:
|
|
67
|
+
pass
|
|
68
|
+
raise
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def process_report_payload(
|
|
72
|
+
server: RuntimeBridgeServer,
|
|
73
|
+
payload: dict | list,
|
|
74
|
+
) -> int:
|
|
75
|
+
items = payload if isinstance(payload, list) else [payload]
|
|
76
|
+
catalog = get_catalog()
|
|
77
|
+
added_count = 0
|
|
78
|
+
with server.lock:
|
|
79
|
+
for item in items:
|
|
80
|
+
if not isinstance(item, dict):
|
|
81
|
+
continue
|
|
82
|
+
finding = Finding(
|
|
83
|
+
severity=str(item.get("severity", "INFO")),
|
|
84
|
+
title=str(item.get("title", "Security Finding")),
|
|
85
|
+
path=str(item.get("path", "Unknown")),
|
|
86
|
+
flaw=str(item.get("flaw", "")),
|
|
87
|
+
abuse=str(item.get("abuse", "")),
|
|
88
|
+
fix=str(item.get("fix", "")),
|
|
89
|
+
category=str(item.get("category", "RuntimeAudit")),
|
|
90
|
+
code_example=str(item.get("code_example", "")),
|
|
91
|
+
)
|
|
92
|
+
catalog.enrich_finding(finding)
|
|
93
|
+
if server.session.add_finding(finding):
|
|
94
|
+
added_count += 1
|
|
95
|
+
print_finding(finding, filter_level=server.filter_level)
|
|
96
|
+
return added_count
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def process_telemetry_payload(
|
|
100
|
+
server: RuntimeBridgeServer,
|
|
101
|
+
payload: dict,
|
|
102
|
+
) -> None:
|
|
103
|
+
with server.lock:
|
|
104
|
+
now_str = datetime.now().strftime("%H:%M:%S")
|
|
105
|
+
elapsed = float(payload.get("elapsed_sec", 0.0))
|
|
106
|
+
ws_inst = int(payload.get("workspace_instances", 0))
|
|
107
|
+
pl_inst = int(payload.get("player_instances", 0))
|
|
108
|
+
mem_mb = float(payload.get("total_memory_mb", 0.0))
|
|
109
|
+
|
|
110
|
+
prev_snap = (
|
|
111
|
+
server.session.memory_snapshots[-1]
|
|
112
|
+
if server.session.memory_snapshots
|
|
113
|
+
else None
|
|
114
|
+
)
|
|
115
|
+
curr_snap = MemorySnapshot(
|
|
116
|
+
timestamp=now_str,
|
|
117
|
+
elapsed_sec=elapsed,
|
|
118
|
+
workspace_instances=ws_inst,
|
|
119
|
+
player_instances=pl_inst,
|
|
120
|
+
total_memory_mb=mem_mb,
|
|
121
|
+
)
|
|
122
|
+
server.session.memory_snapshots.append(curr_snap)
|
|
123
|
+
print_memory_diff(prev_snap, curr_snap)
|
|
124
|
+
|
|
125
|
+
# Detect instance leak or memory spike between 10s snapshots
|
|
126
|
+
if prev_snap is not None:
|
|
127
|
+
ws_delta = curr_snap.workspace_instances - prev_snap.workspace_instances
|
|
128
|
+
pl_delta = curr_snap.player_instances - prev_snap.player_instances
|
|
129
|
+
mem_delta = curr_snap.total_memory_mb - prev_snap.total_memory_mb
|
|
130
|
+
|
|
131
|
+
if ws_delta >= 75 or mem_delta >= 20.0:
|
|
132
|
+
sev = "CRITICAL" if (ws_delta >= 200 or mem_delta >= 50.0) else "WARN"
|
|
133
|
+
leak_finding = Finding(
|
|
134
|
+
severity=sev,
|
|
135
|
+
category="MemoryDiff",
|
|
136
|
+
title=f"Instance / Memory Growth Spike (+{ws_delta} Workspace instances, {mem_delta:+.1f} MB)",
|
|
137
|
+
path="Workspace / Memory",
|
|
138
|
+
flaw=(
|
|
139
|
+
f"Between 10s snapshots ({prev_snap.timestamp} -> {curr_snap.timestamp}), "
|
|
140
|
+
f"Workspace grew by {ws_delta:+d} instances (Players {pl_delta:+d}) and "
|
|
141
|
+
f"total memory changed by {mem_delta:+.2f} MB."
|
|
142
|
+
),
|
|
143
|
+
abuse=(
|
|
144
|
+
"Uncleaned projectiles, VFX parts, or disconnected event connections cause progressive "
|
|
145
|
+
"server lag, replication choke, and eventual server crash."
|
|
146
|
+
),
|
|
147
|
+
fix=(
|
|
148
|
+
"Schedule transient instances for cleanup with Debris:AddItem(instance, lifetime), "
|
|
149
|
+
"pool high-frequency projectiles, and disconnect RBXScriptConnections on destroy."
|
|
150
|
+
),
|
|
151
|
+
code_example=(
|
|
152
|
+
'local Debris = game:GetService("Debris")\n'
|
|
153
|
+
"local fxPart = projectileTemplate:Clone()\n"
|
|
154
|
+
"fxPart.Parent = workspace.Effects\n"
|
|
155
|
+
"Debris:AddItem(fxPart, 3) -- Guaranteed cleanup after 3 seconds"
|
|
156
|
+
),
|
|
157
|
+
)
|
|
158
|
+
server.session.add_finding(leak_finding)
|
|
159
|
+
print_finding(leak_finding, filter_level=server.filter_level)
|
|
160
|
+
|
|
161
|
+
# Process Remote Traffic Profiler samples
|
|
162
|
+
remotes = payload.get("remotes", [])
|
|
163
|
+
if isinstance(remotes, list):
|
|
164
|
+
for rem in remotes:
|
|
165
|
+
if not isinstance(rem, dict):
|
|
166
|
+
continue
|
|
167
|
+
rpath = str(rem.get("remote_path", "UnknownRemote"))
|
|
168
|
+
rtype = str(rem.get("remote_type", "RemoteEvent"))
|
|
169
|
+
total_calls = int(rem.get("total_calls", 0))
|
|
170
|
+
rate = float(rem.get("rate_per_sec", 0.0))
|
|
171
|
+
|
|
172
|
+
stat = server.session.remote_traffic.get(rpath)
|
|
173
|
+
if stat is None:
|
|
174
|
+
stat = RemoteTrafficStat(remote_path=rpath, remote_type=rtype)
|
|
175
|
+
server.session.remote_traffic[rpath] = stat
|
|
176
|
+
|
|
177
|
+
stat.total_calls = total_calls
|
|
178
|
+
stat.last_rate_per_sec = rate
|
|
179
|
+
if rate > stat.peak_rate_per_sec:
|
|
180
|
+
stat.peak_rate_per_sec = rate
|
|
181
|
+
|
|
182
|
+
if rate > 0:
|
|
183
|
+
print_remote_traffic_update(rpath, rate, total_calls)
|
|
184
|
+
|
|
185
|
+
if rate >= 12.0 and not stat.has_cooldown_warning:
|
|
186
|
+
stat.has_cooldown_warning = True
|
|
187
|
+
sev = "CRITICAL" if rate >= 25.0 else "WARN"
|
|
188
|
+
spam_finding = Finding(
|
|
189
|
+
severity=sev,
|
|
190
|
+
category="RemoteTraffic",
|
|
191
|
+
title=f"Unthrottled Remote Traffic ({rate:.1f} calls/sec): {rpath}",
|
|
192
|
+
path=rpath,
|
|
193
|
+
flaw=(
|
|
194
|
+
f"Remote '{rpath}' is firing at {rate:.1f} calls/sec "
|
|
195
|
+
f"(total {total_calls} calls) without effective server-side rate limiting."
|
|
196
|
+
),
|
|
197
|
+
abuse=(
|
|
198
|
+
"Exploiters can fire this remote hundreds of times per frame to exhaust server CPU, "
|
|
199
|
+
"flood replication queues, or exploit non-atomic datastore/currency operations."
|
|
200
|
+
),
|
|
201
|
+
fix=(
|
|
202
|
+
"Add a per-player rate limiter (os.clock() cooldown map or token bucket) at the very "
|
|
203
|
+
"start of OnServerEvent before performing any workspace, table, or datastore work."
|
|
204
|
+
),
|
|
205
|
+
code_example=(
|
|
206
|
+
"local COOLDOWN = 0.25\n"
|
|
207
|
+
"local lastCall: {[Player]: number} = {}\n"
|
|
208
|
+
"Players.PlayerRemoving:Connect(function(plr) lastCall[plr] = nil end)\n\n"
|
|
209
|
+
"remote.OnServerEvent:Connect(function(plr, ...)\n"
|
|
210
|
+
" local now = os.clock()\n"
|
|
211
|
+
" if now - (lastCall[plr] or 0) < COOLDOWN then return end\n"
|
|
212
|
+
" lastCall[plr] = now\n"
|
|
213
|
+
" -- Safe to process request\n"
|
|
214
|
+
"end)"
|
|
215
|
+
),
|
|
216
|
+
)
|
|
217
|
+
server.session.add_finding(spam_finding)
|
|
218
|
+
print_finding(spam_finding, filter_level=server.filter_level)
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
class DebugReportHandler(BaseHTTPRequestHandler):
|
|
222
|
+
server: RuntimeBridgeServer # type annotation for IDE/typechecker
|
|
223
|
+
|
|
224
|
+
def log_message(self, format: str, *args: object) -> None:
|
|
225
|
+
# Suppress default HTTP access logs for clean terminal dashboard output
|
|
226
|
+
pass
|
|
227
|
+
|
|
228
|
+
def _send_json(self, status_code: int, data: dict) -> None:
|
|
229
|
+
body = json.dumps(data).encode("utf-8")
|
|
230
|
+
self.send_response(status_code)
|
|
231
|
+
self.send_header("Content-Type", "application/json")
|
|
232
|
+
self.send_header("Content-Length", str(len(body)))
|
|
233
|
+
self.end_headers()
|
|
234
|
+
self.wfile.write(body)
|
|
235
|
+
|
|
236
|
+
def do_GET(self) -> None:
|
|
237
|
+
# Check if client requested a WebSocket upgrade
|
|
238
|
+
upgrade = self.headers.get("Upgrade", "").lower()
|
|
239
|
+
if upgrade == "websocket":
|
|
240
|
+
self._handle_websocket()
|
|
241
|
+
return
|
|
242
|
+
|
|
243
|
+
if self.path in ("/", "/status", "/health"):
|
|
244
|
+
counts = self.server.session.counts_by_severity()
|
|
245
|
+
self._send_json(
|
|
246
|
+
200,
|
|
247
|
+
{
|
|
248
|
+
"status": "ok",
|
|
249
|
+
"tool": "rcdebug",
|
|
250
|
+
"mode": self.server.session.mode,
|
|
251
|
+
"findings_count": len(self.server.session.findings),
|
|
252
|
+
"severity_counts": counts,
|
|
253
|
+
"snapshots_count": len(self.server.session.memory_snapshots),
|
|
254
|
+
"remotes_profiled": len(self.server.session.remote_traffic),
|
|
255
|
+
},
|
|
256
|
+
)
|
|
257
|
+
return
|
|
258
|
+
|
|
259
|
+
self._send_json(404, {"error": "not_found"})
|
|
260
|
+
|
|
261
|
+
def do_POST(self) -> None:
|
|
262
|
+
content_length = int(self.headers.get("Content-Length", 0))
|
|
263
|
+
raw_body = self.rfile.read(content_length).decode("utf-8", errors="replace")
|
|
264
|
+
|
|
265
|
+
try:
|
|
266
|
+
data = json.loads(raw_body) if raw_body else {}
|
|
267
|
+
except json.JSONDecodeError:
|
|
268
|
+
self._send_json(400, {"error": "invalid_json"})
|
|
269
|
+
return
|
|
270
|
+
|
|
271
|
+
if self.path == "/report":
|
|
272
|
+
added = process_report_payload(self.server, data)
|
|
273
|
+
self._send_json(200, {"status": "ok", "added": added})
|
|
274
|
+
elif self.path == "/telemetry":
|
|
275
|
+
if isinstance(data, dict):
|
|
276
|
+
process_telemetry_payload(self.server, data)
|
|
277
|
+
self._send_json(200, {"status": "ok"})
|
|
278
|
+
else:
|
|
279
|
+
self._send_json(400, {"error": "expected_object"})
|
|
280
|
+
elif self.path == "/shutdown":
|
|
281
|
+
self._send_json(200, {"status": "shutting_down"})
|
|
282
|
+
threading.Thread(target=self.server.shutdown, daemon=True).start()
|
|
283
|
+
else:
|
|
284
|
+
self._send_json(404, {"error": "not_found"})
|
|
285
|
+
|
|
286
|
+
def _handle_websocket(self) -> None:
|
|
287
|
+
"""Minimal RFC 6455 WebSocket handler for Studio WebSocket streams."""
|
|
288
|
+
ws_key = self.headers.get("Sec-WebSocket-Key", "")
|
|
289
|
+
if not ws_key:
|
|
290
|
+
self.send_response(400)
|
|
291
|
+
self.end_headers()
|
|
292
|
+
return
|
|
293
|
+
|
|
294
|
+
accept_raw = hashlib.sha1((ws_key + WS_MAGIC_GUID).encode("utf-8")).digest()
|
|
295
|
+
accept_key = base64.b64encode(accept_raw).decode("utf-8")
|
|
296
|
+
|
|
297
|
+
self.send_response(101, "Switching Protocols")
|
|
298
|
+
self.send_header("Upgrade", "websocket")
|
|
299
|
+
self.send_header("Connection", "Upgrade")
|
|
300
|
+
self.send_header("Sec-WebSocket-Accept", accept_key)
|
|
301
|
+
self.end_headers()
|
|
302
|
+
|
|
303
|
+
while True:
|
|
304
|
+
try:
|
|
305
|
+
header = self.rfile.read(2)
|
|
306
|
+
if not header or len(header) < 2:
|
|
307
|
+
break
|
|
308
|
+
b1, b2 = header[0], header[1]
|
|
309
|
+
opcode = b1 & 0x0F
|
|
310
|
+
if opcode == 0x8: # Close frame
|
|
311
|
+
break
|
|
312
|
+
masked = bool(b2 & 0x80)
|
|
313
|
+
payload_len = b2 & 0x7F
|
|
314
|
+
if payload_len == 126:
|
|
315
|
+
ext = self.rfile.read(2)
|
|
316
|
+
payload_len = struct.unpack(">H", ext)[0]
|
|
317
|
+
elif payload_len == 127:
|
|
318
|
+
ext = self.rfile.read(8)
|
|
319
|
+
payload_len = struct.unpack(">Q", ext)[0]
|
|
320
|
+
|
|
321
|
+
mask_key = self.rfile.read(4) if masked else b""
|
|
322
|
+
payload_bytes = bytearray(self.rfile.read(payload_len))
|
|
323
|
+
if masked and mask_key:
|
|
324
|
+
for i in range(len(payload_bytes)):
|
|
325
|
+
payload_bytes[i] ^= mask_key[i % 4]
|
|
326
|
+
|
|
327
|
+
text = payload_bytes.decode("utf-8", errors="replace")
|
|
328
|
+
msg = json.loads(text)
|
|
329
|
+
if isinstance(msg, dict) and "workspace_instances" in msg:
|
|
330
|
+
process_telemetry_payload(self.server, msg)
|
|
331
|
+
else:
|
|
332
|
+
process_report_payload(self.server, msg)
|
|
333
|
+
except Exception:
|
|
334
|
+
break
|
|
335
|
+
|
|
336
|
+
|
|
337
|
+
ROBLOX_LOGS_DIR = Path.home() / "Library" / "Logs" / "Roblox"
|
|
338
|
+
|
|
339
|
+
_WIRE_REPORT_RE = re.compile(r"\[rcdebug-wire:report\]\s+(\{.*\})\s*$")
|
|
340
|
+
_WIRE_TELEMETRY_RE = re.compile(r"\[rcdebug-wire:telemetry\]\s+(\{.*\})\s*$")
|
|
341
|
+
_CONSOLE_FINDING_RE = re.compile(
|
|
342
|
+
r"\[rcdebug-console\]\s+\[(CRITICAL|WARN|INFO)\]\s+\[([^\]]+)\]\s+(.+?)\s+\|\s+(.+?)\s*$"
|
|
343
|
+
)
|
|
344
|
+
_CONSOLE_TELEMETRY_RE = re.compile(
|
|
345
|
+
r"\[rcdebug-console\]\s+t=([\d.]+)s\s+\|\s+Workspace=(\d+)\s+\|\s+(?:LocalPlayer|Players)=(\d+)\s+\|\s+Mem=([\d.]+)\s+MB"
|
|
346
|
+
)
|
|
347
|
+
|
|
348
|
+
|
|
349
|
+
def ingest_log_line(server: RuntimeBridgeServer, line: str) -> bool:
|
|
350
|
+
"""
|
|
351
|
+
Parses a single Roblox log line for rcdebug wire JSON or console fallback messages
|
|
352
|
+
and dispatches them to the active RuntimeBridgeServer session.
|
|
353
|
+
Returns True if the line was handled.
|
|
354
|
+
"""
|
|
355
|
+
if "[rcdebug" not in line:
|
|
356
|
+
return False
|
|
357
|
+
|
|
358
|
+
m_rep = _WIRE_REPORT_RE.search(line)
|
|
359
|
+
if m_rep:
|
|
360
|
+
try:
|
|
361
|
+
data = json.loads(m_rep.group(1))
|
|
362
|
+
process_report_payload(server, data)
|
|
363
|
+
return True
|
|
364
|
+
except json.JSONDecodeError:
|
|
365
|
+
pass
|
|
366
|
+
|
|
367
|
+
m_tel = _WIRE_TELEMETRY_RE.search(line)
|
|
368
|
+
if m_tel:
|
|
369
|
+
try:
|
|
370
|
+
data = json.loads(m_tel.group(1))
|
|
371
|
+
if isinstance(data, dict):
|
|
372
|
+
process_telemetry_payload(server, data)
|
|
373
|
+
return True
|
|
374
|
+
except json.JSONDecodeError:
|
|
375
|
+
pass
|
|
376
|
+
|
|
377
|
+
m_cf = _CONSOLE_FINDING_RE.search(line)
|
|
378
|
+
if m_cf:
|
|
379
|
+
sev, cat, title, path = m_cf.groups()
|
|
380
|
+
process_report_payload(
|
|
381
|
+
server,
|
|
382
|
+
{
|
|
383
|
+
"severity": sev,
|
|
384
|
+
"category": cat,
|
|
385
|
+
"title": title,
|
|
386
|
+
"path": path,
|
|
387
|
+
"flaw": f"Detected via Roblox Client Console ({cat}) on {path}.",
|
|
388
|
+
"abuse": "Client-exposed state, remote, or unanchored physics surface can be manipulated locally.",
|
|
389
|
+
"fix": "Enforce server-authoritative validation, cooldowns, and ServerScriptService state.",
|
|
390
|
+
},
|
|
391
|
+
)
|
|
392
|
+
return True
|
|
393
|
+
|
|
394
|
+
m_ct = _CONSOLE_TELEMETRY_RE.search(line)
|
|
395
|
+
if m_ct:
|
|
396
|
+
elapsed, ws_inst, pl_inst, mem_mb = m_ct.groups()
|
|
397
|
+
process_telemetry_payload(
|
|
398
|
+
server,
|
|
399
|
+
{
|
|
400
|
+
"elapsed_sec": float(elapsed),
|
|
401
|
+
"workspace_instances": int(ws_inst),
|
|
402
|
+
"player_instances": int(pl_inst),
|
|
403
|
+
"total_memory_mb": float(mem_mb),
|
|
404
|
+
"remotes": [],
|
|
405
|
+
},
|
|
406
|
+
)
|
|
407
|
+
return True
|
|
408
|
+
|
|
409
|
+
return False
|
|
410
|
+
|
|
411
|
+
|
|
412
|
+
class RobloxLogTailer:
|
|
413
|
+
"""
|
|
414
|
+
Tails active Roblox Player & Studio log files on macOS (~/Library/Logs/Roblox/)
|
|
415
|
+
so 100% client-sided scripts stream seamlessly to the terminal even when
|
|
416
|
+
Roblox restricts HttpService.PostAsync inside live Client contexts.
|
|
417
|
+
"""
|
|
418
|
+
|
|
419
|
+
def __init__(
|
|
420
|
+
self,
|
|
421
|
+
server: RuntimeBridgeServer,
|
|
422
|
+
log_dir: Path = ROBLOX_LOGS_DIR,
|
|
423
|
+
replay_latest: bool = False,
|
|
424
|
+
poll_interval: float = 0.2,
|
|
425
|
+
) -> None:
|
|
426
|
+
self.server = server
|
|
427
|
+
self.log_dir = log_dir
|
|
428
|
+
self.replay_latest = replay_latest
|
|
429
|
+
self.poll_interval = poll_interval
|
|
430
|
+
self._stop_event = threading.Event()
|
|
431
|
+
self._offsets: dict[Path, int] = {}
|
|
432
|
+
self._thread: threading.Thread | None = None
|
|
433
|
+
|
|
434
|
+
def _candidate_logs(self) -> list[Path]:
|
|
435
|
+
if not self.log_dir.exists():
|
|
436
|
+
return []
|
|
437
|
+
files = []
|
|
438
|
+
for p in self.log_dir.iterdir():
|
|
439
|
+
if not p.is_file() or not p.name.endswith("_last.log"):
|
|
440
|
+
continue
|
|
441
|
+
if "CrashHandler" in p.name:
|
|
442
|
+
continue
|
|
443
|
+
if "_Player_" in p.name or "_Studio_" in p.name:
|
|
444
|
+
files.append(p)
|
|
445
|
+
files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
|
|
446
|
+
return files
|
|
447
|
+
|
|
448
|
+
def _init_offsets(self) -> None:
|
|
449
|
+
candidates = self._candidate_logs()
|
|
450
|
+
for idx, path in enumerate(candidates):
|
|
451
|
+
try:
|
|
452
|
+
if self.replay_latest and idx == 0:
|
|
453
|
+
self._offsets[path] = 0
|
|
454
|
+
else:
|
|
455
|
+
self._offsets[path] = path.stat().st_size
|
|
456
|
+
except OSError:
|
|
457
|
+
continue
|
|
458
|
+
|
|
459
|
+
def poll_once(self) -> int:
|
|
460
|
+
processed = 0
|
|
461
|
+
for path in self._candidate_logs():
|
|
462
|
+
try:
|
|
463
|
+
size = path.stat().st_size
|
|
464
|
+
except OSError:
|
|
465
|
+
continue
|
|
466
|
+
|
|
467
|
+
if path not in self._offsets:
|
|
468
|
+
# Newly created log file after rcdebug started -> read from byte 0
|
|
469
|
+
self._offsets[path] = 0
|
|
470
|
+
elif size < self._offsets[path]:
|
|
471
|
+
# File rotated/truncated
|
|
472
|
+
self._offsets[path] = 0
|
|
473
|
+
|
|
474
|
+
offset = self._offsets[path]
|
|
475
|
+
if size <= offset:
|
|
476
|
+
continue
|
|
477
|
+
|
|
478
|
+
try:
|
|
479
|
+
with path.open("r", encoding="utf-8", errors="replace") as fh:
|
|
480
|
+
fh.seek(offset)
|
|
481
|
+
chunk = fh.read()
|
|
482
|
+
self._offsets[path] = fh.tell()
|
|
483
|
+
except OSError:
|
|
484
|
+
continue
|
|
485
|
+
|
|
486
|
+
for line in chunk.splitlines():
|
|
487
|
+
if ingest_log_line(self.server, line):
|
|
488
|
+
processed += 1
|
|
489
|
+
return processed
|
|
490
|
+
|
|
491
|
+
def start(self) -> None:
|
|
492
|
+
self._init_offsets()
|
|
493
|
+
if self.replay_latest:
|
|
494
|
+
self.poll_once()
|
|
495
|
+
self._thread = threading.Thread(target=self._run_loop, daemon=True)
|
|
496
|
+
self._thread.start()
|
|
497
|
+
|
|
498
|
+
def _run_loop(self) -> None:
|
|
499
|
+
while not self._stop_event.is_set():
|
|
500
|
+
self.poll_once()
|
|
501
|
+
self._stop_event.wait(self.poll_interval)
|
|
502
|
+
|
|
503
|
+
def stop(self) -> None:
|
|
504
|
+
self._stop_event.set()
|
|
505
|
+
if self._thread and self._thread.is_alive():
|
|
506
|
+
self._thread.join(timeout=1.0)
|
|
507
|
+
|
|
508
|
+
|
|
509
|
+
def simulate_studio_playtest_traffic(host: str, port: int) -> None:
|
|
510
|
+
"""
|
|
511
|
+
Sends realistic synthetic Roblox Studio playtest findings and telemetry snapshots
|
|
512
|
+
to the local rcdebug listener (used when --simulate is passed).
|
|
513
|
+
"""
|
|
514
|
+
time.sleep(0.35)
|
|
515
|
+
report_url = f"http://{host}:{port}/report"
|
|
516
|
+
telemetry_url = f"http://{host}:{port}/telemetry"
|
|
517
|
+
|
|
518
|
+
def post(url: str, data: dict | list) -> None:
|
|
519
|
+
req = Request(
|
|
520
|
+
url,
|
|
521
|
+
data=json.dumps(data).encode("utf-8"),
|
|
522
|
+
headers={"Content-Type": "application/json"},
|
|
523
|
+
method="POST",
|
|
524
|
+
)
|
|
525
|
+
with urlopen(req, timeout=3) as resp:
|
|
526
|
+
resp.read()
|
|
527
|
+
|
|
528
|
+
sample_findings = [
|
|
529
|
+
{
|
|
530
|
+
"severity": "CRITICAL",
|
|
531
|
+
"category": "StateReplication",
|
|
532
|
+
"title": "Sensitive IntValue in Character: Cash",
|
|
533
|
+
"path": "Workspace.Player1.Cash",
|
|
534
|
+
"flaw": "Gameplay state ('cash') is stored in an IntValue parented inside the player's Character model.",
|
|
535
|
+
"abuse": (
|
|
536
|
+
"Because the Character model is subject to client physics/replication quirks and often read by poorly "
|
|
537
|
+
"written scripts, storing currency in Character allows tampering or state desync on respawn."
|
|
538
|
+
),
|
|
539
|
+
"fix": "Move authoritative currency state into a ServerScriptService module table and expose read-only Attributes on Player.",
|
|
540
|
+
"code_example": (
|
|
541
|
+
"local Balances: {[number]: number} = {}\n"
|
|
542
|
+
"function AddCash(player: Player, delta: number)\n"
|
|
543
|
+
" Balances[player.UserId] = (Balances[player.UserId] or 0) + delta\n"
|
|
544
|
+
' player:SetAttribute("Cash", Balances[player.UserId])\n'
|
|
545
|
+
"end"
|
|
546
|
+
),
|
|
547
|
+
},
|
|
548
|
+
{
|
|
549
|
+
"severity": "WARN",
|
|
550
|
+
"category": "RemoteSecurity",
|
|
551
|
+
"title": "High-Value Network Endpoint: GiveCashRemote (matched 'cash')",
|
|
552
|
+
"path": "ReplicatedStorage.Remotes.GiveCashRemote",
|
|
553
|
+
"flaw": "RemoteEvent name suggests privileged currency mutation accessible to all clients.",
|
|
554
|
+
"abuse": "Malicious clients can fire GiveCashRemote:FireServer(999999999) or pass negative values to drain/mint currency.",
|
|
555
|
+
"fix": "Remove direct reward remotes; calculate rewards strictly inside server-side objective/combat completion handlers.",
|
|
556
|
+
"code_example": (
|
|
557
|
+
"-- Do NOT let clients request arbitrary currency.\n"
|
|
558
|
+
"-- Award currency on the server only when a verified server event completes."
|
|
559
|
+
),
|
|
560
|
+
},
|
|
561
|
+
{
|
|
562
|
+
"severity": "WARN",
|
|
563
|
+
"category": "NetworkOwnership",
|
|
564
|
+
"title": "Unanchored Part with Client/Auto NetworkOwnership: VaultDoor",
|
|
565
|
+
"path": "Workspace.BankLevel.VaultDoor",
|
|
566
|
+
"flaw": "Unanchored interactive BasePart allows automatic client physics ownership (Current Owner: Auto).",
|
|
567
|
+
"abuse": "Exploiters standing near VaultDoor gain physics authority and can set its CFrame to bypass locked barriers.",
|
|
568
|
+
"fix": "Anchor the door and animate via server TweenService, or lock physics authority to the server via part:SetNetworkOwner(nil).",
|
|
569
|
+
"code_example": "workspace.BankLevel.VaultDoor:SetNetworkOwner(nil)",
|
|
570
|
+
},
|
|
571
|
+
{
|
|
572
|
+
"severity": "INFO",
|
|
573
|
+
"category": "RemoteSecurity",
|
|
574
|
+
"title": "Exposed Network Endpoint: SprintToggle",
|
|
575
|
+
"path": "ReplicatedStorage.Remotes.SprintToggle",
|
|
576
|
+
"flaw": "Client-accessible RemoteEvent found in ReplicatedStorage.",
|
|
577
|
+
"abuse": "Clients can fire SprintToggle with non-boolean payloads or spam it every frame.",
|
|
578
|
+
"fix": "Validate typeof(isSprinting) == 'boolean' and enforce a 0.15s per-player debounce on the server.",
|
|
579
|
+
},
|
|
580
|
+
]
|
|
581
|
+
|
|
582
|
+
for f in sample_findings:
|
|
583
|
+
post(report_url, f)
|
|
584
|
+
time.sleep(0.1)
|
|
585
|
+
|
|
586
|
+
# Send baseline telemetry snapshot
|
|
587
|
+
post(
|
|
588
|
+
telemetry_url,
|
|
589
|
+
{
|
|
590
|
+
"elapsed_sec": 0.0,
|
|
591
|
+
"workspace_instances": 1420,
|
|
592
|
+
"player_instances": 85,
|
|
593
|
+
"total_memory_mb": 412.5,
|
|
594
|
+
"remotes": [
|
|
595
|
+
{
|
|
596
|
+
"remote_path": "ReplicatedStorage.Remotes.SprintToggle",
|
|
597
|
+
"remote_type": "RemoteEvent",
|
|
598
|
+
"total_calls": 4,
|
|
599
|
+
"rate_per_sec": 0.4,
|
|
600
|
+
}
|
|
601
|
+
],
|
|
602
|
+
},
|
|
603
|
+
)
|
|
604
|
+
time.sleep(0.15)
|
|
605
|
+
|
|
606
|
+
# Send 10s snapshot with simulated remote spam & uncleaned debris spike
|
|
607
|
+
post(
|
|
608
|
+
telemetry_url,
|
|
609
|
+
{
|
|
610
|
+
"elapsed_sec": 10.0,
|
|
611
|
+
"workspace_instances": 1665,
|
|
612
|
+
"player_instances": 92,
|
|
613
|
+
"total_memory_mb": 448.2,
|
|
614
|
+
"remotes": [
|
|
615
|
+
{
|
|
616
|
+
"remote_path": "ReplicatedStorage.Remotes.GiveCashRemote",
|
|
617
|
+
"remote_type": "RemoteEvent",
|
|
618
|
+
"total_calls": 340,
|
|
619
|
+
"rate_per_sec": 34.0,
|
|
620
|
+
}
|
|
621
|
+
],
|
|
622
|
+
},
|
|
623
|
+
)
|
|
624
|
+
|
|
625
|
+
|
|
626
|
+
def _try_reclaim_rcdebug_port(host: str, port: int) -> bool:
|
|
627
|
+
"""If an older rcdebug listener is holding `host:port`, request a clean shutdown."""
|
|
628
|
+
try:
|
|
629
|
+
with urlopen(f"http://{host}:{port}/status", timeout=0.4) as resp:
|
|
630
|
+
info = json.loads(resp.read().decode("utf-8", errors="replace"))
|
|
631
|
+
if isinstance(info, dict) and info.get("tool") == "rcdebug":
|
|
632
|
+
req = Request(f"http://{host}:{port}/shutdown", data=b"{}", method="POST")
|
|
633
|
+
with urlopen(req, timeout=0.5) as sresp:
|
|
634
|
+
sresp.read()
|
|
635
|
+
time.sleep(0.15)
|
|
636
|
+
return True
|
|
637
|
+
except Exception:
|
|
638
|
+
pass
|
|
639
|
+
return False
|
|
640
|
+
|
|
641
|
+
|
|
642
|
+
def bind_runtime_bridge_server(
|
|
643
|
+
host: str,
|
|
644
|
+
preferred_port: int,
|
|
645
|
+
session: AuditSession,
|
|
646
|
+
filter_level: str | None = None,
|
|
647
|
+
max_tries: int = 50,
|
|
648
|
+
) -> tuple[RuntimeBridgeServer, int, bool]:
|
|
649
|
+
"""
|
|
650
|
+
Binds RuntimeBridgeServer to `preferred_port`. If another process (such as
|
|
651
|
+
MacSploit or another service) is already holding `preferred_port`, automatically
|
|
652
|
+
selects the next available port so `--client` never crashes with Errno 48.
|
|
653
|
+
"""
|
|
654
|
+
try:
|
|
655
|
+
srv = RuntimeBridgeServer((host, preferred_port), DebugReportHandler, session=session, filter_level=filter_level)
|
|
656
|
+
return srv, int(srv.server_address[1]), False
|
|
657
|
+
except OSError:
|
|
658
|
+
if _try_reclaim_rcdebug_port(host, preferred_port):
|
|
659
|
+
try:
|
|
660
|
+
srv = RuntimeBridgeServer((host, preferred_port), DebugReportHandler, session=session, filter_level=filter_level)
|
|
661
|
+
return srv, int(srv.server_address[1]), False
|
|
662
|
+
except OSError:
|
|
663
|
+
pass
|
|
664
|
+
|
|
665
|
+
for offset in range(1, max_tries + 1):
|
|
666
|
+
candidate = preferred_port + offset
|
|
667
|
+
if candidate > 65535:
|
|
668
|
+
break
|
|
669
|
+
try:
|
|
670
|
+
srv = RuntimeBridgeServer((host, candidate), DebugReportHandler, session=session, filter_level=filter_level)
|
|
671
|
+
return srv, int(srv.server_address[1]), True
|
|
672
|
+
except OSError:
|
|
673
|
+
continue
|
|
674
|
+
|
|
675
|
+
srv = RuntimeBridgeServer((host, 0), DebugReportHandler, session=session, filter_level=filter_level)
|
|
676
|
+
return srv, int(srv.server_address[1]), True
|
|
677
|
+
|
|
678
|
+
|
|
679
|
+
def run_client_mode(
|
|
680
|
+
host: str = "127.0.0.1",
|
|
681
|
+
port: int = 8765,
|
|
682
|
+
filter_level: str | None = None,
|
|
683
|
+
export_path: str | None = None,
|
|
684
|
+
auto_clipboard: bool = True,
|
|
685
|
+
simulate: bool = False,
|
|
686
|
+
enable_log_tail: bool = True,
|
|
687
|
+
replay_latest_log: bool = False,
|
|
688
|
+
) -> AuditSession:
|
|
689
|
+
catalog = get_catalog()
|
|
690
|
+
session = AuditSession(
|
|
691
|
+
mode="client",
|
|
692
|
+
target_name=f"Roblox Client Runtime Bridge ({host}:{port})",
|
|
693
|
+
)
|
|
694
|
+
server, actual_port, used_fallback = bind_runtime_bridge_server(
|
|
695
|
+
host=host,
|
|
696
|
+
preferred_port=port,
|
|
697
|
+
session=session,
|
|
698
|
+
filter_level=filter_level,
|
|
699
|
+
)
|
|
700
|
+
session.target_name = f"Roblox Client Runtime Bridge ({host}:{actual_port})"
|
|
701
|
+
|
|
702
|
+
print_banner(
|
|
703
|
+
"CLIENT RUNTIME BRIDGE",
|
|
704
|
+
subtitle=f"HTTP/WS ({host}:{actual_port}) + Log Bridge | {catalog.count():,} Flaw Signatures | Filter: {normalize_filter_label(filter_level)}",
|
|
705
|
+
)
|
|
706
|
+
if used_fallback:
|
|
707
|
+
print(
|
|
708
|
+
f"\n{YELLOW}{BOLD}⚠ Port {port} is in use by another process; "
|
|
709
|
+
f"automatically bound to {host}:{actual_port}.{RESET}"
|
|
710
|
+
)
|
|
711
|
+
|
|
712
|
+
luau_script = build_luau_bridge_script(host=host, port=actual_port)
|
|
713
|
+
|
|
714
|
+
if auto_clipboard:
|
|
715
|
+
copied = copy_to_clipboard(luau_script)
|
|
716
|
+
if copied:
|
|
717
|
+
print(f"\n{GREEN}{BOLD}✔ Luau diagnostic snippet automatically copied to macOS clipboard (pbcopy)!{RESET}")
|
|
718
|
+
print(f" {WHITE}Paste ({BOLD}Cmd+V{RESET}{WHITE}) into Roblox Client / Studio Command Bar.{RESET}")
|
|
719
|
+
else:
|
|
720
|
+
print(f"\n{YELLOW}⚠ Could not copy to clipboard automatically; copy the snippet below.{RESET}")
|
|
721
|
+
|
|
722
|
+
print(f"\n{YELLOW}{BOLD}─── Luau Diagnostic & Telemetry Bridge Snippet ───{RESET}")
|
|
723
|
+
print(f"{DIM}{luau_script.strip()}{RESET}")
|
|
724
|
+
print(f"{YELLOW}{BOLD}──────────────────────────────────────────────────{RESET}\n")
|
|
725
|
+
|
|
726
|
+
print(
|
|
727
|
+
f"{BOLD}{GREEN}● Listening for telemetry on{RESET} "
|
|
728
|
+
f"{BOLD}{CYAN}http://{host}:{actual_port}/report{RESET} & {BOLD}{CYAN}ws://{host}:{actual_port}/ws{RESET}"
|
|
729
|
+
)
|
|
730
|
+
|
|
731
|
+
log_tailer: RobloxLogTailer | None = None
|
|
732
|
+
if enable_log_tail and not simulate:
|
|
733
|
+
log_tailer = RobloxLogTailer(server, replay_latest=replay_latest_log)
|
|
734
|
+
log_tailer.start()
|
|
735
|
+
print(
|
|
736
|
+
f"{BOLD}{GREEN}● Roblox Log Bridge active — tailing{RESET} "
|
|
737
|
+
f"{BOLD}{CYAN}{ROBLOX_LOGS_DIR}{RESET}"
|
|
738
|
+
)
|
|
739
|
+
|
|
740
|
+
print(f"{DIM} Press Ctrl+C to stop listener and finalize session report.{RESET}")
|
|
741
|
+
|
|
742
|
+
if simulate:
|
|
743
|
+
print(f"\n{MAGENTA}{BOLD}[SIMULATION MODE]{RESET} Injecting sample playtest findings & 10s telemetry snapshots...")
|
|
744
|
+
sim_thread = threading.Thread(target=simulate_studio_playtest_traffic, args=(host, actual_port), daemon=True)
|
|
745
|
+
sim_thread.start()
|
|
746
|
+
|
|
747
|
+
def auto_stop() -> None:
|
|
748
|
+
sim_thread.join(timeout=5.0)
|
|
749
|
+
time.sleep(0.25)
|
|
750
|
+
server.shutdown()
|
|
751
|
+
|
|
752
|
+
threading.Thread(target=auto_stop, daemon=True).start()
|
|
753
|
+
|
|
754
|
+
try:
|
|
755
|
+
server.serve_forever()
|
|
756
|
+
except KeyboardInterrupt:
|
|
757
|
+
print(f"\n{YELLOW}[rcdebug] Stopping Client Runtime Bridge listener...{RESET}")
|
|
758
|
+
finally:
|
|
759
|
+
if log_tailer is not None:
|
|
760
|
+
log_tailer.stop()
|
|
761
|
+
server.server_close()
|
|
762
|
+
|
|
763
|
+
print_session_summary(session, filter_level=filter_level)
|
|
764
|
+
|
|
765
|
+
if session.findings:
|
|
766
|
+
learned_new = catalog.learner.learn_from_session(session, catalog)
|
|
767
|
+
print(
|
|
768
|
+
f"{GREEN}{BOLD}✔ Adaptive Learner:{RESET} +{learned_new} new pattern(s) learned "
|
|
769
|
+
f"({len(catalog.learner.learned_tokens)} total) -> {CYAN}{catalog.learner.store_path}{RESET}"
|
|
770
|
+
)
|
|
771
|
+
|
|
772
|
+
if export_path:
|
|
773
|
+
saved_file = export_markdown_report(session, export_path, filter_level=filter_level)
|
|
774
|
+
print(f"{GREEN}{BOLD}✔ Exported Markdown audit report to:{RESET} {CYAN}{saved_file}{RESET}\n")
|
|
775
|
+
|
|
776
|
+
return session
|