Summary

Ruyi Trace is a specialized desktop tool for academic research into website fingerprinting and JavaScript reverse-engineering. It utilizes an instrumented Firefox build to capture runtime execution logs, enabling AI models to automatically generate environment-patching code and fingerprinting risk-control analysis reports. It is essential for researchers needing to understand and counter sophisticated anti-bot techniques.

How It Works

The core innovation is C++ kernel-level instrumentation, making tracing probes undetectable by page scripts via standard JS detection methods. An Electron client manages the custom Firefox build, collects NDJSON runtime logs, and facilitates AI analysis. This approach provides a high-fidelity baseline for studying fingerprinting detection strategies.

Quick Start & Requirements

• Installation: Place RuyiTrace.exe and the firefox/ directory together. Double-click RuyiTrace.exe to launch.
• Prerequisites: Requires the provided custom Firefox build (approx. 427 MB total distribution). Windows x64 executable.
• Usage: Launch the client, specify a start URL and log directory, ensure the custom kernel is ready, and click "Start Collection." Browse the target page, then click "Stop Collection." Logs are saved as .ndjson.
• Links: ruyiPage framework: https://github.com/LoseNine/ruyipage

Highlighted Details

• Undetectable Instrumentation: C++ kernel probes evade JavaScript detection.
• AI-Assisted Analysis: NDJSON logs feed LLMs for automatic fingerprinting reports and environment-patching code generation.
• Comprehensive Logging: Captures detailed DOM/JS API runtime execution, including call stacks and source info.
• Integrated Workflow: Pairs with ruyiPage for initial site profiling (JS, network) to contextualize AI analysis.

Maintenance & Community

Presented as "Built for researchers, by researchers." No specific community channels or contributor details are provided. Project status is "research."

Licensing & Compatibility

Licensed under MPL-2.0. Modifies Firefox source code but is unaffiliated with Mozilla. MPL-2.0 generally permits commercial use, requiring modifications to remain open-source.

Limitations & Caveats

Strictly for academic research, security education, and defensive analysis; prohibited for bypassing terms of service. An internal version reportedly offers significantly more features than the open-source release. Project status is "research."