ghidra-cli 0.1.10

Rust CLI to run Ghidra headless for reverse engineering with Claude Code and other agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# Common Test Utilities

Shared infrastructure for E2E tests.

## DaemonTestHarness

Manages bridge lifecycle for test suites requiring Ghidra bridge interaction.

### Usage

```rust
use common::{DaemonTestHarness, ensure_test_project};

const TEST_PROJECT: &str = "my-test";
const TEST_PROGRAM: &str = "sample_binary";

#[test]
#[serial]
fn test_with_bridge() {
    ensure_test_project(TEST_PROJECT, TEST_PROGRAM);

    let harness = DaemonTestHarness::new(TEST_PROJECT, TEST_PROGRAM)
        .expect("Failed to start bridge");

    Command::cargo_bin("ghidra")
        .unwrap()
        .arg("--project")
        .arg(TEST_PROJECT)
        .arg("my-command")
        .arg("--program")
        .arg(TEST_PROGRAM)
        .assert()
        .success();

    // Bridge automatically shuts down when harness drops
}
```

### Port File Discovery

Each harness discovers the bridge via port file:
```
~/.local/share/ghidra-cli/bridge-{md5_hash}.port
```

Where `{md5_hash}` is derived from the canonical project path. The harness reads the port number from this file and connects via TCP.

### Cleanup Guarantees

Drop implementation ensures best-effort cleanup:
1. Send shutdown command via TCP (ignores errors)
2. Bridge deletes its own port/PID files on clean shutdown
3. Kill process via PID if still running

## Fixtures

### fixture_binary()

Returns path to compiled sample_binary fixture.

```rust
let binary = fixture_binary();
assert!(binary.exists());
```

Binary must be compiled before tests:
```bash
rustc --edition 2021 -o tests/fixtures/sample_binary tests/fixtures/sample_binary.rs
```

### ensure_test_project()

Idempotent project setup using `Once::call_once`. Imports and analyzes sample_binary if needed.

```rust
ensure_test_project("my-project", "sample_binary");
// Second call does nothing - project already exists
```

Handles "already exists" errors gracefully. Safe to call from multiple tests.

## require_ghidra! Macro

Tests should call this macro to assert Ghidra availability up front:

```rust
#[test]
fn test_something() {
    require_ghidra!();

    // Test code runs only if ghidra doctor succeeds
}
```

Runs `ghidra doctor` and fails the test if Ghidra is unavailable, including doctor output.

## GhidraCommand Builder (helpers.rs)

Fluent builder for constructing CLI commands in tests:

```rust
use common::helpers::{ghidra, GhidraCommand};

let result = ghidra(&harness)
    .arg("function")
    .arg("list")
    .run();

result.assert_success();
```

The `ghidra(&harness)` helper pre-configures `--project` args from the harness. Additional helpers include `with_project()`, `json_format()`, and `timeout()`.

## Design Decisions

### Exponential Backoff Parameters

`wait_for_port()` uses backoff to wait for the bridge port file to appear after launching `analyzeHeadless`. Typical fast start exits in <5s.

### Why 5s Shutdown Timeout

Most bridges shut down in <1s. 5s allows graceful cleanup without blocking tests indefinitely. If bridge hangs, hard kill via PID prevents test suite deadlock.