plex-docker/Freeloader/AGENTS.md

AGENTS.md - Plex_Patch

Project overview

Reverse-engineering notes and a runtime patch for Plex Media Server on Linux x86-64 (and ARM64/aarch64). It hooks Plex's FeatureManager and forces every feature bit on, unlocking gated features. Educational / RE use on software you run yourself; it ships no Plex code and bypasses no account/server authentication.

Target & runtime reality (important)

• Target: the main Plex Media Server executable (PIE). The feature machinery moved here from libsoci_core.so on post-2024/08/13 builds; libsoci_core.so is no longer the target.
• Plex runs against its OWN bundled musl libc + libgcompat (/usr/lib/plexmediaserver/lib/), NOT the host glibc. This drives the build and injection choices below.
• ARM64: confirmed working on aarch64-linux-musl. The ARM64 binary has the same musl constraint; zig cross-compilation targets aarch64-linux-musl.

Architecture

x86-64

• Language: C++20, plus the vendored Zydis C amalgamation for instruction decoding.
• Module discovery: dl_iterate_phdr used in early versions; current code uses /proc/self/maps (the constructor runs before the main PIE is loaded by musl, so dl_iterate_phdr returns 0 callbacks).
• Hook: sig_scan() finds target functions by byte-pattern signature; create_hook() installs a 14-byte jmp [rip+0x06] trampoline (Zydis decodes the prologue so relocated bytes stay valid).
• Feature unlock effect: after Plex applies its MyPlex feature list, the hook forces all 14 g_feature_bitset_slots qwords on (std::bitset<896>), so every feature (including Plex Pass, code 92, slot 11) reads as enabled.
• Webhook unlock: an additional hook targets sub_122B2F2 (the generic preference getter at 0x122B2F2). When the key is "WebHooksEnabled", it returns true regardless of the actual persisted value, enabling Plex's built-in webhook dispatch (play/pause/stop/rate events). This is a separate mechanism from the feature bitset — WebHooksEnabled is a plain boolean preference, not a feature bit. Both dispatch functions (sub_125A6D4 @ 0x125A6D4 and sub_125B766 @ 0x125B766) check only this preference with no secondary feature-bit gate.

ARM64 / aarch64

• Language: C++20. Zydis is NOT used on ARM64 (fixed 4-byte instructions, no length decoding needed). Zydis.h is conditionally excluded via #ifndef __aarch64__.
• Module discovery: same /proc/self/maps parser (get_dottext_info()) works identically on ARM64.
• Hook: create_hook_arm64() installs a 16-byte LDR X17, [PC, #8]; BR X17; <8-byte target> trampoline. No Zydis needed. The trampoline copies 4 original instructions (16 bytes) and appends the same LDR+BR jump-back sequence.
• Feature unlock effect: same bitset-force approach — hook the FeatureManager constructor via ARM64 signature, then force all 14 uint64_t slots to UINT64_MAX.
• Webhook unlock: currently targets preference init functions (SSO-check prologue patterns like ldrb w?, [x?, #0x17]). The ARM64 callbacks are generic feature-return-true for now; WebHooksEnabled-specific key matching (like the x86-64 sub_122B2F2 hook) is pending identification of the exact ARM64 preference getter function.
• Analysis tooling: get_arm64_sigs.py uses Capstone to extract ARM64 function signatures with ADRP page counting; check_webhooks.py dumps ADRP+ADD string loads inside candidate functions; disasm_final.py / disasm_key_areas.py are earlier (broken) Capstone analysis scripts.

ARM64 function signatures (from get_arm64_sigs.py)

VAddr	Signature	Notes
0x10dd904	FD 7B BA A9 FC 6F 01 A9 FA 67 02 A9 F8 5F 03 A9 F6 57 04 A9 F4 4F 05 A9 FD 03 00 91 FF 43 09 D1	Preference init function — 6 stp pairs (save 12 regs), sub sp,#0x250. The function at this address loads "WebHooksEnabled" string via ADRP+ADD at 0x10e0eac.
0x658120	FD 7B BD A9 F5 0B 00 F9 F4 4F 02 A9 FD 03 00 91 F3 03 01 AA F4 03 00 AA 61 00 80 52 E0 03 13 AA	FeatureManager class function — saves 2 regs, calls with x0/x1, loads FeatureManager strings from page 0x1B7000.
0x658070	FD 7B 03 A9 F4 4F 04 A9 FD C3 00 91	FeatureManager constructor-like — stp x29,x30,[sp,#-0x30]! ; stp x20,x19,[sp,#0x10] ; mov x29,sp. Used as catch-all FeatureManager hook target.
0xeba0b4	FD 7B BE A9 F3 0B 00 F9 FD 03 00 91 08 5C 40 39 09 04 40 F9 F3 03 00 AA 0A 1D 00 13 5F 01 00 71	Feature-check function — stp x29,x30,[sp,#-0x10]! ; str x19,[sp,#8] ; mov x29,sp ; ldrb w8,[x0,#0x17] (SSO check). 3 ADRP refs to page 0x1BD000 (hasPlexPass strings).
0x5e4188	FD 7B 01 A9 FD 43 00 91 A8 65 00 B0 08 85 42 F9 49 66 00 F0 ...	hasPlexPass checking function — 3 ADRP refs to page 0x1BD000.
0x5e42c0	FD 7B BE A9 F4 4F 01 A9 FD 03 00 91 74 66 00 90 88 82 46 39 ...	hasPlexPass checking function — 3 ADRP refs to page 0x1BD000.
0x5e4368	FD 7B BE A9 F3 0B 00 F9 FD 03 00 91 73 66 00 90 68 A2 47 39 ...	hasPlexPass checking function — 3 ADRP refs to page 0x1BD000.

ARM64 binary layout (from _Plex Media Server, text section at file offset 0x5d35bc)

Page	Contains	Notable Strings
0x1B7000	FeatureManager strings, preference init strings	"FeatureManager", "FeatureManager: Using cached data" (@ 0x1B72AB), "hasPlexPass" (@ 0x1B749B)
0x1BD000	Feature checking strings	"playing", "paused", "buffering", "media_css_min_assets_cache_ms"
0x363000	Webhook/web-related strings	"WebHooksEnabled" (@ 0x363871)

ARM64 text section

• Text section: vaddr=0x5e35bc, file_offset=0x5d35bc, size=0xc05964 (~12MB)
• Built for aarch64 Linux (little-endian), PIE position-independent
• All functions use ARM64 standard prologue: stp x29, x30, [sp, #-N]!
• String references via ADRP+ADD pairs (PC-relative page + 12-bit offset)
• No fixed function addresses when PIE-loaded; all discovery via sig_scan

Build & inject (details in README.md / docs/BUILD.md)

• Build with musl via zig (-target x86_64-linux-musl): bash build.sh. For ARM64: bash build.sh --arm64. A glibc build cannot relocate glibc-only symbols (__isoc23_strtol, arc4random, *_chk, _dl_find_object) in Plex's musl runtime → exit 127.
• Inject with LD_PRELOAD via scripts/plex-crack-wrapper.sh + a systemd

Key files

• src/hook.cpp / src/hook.hpp — hook engine, feature logic, feature-UUID catalog
• src/main.cpp — library constructor (unsetenv("LD_PRELOAD") then hook())
• build.sh — musl build via zig (auto-downloaded) with an ABI sanity gate
• scripts/plex-crack-wrapper.sh — LD_PRELOAD launcher scoped to the PMS process
• scripts/readbitset.py — live feature-bitset verifier
• third_party/zydis/ — vendored Zydis disassembler (MIT)
• get_arm64_sigs.py — Capstone-based ARM64 function signature extractor with ADRP page counting
• check_webhooks.py — dump ADRP+ADD string loads within candidate ARM64 functions
• experimental/debug_hook.c — standalone alternate hook (legacy is_feature_available signature)

RE artifacts (the Plex Media Server binary, libsoci_core.so, and *.i64 IDA databases) are git-ignored and not redistributed.

Signature patterns

Hex bytes with ? wildcards; spaces ignored (? = one-byte wildcard). Patterns are version-specific — re-verify after PMS updates.

x86-64 signatures

Target	Address	Signature	Notes
bitset_init (modern path constructor)	dynamic	55 48 89 E5 41 57 41 56 41 55 41 54 53 48 81 EC ? ? 00 00 49 89 FE 48 8D 9D ? ? ? ? 48 89 DF E8 ? ? ? ? 48 8B 1B 48 85 DB	FeatureManager_apply_feature_list_xml — post-2024/08/13
sub_122B2F2 (preference getter)	0x122B2F2	48 89 F3 4C 89 F7 0F B6 46 17 48 89 F1 84 C0	mov rbx, rsi; mov r14, rdi; movzx eax,[rsi+0x17] — std::string SSO check prologue
is_user_feature_set (legacy)	dynamic	55 48 89 E5 48 8B 07 48 85 C0 74 09	Pre-2024/08/13 fallback
is_feature_available (legacy)	dynamic	E8 ? ? ? ? 86 43 (call rel32 + test al, byte ptr [rbx+3])	Rel32 followed, pre-2024/08/13 fallback
map_find (legacy)	dynamic	55 48 89 E5 41 57 41 56 53 48 83 EC ? 49 89 F7 4C 8D 77	Pre-2024/08/13 fallback

ARM64 signatures (built with bash build.sh --arm64)

Target	Signature	Notes
FeatureManager_init (bitset constructor)	FD 7B 03 A9 F4 4F 04 A9 FD C3 00 91	stp x29,x30,[sp,#-0x30]! ; stp x20,x19,[sp,#0x10] ; mov x29,sp. Catches FeatureManager init to force bits on.
FeatureManager_class_method (alternative)	FD 7B BD A9 F5 0B 00 F9 F4 4F 02 A9 FD 03 00 91 F3 03 01 AA F4 03 00 AA 61 00 80 52 E0 03 13 AA	Saves 1 reg pair + str ; handles x0/x1 args.
feature_check_sso (feature checker)	FD 7B BE A9 F3 0B 00 F9 FD 03 00 91 08 5C 40 39	stp x29,x30,[sp,#-0x10]! ; str x19,[sp,#8] ; mov x29,sp ; ldrb w8,[x0,#0x17]. Hooked to always return true.
pref_init (preference init)	FD 7B BA A9 FC 6F 01 A9 FA 67 02 A9 F8 5F 03 A9 F6 57 04 A9 F4 4F 05 A9 FD 03 00 91 FF 43 09 D1	6 stp pairs, sub sp,#0x250. Loads "WebHooksEnabled" string. WebHooksEnabled-specific hook pending.
pref_getter_sso (generic getter, placeholder)	FD 7B ?? A9 ?? ?? ?? A9 FD 03 00 91 ?? 5C 40 39 ??	Broad pattern: prologue + SSO check on any x-reg. May match the preference getter.