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.
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.
| 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 |
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_PPURELAentries and standardRELA, with the PPC relocation types PS3 modules actually use:ADDR32/64,ADDR16_LO/HI/HA,ADDR16_LO_DS, andREL24/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.elfwrites 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, andsceModuleInfo- Import (
libstub) and export (libent) tables, with the entry size read from the structure rather than assumed - The
.opddescriptor table, with entry-width detection - TOC (
r2) base resolution with a confidence score - ELF symbol tables, from
.symtaband.dynsymor throughPT_DYNAMICwhen 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:
- Symbol-table join (exact). A module that kept
.symtabgives 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. - 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 ./modulesdoes this across a whole folder. - Own-strings brute force. Every identifier-shaped token in the binary's own
strings is hashed against the NIDs it uses, including the
sys_andcellprefixes. These names are marked inferred, not exact. - 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
r2seeded from the real TOC base, solis/oripairs,addis/addi r2pairs, andld 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
r3tor10at everybland 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-lineTableSpec, 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 + 4and you have written a four-instruction sequence there, it lands in the middle of it.assess_patch_sitereports 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
r12orctr? Alis/ori/mtctr/bctrjump overwrites both. Do not assume either is free. At a retail process entry point, a stub ending inmtctr/bctrfailed, while the same stub ending in a relativebran.
python tools/assess_hook_sites.py EBOOT.elf \
LoadAsset=0x00123450 RunScript=0x00234560 \
--width 1 --also-width 4 --json sites.jsonThe 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_LOADmaps 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. .rodatasits in the samer-xPT_LOADas.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 toX, while the same code split across alignment gaps inside theSHF_EXECINSTRsections ran fine. CellScope only reports code-section padding as usable, and a binary with no section headers yields no usable caves at all.
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 neededNo 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.
# 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.
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.
- Load the ELF as
PowerPC:BE:64:default. It is always big endian. - Add
<register name="r2"/>to the<unaffected>list inppc_64_32.cspec. That stops the decompiler from overwriting the TOC pointer. - Run
PS3_Analyze.pybefore Ghidra's auto-analysis if you can. It setsr2first, which lets Ghidra's own reference analyzer resolve TOC-relative loads, instead of CellScope injecting them afterwards. - CellScope refuses to set
r2when its confidence is below 50%, because a wrongr2makes every TOC reference point somewhere plausible but false. That is worse than having none.
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())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.
- 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-relocatedorcellscope relocs --outwhen you want the image on disk. - Only a small seed of well-known NID names ships, in
data/nids/ps3_common.txt. Point--harvest-dirat 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, assrc/cellscope/data/nids/README.mdexplains. - 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.
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.
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.
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.
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!
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.
MIT. See LICENSE.