rcdebug 1.0.0__tar.gz

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,111 @@
1
+ # rcdebug Architecture Reference
2
+
3
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
4
+ [![Flaw Corpus](https://img.shields.io/badge/corpus-120%2C000_flaws-E11D48?style=flat-square)](rcdebug/data/flaws_120000.txt)
5
+ [![Debugger Pack](https://img.shields.io/badge/probes-120_luau_rules-F59E0B?style=flat-square)](rcdebug/data/luau_debugger_pack_120.json)
6
+ [![Lookup Latency](https://img.shields.io/badge/lookup-%3C10ms_mmap-10B981?style=flat-square)](rcdebug/flaw_catalog.py)
7
+
8
+ Technical reference for `rcdebug`. Keep this file updated whenever CLI flags, modules, or data files change.
9
+
10
+ ![Roblox Developer Console output](assets/roblox-devconsole.jpg)
11
+
12
+ ![rcdebug CLI listener](assets/cli-listener.jpg)
13
+
14
+ ---
15
+
16
+ ## 1. CLI Modes
17
+
18
+ Running `rcdebug` with no arguments defaults to `--client`.
19
+
20
+ | Flag | Module | Description |
21
+ | :--- | :--- | :--- |
22
+ | `--client` | `rcdebug/client_bridge.py` | Starts HTTP/WS listener on `127.0.0.1:8765` (auto-switches to `8766+` if `8765` is busy), copies the client Luau script to clipboard, and tails `~/Library/Logs/Roblox/*_last.log`. |
23
+ | `--server` | `rcdebug/mcp_inspector.py` | Audits a live Roblox Studio MCP server or scans local `.rbxlx`, `.rbxmx`, `.luau`, and `.lua` files via `--place <path>`. |
24
+ | `--catalog [QUERY]` | `rcdebug/flaw_catalog.py` | Searches `rcdebug/data/flaws_120000.txt` using the mmap index in `~/.rcdebug/index_cache.bin`. |
25
+ | `--pack [QUERY]` | `rcdebug/debugger_pack.py` | Searches `rcdebug/data/luau_debugger_pack_120.json` (`LDP-001` to `LDP-120`). |
26
+ | `--learn [PATH]` | `rcdebug/learner.py` | Extracts game tokens from a local path, recent Roblox logs, or GitHub (`--learn --github [QUERY]`). |
27
+ | `--history` | `rcdebug/learner.py` | Prints `~/.rcdebug/command_history.json` and `FlawBrain` stats. |
28
+ | `--watch` | `rcdebug/learner.py` | Polls `command_history.json` and `~/Library/Logs/Roblox/*_last.log` every 2 seconds to learn new tokens. |
29
+
30
+ ---
31
+
32
+ ## 2. File Map
33
+
34
+ ```text
35
+ rcdebug/
36
+ ├── bin/rcdebug # Executable linked to ~/.local/bin/rcdebug
37
+ ├── pyproject.toml # PEP 621 package config & console_scripts entrypoint
38
+ ├── setup.py # Setuptools sdist/bdist_wheel builder
39
+ ├── MANIFEST.in # Package data manifest (data/*.txt, data/*.json)
40
+ ├── LICENSE # MIT License
41
+ ├── README.md # User guide & pip install instructions
42
+ ├── AI_ARCHITECTURE.md # Architecture reference
43
+ ├── .github/workflows/
44
+ │ ├── ci.yml # Unit test CI workflow
45
+ │ └── publish.yml # Automated GitHub Release & PyPI publisher on v* tags
46
+ ├── assets/
47
+ │ ├── roblox-devconsole.jpg # In-game Developer Console telemetry screenshot
48
+ │ └── cli-listener.jpg # macOS terminal listener screenshot
49
+ ├── rcdebug/
50
+ │ ├── __init__.py # __version__ = "1.0.0"
51
+ │ ├── cli.py # Argument parser, severity filter resolver, history logger
52
+ │ ├── models.py # Finding, MemorySnapshot, RemoteTrafficStat, AuditSession
53
+ │ ├── terminal.py # ANSI formatting and pbcopy wrapper
54
+ │ ├── exporter.py # Markdown report generator (--export)
55
+ │ ├── luau_payload.py # Client-only Luau scanner script generator
56
+ │ ├── client_bridge.py # RuntimeBridgeServer, port fallback, RobloxLogTailer
57
+ │ ├── mcp_inspector.py # StudioMCP client and parallel local file scanner
58
+ │ ├── flaw_catalog.py # mmap-backed 120,000-flaw catalog + 12 static regex rules
59
+ │ ├── debugger_pack.py # 120 static Luau probes
60
+ │ ├── github_harvester.py # GitHub REST API Luau harvester
61
+ │ ├── learner.py # AdaptiveLearner, CommandHistory, AutonomousBrainSync, FlawBrain
62
+ │ └── data/
63
+ │ ├── flaws_120000.txt # 120,000 pipe-delimited flaw records (RCD-000001..RCD-120000)
64
+ │ └── luau_debugger_pack_120.json # 120 Luau probes (LDP-001..LDP-120)
65
+ ├── scripts/
66
+ │ └── build_120k_corpus.py # Deterministic builder for flaws_120000.txt
67
+ └── tests/
68
+ └── test_rcdebug.py # 15 unit and integration tests
69
+ ```
70
+
71
+ ### Local State (`~/.rcdebug/`)
72
+
73
+ - `index_cache.bin`: `marshal` cache containing byte offsets and inverted keyword posting lists for `flaws_120000.txt`, keyed by file size and `mtime_ns`.
74
+ - `command_history.json`: Last 500 CLI runs and domain frequency weights.
75
+ - `learned_flaws.json` & `learned_patterns.txt`: Custom tokens learned from games and logs.
76
+ - `flaw_brain.json`: Token-to-domain and severity weights trained on all 120,000 flaws, 120 probes, and live findings.
77
+ - `brain_sync_state.json`: File byte offsets for `AutonomousBrainSync`.
78
+
79
+ ---
80
+
81
+ ## 3. Core Invariants
82
+
83
+ ### A. Client-Only Luau Payload (`luau_payload.py`)
84
+ - Uses only client-accessible services: `Players.LocalPlayer`, `ReplicatedStorage`, `ReplicatedFirst`, `Workspace`, `StarterGui`, `StarterPack`, `Lighting`, `SoundService`, `Teams`, `Stats`, `RunService`.
85
+ - Never calls server-only APIs (`ServerScriptService`, `ServerStorage`, `OnServerEvent`, `RunService:IsServer()`, `GetNetworkOwner()`) or custom executor hooks (`hookmetamethod`, `getnamecallmethod`).
86
+ - Scans `Workspace:GetDescendants()` in batches of `1500` with `task.wait()` yields to prevent client freezes on large maps.
87
+ - Sends findings via `HttpService:PostAsync` when available and always prints `[rcdebug-wire:report]`, `[rcdebug-wire:telemetry]`, and `[rcdebug-console]` lines so `RobloxLogTailer` can read them from `~/Library/Logs/Roblox/*_last.log`.
88
+
89
+ ### B. Port Binding Before Clipboard Copy (`client_bridge.py`)
90
+ - `bind_runtime_bridge_server()` binds the TCP socket before generating the Luau snippet.
91
+ - If `127.0.0.1:8765` is held by an older `rcdebug` process (`GET /status` returns `{"tool": "rcdebug"}`), it sends `POST /shutdown` to reclaim port `8765`.
92
+ - If `127.0.0.1:8765` is held by another app (such as MacSploit), it binds `8766` (or the next free port) and writes that port into the copied Luau script.
93
+
94
+ ### C. 120,000-Flaw Ordering & Binary Index (`flaws_120000.txt` + `flaw_catalog.py`)
95
+ - Schema: `CODE|SEVERITY|CATEGORY|DOMAIN|KEYWORDS_CSV|TITLE|FLAW|ABUSE|FIX|RANK`
96
+ - Strictly ordered by rank `1` to `120000`:
97
+ - `RCD-000001` to `RCD-025000`: `CRITICAL`
98
+ - `RCD-025001` to `RCD-065000`: `WARN`
99
+ - `RCD-065001` to `RCD-120000`: `INFO`
100
+ - `FlawCatalog` never loads all 120,000 lines into Python dicts on startup. It loads `~/.rcdebug/index_cache.bin` and seek-reads matching byte offsets from `flaws_120000.txt` via `mmap`.
101
+ - Findings sort by `(severity_tier, rank_asc, -confidence, path)` so critical issues always appear first.
102
+
103
+ ---
104
+
105
+ ## 4. Verification
106
+
107
+ Run before committing changes:
108
+
109
+ ```bash
110
+ python3 -m unittest discover -s /Users/revanveroka/Music/rcdebug/tests -v
111
+ ```
rcdebug-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Revan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,4 @@
1
+ include README.md
2
+ include LICENSE
3
+ include AI_ARCHITECTURE.md
4
+ recursive-include rcdebug/data *.txt *.json
rcdebug-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,171 @@
1
+ Metadata-Version: 2.4
2
+ Name: rcdebug
3
+ Version: 1.0.0
4
+ Summary: Revan Cool Debugger - macOS CLI developer and security-auditing tool for Roblox Studio (Runtime Bridge & MCP Inspector)
5
+ Author: Revan
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/roulettegun/rcdebug
8
+ Project-URL: Repository, https://github.com/roulettegun/rcdebug.git
9
+ Project-URL: Issues, https://github.com/roulettegun/rcdebug/issues
10
+ Project-URL: Releases, https://github.com/roulettegun/rcdebug/releases
11
+ Keywords: roblox,luau,security,audit,mcp,debugger,studio
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Environment :: Console
14
+ Classifier: Environment :: MacOS X
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: MacOS
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Security
24
+ Classifier: Topic :: Software Development :: Debuggers
25
+ Requires-Python: >=3.10
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Dynamic: license-file
29
+
30
+ # rcdebug
31
+
32
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
33
+ [![Platform macOS](https://img.shields.io/badge/platform-macOS-000000?style=flat-square&logo=apple&logoColor=white)](https://github.com/roulettegun/rcdebug)
34
+ [![Flaw Database](https://img.shields.io/badge/flaw_signatures-120%2C000-E11D48?style=flat-square)](rcdebug/data/flaws_120000.txt)
35
+ [![Luau Probes](https://img.shields.io/badge/luau_probes-120-F59E0B?style=flat-square)](rcdebug/data/luau_debugger_pack_120.json)
36
+ [![Dependencies](https://img.shields.io/badge/dependencies-zero-10B981?style=flat-square)](pyproject.toml)
37
+
38
+ `rcdebug` (Revan Cool Debugger) is a macOS command-line debugger and security auditor for Roblox games. It finds exposed remotes, unanchored parts that leak network ownership, replicated player stats, memory spikes, and server script vulnerabilities.
39
+
40
+ It runs on Python's standard library with zero external packages.
41
+
42
+ ![Roblox Developer Console running rcdebug](assets/roblox-devconsole.jpg)
43
+
44
+ ![rcdebug terminal listener](assets/cli-listener.jpg)
45
+
46
+ ---
47
+
48
+ ## Install
49
+
50
+ ### Option 1: Install via `pip` directly from GitHub
51
+
52
+ ```bash
53
+ pip install git+https://github.com/roulettegun/rcdebug.git
54
+ ```
55
+
56
+ Or install the pre-built release wheel from GitHub Releases:
57
+
58
+ ```bash
59
+ pip install https://github.com/roulettegun/rcdebug/releases/download/v1.0.0/rcdebug-1.0.0-py3-none-any.whl
60
+ ```
61
+
62
+ ### Option 2: Clone & Link Locally
63
+
64
+ ```bash
65
+ git clone https://github.com/roulettegun/rcdebug.git
66
+ cd rcdebug
67
+ pip install -e .
68
+ ```
69
+
70
+ ---
71
+
72
+ ## Quick Start
73
+
74
+ ### 1. Live Game / Client Audit (`--client`)
75
+
76
+ Run `rcdebug` in your terminal:
77
+
78
+ ```bash
79
+ rcdebug
80
+ ```
81
+
82
+ What happens:
83
+ 1. Starts a local listener on `127.0.0.1:8765` (if port `8765` is used by MacSploit or another process, it automatically switches to `8766`).
84
+ 2. Copies the 100% client-sided Luau scanner to your macOS clipboard (`pbcopy`).
85
+ 3. Tails `~/Library/Logs/Roblox/*_last.log` in real time so findings still stream to your terminal even when Roblox blocks `HttpService:PostAsync` on the client.
86
+
87
+ Paste (`Cmd+V`) the copied script into your executor, Roblox Developer Console, or Studio Command Bar.
88
+
89
+ ### 2. Static Place & Studio MCP Audit (`--server`)
90
+
91
+ Scan local `.luau` / `.lua` scripts, `.rbxlx` / `.rbxmx` place files, or an open Roblox Studio session over MCP:
92
+
93
+ ```bash
94
+ # Scan a local folder or .rbxlx place file
95
+ rcdebug --server --place ./src --export audit.md
96
+
97
+ # Connect to Roblox Studio MCP
98
+ rcdebug --server
99
+ ```
100
+
101
+ ---
102
+
103
+ ## Commands & Flags
104
+
105
+ | Command | What it does |
106
+ | :--- | :--- |
107
+ | `rcdebug` or `rcdebug --client` | Start the live client bridge, copy the Luau scanner, and tail Roblox logs. |
108
+ | `rcdebug --server` | Audit an active Roblox Studio MCP session or a local `--place <path>`. |
109
+ | `rcdebug --catalog [query]` | Search the 120,000-flaw database (`RCD-000001` to `RCD-120000`). |
110
+ | `rcdebug --pack [query]` | Search the 120 Luau debugger probes (`LDP-001` to `LDP-120`). |
111
+ | `rcdebug --learn [path]` | Learn custom remote, attribute, and folder names from a place or recent logs. |
112
+ | `rcdebug --learn --github [query]` | Pull public Luau scripts from GitHub and train `~/.rcdebug/flaw_brain.json`. |
113
+ | `rcdebug --history` | View terminal command history and learned brain stats. |
114
+ | `rcdebug --watch` | Watch `command_history.json` and Roblox logs in the background. |
115
+
116
+ ### Filtering & Exporting
117
+
118
+ ```bash
119
+ # Show only CRITICAL findings
120
+ rcdebug --client --critical
121
+
122
+ # Show CRITICAL and WARNING findings
123
+ rcdebug --client --critical --warning
124
+
125
+ # Search the 120,000-flaw catalog for DataStore flaws
126
+ rcdebug --catalog datastore --critical --limit 10
127
+
128
+ # Save a Markdown audit report when you stop the session
129
+ rcdebug --client --export report.md
130
+ ```
131
+
132
+ ---
133
+
134
+ ## What It Checks
135
+
136
+ - **Remotes (`ReplicatedStorage` & `Workspace`)**: Lists every client-visible `RemoteEvent`, `RemoteFunction`, and `UnreliableRemoteEvent`, ranked by risk (`Admin`, `Economy`, `DataStore`, `Combat`, `Inventory`), plus live `OnClientEvent` call rates (`calls/sec`).
137
+ - **Network Ownership**: Finds unanchored non-character `BasePart` instances in `Workspace` that nearby clients can move locally.
138
+ - **Player & Character State**: Flags `ValueBase` objects (`IntValue`, `NumberValue`, `BoolValue`, `StringValue`), player attributes, and `Tool` configs replicated to the client.
139
+ - **10s Memory & Instance Diffs**: Logs `Workspace` instance count, `LocalPlayer` instance count, and `Stats:GetTotalMemoryUsageMb()` every 10 seconds to spot leaks.
140
+ - **Static Server Checks (`--server`)**: Flags `loadstring()`, numeric `require(assetId)`, hardcoded Discord webhooks, `DataStore:SetAsync` without `UpdateAsync`, `ProcessReceipt` missing `PurchaseId` checks, unguarded `ProximityPrompt.Triggered` / `BasePart.Touched` handlers, and `OnServerEvent` listeners missing `typeof()` or cooldown guards.
141
+
142
+ ---
143
+
144
+ ## Project Structure
145
+
146
+ ```text
147
+ rcdebug/
148
+ ├── bin/rcdebug # CLI executable
149
+ ├── assets/ # Screenshots
150
+ ├── rcdebug/
151
+ │ ├── cli.py # CLI parser and command router
152
+ │ ├── client_bridge.py # Local HTTP/WS listener + macOS Roblox log tailer
153
+ │ ├── luau_payload.py # Client-sided Luau scanner & 10s telemetry script
154
+ │ ├── mcp_inspector.py # Roblox Studio MCP client & static .rbxlx/.luau scanner
155
+ │ ├── flaw_catalog.py # mmap-indexed 120,000-flaw lookup engine
156
+ │ ├── debugger_pack.py # 120 static Luau probes
157
+ │ ├── learner.py # Adaptive pattern learner & command history tracker
158
+ │ ├── github_harvester.py # GitHub Luau pattern harvester (--learn --github)
159
+ │ ├── exporter.py # Markdown report writer (--export)
160
+ │ └── data/
161
+ │ ├── flaws_120000.txt # 120,000 flaw signatures (RCD-000001..RCD-120000)
162
+ │ └── luau_debugger_pack_120.json # 120 Luau probes (LDP-001..LDP-120)
163
+ ├── scripts/build_120k_corpus.py # Generator for flaws_120000.txt
164
+ └── tests/test_rcdebug.py # Unit test suite
165
+ ```
166
+
167
+ ## Running Tests
168
+
169
+ ```bash
170
+ python3 -m unittest discover -s tests -v
171
+ ```
@@ -0,0 +1,142 @@
1
+ # rcdebug
2
+
3
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
4
+ [![Platform macOS](https://img.shields.io/badge/platform-macOS-000000?style=flat-square&logo=apple&logoColor=white)](https://github.com/roulettegun/rcdebug)
5
+ [![Flaw Database](https://img.shields.io/badge/flaw_signatures-120%2C000-E11D48?style=flat-square)](rcdebug/data/flaws_120000.txt)
6
+ [![Luau Probes](https://img.shields.io/badge/luau_probes-120-F59E0B?style=flat-square)](rcdebug/data/luau_debugger_pack_120.json)
7
+ [![Dependencies](https://img.shields.io/badge/dependencies-zero-10B981?style=flat-square)](pyproject.toml)
8
+
9
+ `rcdebug` (Revan Cool Debugger) is a macOS command-line debugger and security auditor for Roblox games. It finds exposed remotes, unanchored parts that leak network ownership, replicated player stats, memory spikes, and server script vulnerabilities.
10
+
11
+ It runs on Python's standard library with zero external packages.
12
+
13
+ ![Roblox Developer Console running rcdebug](assets/roblox-devconsole.jpg)
14
+
15
+ ![rcdebug terminal listener](assets/cli-listener.jpg)
16
+
17
+ ---
18
+
19
+ ## Install
20
+
21
+ ### Option 1: Install via `pip` directly from GitHub
22
+
23
+ ```bash
24
+ pip install git+https://github.com/roulettegun/rcdebug.git
25
+ ```
26
+
27
+ Or install the pre-built release wheel from GitHub Releases:
28
+
29
+ ```bash
30
+ pip install https://github.com/roulettegun/rcdebug/releases/download/v1.0.0/rcdebug-1.0.0-py3-none-any.whl
31
+ ```
32
+
33
+ ### Option 2: Clone & Link Locally
34
+
35
+ ```bash
36
+ git clone https://github.com/roulettegun/rcdebug.git
37
+ cd rcdebug
38
+ pip install -e .
39
+ ```
40
+
41
+ ---
42
+
43
+ ## Quick Start
44
+
45
+ ### 1. Live Game / Client Audit (`--client`)
46
+
47
+ Run `rcdebug` in your terminal:
48
+
49
+ ```bash
50
+ rcdebug
51
+ ```
52
+
53
+ What happens:
54
+ 1. Starts a local listener on `127.0.0.1:8765` (if port `8765` is used by MacSploit or another process, it automatically switches to `8766`).
55
+ 2. Copies the 100% client-sided Luau scanner to your macOS clipboard (`pbcopy`).
56
+ 3. Tails `~/Library/Logs/Roblox/*_last.log` in real time so findings still stream to your terminal even when Roblox blocks `HttpService:PostAsync` on the client.
57
+
58
+ Paste (`Cmd+V`) the copied script into your executor, Roblox Developer Console, or Studio Command Bar.
59
+
60
+ ### 2. Static Place & Studio MCP Audit (`--server`)
61
+
62
+ Scan local `.luau` / `.lua` scripts, `.rbxlx` / `.rbxmx` place files, or an open Roblox Studio session over MCP:
63
+
64
+ ```bash
65
+ # Scan a local folder or .rbxlx place file
66
+ rcdebug --server --place ./src --export audit.md
67
+
68
+ # Connect to Roblox Studio MCP
69
+ rcdebug --server
70
+ ```
71
+
72
+ ---
73
+
74
+ ## Commands & Flags
75
+
76
+ | Command | What it does |
77
+ | :--- | :--- |
78
+ | `rcdebug` or `rcdebug --client` | Start the live client bridge, copy the Luau scanner, and tail Roblox logs. |
79
+ | `rcdebug --server` | Audit an active Roblox Studio MCP session or a local `--place <path>`. |
80
+ | `rcdebug --catalog [query]` | Search the 120,000-flaw database (`RCD-000001` to `RCD-120000`). |
81
+ | `rcdebug --pack [query]` | Search the 120 Luau debugger probes (`LDP-001` to `LDP-120`). |
82
+ | `rcdebug --learn [path]` | Learn custom remote, attribute, and folder names from a place or recent logs. |
83
+ | `rcdebug --learn --github [query]` | Pull public Luau scripts from GitHub and train `~/.rcdebug/flaw_brain.json`. |
84
+ | `rcdebug --history` | View terminal command history and learned brain stats. |
85
+ | `rcdebug --watch` | Watch `command_history.json` and Roblox logs in the background. |
86
+
87
+ ### Filtering & Exporting
88
+
89
+ ```bash
90
+ # Show only CRITICAL findings
91
+ rcdebug --client --critical
92
+
93
+ # Show CRITICAL and WARNING findings
94
+ rcdebug --client --critical --warning
95
+
96
+ # Search the 120,000-flaw catalog for DataStore flaws
97
+ rcdebug --catalog datastore --critical --limit 10
98
+
99
+ # Save a Markdown audit report when you stop the session
100
+ rcdebug --client --export report.md
101
+ ```
102
+
103
+ ---
104
+
105
+ ## What It Checks
106
+
107
+ - **Remotes (`ReplicatedStorage` & `Workspace`)**: Lists every client-visible `RemoteEvent`, `RemoteFunction`, and `UnreliableRemoteEvent`, ranked by risk (`Admin`, `Economy`, `DataStore`, `Combat`, `Inventory`), plus live `OnClientEvent` call rates (`calls/sec`).
108
+ - **Network Ownership**: Finds unanchored non-character `BasePart` instances in `Workspace` that nearby clients can move locally.
109
+ - **Player & Character State**: Flags `ValueBase` objects (`IntValue`, `NumberValue`, `BoolValue`, `StringValue`), player attributes, and `Tool` configs replicated to the client.
110
+ - **10s Memory & Instance Diffs**: Logs `Workspace` instance count, `LocalPlayer` instance count, and `Stats:GetTotalMemoryUsageMb()` every 10 seconds to spot leaks.
111
+ - **Static Server Checks (`--server`)**: Flags `loadstring()`, numeric `require(assetId)`, hardcoded Discord webhooks, `DataStore:SetAsync` without `UpdateAsync`, `ProcessReceipt` missing `PurchaseId` checks, unguarded `ProximityPrompt.Triggered` / `BasePart.Touched` handlers, and `OnServerEvent` listeners missing `typeof()` or cooldown guards.
112
+
113
+ ---
114
+
115
+ ## Project Structure
116
+
117
+ ```text
118
+ rcdebug/
119
+ ├── bin/rcdebug # CLI executable
120
+ ├── assets/ # Screenshots
121
+ ├── rcdebug/
122
+ │ ├── cli.py # CLI parser and command router
123
+ │ ├── client_bridge.py # Local HTTP/WS listener + macOS Roblox log tailer
124
+ │ ├── luau_payload.py # Client-sided Luau scanner & 10s telemetry script
125
+ │ ├── mcp_inspector.py # Roblox Studio MCP client & static .rbxlx/.luau scanner
126
+ │ ├── flaw_catalog.py # mmap-indexed 120,000-flaw lookup engine
127
+ │ ├── debugger_pack.py # 120 static Luau probes
128
+ │ ├── learner.py # Adaptive pattern learner & command history tracker
129
+ │ ├── github_harvester.py # GitHub Luau pattern harvester (--learn --github)
130
+ │ ├── exporter.py # Markdown report writer (--export)
131
+ │ └── data/
132
+ │ ├── flaws_120000.txt # 120,000 flaw signatures (RCD-000001..RCD-120000)
133
+ │ └── luau_debugger_pack_120.json # 120 Luau probes (LDP-001..LDP-120)
134
+ ├── scripts/build_120k_corpus.py # Generator for flaws_120000.txt
135
+ └── tests/test_rcdebug.py # Unit test suite
136
+ ```
137
+
138
+ ## Running Tests
139
+
140
+ ```bash
141
+ python3 -m unittest discover -s tests -v
142
+ ```
@@ -0,0 +1,47 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "rcdebug"
7
+ version = "1.0.0"
8
+ description = "Revan Cool Debugger - macOS CLI developer and security-auditing tool for Roblox Studio (Runtime Bridge & MCP Inspector)"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ authors = [
13
+ { name = "Revan" }
14
+ ]
15
+ keywords = ["roblox", "luau", "security", "audit", "mcp", "debugger", "studio"]
16
+ classifiers = [
17
+ "Development Status :: 5 - Production/Stable",
18
+ "Environment :: Console",
19
+ "Environment :: MacOS X",
20
+ "Intended Audience :: Developers",
21
+ "Operating System :: MacOS",
22
+ "Programming Language :: Python :: 3",
23
+ "Programming Language :: Python :: 3 :: Only",
24
+ "Programming Language :: Python :: 3.10",
25
+ "Programming Language :: Python :: 3.11",
26
+ "Programming Language :: Python :: 3.12",
27
+ "Programming Language :: Python :: 3.13",
28
+ "Topic :: Security",
29
+ "Topic :: Software Development :: Debuggers",
30
+ ]
31
+ dependencies = []
32
+
33
+ [project.urls]
34
+ Homepage = "https://github.com/roulettegun/rcdebug"
35
+ Repository = "https://github.com/roulettegun/rcdebug.git"
36
+ Issues = "https://github.com/roulettegun/rcdebug/issues"
37
+ Releases = "https://github.com/roulettegun/rcdebug/releases"
38
+
39
+ [project.scripts]
40
+ rcdebug = "rcdebug.cli:main"
41
+
42
+ [tool.setuptools.packages.find]
43
+ where = ["."]
44
+ include = ["rcdebug*"]
45
+
46
+ [tool.setuptools.package-data]
47
+ rcdebug = ["data/*.txt", "data/*.json"]
@@ -0,0 +1,7 @@
1
+ """
2
+ rcdebug - Revan Cool Debugger
3
+ Local Roblox Studio Runtime Bridge & MCP Security/Performance Auditor
4
+ """
5
+
6
+ __version__ = "1.0.0"
7
+ __author__ = "Revan"