cerberus-re
Cerberus RE is a local Apple-focused reverse-engineering workbench for building a repeatable three-headed static/dynamic/instrumentation loop around Ghidra, LLDB, and Frida. Trigger when the user wants static Ghidra analysis, LLDB dynamic/live analysis, Frida instrumentation, decompilation, runtime traces, or structured reversing artifacts such as functions, strings, symbols, Objective-C metadata, Swift metadata, xrefs, and runtime hits.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/owenpawl--cerberus-re-skill)HTML
<a href="/listings/owenpawl--cerberus-re-skill"><img src="/api/listings/owenpawl--cerberus-re-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
For a fresh checkout, start with the dependency installer in dry-run mode:
python3 scripts/install_dependencies.py python3 scripts/install_dependencies.py --execute source .venv/bin/activate cerberus-re bootstrap
The installer creates a local virtual environment, installs Cerberus RE, and adds Frida Python tooling. On macOS with Homebrew it can install Ghidra/Java and Node. On Linux and Windows it prints package-manager-specific commands for review instead of running system installs automatically.
If your system dependencies are already present:
pip install -e . cerberus-re bootstrap
Install the strongly encouraged mission companion when you want one unified local MCP server:
pip install git+https://github.com/OwenPawl/long-run-agent-skill.git pip install -e . cerberus-mcp
`cerberus-mcp` exposes first-class tools for the core Ghidra/LLDB/Frida loop, guarded runtime and bridge operations, restart-safe background jobs, and a bounded `cerberus_run` escape hatch. When long-run-agent is installed, the same server also composes its namespaced `mission_*` tools for durable control, claims, artifacts, friction, search, and closeout. Cerberus remains usable by itself for bounded work; `mission_companion_status` reports whether composition succeeded.
Example local MCP client configuration:
{
"mcpServers": {
"cerberus-re": {
"command": "/absolute/path/to/venv/bin/cerberus-mcp",
"env": {
"GHIDRA_WORKSPACE": "/absolute/path/to/ghidra-projects",
"CERBERUS_MCP_STRICT_SURFACE": "1"
}
}
}
}See [`references/mcp-server.md`](references/mcp-server.md) for the tool, approval, audit, and client contract.
Optional skill install:
cerberus-re install --host codex cerberus-re install --host claude cerberus-re install --host both
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 223 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: cerberus-re
- description: Cerberus RE is a local Apple-focused reverse-engineering workbench for building a repeatable three-headed static/dynamic/instrumentation loop around Ghidra, LLDB, and Frida. Trigger when the user wants static Ghidra analysis, LLDB dynamic/live analysis, Frida instrumentation, decompilation, runtime traces, or structured reversing artifacts such as functions, strings, symbols, Objective-C metadata, Swift metadata, xrefs, and runtime hits.
- ---
- # Cerberus RE
- Use this skill for local Apple-focused reverse engineering with a repeatable
- three-headed static/dynamic/instrumentation loop around Ghidra, LLDB, and
- Frida. The public CLI is `cerberus-re`.
- [`long-run-agent`](https://github.com/OwenPawl/long-run-agent-skill) is a
- strongly encouraged companion dependency for substantial work. Use it to
- preserve mission state, claims, artifacts, failures, friction, and next actions
- while Cerberus RE handles static, dynamic, and instrumentation evidence.
- Cerberus RE can still run alone for bounded one-off tasks.
- When driving through MCP, prefer `cerberus-mcp`. It exposes the core RE loop
- and composes long-run-agent's namespaced `mission_*` tools into the same local
- stdio server when the companion package or installed skill is available. Check
- `mission_companion_status` before assuming durable mission tools exist.
- ## Operating Contract
- - Resolve the repo or installed skill root first. If working from this checkout,
- run commands from the repo root.
- - Prefer the Python CLI: `cerberus-re` or `python3 -m cerberus_re_skill`.
- - Prefer `cerberus-mcp` when the host supports MCP; use its typed envelope
- status rather than parsing prose.
- - Keep generated evidence as JSON or Markdown artifacts, not terminal-only output.
- - Use durable workspace paths under `~/ghidra-projects`.
- - Preserve dirty worktree changes you did not make.
- - Capture runtime validation before treating runtime behavior as understood.
- - Keep ranking and prioritization framed as safe reverse-engineering workflow.
- - Runtime attach is guarded. Frida rechecks stay artifact-only unless
- `--allow-runtime` is explicit.
- - Mutating bridge calls require `write=true`; destructive bridge calls also
- require `destructive=true`.
- ## First Commands
- ```bash
- git status --short --branch
- python3 scripts/install_dependencies.py
- cerberus-re doctor
- cerberus-re bootstrap
- cerberus-re bridge audit
- ```
- Run `python3 scripts/install_dependencies.py --execute` from a fresh checkout
- when the host needs a local virtual environment or macOS Homebrew-managed
- dependencies.
- ## Static Workflow
- ```bash
- cerberus-re import analyze <binary-or-source-ref> <project_name>
- cerberus-re export apple-bundle <project_name> <program_name>
- cerberus-re export xpc-surface <project_name> <program_name>
- ```
- If a standalone Mach-O target fails while Ghidra resolves reexported
- dependencies, retry with:
- ```bash
- cerberus-re import analyze <binary-or-source-ref> <project_name> --skip-macho-reexports
- ```
- Record that the resulting static view excludes reexport behavior.
- For universal Mach-O targets, choose the intended runtime slice explicitly:
- ```bash
- cerberus-re import analyze <binary-or-source-ref> <project_name> --macho-arch arm64e
- ```
- This stages a thin copy under the Cerberus RE workspace before import.
- If a specific Ghidra analyzer reproducibly blocks import, disable only that
- named analyzer and record the exception in the evidence report:
- ```bash
- cerberus-re import analyze <binary-or-source-ref> <project_name> \
- --disable-analysis-option "Objective-C Selector Trampoline Analysis"
- ```
- ## Runtime Workflow
- Use LLDB when you can launch or safely attach to a process:
- ```bash
- cerberus-re validate lldb-trace <project> <program> \
- --launch-cmd <binary> \
- --symbols '<symbol-or-selector>' \
- --binary <binary>
- ```
- Pass multiple LLDB trace symbols either by repeating `--symbols` or with a
- comma-separated value; both forms are normalized before tracing.
- For dyld-cache-backed Apple frameworks, the live `/System/Library/...framework`
- path may be a stub without an on-disk Mach-O. Use the extracted dyld-cache
- binary for `--binary`, while the launch or attach target remains the live
- process under test.
- If the static export under test is saved outside the default export tree, add:
- ```bash
- --function-inventory /path/to/function_inventory.json
- ```
- Use Frida for guarded instrumentation:
- ```bash
- cerberus-re frida diagnose --target <binary>
- cerberus-re frida validate-scripts --symbol '<ObjC method>' --class-name <Class>
- cerberus-re frida recheck-attach \
- --target <owned-binary> \
- --symbol '<ObjC method>' \
- --capture-returns \
- --allow-runtime
- cerberus-re frida recheck-attach \
- --attach-pid <pid> \
- --selector '<ObjC selector>' \
- --class-filter '<ClassSubstring>' \
- --require-runtime-hit \
- --allow-runtime
- cerberus-re frida recheck-attach \
- --attach-pid <pid> \
- --selector '<ObjC selector>' \
- --exact-class '<KnownClass>' \
- --require-runtime-hit \
- --allow-runtime
- cerberus-re frida recheck-attach \
- --target <owned-binary> \
- --native-symbol 'ExampleFramework!late_loaded_export' \
- --native-wait-seconds 3 \
- --native-arg-preview \
- --require-runtime-hit \
- --allow-runtime
- cerberus-re frida gadget-probe <owned-binary> \
- --gadget /path/to/FridaGadget.dylib \
- --script /path/to/autonomous-probe.js \
- --stable-target-key <stable-owned-target-id> \
- --output-dir /tmp/cerberus-gadget-evidence \
- --allow-runtime
- ```
- Prefer `Module!symbol` for native exports when the intended framework or dylib
- is known. Unqualified native symbols remain supported, but an installed
- zero-hit unqualified hook is ambiguous evidence and should usually be retried
- with module qualification. Exact ObjC method hooks (`--symbol`), selector-wide
- ObjC hooks (`--selector`), and native hooks (`--native-symbol` or `--address`)
- are separate Frida recheck modes; run separate commands when you need coverage
- from more than one mode. Native hooks always preserve raw register strings under
- `args`; `--native-arg-preview` adds bounded best-effort string/module previews
- for readable values. If task-port attachment is blocked for an owned analysis
- copy, `gadget-probe` can launch that copy with a content-addressed Gadget,
- configuration, and autonomous script through `DYLD_INSERT_LIBRARIES`. Treat
- this as launch-injection evidence, not proof that ordinary Frida attach works.
- for those registers without making signature-correctness claims.
- After LLDB or Frida emits `runtime_hits.json`, correlate it back to static
- context:
- ```bash
- cerberus-re export runtime-enrich <project> <program> <runtime_hits.json>
- ```
- ## Bridge Workflow
- Use the live bridge when an interactive loop is faster than repeated exports:
- ```bash
- cerberus-re bridge arm <project_name> [program_name]
- cerberus-re bridge sessions
- cerberus-re bridge call /functions/search '{"query":"SomeFunction"}'
- cerberus-re bridge call /decompile '{"function":"SomeFunction"}'
- cerberus-re bridge close --project <project_name>
- ```
- ## XPC Workflow
- - Export XPC surfaces with `cerberus-re export xpc-surface`.
- - If an XPC report shows zero counts, check `warnings` and `missing_input_count`
- before treating it as real absence evidence; pass `--bundle-dir` or explicit
- export JSON paths when using an Apple bundle saved outside the default export
- directory.
- - Merge surfaces with `cerberus-re export xpc-graph`.
- - Use owner hints only until imported owner evidence confirms or disproves them.
- - Generate harness skeletons only after service, protocol, and endpoint evidence
- are concrete enough to rank.
- - Recover `NSXPCInterface` factory/configuration evidence before planning a
- bounded remote method probe.
- ## Validation
- Before a milestone push or release closeout, run:
- ```bash
- python3 -m unittest discover -s tests
- python3 -m compileall cerberus_re_skill scripts tests
- python3 -m cerberus_re_skill polish release --mode quick --strict-command-surface
- git diff --check
- python3 -m cerberus_re_skill bridge audit
- ```
- Add targeted live/static validation when changing Ghidra, LLDB, or Frida behavior.
- ## References
- Read only the file needed for the current task:
- - `references/operating-workflows.md`: detailed workflows and fallback rules.
- - `references/command-surface.md`: public CLI catalog.
- - `references/output-files.md`: artifact paths, schemas, and report meanings.
- - `references/raw-bridge-recipes.md`: bridge endpoint payloads and examples.
- - `references/frida-diagnostics.md`: Frida policy and validation guidance.
- - `references/apple-macho-notes.md`: Apple Mach-O and dyld target notes.
- - `references/builtins.md`: built-in Ghidra script caveats.
- - `references/triage-outputs.md`: triage output details.
- - `references/triage-patterns.json`: triage heuristic categories.
- - `references/mcp-server.md`: local stdio tools, composition, gates, and audit behavior.
README.md · README · 204 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Cerberus RE
- `cerberus-re` is a local Apple-focused reverse-engineering workbench for
- building a repeatable three-headed static/dynamic/instrumentation loop around
- Ghidra, LLDB, and Frida.
- It is designed for analysts and coding agents that need durable artifacts
- instead of terminal-only notes:
- - Ghidra import, headless export, decompilation, xrefs, and metadata recovery.
- - LLDB runtime traces with static enrichment back into exported function context.
- - Frida diagnostics, guarded runtime rechecks, Objective-C probes, and heap or archive inspection helpers.
- - XPC surface and graph reports from exported Objective-C/string/symbol data.
- - RE evidence reports, notes, case files, and release-gate validation checks.
- - Cross-platform Python CLI support for macOS, Linux, Windows, OpenAI Codex, and Claude Code.
- Runtime attach and target invocation are always explicit. The tooling favors
- owned processes, no-attach validation, generated artifacts, and bounded probes
- whose assumptions are recorded alongside the evidence.
- ## Public Scope
- The public workbench is general Apple binary-analysis infrastructure: Ghidra
- imports and exports, LLDB/Frida correlation, Mach-O/ObjC/Swift/XPC evidence,
- and portable reports. It is not a project-specific research log or a generic
- long-running agent memory system. Domain-specific research workflows should
- live in private overlays or durable run artifacts, while generic long-run state
- belongs in `long-run-agent`.
- ## Strongly Encouraged Companion Dependency
- Use Cerberus RE with
- [`long-run-agent`](https://github.com/OwenPawl/long-run-agent-skill) for
- substantial reverse-engineering work.
- Cerberus RE provides the static, dynamic, and instrumentation workbench;
- `long-run-agent` preserves mission state, claims, artifacts, failures, friction,
- and next actions so longer investigations stay auditable and resumable.
- Cerberus RE can run by itself for bounded tasks, but benchmark and release
- workflows should prefer the combined `cerberus-re + long-run-agent`
- configuration.
- ## Install
- For a fresh checkout, start with the dependency installer in dry-run mode:
- ```bash
- python3 scripts/install_dependencies.py
- python3 scripts/install_dependencies.py --execute
- source .venv/bin/activate
- cerberus-re bootstrap
- ```
- The installer creates a local virtual environment, installs Cerberus RE, and
- adds Frida Python tooling. On macOS with Homebrew it can install Ghidra/Java
- and Node. On Linux and Windows it prints package-manager-specific commands for
- review instead of running system installs automatically.
- If your system dependencies are already present:
- ```bash
- pip install -e .
- cerberus-re bootstrap
- ```
- Install the strongly encouraged mission companion when you want one unified
- local MCP server:
- ```bash
- pip install git+https://github.com/OwenPawl/long-run-agent-skill.git
- pip install -e .
- cerberus-mcp
- ```
- `cerberus-mcp` exposes first-class tools for the core Ghidra/LLDB/Frida loop,
- guarded runtime and bridge operations, restart-safe background jobs, and a
- bounded `cerberus_run` escape hatch. When long-run-agent is installed, the same
- server also composes its namespaced `mission_*` tools for durable control,
- claims, artifacts, friction, search, and closeout. Cerberus remains usable by
- itself for bounded work; `mission_companion_status` reports whether composition
- succeeded.
- Example local MCP client configuration:
- ```json
- {
- "mcpServers": {
- "cerberus-re": {
- "command": "/absolute/path/to/venv/bin/cerberus-mcp",
- "env": {
- "GHIDRA_WORKSPACE": "/absolute/path/to/ghidra-projects",
- "CERBERUS_MCP_STRICT_SURFACE": "1"
- }
- }
- }
- }
- ```
- See [`references/mcp-server.md`](references/mcp-server.md) for the tool,
- approval, audit, and client contract.
- Optional skill install:
- ```bash
- cerberus-re install --host codex
- cerberus-re install --host claude
- cerberus-re install --host both
- ```
- ## Requirements
- - Python 3.11+
- - Ghidra 12.x
- - Java 21
- - macOS, Linux, or Windows for the Python CLI and report tooling
- - macOS for Apple runtime attach workflows against local Apple frameworks
- - LLDB and Frida only for the workflows that use them
- Default paths can be overridden with environment variables documented in
- `templates/config.env.example`.
- ## Core Loop
- ```bash
- cerberus-re doctor
- cerberus-re bootstrap
- cerberus-re import analyze /path/to/Binary my_project
- cerberus-re export apple-bundle my_project BinaryName
- cerberus-re bridge arm my_project BinaryName
- cerberus-re bridge call /functions/search '{"query":"interestingName"}'
- cerberus-re validate lldb-trace my_project BinaryName --launch-cmd /path/to/host --symbols '-[Owner selector:]'
- cerberus-re validate lldb-trace my_project BinaryName --launch-cmd /path/to/host --symbols FirstExport --symbols SecondExport
- cerberus-re frida validate-scripts
- cerberus-re frida recheck-attach --target /path/to/owned-host --symbol '-[Owner selector:]' --allow-runtime
- cerberus-re export runtime-enrich my_project BinaryName /path/to/runtime_hits.json
- ```
- ## Useful Commands
- ```bash
- cerberus-re export xpc-surface my_project BinaryName
- cerberus-re export xpc-graph my_project:BinaryName other_project:OtherBinary
- cerberus-re export function-dossier my_project BinaryName --function '-[Owner selector:]'
- cerberus-re export triage-bundle my_project BinaryName --top-candidates 25
- cerberus-re polish release --mode quick --strict-command-surface
- ```
- If `export xpc-surface` reports zero counts, inspect `warnings` and
- `missing_input_count` before using that as absence evidence. Pass `--bundle-dir`
- or explicit export JSON paths when analyzing an Apple bundle stored outside the
- default export directory.
- Use `python3 -m cerberus_re_skill` or `cerberus-re` for automation. Generic
- long-running run state, steering files, durable project memory, and agent
- closeout orchestration belong in `long-run-agent`, not this workbench.
- ## Benchmarks
- The public benchmark scaffold defines a reproducible agent/task matrix without
- shipping benchmark results:
- ```bash
- python3 scripts/agent_benchmark.py list
- python3 scripts/agent_benchmark.py scaffold --runner codex --configuration cerberus-re-long-run-agent --output benchmarks/results/example/codex/cerberus-re-long-run-agent
- python3 scripts/agent_benchmark.py validate --bundle benchmarks/results/example/codex/cerberus-re-long-run-agent
- ```
- Use `benchmarks/agent_benchmark.v1.json` as the machine-readable source of
- truth. A scaffolded bundle is only a result after a real runner records durable
- commands, claims, artifacts, failures, and metrics.
- ## Safety Model
- - No runtime attach happens unless a command receives an explicit runtime flag.
- - Mutating bridge calls require explicit write opt-in.
- - Destructive bridge calls require a separate destructive opt-in.
- - Generated harnesses leave calls commented or bounded until the caller supplies target-specific objects.
- - Reports should distinguish successful runtime hits, no-hit status, attach blockers, and unverified assumptions.
- ## Repository Layout
- - `SKILL.md`: agent-facing operating procedure.
- - `cerberus_re_skill/`: Python CLI and report builders.
- - `cerberus_re_skill/mcp_server.py`: local stdio MCP and optional mission-tool composition.
- - `scripts/`: installer, helper scripts, sourced shell libraries, and Ghidra Java scripts.
- - `bridge-extension/`: Ghidra bridge source.
- - `references/`: public command and artifact references.
- - `benchmarks/`: benchmark definition, result-bundle scaffold, and future public result shapes.
- - `tests/`: smoke and regression tests.
- ## Validation
- Before publishing a milestone:
- ```bash
- python3 -m unittest discover -s tests
- python3 -m compileall cerberus_re_skill scripts tests
- python3 -m cerberus_re_skill polish release --mode quick --strict-command-surface
- python3 -m cerberus_re_skill bridge audit
- git diff --check
- ```
- ## License
- Apache-2.0. See `LICENSE`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.