Skip to content
Back to search

cerberus-re

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/owenpawl--cerberus-re-skill/badge.svg)](/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

i

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)

  1. ---
  2. name: cerberus-re
  3. 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.
  4. ---
  5. # Cerberus RE
  6. Use this skill for local Apple-focused reverse engineering with a repeatable
  7. three-headed static/dynamic/instrumentation loop around Ghidra, LLDB, and
  8. Frida. The public CLI is `cerberus-re`.
  9. [`long-run-agent`](https://github.com/OwenPawl/long-run-agent-skill) is a
  10. strongly encouraged companion dependency for substantial work. Use it to
  11. preserve mission state, claims, artifacts, failures, friction, and next actions
  12. while Cerberus RE handles static, dynamic, and instrumentation evidence.
  13. Cerberus RE can still run alone for bounded one-off tasks.
  14. When driving through MCP, prefer `cerberus-mcp`. It exposes the core RE loop
  15. and composes long-run-agent's namespaced `mission_*` tools into the same local
  16. stdio server when the companion package or installed skill is available. Check
  17. `mission_companion_status` before assuming durable mission tools exist.
  18. ## Operating Contract
  19. - Resolve the repo or installed skill root first. If working from this checkout,
  20. run commands from the repo root.
  21. - Prefer the Python CLI: `cerberus-re` or `python3 -m cerberus_re_skill`.
  22. - Prefer `cerberus-mcp` when the host supports MCP; use its typed envelope
  23. status rather than parsing prose.
  24. - Keep generated evidence as JSON or Markdown artifacts, not terminal-only output.
  25. - Use durable workspace paths under `~/ghidra-projects`.
  26. - Preserve dirty worktree changes you did not make.
  27. - Capture runtime validation before treating runtime behavior as understood.
  28. - Keep ranking and prioritization framed as safe reverse-engineering workflow.
  29. - Runtime attach is guarded. Frida rechecks stay artifact-only unless
  30. `--allow-runtime` is explicit.
  31. - Mutating bridge calls require `write=true`; destructive bridge calls also
  32. require `destructive=true`.
  33. ## First Commands
  34. ```bash
  35. git status --short --branch
  36. python3 scripts/install_dependencies.py
  37. cerberus-re doctor
  38. cerberus-re bootstrap
  39. cerberus-re bridge audit
  40. ```
  41. Run `python3 scripts/install_dependencies.py --execute` from a fresh checkout
  42. when the host needs a local virtual environment or macOS Homebrew-managed
  43. dependencies.
  44. ## Static Workflow
  45. ```bash
  46. cerberus-re import analyze <binary-or-source-ref> <project_name>
  47. cerberus-re export apple-bundle <project_name> <program_name>
  48. cerberus-re export xpc-surface <project_name> <program_name>
  49. ```
  50. If a standalone Mach-O target fails while Ghidra resolves reexported
  51. dependencies, retry with:
  52. ```bash
  53. cerberus-re import analyze <binary-or-source-ref> <project_name> --skip-macho-reexports
  54. ```
  55. Record that the resulting static view excludes reexport behavior.
  56. For universal Mach-O targets, choose the intended runtime slice explicitly:
  57. ```bash
  58. cerberus-re import analyze <binary-or-source-ref> <project_name> --macho-arch arm64e
  59. ```
  60. This stages a thin copy under the Cerberus RE workspace before import.
  61. If a specific Ghidra analyzer reproducibly blocks import, disable only that
  62. named analyzer and record the exception in the evidence report:
  63. ```bash
  64. cerberus-re import analyze <binary-or-source-ref> <project_name> \
  65. --disable-analysis-option "Objective-C Selector Trampoline Analysis"
  66. ```
  67. ## Runtime Workflow
  68. Use LLDB when you can launch or safely attach to a process:
  69. ```bash
  70. cerberus-re validate lldb-trace <project> <program> \
  71. --launch-cmd <binary> \
  72. --symbols '<symbol-or-selector>' \
  73. --binary <binary>
  74. ```
  75. Pass multiple LLDB trace symbols either by repeating `--symbols` or with a
  76. comma-separated value; both forms are normalized before tracing.
  77. For dyld-cache-backed Apple frameworks, the live `/System/Library/...framework`
  78. path may be a stub without an on-disk Mach-O. Use the extracted dyld-cache
  79. binary for `--binary`, while the launch or attach target remains the live
  80. process under test.
  81. If the static export under test is saved outside the default export tree, add:
  82. ```bash
  83. --function-inventory /path/to/function_inventory.json
  84. ```
  85. Use Frida for guarded instrumentation:
  86. ```bash
  87. cerberus-re frida diagnose --target <binary>
  88. cerberus-re frida validate-scripts --symbol '<ObjC method>' --class-name <Class>
  89. cerberus-re frida recheck-attach \
  90. --target <owned-binary> \
  91. --symbol '<ObjC method>' \
  92. --capture-returns \
  93. --allow-runtime
  94. cerberus-re frida recheck-attach \
  95. --attach-pid <pid> \
  96. --selector '<ObjC selector>' \
  97. --class-filter '<ClassSubstring>' \
  98. --require-runtime-hit \
  99. --allow-runtime
  100. cerberus-re frida recheck-attach \
  101. --attach-pid <pid> \
  102. --selector '<ObjC selector>' \
  103. --exact-class '<KnownClass>' \
  104. --require-runtime-hit \
  105. --allow-runtime
  106. cerberus-re frida recheck-attach \
  107. --target <owned-binary> \
  108. --native-symbol 'ExampleFramework!late_loaded_export' \
  109. --native-wait-seconds 3 \
  110. --native-arg-preview \
  111. --require-runtime-hit \
  112. --allow-runtime
  113. cerberus-re frida gadget-probe <owned-binary> \
  114. --gadget /path/to/FridaGadget.dylib \
  115. --script /path/to/autonomous-probe.js \
  116. --stable-target-key <stable-owned-target-id> \
  117. --output-dir /tmp/cerberus-gadget-evidence \
  118. --allow-runtime
  119. ```
  120. Prefer `Module!symbol` for native exports when the intended framework or dylib
  121. is known. Unqualified native symbols remain supported, but an installed
  122. zero-hit unqualified hook is ambiguous evidence and should usually be retried
  123. with module qualification. Exact ObjC method hooks (`--symbol`), selector-wide
  124. ObjC hooks (`--selector`), and native hooks (`--native-symbol` or `--address`)
  125. are separate Frida recheck modes; run separate commands when you need coverage
  126. from more than one mode. Native hooks always preserve raw register strings under
  127. `args`; `--native-arg-preview` adds bounded best-effort string/module previews
  128. for readable values. If task-port attachment is blocked for an owned analysis
  129. copy, `gadget-probe` can launch that copy with a content-addressed Gadget,
  130. configuration, and autonomous script through `DYLD_INSERT_LIBRARIES`. Treat
  131. this as launch-injection evidence, not proof that ordinary Frida attach works.
  132. for those registers without making signature-correctness claims.
  133. After LLDB or Frida emits `runtime_hits.json`, correlate it back to static
  134. context:
  135. ```bash
  136. cerberus-re export runtime-enrich <project> <program> <runtime_hits.json>
  137. ```
  138. ## Bridge Workflow
  139. Use the live bridge when an interactive loop is faster than repeated exports:
  140. ```bash
  141. cerberus-re bridge arm <project_name> [program_name]
  142. cerberus-re bridge sessions
  143. cerberus-re bridge call /functions/search '{"query":"SomeFunction"}'
  144. cerberus-re bridge call /decompile '{"function":"SomeFunction"}'
  145. cerberus-re bridge close --project <project_name>
  146. ```
  147. ## XPC Workflow
  148. - Export XPC surfaces with `cerberus-re export xpc-surface`.
  149. - If an XPC report shows zero counts, check `warnings` and `missing_input_count`
  150. before treating it as real absence evidence; pass `--bundle-dir` or explicit
  151. export JSON paths when using an Apple bundle saved outside the default export
  152. directory.
  153. - Merge surfaces with `cerberus-re export xpc-graph`.
  154. - Use owner hints only until imported owner evidence confirms or disproves them.
  155. - Generate harness skeletons only after service, protocol, and endpoint evidence
  156. are concrete enough to rank.
  157. - Recover `NSXPCInterface` factory/configuration evidence before planning a
  158. bounded remote method probe.
  159. ## Validation
  160. Before a milestone push or release closeout, run:
  161. ```bash
  162. python3 -m unittest discover -s tests
  163. python3 -m compileall cerberus_re_skill scripts tests
  164. python3 -m cerberus_re_skill polish release --mode quick --strict-command-surface
  165. git diff --check
  166. python3 -m cerberus_re_skill bridge audit
  167. ```
  168. Add targeted live/static validation when changing Ghidra, LLDB, or Frida behavior.
  169. ## References
  170. Read only the file needed for the current task:
  171. - `references/operating-workflows.md`: detailed workflows and fallback rules.
  172. - `references/command-surface.md`: public CLI catalog.
  173. - `references/output-files.md`: artifact paths, schemas, and report meanings.
  174. - `references/raw-bridge-recipes.md`: bridge endpoint payloads and examples.
  175. - `references/frida-diagnostics.md`: Frida policy and validation guidance.
  176. - `references/apple-macho-notes.md`: Apple Mach-O and dyld target notes.
  177. - `references/builtins.md`: built-in Ghidra script caveats.
  178. - `references/triage-outputs.md`: triage output details.
  179. - `references/triage-patterns.json`: triage heuristic categories.
  180. - `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)

  1. # Cerberus RE
  2. `cerberus-re` is a local Apple-focused reverse-engineering workbench for
  3. building a repeatable three-headed static/dynamic/instrumentation loop around
  4. Ghidra, LLDB, and Frida.
  5. It is designed for analysts and coding agents that need durable artifacts
  6. instead of terminal-only notes:
  7. - Ghidra import, headless export, decompilation, xrefs, and metadata recovery.
  8. - LLDB runtime traces with static enrichment back into exported function context.
  9. - Frida diagnostics, guarded runtime rechecks, Objective-C probes, and heap or archive inspection helpers.
  10. - XPC surface and graph reports from exported Objective-C/string/symbol data.
  11. - RE evidence reports, notes, case files, and release-gate validation checks.
  12. - Cross-platform Python CLI support for macOS, Linux, Windows, OpenAI Codex, and Claude Code.
  13. Runtime attach and target invocation are always explicit. The tooling favors
  14. owned processes, no-attach validation, generated artifacts, and bounded probes
  15. whose assumptions are recorded alongside the evidence.
  16. ## Public Scope
  17. The public workbench is general Apple binary-analysis infrastructure: Ghidra
  18. imports and exports, LLDB/Frida correlation, Mach-O/ObjC/Swift/XPC evidence,
  19. and portable reports. It is not a project-specific research log or a generic
  20. long-running agent memory system. Domain-specific research workflows should
  21. live in private overlays or durable run artifacts, while generic long-run state
  22. belongs in `long-run-agent`.
  23. ## Strongly Encouraged Companion Dependency
  24. Use Cerberus RE with
  25. [`long-run-agent`](https://github.com/OwenPawl/long-run-agent-skill) for
  26. substantial reverse-engineering work.
  27. Cerberus RE provides the static, dynamic, and instrumentation workbench;
  28. `long-run-agent` preserves mission state, claims, artifacts, failures, friction,
  29. and next actions so longer investigations stay auditable and resumable.
  30. Cerberus RE can run by itself for bounded tasks, but benchmark and release
  31. workflows should prefer the combined `cerberus-re + long-run-agent`
  32. configuration.
  33. ## Install
  34. For a fresh checkout, start with the dependency installer in dry-run mode:
  35. ```bash
  36. python3 scripts/install_dependencies.py
  37. python3 scripts/install_dependencies.py --execute
  38. source .venv/bin/activate
  39. cerberus-re bootstrap
  40. ```
  41. The installer creates a local virtual environment, installs Cerberus RE, and
  42. adds Frida Python tooling. On macOS with Homebrew it can install Ghidra/Java
  43. and Node. On Linux and Windows it prints package-manager-specific commands for
  44. review instead of running system installs automatically.
  45. If your system dependencies are already present:
  46. ```bash
  47. pip install -e .
  48. cerberus-re bootstrap
  49. ```
  50. Install the strongly encouraged mission companion when you want one unified
  51. local MCP server:
  52. ```bash
  53. pip install git+https://github.com/OwenPawl/long-run-agent-skill.git
  54. pip install -e .
  55. cerberus-mcp
  56. ```
  57. `cerberus-mcp` exposes first-class tools for the core Ghidra/LLDB/Frida loop,
  58. guarded runtime and bridge operations, restart-safe background jobs, and a
  59. bounded `cerberus_run` escape hatch. When long-run-agent is installed, the same
  60. server also composes its namespaced `mission_*` tools for durable control,
  61. claims, artifacts, friction, search, and closeout. Cerberus remains usable by
  62. itself for bounded work; `mission_companion_status` reports whether composition
  63. succeeded.
  64. Example local MCP client configuration:
  65. ```json
  66. {
  67. "mcpServers": {
  68. "cerberus-re": {
  69. "command": "/absolute/path/to/venv/bin/cerberus-mcp",
  70. "env": {
  71. "GHIDRA_WORKSPACE": "/absolute/path/to/ghidra-projects",
  72. "CERBERUS_MCP_STRICT_SURFACE": "1"
  73. }
  74. }
  75. }
  76. }
  77. ```
  78. See [`references/mcp-server.md`](references/mcp-server.md) for the tool,
  79. approval, audit, and client contract.
  80. Optional skill install:
  81. ```bash
  82. cerberus-re install --host codex
  83. cerberus-re install --host claude
  84. cerberus-re install --host both
  85. ```
  86. ## Requirements
  87. - Python 3.11+
  88. - Ghidra 12.x
  89. - Java 21
  90. - macOS, Linux, or Windows for the Python CLI and report tooling
  91. - macOS for Apple runtime attach workflows against local Apple frameworks
  92. - LLDB and Frida only for the workflows that use them
  93. Default paths can be overridden with environment variables documented in
  94. `templates/config.env.example`.
  95. ## Core Loop
  96. ```bash
  97. cerberus-re doctor
  98. cerberus-re bootstrap
  99. cerberus-re import analyze /path/to/Binary my_project
  100. cerberus-re export apple-bundle my_project BinaryName
  101. cerberus-re bridge arm my_project BinaryName
  102. cerberus-re bridge call /functions/search '{"query":"interestingName"}'
  103. cerberus-re validate lldb-trace my_project BinaryName --launch-cmd /path/to/host --symbols '-[Owner selector:]'
  104. cerberus-re validate lldb-trace my_project BinaryName --launch-cmd /path/to/host --symbols FirstExport --symbols SecondExport
  105. cerberus-re frida validate-scripts
  106. cerberus-re frida recheck-attach --target /path/to/owned-host --symbol '-[Owner selector:]' --allow-runtime
  107. cerberus-re export runtime-enrich my_project BinaryName /path/to/runtime_hits.json
  108. ```
  109. ## Useful Commands
  110. ```bash
  111. cerberus-re export xpc-surface my_project BinaryName
  112. cerberus-re export xpc-graph my_project:BinaryName other_project:OtherBinary
  113. cerberus-re export function-dossier my_project BinaryName --function '-[Owner selector:]'
  114. cerberus-re export triage-bundle my_project BinaryName --top-candidates 25
  115. cerberus-re polish release --mode quick --strict-command-surface
  116. ```
  117. If `export xpc-surface` reports zero counts, inspect `warnings` and
  118. `missing_input_count` before using that as absence evidence. Pass `--bundle-dir`
  119. or explicit export JSON paths when analyzing an Apple bundle stored outside the
  120. default export directory.
  121. Use `python3 -m cerberus_re_skill` or `cerberus-re` for automation. Generic
  122. long-running run state, steering files, durable project memory, and agent
  123. closeout orchestration belong in `long-run-agent`, not this workbench.
  124. ## Benchmarks
  125. The public benchmark scaffold defines a reproducible agent/task matrix without
  126. shipping benchmark results:
  127. ```bash
  128. python3 scripts/agent_benchmark.py list
  129. python3 scripts/agent_benchmark.py scaffold --runner codex --configuration cerberus-re-long-run-agent --output benchmarks/results/example/codex/cerberus-re-long-run-agent
  130. python3 scripts/agent_benchmark.py validate --bundle benchmarks/results/example/codex/cerberus-re-long-run-agent
  131. ```
  132. Use `benchmarks/agent_benchmark.v1.json` as the machine-readable source of
  133. truth. A scaffolded bundle is only a result after a real runner records durable
  134. commands, claims, artifacts, failures, and metrics.
  135. ## Safety Model
  136. - No runtime attach happens unless a command receives an explicit runtime flag.
  137. - Mutating bridge calls require explicit write opt-in.
  138. - Destructive bridge calls require a separate destructive opt-in.
  139. - Generated harnesses leave calls commented or bounded until the caller supplies target-specific objects.
  140. - Reports should distinguish successful runtime hits, no-hit status, attach blockers, and unverified assumptions.
  141. ## Repository Layout
  142. - `SKILL.md`: agent-facing operating procedure.
  143. - `cerberus_re_skill/`: Python CLI and report builders.
  144. - `cerberus_re_skill/mcp_server.py`: local stdio MCP and optional mission-tool composition.
  145. - `scripts/`: installer, helper scripts, sourced shell libraries, and Ghidra Java scripts.
  146. - `bridge-extension/`: Ghidra bridge source.
  147. - `references/`: public command and artifact references.
  148. - `benchmarks/`: benchmark definition, result-bundle scaffold, and future public result shapes.
  149. - `tests/`: smoke and regression tests.
  150. ## Validation
  151. Before publishing a milestone:
  152. ```bash
  153. python3 -m unittest discover -s tests
  154. python3 -m compileall cerberus_re_skill scripts tests
  155. python3 -m cerberus_re_skill polish release --mode quick --strict-command-surface
  156. python3 -m cerberus_re_skill bridge audit
  157. git diff --check
  158. ```
  159. ## License
  160. Apache-2.0. See `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.