RSProx

Introduction

RSProx is a locally hosted proxy server intended to act as a middleman between the clients and servers in Old School RuneScape. Support for RuneScape 3 may be added later in the future, if a maintainer for packet decoders can be found.

RSProx will work by patching a root client, allowing it to connect to the locally-hosted proxy server rather than the real servers. The original information that the patcher overwrote will be passed onto the proxy tool, allowing it to establish connections with what the client had originally intended. We intend to support most java clients, as well as the C++ client. A technical breakdown of the processes involved can be found in issues/RSProx.

Installer

Tip

Use the installer for better compatibility and ease of use.

The installer for RSProx can be found under releases, the latest installer is v1.0.

The installer comes with a bundled JDK which it utilizes. The launcher auto-updates RSProx whenever a new version is published.

Guide

Below is a quick guide demonstrating how to use RSProx.

Cloning

As of right now, RSProx can only be used by cloning the repository yourself.

Launching

RSProx project can be launched by either running the class net.rsprox.gui.ProxyToolGuiKt directly in gui/proxy-tool module, or by it via gradle as ./gradlew proxy.

Note

Native client can currently only be run on Windows and Linux (requiring wine). MacOS support will be added in the future.

Usage

Upon launching RSProx tool, you will be met with a relatively empty GUI. In order to start using it, select the Jagex Account Mode from the first dropdown as seen below, the client type you wish to use from the second dropdown and press the launch button to the right. The 'Default' Jagex Account mode means no Jagex Account will be used, and you will be prompted for an e-mail and password to login.

Caution

MacOS support requires whitelisting certain loopback addresses! See the chapter below.

After launching a client, a process will occur which will download the necessary files and patch them, so they can pass data through the proxy itself. On RuneLite, this can take tens of seconds as everything loads up. Caching mechanism is included on RuneLite that makes consecutive launches faster than the first one (or whenever the cache is invalidated).

Once the client has fully booted up, you may log in. All the data will flow through the proxy and get logged on your PC. No data will leave your PC without your permission. Upon logging in, you should be met with logs being written in your RSProx GUI as depicted here:

In order to filter the data that gets logged, you may use the filters panel that is at the top-right section of the client, as seen depicted here:

Within the filters, you can toggle individual packets, entire packet groups, or even the full Incoming or Outgoing categories, by right-clicking on said categories.

Additionally, on-top of the regular filters, one can use the settings above it to toggle general-purpose preferences that apply regardless of the selected filter preset.

Tip

The Default preset does not support modifications. If you wish to toggle filters, you must make a filter preset of your choice. You can have an unlimited amount of filter presets, and they are saved on your PC.

MacOS Support

MacOS does not whitelist any loopback address other than 127.0.0.1 by default, which means RSProx cannot establish a connection, as we use unique loopback addresses per connection established, which describes the world to which we're connecting.

As such, it is necessary for anyone connecting via MacOS to run some commands. In order to whitelist the necessary loopback addresses, this script must be run: (Note that for custom private server targets, the group id must be changed from 2 to 3+, where 3 is the first custom target, 4 is the second and so on)

Warning

Whitelisting a lot of worlds will result in DNS lookups significantly slowing down. It is recommended you only select your preferred worlds and whitelist those specific ones. Ensure that your default world is configured and whitelisted, or the client will not be able to boot up.

#!/bin/bash
set -euo pipefail

# === Config ====================================================
MIN_WORLD_ID=300      # Minimum world id to whitelist, inclusive.
MAX_WORLD_ID=650      # Maximum world id to whitelist, inclusive.
GROUP_ID=2            # Proxy target (2 is Oldschool, 3 is first custom, etc).
MODE=+                # "+" to whitelist, "-" to un-whitelist
# ===============================================================

for ((w=MIN_WORLD_ID; w<=MAX_WORLD_ID; w++)); do
  a=$(( w / 256 ))
  b=$(( w % 256 ))
  c=$GROUP_ID
  ip="127.$a.$b.$c"

  if [[ "$MODE" == "+" ]]; then
    sudo ifconfig lo0 alias "$ip"
  else
    sudo ifconfig lo0 -alias "$ip"
  fi
done

echo "Alias IPs added for worlds $MIN_WORLD_ID..$MAX_WORLD_ID (group $GROUP_ID)."

Transcribing

Besides live transcribing which happens on the UI directly, it is possible to transcribe .bin files previously created. To do so, one can simply drag the .bin files they wish to transcribe anywhere onto the GUI, and a background process will take place, which ends up making .txt files with the same name. The transcription uses the currently-active filters as it would during live transcripts.

Jagex Accounts

Jagex Accounts are now fully supported. There are two ways of using a Jagex account: build.gradle.kts

1. Using the built-in authentication system. RSProx allows you to login via your browser to authenticate yourself for the proxy tool, allowing easy access to all the characters under that Jagex account. You can also link multiple different Jagex accounts to make the process of switching accounts easier.
2. The Default, legacy behaviour. In this mode, you need to export the credentials.properties file in user.home/.runelite/credentials.properties via this. Once you have exported the credentials.properties as shown in the tutorial, the RSProx tool will always load them up from user.home/.runelite/credentials.properties. If you wish to stop using a Jagex Account in this Default mode, simply delete the credentials file. In this Default mode, you may only have one character/account, as it always reads from the same file when launching the client.

Linux Setup

On Linux, there are a few extra steps involved in setting up a Jagex Account:

1. Run RSProx.AppImage normally to generate the required folders.
2. Afterward, you must run RSProx.AppImage with sudo, this is because of the Jagex Account login page only allowing redirects to localhost:80, which is a protected port by default on Linux, after this you can setup and import your Jagex Account via the GUI.
3. Once the above is done, you must copy the jagex-accounts.properties file from /root/.rsprox/ to ~/.rsprox/ (i.e sudo cp /root/.rsprox/jagex-accounts.properties ~/.rsprox/) as RSProx puts its config folder in the user's home folder by default, which is different when ran as root.
4. You must then make yourself the owner of the file, this is done via sudo chown "$USER" ~/.rsprox/jagex-accounts.properties.
5. You can now simply run RSProx.AppImage and you will be able to access your Jagex Account.

Additionally, if you would like to run the Native Client under Proton (at the time of writing this is currently necessary to use the new renderer), you must create a protonpath file in ~/.rsprox/ containing the file path to a proton executable, for example:

/home/grian/.steam/steam/steamapps/common/Proton - Experimental/proton

Security

We have taken many measures to ensure the players can securely use this tool, without having to worry about getting banned or having their information leaked.

So, is it safe to use?

It depends. We are very confident in the Native client being safe for use, as there are very minor modifications done to that client, and knowing the limits of C++, it is not possible for Jagex to identify these changes.

However, when it comes to RuneLite, there are quite a bit more changes done. While we are certain about RuneLite being safe to use right now, nothing prevents RuneLite developers from adding in more checks in the future that this tool might not catch. Is this likely? No. Could it still happen? Absolutely.

People may have concerns over so many third-party clients getting banned as of recent, and while the concerns are valid, they do not apply to RSProx. We simply do not modify enough for it to be detectable. Every bit of information sent on login, which is how third party clients tend to get caught, is unaffected. This was achieved via numerous clever tricks that will not be explored here, as to avoid people maliciously using them.

Private Server Usage

RSProx can currently be used to connect to private servers, but only under certain circumstances. The following criteria must be met in order to do this:

Note

This list is subject to changes over time, we hope to improve the overall support for further platforms and client types.

1. This only works with Windows and Linux, not macOS.
2. The client must not have any protocol-breaking changes, same traditional networking must be used. The only supported change at this time is changing the varp count in the client from the size-5000 int array.
3. Must be on revision 223 or higher.

Setting Up Custom Targets

In order to use the new proxy targets feature, one has to manually fill in the yaml file containing them. The file is expected at user.home/.rsprox/proxy-targets.yaml (.yml suffix also supported). The file does not exist by default, so it must be created by the user!

Here is an example RSPS target:

config:
  - name: Blurite
    jav_config_url: https://client.blurite.io/jav_local_227.ws
    revision: 227.3
    modulus: d2a780dccbcf534dc61a36deff725aabf9f46fc9ea298ac8c39b89b5bcb5d0817f8c9f59621187d448da9949aca848d0b2acae50c3122b7da53a79e6fe87ff76b675bcbf5bc18fbd2c9ed8f4cff2b7140508049eb119259af888eb9d20e8cea8a4384b06589483bcda11affd8d67756bc93a4d786494cdf7b634e3228b64116d

Properties breakdown:

• name - The name given to the client. Any references to OldSchool RuneScape will be replaced by this. This is a required property to ensure caches don't overwrite and cause crashing at runtime when loading different games simultaneously.
• jav_config_url - The URL to the jav_config that will be used to load initial world and world list. This is a required property.
• modulus - A hexadecimal (base-16) RSA modulus used to encrypt the login packet sent to the client. This is a required property.
• revision - A revision number used to pick the client and correct decoders. The default is whatever is currently latest stable in Old School RuneScape. The exact version and subversion must be defined for Native clients (see: https://archive.lostcity.rs/oldschool.runescape.com/native/osrs-win/). This is an optional property.
• varp_count - (OPTIONAL) Changes the array length used for varps in the client, the default value is 5000. This is an optional property. As of revision 232, it is no longer patched as the value is now based on cache.
• runelite_bootstrap_commithash - (OPTIONAL) A hash pointing to a version of RuneLite you wish to use. This is an optional property, not defining it will use the latest for your revision.
• runelite_gamepack_url - (OPTIONAL) A URL pointing to a valid gamepack file for the given revision. This is only necessary for revisions 228 and older. Not defining it will use the latest for your revision.

Short guide:

1. Copy the config file from above and save it as described above.
2. Change the name to what you'd like to call the client.
3. Change the number 227 in the jav_config_url to the revision you're using. I maintain local javconfigs from revision 223 onwards. You can also host your own, but this will easily get you started.
4. Change the revision number 227.3 to match with the revision you're using. The list of valid revisions can be seen here. A safe bet is using .1 subrevision as that exists in all revisions.
5. Change the modulus to what your server is using. In the case of RSMod, this is exported during the installation.
6. If you wish to use RuneLite and your server is older than the very latest revision, you'll need to update the commithash for RuneLite that indicates the version of RuneLite to use. The list of valid bootstraps can be seen here. You'll have to locate the correct bootstrap based on the date when the commit was made, and click the "Copy full SHA for ..." button to get the value for the commithash. If you don't know the date for your revision, you can approximately date it via OpenRS2's Caches - simply look for you revision, look at the date it was first and last published and then locate a bootstrap that falls in that date range.
7. If you wish to use RuneLite, and your revision is 228 or older, you must assign the runelite_gamepack_url property. The gamepacks can be found here. Simply pick your revision and click the "Copy Link" button in your browser for the Raw File. This is the URL to enter.

Progress

Below is a small task list showing a rough breakdown of what the tool will consist of, and how far the progress is at any given moment.

• Patch Tool
  • Native (Win)
    • Supports Unix via wine or proton
  • Native (Mac) (Automated patching too fragile)
  • RuneLite (All Operating systems)
• World identification via localhost address
• World-hop host address injection
• Login re-encoding & obtaining ISAAC Seed
• HTTP Server (worldlist.ws, jav_config.ws)
• Binary header building
• Binary blob reader/writer
• Privacy concerns
  • Bank Pin erasure (4-digit code)
  • Private message content erasure
  • Login tokens in URL open packets
  • 192-bit UID (linked to account recoveries)
  • Site settings (linked to account recoveries)
  • Erases all keyboard presses
• Graphical User Interface (Proxy tool)
• Graphical User Interface (Live Transcriber)
• Live cache loading
• Historical cache loading
• Public archive
  • Automated binary blob uploading at the end of a session
  • Indexing of binary files
  • Ability to download any binary blobs
• Decoders (Every revision starting from 223)
• Transcriber
• Launchers
  • Proxy launcher/updater
  • RuneLite launcher (necessary to avoid detection)