Ghidra Server Architecture and Team Collaboration Setup Guide

Ghidra Server uses an RMI-based architecture with SSL-protected communication to enable real-time collaboration on reverse engineering projects through version-controlled shared repositories.

The Ghidra Server is the central collaboration service in the NationalSecurityAgency/ghidra repository that allows multiple analysts to share projects, track file versions, and work simultaneously on binary analysis tasks. Understanding the Ghidra Server architecture is essential for teams needing secure, concurrent access to reverse engineering assets across distributed environments.

Core Architecture Components

The server follows a modular design where the same binaries function on developer workstations, CI headless nodes, or production servers. Each component handles specific responsibilities within the distributed system.

Main Entry Point and RMI Registry

The GhidraServer class serves as the bootstrap mechanism. Located at Ghidra/Features/GhidraServer/src/main/java/ghidra/server/remote/GhidraServer.java, this component starts an RMI registry on a configurable port, instantiates SSL socket factories via ServerPortFactory.getRMISSLPort(), and registers a single GhidraServerHandle object that clients use for all remote procedure calls.

Remote Interface and Client Communication

The GhidraServerHandle interface (implemented by GhidraServer) exposes remote methods for repository lookup, authentication, and block-stream creation. Found in Ghidra/Framework/Remote/src/main/java/ghidra/framework/remote/GhidraServerHandle.java, this interface funnels all client-side operations through a centralized remote proxy.

Repository Management

Two classes manage persistent storage:

• RepositoryManager (Ghidra/Features/GhidraServer/src/main/java/ghidra/server/RepositoryManager.java): Manages the set of repositories under the server's root directory, handling creation, deletion, and lookup while enforcing read/write privileges.
• Repository (Ghidra/Features/GhidraServer/src/main/java/ghidra/server/Repository.java): Represents a single version-controlled repository on disk, storing data in an indexed filesystem (IndexedLocalFileSystem) that provides fast random access and automatic index rebuilding.

Authentication and Security

The UserManager (Ghidra/Features/GhidraServer/src/main/java/ghidra/server/UserManager.java) maintains authorized user lists through password files, Active Directory, PKI, or JAAS modules. Pluggable authentication implementations include:

• PasswordFileAuthenticationModule for local password files
• PKIAuthenticationModule for certificate-based access
• JAASAuthenticationModule for enterprise integration

The entire stack is SSL-protected by default, with configurable TLS protocol versions controlled via TLS_SERVER_PROTOCOLS_PROPERTY in GhidraServer.java.

High-Performance Data Transfer

The BlockStreamServer (Ghidra/Features/GhidraServer/src/main/java/ghidra/server/stream/BlockStreamServer.java) provides high-throughput binary streaming for large files such as program binaries and symbol files. Accessed via RemoteBlockStreamHandle, this component uses dedicated SSL sockets to keep the regular RMI channel lightweight.

Communication Flow

The interaction between clients and server follows a strict sequence:

1. Server Startup: GhidraServer.main() parses command-line options (IP, port, authentication mode), creates the appropriate AuthenticationModule, and registers the server in the RMI registry.

2. Client Connection: Ghidra UI or headless scripts build a GhidraURL object (parsed by Ghidra/Framework/Project/src/main/java/ghidra/framework/protocol/ghidra/GhidraURL.java), which contacts the RMI registry, obtains the remote GhidraServerHandle, and authenticates via the selected module.

3. Repository Access: After authentication, the client requests a RepositoryHandle. The server returns a proxy forwarding all filesystem operations to the underlying Repository instance.

4. Data Transfer: Large binary blobs travel through the BlockStreamServer using dedicated SSL sockets, isolating bulk data from control messages.

Setting Up Ghidra Server for Team Collaboration

Prepare the Repository Root

Create a dedicated directory for version-controlled projects:

SERVER_ROOT=/opt/ghidra/server_repo
mkdir -p "$SERVER_ROOT"
chmod 770 "$SERVER_ROOT"

The root directory holds one subdirectory per repository. Names are mangled internally (e.g., My_Project becomes _my___project).

Configure Authentication

For password-file authentication, generate salted hashes using the Ghidra utility:

$GHIDRA_HOME/support/create_user.sh admin

Append additional users as needed. The password file path is referenced with the -p flag during server startup.

Launch the Server

Start the server with SSL enabled and password authentication:

java -cp "$GHIDRA_HOME/build/libs/ghidra.jar" \
    ghidra.server.remote.GhidraServer \
    -ip 0.0.0.0 \
    -p /opt/ghidra/server_repo \
    -a0 \
    -jaas none

Key command-line options (documented in GhidraServer.USAGE_ARGS):

• -ip <hostname>: Bind address (0.0.0.0 for all interfaces)
• -p <repoPath>: Root repository directory
• -a#: Authentication mode (0=password file, 1=AD/Kerberos, 2=PKI, 4=JAAS)
• -anonymous: Allow read-only anonymous access
• -autoProvision: Create missing users automatically after successful authentication

Create Shared Repositories

From the Ghidra UI:

1. Select File → New Project → Shared Project
2. Choose Ghidra Server as the location
3. Enter the server URL: ghidra://myhost/TeamRepo
4. Supply credentials when prompted

Programmatically, use the GhidraServerHandle API:

import ghidra.framework.remote.GhidraServerHandle;
import ghidra.framework.protocol.ghidra.GhidraURL;

GhidraServerHandle server = GhidraURL.getServerHandle("ghidra://myhost");
server.createRepository("admin", "TeamRepo");

Connect Team Members

Collaborators connect using the standard URL format:

ghidra://myhost/TeamRepo

Once authenticated, all changes are version-controlled on the server and immediately visible to other connected users.

Practical Configuration Examples

Production Server Startup Script

#!/bin/bash

# start_ghidra_server.sh

GHIDRA_HOME=/opt/ghidra
REPO_ROOT=/opt/ghidra/server_repo

java -cp "$GHIDRA_HOME/build/libs/ghidra.jar" \
     ghidra.server.remote.GhidraServer \
     -ip 0.0.0.0 \
     -p "$REPO_ROOT" \
     -a0 \
     -jaas none \
     -d mydomain.com \
     -autoProvision \
     -anonymous

Headless Repository Creation

import ghidra.framework.remote.GhidraServerHandle;
import ghidra.framework.protocol.ghidra.GhidraURL;
import ghidra.framework.remote.RepositoryHandle;

public class TeamSetup {
    public static void main(String[] args) throws Exception {
        GhidraServerHandle server = GhidraURL.getServerHandle("ghidra://myhost");
        server.createRepository("admin", "MalwareAnalysis2024");
        
        RepositoryHandle repo = server.getRepository("MalwareAnalysis2024");
        System.out.println("Repository created with handle: " + repo);
    }
}

Accessing Shared Programs

import ghidra.framework.remote.GhidraServerHandle;
import ghidra.framework.remote.RepositoryHandle;
import ghidra.framework.protocol.ghidra.GhidraURL;
import ghidra.program.model.listing.Program;

public class SharedAccess {
    public static void main(String[] args) throws Exception {
        GhidraServerHandle server = GhidraURL.getServerHandle("ghidra://myhost");
        RepositoryHandle repo = server.getRepository("MalwareAnalysis2024");
        Program prog = repo.getProgram("sample.exe", true);
        System.out.println("Loaded program entry point: " + prog.getEntryPoint());
    }
}

Summary

• Ghidra Server operates as an RMI-based service with SSL-encrypted communication, defaulting to port 13100.
• The architecture separates concerns between connection handling (GhidraServer), repository management (RepositoryManager), and authentication (UserManager).
• Indexed filesystems provide fast random access to version-controlled data stored in the server root directory.
• Pluggable authentication supports password files, Active Directory, PKI, and JAAS through command-line flags (-a0 through -a4).
• Block-stream servers isolate large file transfers from RMI control channels to maintain responsiveness.
• Administrative tasks can be performed via ServerAdmin.java for repository migration and diagnostics.

Frequently Asked Questions

What network ports does Ghidra Server require?

Ghidra Server defaults to port 13100 for RMI registry communication. The BlockStreamServer allocates additional ephemeral ports for SSL data transfer. Configure the primary port using the -ip option followed by the port number (e.g., -ip 0.0.0.0:13100). Firewall rules must allow outbound connections from clients to these ports on the server host.

How does Ghidra Server handle user authentication?

The server supports four authentication modes selected via the -a flag: password files (-a0), Active Directory/Kerberos (-a1), PKI certificates (-a2), and JAAS (-a4). The UserManager class enforces password expiration policies and supports anonymous read-only access when the -anonymous flag is enabled. For enterprise environments, PKIAuthenticationModule or JAASAuthenticationModule provides integration with existing identity infrastructure.

Can Ghidra Server run on Windows Server?

Yes. The Java-based architecture runs on any platform supporting a Java Runtime Environment. Windows deployments should adjust file paths in startup scripts and ensure the repository root directory has appropriate NTFS permissions. Use Windows Service wrappers or scheduled tasks to maintain server persistence, as the ghidraRun wrapper and GhidraServer class work identically across platforms.

How do I backup Ghidra Server repositories?

Backup the repository root directory specified by the -p flag. Each repository subdirectory contains an IndexedLocalFileSystem with data files and index metadata. Use ServerAdmin.java (located at Ghidra/Features/GhidraServer/src/main/java/ghidra/server/ServerAdmin.java) to gracefully pause writes during backup windows. The server supports repository migration and integrity checking through command-line admin tools documented in the server's usage output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}