mcpField
H
headless-ghidra-batch-decompile

headless-ghidra-batch-decompile

github.com/bytelandtechnologyDevelopment5114 installsUpdated 25w ago
Repository

About headless-ghidra-batch-decompile

headless-ghidra-batch-decompile defines a CLI workflow for processing selected function batches with Ghidra decompilation and substitution artifacts. It is intended for users running the P4 phase through ghidra-agent-cli, with batch scope and provenance requirements.

Key features

  1. 01Apply and verify renames
  2. 02Apply and verify signatures
  3. 03Ghidra decompilation
  4. 04Record function-level artifacts
  5. 05Validate substitutions and P4 gate

Use cases

  1. 01Decompiling the active function batch
  2. 02Applying enriched function metadata
  3. 03Recording fixtures before substitution
  4. 04Checking P4 batch readiness

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/bytelandtechnology/headless-ghidra --skill headless-ghidra-batch-decompile

After installing, type/headless-ghidra-batch-decompilein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.ja-JP.md
README.md
README.zh-CN.md

Details

From the project README

Headless Ghidra Function Substitution — P4

P4 consumes the current selected batch, applies enriched metadata, runs the approved Ghidra decompilation path, and records per-function substitution artifacts.

Required ghidra-agent-cli Commands

  • ghidra-agent-cli ghidra apply-renames
  • ghidra-agent-cli ghidra verify-renames
  • ghidra-agent-cli ghidra apply-signatures
  • ghidra-agent-cli ghidra verify-signatures
  • ghidra-agent-cli ghidra decompile
  • ghidra-agent-cli ghidra rebuild-project
  • ghidra-agent-cli substitute add
  • ghidra-agent-cli substitute validate
  • ghidra-agent-cli gate check --phase P4

Locking and Ghidra invocation are handled internally by the CLI. The public workflow surface is the CLI plus the YAML outputs below. When substitution/next-batch.yaml is ready, process only functions with clear P3 names and signatures.

Inputs

  • artifacts/<target-id>/baseline/*.yaml
  • artifacts/<target-id>/runtime/fixtures/
  • artifacts/<target-id>/runtime/hotpaths/call-chain.yaml
  • artifacts/<target-id>/third-party/identified.yaml
  • artifacts/<target-id>/third-party/pristine/<library>@<version>/
  • artifacts/<target-id>/third-party/compat/<library>@<version>/ if needed
  • artifacts/<target-id>/metadata/renames.yaml
  • artifacts/<target-id>/metadata/signatures.yaml
  • artifacts/<target-id>/substitution/next-batch.yaml

Outputs

  • artifacts/<target-id>/substitution/functions/<fn_id>/capture.yaml
  • artifacts/<target-id>/substitution/functions/<fn_id>/substitution.yaml
  • Additional per-function YAML such as blocked, injected, or follow-up records when the workflow records them

Exit Expectations

  • Function-level I/O fixtures and capture YAML are recorded before coding a substitute.
  • Each substituted function has a substitution.yaml with provenance, fixtures, and status.
  • P4 gate material is available under substitution/functions/<fn_id>/.

Constraints

  • Use Ghidra as the only decompilation backend.
  • Acquire the Ghidra queue/lock before mutating or reading shared Ghidra state when the backend requires it.
  • Do not modify artifacts for functions outside the active batch.
  • Do not bypass ghidra-agent-cli for supported apply/verify/decompile, substitution, fixture, or gate actions.
  • Do not modify pristine third-party source; place local adaptation changes under third-party/compat/.
  • Do not create or run a new Ghidra script if the CLI lacks a capability; pause and ask the user first.

Next Step

  • P4 gate passes for the batch → return to P3 for another round or finish.

Comments

Markdown supported