From the root directory of your Ghidra release, run the following command.
./docker/build-docker-image.sh
This will build the ghidra docker image with a tag corresponding to the release version of Ghidra.
The Ghidra Docker Container supports the following MODE
's of execution:
The MODE
environment variable designates which entrypoint of Ghidra to execute.
The entrypoint.sh
script is executed upon container startup.
Configuration of a container is done just as any other docker container would be configured. Volumes can be mounted, environment variables can be set, ports can be mapped from container to the host, and so on. Configuration steps vary a lot based on what MODE the container is started with.
The base directory for Ghidra within the container is located at /ghidra
.
All of ghidra's default locations for files, configs, etc., are the same within that.
Ghidra is run as the user ghidra
within the container, with uid 1001
and guid 1001
.
The ghidra
user only has permissions to the following directories inside the container:
/ghidra
/home/ghidra
When a container does not receive any arguments passed to it with the docker run
command,
the corresponding Command Line Interface (CLI) for the MODE
executed will display it's usage statement.
Volumes within the container may run into permission issues if the volumes are not accessible by users in the group id 1001
.
The default uid and guid for the container is 1001:1001
. Volumes that get mapped to the container should be accessible by this uid/guid.
Adding the host machine's user to the group 1001
on the host helps manage volumes that will be used in the container.
This can easily be done by executing sudo usermod -aG 1001 <user>
on Linux.
docker run \
--env MODE=headless \
--rm \
--volume /path/to/myproject:/home/ghidra/myproject \
--volume /path/to/mybinary:/home/ghidra/mybinary \
ghidra/ghidra:<version> \
/home/ghidra/myproject programFolder -import /home/ghidra/mybinary
Breaking this down line by line:
docker run
is going to start a docker container using the image ghidra/ghidra<:<version>
--env MODE=headless
configures the environment variable MODE
within the container to be the value headless
--rm
removes the container after the command is complete--volume /path/to/myproject:/home/ghidra/myproject
mounts the local volume
/path/to/myproject
on the host to /home/ghidra/myproject
within the container--volume /path/to/mybinary:/home/ghidra/mybinary
mounts the local volume
/path/to/mybinary
on the host to /home/ghidra/mybinary
within the containerghidra/ghidra:<version>
is the full reference for the docker image, where ghidra/ghidra
is the group and name of the image, and <version>
is the tag./home/ghidra/myproject programFolder -import /home/ghidra/mybinary
are arguments being passed to Ghidra's headless analyzer's command line interfacePassing no arguments will result in the usage of the headless analyzer being displayed.
/path/to/myproject
on the host must be accessible to guid 1001
with rwx
permissions.
Running Ghidra's Graphical User Interface (GUI) in the docker container is not a recommended method for running Ghidra. GUI's are not a typical use case for dockerized applications.
docker run \
--env MODE=gui \
-it \
--rm \
--net host \
--env DISPLAY \
--volume "$HOME/.Xauthority:/home/ghidra/.Xauthority" \
ghidra/ghidra:<version>
In this mode, the container relies on X11 forwarding to display the GUI. Configuration of X11 can vary, but in this case, the host's Xauthority file is mounted into the container, the container is configured to use the host's network, and the DISPLAY environment variable is passed to the container. This enables forwarding the GUI back to the host machine's display. Volumes containing binaries would still need to be mounted to the container as well as volumes for ghidra projects.
The host's .Xauthority
file must have appropriate permissions - assigned the group:1001
with rw
group permissions.
docker run \
--env MODE=ghidra-server \
--rm \
-it \
--volume /path/to/my/repositories:/ghidra/repositories \
--volume /path/to/my/configs/server.conf:/ghidra/server/server.conf \
-p 13100:13100 \
-p 13101:13101 \
-p 13102:13102 \
ghidra/ghidra:<version>
Volumes would need to be mounted to the server container to save the repositories, users, and also to configure the server as well.
To utilize svrAdmin, exec into the running ghidra server container (docker exec -it <container-id> bash
) for a bash shell in the container.
After exec'ing into the container, administration and management of the Ghidra server is the same as outside of a containerized environment.
To stop the container, execute the command docker stop <container-id>
.
docker run \
--env MODE=bsim-server \
--rm \
-it \
--volume /path/to/my/datadir:/ghidra/bsim_datadir \
-p 5432:5432 \
ghidra/ghidra:<version> \
/ghidra/bsim_datadir
/ghidra/bsim_datadir
is the directory used to store bsim's data in the container. Other directories could be used on the container,
but make sure that the folder on the host machine has appropriate permissions, assigned the group :1001
.
This example simply starts a bsim server. Configuring the bsim server and populating it with data
could be done post start within the container in a similar way that ghidra server administration is done.
An administrator would have to exec into the running bsim server container (docker exec -it <container-id> bash
),
and after exec'ing into the container, administration and management of the Bsim server is the same as outside of a containerized environment.
To stop the container, execute the command docker stop <container-id>
.
docker run \
--env MODE=bsim \
--rm \
-it \
ghidra/ghidra:<version> \
generatesigs ghidra://ghidrasvr/demo /home/ghidra \
--bsim postgresql://bsimsvr/demo \
--commit --overwrite \
--user ghidra
In this example, the bsim CLI is used to connect to a ghidra server hosted on ghidrasvr
,
generate signatures for the demo
repository in that ghidra server and save them to /home/ghidra
.
and then commit the signatures to the BSIM server hosted on bsimsvr
in the demo
database.
Running Ghidra's Graphical User Interface (GUI) in the docker container is not a recommended method for running Ghidra. GUI's are not a typical use case for dockerized applications.
docker run \
--env MODE=pyghidra \
-it \
--rm \
--net host \
--env DISPLAY \
--volume="$HOME/.Xauthority:/home/ghidra/.Xauthority:rw" \
ghidra/ghidra:<version> -c
In this mode, the container relies on X11 forwarding to display the GUI. Configuration of X11 can vary, but in this case, the host's Xauthority file is mounted into the container, the container is configured to use the host's network, and the DISPLAY environment variable is passed to the container. This enables forwarding the GUI back to the host machine's display. Volumes containing binaries would still need to be mounted to the container as well as volumes for ghidra projects.
The host's .Xauthority
file must have appropriate permissions - owned by :1001
with rw
group permissions.
docker run \
--env MODE=pyghidra \
--rm \
--volume /path/to/myproject:/myproject \
--volume /path/to/mybinary:/mybinary \
ghidra/ghidra:<version> -H \
/myproject programFolder -import /mybinary
Passing no arguments to the pyghidra headless analyzer will result in the help menu being displayed, just like the headless analyzer.
This use case is very similar to the headless mode's example with the added benefit of being able to utilize python3 for Ghidra Scripts.
Again, in this example, appropriate permissions and group assignment for /path/to/myproject
and /path/to/mybinary
are necessary
in order to not run into permissions issues.