Skip to content
fl4r3techPublic

About

PS3 reverse-engineering toolkit for Ghidra: NIDs, PRX relocations, TOC-aware analysis, signatures

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

CellScope

CellScope is a PS3 reverse-engineering toolkit for Ghidra. All of its analysis is plain, tested Python that never imports Ghidra, and a thin adapter pushes the results into Ghidra.

Why I built it

CellScope is a ground-up replacement for the Ps3GhidraScripts family. Those scripts are a Java Ghidra extension, so every Ghidra release needs a matching .zip, every internal API change breaks them, and when something goes wrong you are left with a stack trace from inside Ghidra that you cannot reproduce outside the GUI. They also inherit Ghidra's PPC64 weaknesses. The most painful one is that when the analyzer fails to infer r2, every TOC-relative reference silently disappears, and identifying functions by the strings they use stops working.

I wanted a toolkit that keeps working when Ghidra changes, so I split the problem in two:

src/cellscope/
  io/ elf/ ps3/ analysis/ report/   <- zero Ghidra imports, pure Python, tested
  ghidra/                           <- the ONLY place Ghidra's API is touched
ghidra_scripts/                     <- thin PyGhidra entry points

When Ghidra changes, you fix ghidra/compat.py. When you want to check something, you run it on the command line with no Ghidra at all. When you want a regression test, you write one, because none of it needs a GUI.

CellScope knows the platform: containers, PRX metadata, NIDs, relocations, the TOC, and PPC64 code. It deliberately knows nothing about any particular game. Engine-specific analyses plug in as extensions.

Documentation

document what it covers
docs/TESTING_IN_GHIDRA.md installing and checking CellScope in Ghidra, step by step
docs/EXTENSIONS.md writing your own analysis as an extension, without forking CellScope
docs/CLI.md every command and option, generated from the tool itself
docs/SUBMITTING.md how to send test reports, NID names, bug reports, proposals, and pull requests
examples/string_registrars.py a complete, tested example extension
CHANGELOG.md what changed in each release
ROADMAP.md what comes next
CONTRIBUTING.md how to help, and the two rules that are never bent
CODE_OF_CONDUCT.md how we treat each other
SECURITY.md how to report a security problem privately

What it does

Containers

  • ELF32/64, big and little endian, PPU and SPU
  • EXEC, PRX, and SPRX classification
  • Detects a still-encrypted SELF (EBOOT.BIN) and says so in one clear sentence, instead of failing with "invalid ELF"
  • Finds and extracts SPU images embedded in a PPU binary

Relocations

  • SCE PT_SCE_PPURELA entries and standard RELA, with the PPC relocation types PS3 modules actually use: ADDR32/64, ADDR16_LO/HI/HA, ADDR16_LO_DS, and REL24/14/64
  • Applied to a fresh copy of the image, so a PRX's descriptors, import tables, and materialized addresses resolve instead of pointing into nothing
  • cellscope relocs mod.sprx --out relocated.elf writes the relocated image. Load that one in Ghidra, because Ghidra cannot apply SCE relocations itself.
  • Anything unsupported is counted and reported, never silently skipped

PS3 metadata

  • PT_PROC_PARAM, PT_PROC_PRX, and sceModuleInfo
  • Import (libstub) and export (libent) tables, with the entry size read from the structure rather than assumed
  • The .opd descriptor table, with entry-width detection
  • TOC (r2) base resolution with a confidence score
  • ELF symbol tables, from .symtab and .dynsym or through PT_DYNAMIC when the section headers are gone
  • Syscall stubs, found by their shape (li r11,N, sc, blr), so the result cannot go stale

NID extraction from the binary itself

You do not need someone else's NID table if the binary will tell you. CellScope uses four sources, from most trusted to least:

  1. Symbol-table join (exact). A module that kept .symtab gives name to address, and its libent and libstub tables give NID to address. Joining on the address, with descriptors resolved through .opd, gives you ground truth.
  2. Corpus cross-join (exact). If module A imports NID X from cellFs, and module B exports X and still has its symbols, A's import gets named without A carrying any symbols at all. cellscope nids --harvest-dir ./modules does this across a whole folder.
  3. Own-strings brute force. Every identifier-shaped token in the binary's own strings is hashed against the NIDs it uses, including the sys_ and cell prefixes. These names are marked inferred, not exact.
  4. Hash-variant discovery. The pairs from sources 1 and 2 are ground truth the hash cannot fake, so CellScope runs every candidate hashing variant against them and adopts the one that reproduces them. On a real retail EBOOT, this showed that the NID digest is truncated little-endian, even though the platform is big-endian everywhere else. With the corrected form, 16 of that binary's 18 imports resolved, and with the other form, none did. Those pairs are pinned in tests/test_nid_vectors.py.

Every structure is located by several independent strategies. Each candidate is scored by a validator, and the losing candidates are kept in diagnostics, so when something is wrong you can see what was tried and why each attempt was rejected.

Code analysis

  • A small, purpose-built PPC64 decoder
  • Function discovery by recursive descent from .opd, the exports, and the entry point, followed by a linear prologue sweep for callbacks that nothing calls directly
  • A TOC-aware cross-reference engine. It tracks registers with r2 seeded from the real TOC base, so lis/ori pairs, addis/addi r2 pairs, and ld rX, off(r2) loads all resolve, including one level of indirection through the TOC slot. It also understands the ABI's TOC restore after a cross-module call (ld r2, N(r1)). Without that, every TOC reference after the first external call is lost, which measured 24% of all TOC references on a retail binary.
  • Call-site argument recovery, which reads the constants in r3 to r10 at every bl and turns "this function is called 900 times" into "here are its 900 arguments"

Structured tables

  • A generic scanner for arrays of {string, code pointer, ...} rows in read-only data, such as command tables, script-builtin tables, and handler tables. Finding one table names dozens or hundreds of functions in one step, with no call site to analyze and no signature to write. A new table type is a five-line TableSpec, not a new scanner.
  • Pointer-array detection for jump and dispatch tables

Struct reconstruction

  • Seed it with a function and a register that holds a pointer. It tracks that pointer through mr, addi, loads, and stores, follows it into callees through the argument registers, and reports every field: offset, width, signedness, read and write counts, whether it holds a pointer, and which functions touch it.
  • Several seeds merge into one layout, and a pointer field can be followed into the struct it points at
  • Emits C with explicit padding for the gaps, because a gap means "nothing observed", not "nothing there"
  • Creates real Ghidra structure types through the adapter

Signatures (the successor to MakePpcSig.py)

  • The decoder decides what to wildcard, rather than whether Ghidra happened to attach a reference. A TOC reference that Ghidra missed is still wildcarded, instead of being frozen into a signature that breaks on the next build.
  • Grows to the shortest unique pattern, verified by re-scanning
  • Falls back to an offset anchor inside the function when the prologue is generic
  • Emits C, JSON, and IDA-style strings

Cross-version diffing

  • Matches functions between two builds in rounds, most confident first: unique string sets, exact masked-code equality, call-graph propagation, and fuzzy shape
  • Ports your symbol names forward and tells you what actually changed

Hook planning

Finding the function you want to hook is the easy half. The other half is whether you can safely overwrite its first few instructions, and the reference graph answers that before you ever touch the hardware:

  • Does anything branch into the region the patch overwrites? If a loop elsewhere jumps to site + 4 and you have written a four-instruction sequence there, it lands in the middle of it. assess_patch_site reports every inbound branch and the largest width that has none.
  • Is each displaced instruction position-independent? A relative branch computes the wrong target once it runs from a trampoline. The verdict tells "unsafe" apart from "safe, but relocate it".
  • Does anything displaced write r12 or ctr? A lis/ori/mtctr/bctr jump overwrites both. Do not assume either is free. At a retail process entry point, a stub ending in mtctr/bctr failed, while the same stub ending in a relative b ran.
python tools/assess_hook_sites.py EBOOT.elf \
    LoadAsset=0x00123450 RunScript=0x00234560 \
    --width 1 --also-width 4 --json sites.json

The exit status is 1 if any site is unsafe, so it can gate a build.

The same command reports which padding runs a relative branch can reach, and which of them will not work. I hit two traps, both confirmed on retail hardware:

  • A PS3 PT_LOAD maps from file offset 0, so the ELF header and the program-header table are in memory, and the alignment zeros inside them look like perfect code caves. Writing there corrupts what the loader reads before the first instruction runs.
  • .rodata sits in the same r-x PT_LOAD as .text, so the program headers say that data-area padding is executable. It is not. Stubs placed there never ran, even with the section flags edited by hand to X, while the same code split across alignment gaps inside the SHF_EXECINSTR sections ran fine. CellScope only reports code-section padding as usable, and a binary with no section headers yields no usable caves at all.

Install

git clone https://github.com/fl4r3tech/CellScope.git
cd CellScope
pip install -e .          # or just add src/ to PYTHONPATH
python run_tests.py       # 125 tests, no Ghidra, network or pytest needed

No git? Download the ZIP from the green Code button on the GitHub page and unpack it, then run the last two lines from inside the folder.

CellScope needs Python 3.9 or newer, and the core has no third-party dependencies.


Use it from the command line

# everything, with reports
cellscope analyze EBOOT.elf --markdown map.md --json map.json --symbols syms.txt

# signatures
cellscope sig EBOOT.elf MyFunction=0x1234 OtherFunction=0x5678 --header sigs.h
cellscope sig EBOOT.elf --from-symbols targets.txt --header sigs.h

# the string-anchored loop, scripted
cellscope xref EBOOT.elf --string "failed to open %s"
cellscope strings EBOOT.elf --grep .cfg

# what moved between versions, and port your names forward
cellscope diff v100.elf v101.elf --symbols my_v100_names.txt \
                             --port-symbols v101_names.txt --out diff.json

# NIDs: harvest them out of the binary instead of hunting for a table
cellscope nids --harvest EBOOT.elf --out nids.json
cellscope nids --harvest-dir ./modules --out nids.json     # cross-joins the folder
cellscope analyze EBOOT.elf --nids ./                       # feed the table back in
cellscope nids --resolve EBOOT.elf --wordlist sdk_symbols.txt

# relocations (PRX/SPRX)
cellscope relocs mod.sprx --show 20
cellscope relocs mod.sprx --out mod.relocated.elf           # load THIS in Ghidra
cellscope analyze mod.sprx --write-relocated mod.relocated.elf --write-nids nids.json

# retained symbols, if any survived
cellscope symbols mod.sprx --functions-only

# struct reconstruction from functions you have identified
cellscope struct EBOOT.elf player_s=0x812340:r3,0x8156A0:r4 --header structs.h

# embedded SPU images
cellscope spu EBOOT.elf --extract ./spu/

analyze relocates the image automatically when it needs it, and turns that off with --no-reloc. It also harvests NIDs automatically, which --no-harvest turns off, and --nid-corpus DIR cross-joins against other modules.


Use it in Ghidra

CellScope is tested on Ghidra 12.2, which needs Java 25 or newer, with PyGhidra 3.2.0. It has been tested on Windows 11 and Linux, with Python 3.10 and 3.14. On Python 3.14, install PyGhidra into a virtual environment first, as in docs/TESTING_IN_GHIDRA.md, because Ghidra's own installer only has JPype for Python 3.13 and older. Start Ghidra with support/pyghidraRun (pyghidraRun.bat on Windows) instead of ghidraRun, because the analysis scripts are CPython 3 and run under PyGhidra.

Add CellScope's ghidra_scripts/ folder in Script Manager under Manage Script Directories. The scripts find src/ next to them on their own. If you move them, either pip install -e . into the Python that PyGhidra uses or set CELLSCOPE_SRC=/path/to/cellscope/src.

docs/TESTING_IN_GHIDRA.md walks you through checking an install step by step, and tools/ghidra_smoke.py checks it automatically. It runs every script inside a real Ghidra against the synthetic test binaries and confirms that what the analysis finds is what lands in Ghidra.

script runtime what it does
PS3_Analyze.py PyGhidra full analysis, applied to the open program
PS3_MakeSig.py PyGhidra signature for the function under the cursor
PS3_ImportSymbols.py PyGhidra or Jython applies a cellscope symbol export

PS3_ImportSymbols.py imports nothing from cellscope and also runs under the legacy Jython runtime. It is the escape hatch: if the Python setup in your Ghidra install is broken, run the analysis on the command line and import the results with that one file.

Setup notes

  • Load the ELF as PowerPC:BE:64:default. It is always big endian.
  • Add <register name="r2"/> to the <unaffected> list in ppc_64_32.cspec. That stops the decompiler from overwriting the TOC pointer.
  • Run PS3_Analyze.py before Ghidra's auto-analysis if you can. It sets r2 first, which lets Ghidra's own reference analyzer resolve TOC-relative loads, instead of CellScope injecting them afterwards.
  • CellScope refuses to set r2 when its confidence is below 50%, because a wrong r2 makes every TOC reference point somewhere plausible but false. That is worse than having none.

Library use

from cellscope import analyze
pm = analyze("EBOOT.elf")
print(pm.report())

# the string-anchored loop
for fn in pm.analyzer.functions_referencing_string("failed to open"):
    print(hex(fn.start), fn.display_name, len(fn.callers), "callers")

# a signature you can paste into your own code
from cellscope.analysis.sigs import make_signature
print(make_signature(pm.elf.address_space, 0x1234, "MyFunction").to_c())

# a struct, from two functions that take it in r3
from cellscope.analysis.structs import StructRecoverer
rec = StructRecoverer(pm.elf.address_space, pm.analyzer)
print(rec.recover("player_s", [(0x812340, 3), (0x8156A0, 3)]).to_c())

Extensions

Analysis that is specific to a game or an engine, such as script VMs, console variables, and entity structs, does not belong in the core. It plugs in as an extension instead, so you never need to fork CellScope to add your own analysis. docs/EXTENSIONS.md walks you through writing one, and examples/string_registrars.py is a complete example to copy:

class MyEngine:
    name = "myengine"

    def run(self, pm, options):
        # pm.elf, pm.analyzer, pm.call_sites, pm.opd, pm.toc_base, pm.strings ...
        return MyResult(...)

pm = analyze("EBOOT.elf", Options(extensions=[MyEngine()]))
pm.extensions["myengine"]

The result can opt in to report_lines(), to_dict(), markdown_lines(), suggested_names(), and apply_to_ghidra(facade, A, rep, apply_comments=True), and each one flows into the matching report, export, or Ghidra pass. Load an extension from a single file or from a package:

cellscope analyze EBOOT.elf --ext path/to/my_engine.py:MyEngine
cellscope analyze EBOOT.elf --ext mypackage.mymodule:MyEngine

In Ghidra, set CELLSCOPE_EXTENSIONS before you start Ghidra, and PS3_Analyze.py runs the extension and applies its results. Only run extensions you trust, because an extension is ordinary Python code.


Honest limits

  • Nothing here decrypts a SELF. CellScope detects one and tells you. Bring a decrypted PPU ELF that you dumped from software you own.
  • Relocations are applied in memory, not written back by default. Pass --write-relocated or cellscope relocs --out when you want the image on disk.
  • Only a small seed of well-known NID names ships, in data/nids/ps3_common.txt. Point --harvest-dir at your own modules and build your own. A stale table baked into a release is exactly the failure this toolkit exists to avoid. The hash self-check deliberately abstains rather than grading its own homework, as src/cellscope/data/nids/README.md explains.
  • String-brute-forced NIDs are marked inferred. Read them before you commit them.
  • Recovered structs are observation, not ground truth. A field is there because analyzed code touched it, and padding means nothing was observed. Overlaps are flagged in warnings, not silently resolved.
  • Float fields and float arguments are under-reported, because the tracker follows the general-purpose registers, not the floating-point ones.
  • Vector and Cell-specific instructions decode generically. That is enough for signatures and references, but it is not a full disassembler.

Layout

src/cellscope/
  errors.py            typed errors that name the offset and the field
  extensions.py        the extension protocol
  io/reader.py         bounds-checked, endian-explicit reader
  elf/                 ELF containers, address space, symbols, SELF/SPU detection
  ps3/                 module info, libstub/libent, .opd, TOC, relocations,
                       NIDs, NID harvesting, syscalls
  analysis/            PPC decoder, xrefs, call-site args, signatures, diffing,
                       structured-table scanner, struct recovery, code caves,
                       patch-site safety assessment
  report/              JSON / symbols / markdown exporters
  ghidra/              compat shim + apply pass  <- the only Ghidra-aware code
ghidra_scripts/        Script Manager entry points
examples/              string_registrars.py, the reference extension
tools/                 assess_hook_sites.py, ghidra_smoke.py, release_check.py,
                       gen_cli_docs.py
docs/                  TESTING_IN_GHIDRA.md, EXTENSIONS.md, CLI.md, SUBMITTING.md
tests/                 synthetic PPU ELF + synthetic PRX, 125 tests

tests/synthetic.py builds a small PPC64 big-endian executable that contains, by construction, exactly the structures the toolkit should find, and the tests check that precisely those are found. That includes a string reachable only through the TOC, which is the regression test for the whole reference engine.

tests/synthetic_prx.py then un-links that executable the way a linker would: every address field is blanked and replaced by a relocation. Applying those relocations must reproduce the original image byte for byte, so a relocation type encoded wrongly fails loudly instead of producing pointers that are subtly wrong.

Roadmap

See ROADMAP.md. Next up are a one-command Ghidra import, real signatures on OS imports, switch-table recovery, and resolving calls through function pointers.

Contributing

There is room for every kind of help: testing on your own binaries, NID names, roadmap items, engine extensions, IDA and Binary Ninja importers, test cases, and docs. See CONTRIBUTING.md for how to get started.

Credits

Written by FL4R3 (Sean Hill).

CellScope was inspired by, and replaces, clienthax's Ps3GhidraScripts. A great deal of its format knowledge comes from the PS3 Developer Wiki and the RPCS3 project. I'm always open to connecting with others in the PS3 and reverse-engineering communities, so feel free to open an issue, start a discussion, or send a pull request. Let's build it together!

Disclaimer

CellScope is an independent project. It is not affiliated with, endorsed by, or sponsored by Sony Interactive Entertainment. PlayStation and PS3 are trademarks of Sony Interactive Entertainment Inc., and all other trademarks belong to their owners.

CellScope is for analyzing software you own and have the right to examine. It does not decrypt, unlock, or circumvent anything, and it ships no game data and no Sony SDK material. You are responsible for following the laws and license terms that apply to you.

License

MIT. See LICENSE.

About

PS3 reverse-engineering toolkit for Ghidra: NIDs, PRX relocations, TOC-aware analysis, signatures

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages