A read-only defensive game/process research sandbox rooted in The Outlast Trials, Toontown Rewritten, and Toontown Corporate Clash.
GhostTrial preserves Stark's original process watcher, memory inspection, and fake honeypot ideas in a modular desktop app. It does not edit saves or game progression. It provides no memory writes, injection, anti-cheat bypass, stealth, credential collection, or automatic startup persistence.
Use Python 3.11 or later. Memory inspection requires 64-bit Python on Windows.
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -r requirements.txt
python -m ghosttrialpython ghosttrial.py and the old python ghosttrials.py both work. Optional
installation: python -m pip install ., then launch ghosttrial.
Tk must be installed with Python (some Linux distributions package it separately).
python -m ghosttrial --data-dir ./my-private-lab
python -m ghosttrial --versionThe default data directory is ghosttrial-data/ in the working directory. Settings,
rotating logs, session JSON, exported reports and generated lab runs live there.
These local files are not OS startup persistence. No service or scheduled task is installed.
| Tab | Behavior |
|---|---|
| Processes | Name, PID, executable path, RSS, uptime, PE architecture, status and watchlist matches; explicit refresh or optional refresh while open |
| Memory inspector | Select a process, enter UTF-8, signed int32 little-endian or hex bytes, then run/cancel an exact bounded search |
| History & reports | View session events, scans, limits, results and errors; export JSON or open a prior saved session/report |
| Honeypot lab | Generate unmistakably fake files in unique runs; check integrity; clean unchanged generated artifacts |
| Logs | View the latest 128 KiB of the rotating application log |
| Settings | Scan limits, timeout, event retention, refresh interval, theme, logging, report directory and named process watchlists |
| About | Identity, scope, platform details, attribution and data location |
Searches run on a worker thread. The UI handles results on its own thread. Closing during a scan requests cancellation and waits for resource cleanup. Only one worker operation runs at a time. No process is automatically opened for memory inspection.
Built-in profiles are Generic, The Outlast Trials (TOT), Toontown Rewritten (TTR),
and Toontown Corporate Clash (TTCC). The names Outlast_Trials.exe, ttr.exe and
ttcc.exe are unverified discovery hints inherited from v2.0, not claims about
current game releases. They filter the dashboard only. Use Generic and select the
correct process when a hint does not match. No demo progression values, offsets,
signatures, unlock mappings or game memory layouts are shipped.
Profiles are immutable data in ghosttrial/profiles/catalog.py, with no game-specific
scanner code. Add a profile there to reuse the same inspector.
In Settings, enter named watchlists as JSON and save:
{
"Lab tools": ["python*.exe"],
"Toontown hints": ["ttr.exe", "ttcc.exe"]
}Patterns are case-insensitive executable-name globs. Matches are informational, not malware findings. Appearance/disappearance events are recorded on inventory refresh after the first baseline. Disappearance can mean the process exited or metadata became unavailable. No background watcher remains after the app closes.
Pymem has been removed. A small Windows adapter requests exactly read/query access
(0x0410) and binds only the native functions needed to read, query and close.
The implementation follows Microsoft's documented
process access rights,
ReadProcessMemory,
and VirtualQueryEx.
Default limits: 64 MiB attempted, 100 matches, 15 seconds. Reads use 64 KiB chunks
and preserve exact matches across contiguous chunk/region boundaries. A search can
finish with complete, byte_limit, result_limit, time_limit, cancelled or
partial_unreadable. These limits mean a zero-match result is not proof a value is
absent from the process. A complete result covers eligible readable regions only.
Read failures are counted, and process identity/exit failures are surfaced.
The dashboard's architecture is read from PE headers; unavailable and non-PE files
show unknown. It does not substitute the host architecture. Process paths and
memory usage may be unavailable due to permissions or process exit.
Every session has its own JSON file under sessions/, saved after each event.
Retention defaults to 200 events per session, with an explicit dropped-event count.
Scan-start events preserve process/profile, query and limits even when attachment
fails. Completed scan events include addresses, bytes attempted/read, skipped reads,
elapsed time and stop reason. Open prior session files with Open saved report.
Export creates a new, uniquely named JSON report under the configured directory. Writes are atomic. No raw memory dump or process command line is saved. Query values, paths and addresses can still be sensitive; review before sharing. Old sessions are not deleted automatically. Runtime data and dumps are excluded from Git.
Each run has four fake files and a manifest with SHA-256 hashes. Every artifact uses
GHOSTTRIAL_FAKE_TEST_DATA_DO_NOT_USE. This is a local artifact exercise, with no
network listeners, real credentials, access interception or attribution.
Integrity checks report unchanged, changed or missing artifacts. Cleanup deletes
only unchanged known artifacts. Modified/unrelated files remain, along with the
manifest; unknown or modified manifests cause cleanup to refuse. Creation, checks
and cleanup results appear in session history. The old ~/.ghosttrial_honeypot
directory is never migrated or deleted automatically.
ghosttrial/
app.py CLI and launch
config.py Validated settings
storage.py Atomic JSON and safe paths
logging_setup.py Rotating application logs
profiles/catalog.py Generic and TOT/TTR/TTCC profile data
scanner/process.py Inventory, identity and architecture
scanner/memory.py Windows read/query-only adapter
scanner/search.py Portable bounded exact search
reports/session.py Session history and JSON reports
honeypot/lab.py Fake artifacts, manifest and cleanup
ui/app.py CustomTkinter workspace
tests/ Utilities, scanner regression and self-buffer tests
.github/ CI and contribution templates
flowchart TD
UI[Desktop UI] --> Worker[Worker queue]
UI --> Settings[Settings and watchlists]
Worker --> Inventory[Process inventory]
Worker --> Search[Bounded exact search]
Search --> Reader[Read/query-only Windows adapter]
Worker --> Lab[Local fake-artifact lab]
UI --> Session[Session events]
Session --> Reports[Atomic JSON reports]
python -m compileall -q ghosttrial tests ghosttrial.py ghosttrials.py
python -m unittest discover -s tests -vTests cover settings recovery, atomic output, profiles, path confinement, bounded history, reports, fake-artifact cleanup, exact searches, limits, PID reuse, and API boundary regressions. The Windows test reads only a known buffer in its own process. CI runs on Windows/Linux with Python 3.11 and 3.13; it also builds a wheel. See VALIDATION.md for this release's actual checks and limitations.
- Missing dependencies: install
requirements.txtin the interpreter used to launch. - Tk unavailable: install the platform's Tk-enabled Python; no
tkinterPyPI package is needed. - Access denied: expected for protected/inaccessible processes; use your own test target.
- No profile results: use Generic; executable hints may be stale.
- No matches: verify encoding and consider the recorded limits and skipped reads.
- Invalid settings: defaults load and the original file remains; the UI reports the error. Saving valid settings explicitly replaces it.
- Cleanup refused: inspect the manifest/files manually; never replace real content with fake markers to force cleanup.
Dependencies remain pinned to verified CustomTkinter 6.0.0 and psutil 7.2.2.
Suggested description: Read-only defensive game/process research sandbox rooted in The Outlast Trials, Toontown Rewritten and Toontown Corporate Clash.
Suggested topics: python, defensive-security, process-inspection, read-only,
game-research, honeypot-lab, customtkinter. Suggested tag: v2.1.0.
Enable private vulnerability reporting in the repository settings. No repository
URL or passing-CI badge is invented in this distribution.
Use the process and lab tabs for release screenshots after testing on your machine. Sanitize private process names/paths first. No mock image is presented as a tested game session.
MIT, retaining Copyright (c) 2026 Stark (@realstarkfr). See CONTRIBUTING.md and SECURITY.md. Unofficial; not affiliated with Red Barrels, Toontown Rewritten, Corporate Clash, Disney or their developers/publishers. Only inspect software you are authorized to research. Game compatibility has not been certified.