Ghidra is a software reverse engineering (SRE) framework
GP-3579 Added docker image generation to Ghidra distribution. Use from development source repo is not supported.
ghidraffefbdcd1c709cb
diff --git a/docker/Dockerfile b/docker/Dockerfilenew file mode 100644index 0000000000..9edff23874--- /dev/null+++ b/docker/Dockerfile@@ -0,0 +1,62 @@+###############################################################+# Dockerfile+# This is the Dockerfile for a release of Ghidra.+# It should be built from the root directory of+# a ghidra release using the command+# docker build -f docker/Dockerfile -t <image-name>+###############################################################+FROM alpine:3.20 as base++LABEL org.opencontainers.image.title="ghidra" \+ org.opencontainers.image.description="Docker image for Ghidra" \+ org.opencontainers.image.source="https://github.com/NationalSecurityAgency/ghidra" \+ org.opencontainers.image.licenses="Apache 2.0"++# Configure user, entrypoint, and some env vars first, before making the image larger with dependencies+# so that we can keep the image size as small as possible.+RUN addgroup -g 1001 -S ghidra && adduser -u 1001 -S ghidra -G ghidra+ENTRYPOINT ["/bin/bash", "/ghidra/docker/entrypoint.sh"]+# Set JAVA_HOME so that we don't need to do this manually when Ghidra is first started.+ENV JAVA_HOME /usr/lib/jvm/java-21-openjdk+ENV LD_LIBRARY_PATH /usr/lib/jvm/java-21-openjdk/lib/:/usr/lib/jvm/java-21-openjdk/lib/server/+WORKDIR /ghidra++# validate build context is correct. an error will happen if this file is not present.+COPY ./ghidraRun ./ghidraRun++# update and install dependencies used to both build and run ghidra+RUN apk update \+ && apk add openjdk21 python3 \+ bash gcompat \+ fontconfig msttcorefonts-installer \+ linux-headers libressl-dev \+ && update-ms-fonts++FROM base as build++# install additional dependencies used to build ghidra+RUN apk add gradle \+ python3-dev py-pip \+ alpine-sdk \+ build-base \+ gcc g++ make libc-dev zlib-dev musl-dev \+ zip readline-dev+# copy the contents of the release into the current working dir.+COPY . .++# build postgres and install pyghidra+RUN /ghidra/Ghidra/Features/BSim/support/make-postgres.sh \+ && python3 -m venv /ghidra/venv \+ && /ghidra/venv/bin/python3 -m pip install --no-index -f /ghidra/Ghidra/Features/PyGhidra/pypkg/dist pyghidra \+ && mkdir /ghidra/repositories && mkdir /ghidra/bsim_datadir+++FROM base as runtime++# install additional dependencies needed for running ghidra+RUN apk add openssl openssh-client \+ xhost musl-locales musl-locales-lang++USER ghidra+WORKDIR /ghidra+COPY --chown=ghidra:ghidra --from=build /ghidra /ghidradiff --git a/docker/Dockerfile.dockerignore b/docker/Dockerfile.dockerignorenew file mode 100644index 0000000000..8ea08e2e8b--- /dev/null+++ b/docker/Dockerfile.dockerignore@@ -0,0 +1 @@+docker/Dockerfile*diff --git a/docker/README.md b/docker/README.mdnew file mode 100644index 0000000000..8181147412--- /dev/null+++ b/docker/README.md@@ -0,0 +1,203 @@+# Dockerized Ghidra++## Build++From the root directory of your Ghidra release, run the following command with the correct version for your release.++```+docker build -f docker/Dockerfile -t ghidra/ghidra[:<version>] .+```++The image tag is optional, but highly recommended.+++## The MODE environment variable++The Ghidra Docker Container supports the following `MODE`'s of execution:+- gui+- headless+- ghidra-server+- bsim+- bsim-server+- pyghidra++The `MODE` environment variable designates which entrypoint of Ghidra to execute.++The `entrypoint.sh` script is executed upon container startup.++## Configuring a Container++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.++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.++### Mapping Local Volumes to a Container++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.++### Example of Headless Mode++```+docker run \+ --env MODE=headless \+ --rm \+ --volume /path/to/myproject:/home/ghidra/myproject \+ --volume /path/to/mybinary:/home/ghidra/mybinary \+ ghidra/ghidra:<version> \+ /myproject programFolder -import /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:/myproject` mounts the local volume `/path/to/myproject` on the host to `/myproject` within the container+- `--volume /path/to/mybinary:/mybinary` mounts the local volume `/path/to/mybinary` on the host to `/mybinary` within the container+- `ghidra/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.+- `/myproject programFolder -import /mybinary` are arguments being passed to Ghidra's headless analyzer's command line interface++Passing no arguments will result in the usage of the headless analyzer being displayed.++### Example of Gui Mode++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.+++### Example of Ghidra Server Mode++```+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>`.++## Example of BSIM Server Mode++```+export DATADIR_PATH=/home/ghidrausr/datadir+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>`.++## Example of BSIM CLI Mode+```+docker run \+ --env MODE=bsim \+ --rm \+ -it \+ ghidra/ghidra:RELEASE \+ 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.+++## Example of Pyghidra Gui Mode++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.+++## Example of Pyghidra Headless Mode++```+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.+diff --git a/docker/build.gradle b/docker/build.gradlenew file mode 100644index 0000000000..04d8eff183--- /dev/null+++ b/docker/build.gradle@@ -0,0 +1,28 @@+/* ###+ * IP: GHIDRA+ *+ * Licensed under the Apache License, Version 2.0 (the "License");+ * you may not use this file except in compliance with the License.+ * You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */++rootProject.assembleDistribution {+ from (ROOT_PROJECT_DIR + "/docker") {+ into "docker"+ exclude "build.gradle"+ }+}++rootProject.assembleMarkdownToHtml {+ from ("${this.projectDir}/README.md") {+ into "."+ }+}diff --git a/docker/certification.manifest b/docker/certification.manifestnew file mode 100644index 0000000000..6d3b1fe641--- /dev/null+++ b/docker/certification.manifest@@ -0,0 +1,4 @@+##VERSION: 2.0+Dockerfile||GHIDRA||||END|+Dockerfile.dockerignore||GHIDRA||||END|+README.md||GHIDRA||||END|diff --git a/docker/entrypoint.sh b/docker/entrypoint.shnew file mode 100755index 0000000000..7e16af8427--- /dev/null+++ b/docker/entrypoint.sh@@ -0,0 +1,55 @@+#!/bin/bash+## ###+# IP: GHIDRA+#+# Licensed under the Apache License, Version 2.0 (the "License");+# you may not use this file except in compliance with the License.+# You may obtain a copy of the License at+#+# http://www.apache.org/licenses/LICENSE-2.0+#+# Unless required by applicable law or agreed to in writing, software+# distributed under the License is distributed on an "AS IS" BASIS,+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+# See the License for the specific language governing permissions and+# limitations under the License.+##++MODE=${MODE:="gui"}++echo "$@"+MAXMEM=${MAXMEM:=2G}++if [[ $MODE == "gui" ]] then+ /ghidra/support/launch.sh bg jdk Ghidra "${MAXMEM}" "" ghidra.GhidraRun "$@"+ # need to do this since the launched process is not blocking terminal exit+ while ! tail -f ~/.config/ghidra/ghidra_*/application.log; do sleep 1 ; done+elif [[ $MODE == "headless" ]] then+ LAUNCH_MODE=${LAUNCH_MODE:=fg}+ DEBUG_ADDRESS=${DEBUG_ADDRESS:=127.0.0.1:13002}+ VMARG_LIST=${VMARG_LIST:="-XX:ParallelGCThreads=2 -XX:CICompilerCount=2 -Djava.awt.headless=true "}+ DEBUG_ADDRESS=${DEBUG_ADDRESS} /ghidra/support/launch.sh "${LAUNCH_MODE}" jdk Ghidra-Headless "${MAXMEM}" "${VMARG_LIST}" ghidra.app.util.headless.AnalyzeHeadless "$@"+elif [[ $MODE == "ghidra-server" ]] then+ # Note, for svrAdmin, you will need to exec into the container running the ghidra server and use the CLI there.+ /ghidra/server/ghidraSvr console+elif [[ $MODE == "bsim" ]] then+ LAUNCH_MODE=${LAUNCH_MODE:=fg}+ VMARG_LIST=${VMARG_LIST:="-Djava.awt.headless=true "}+ /ghidra/support/launch.sh $LAUNCH_MODE jdk "BSim" "${MAXMEM}" "" ghidra.features.bsim.query.ingest.BSimLaunchable "$@"+elif [[ $MODE == "bsim-server" ]] then+ LAUNCH_MODE=${LAUNCH_MODE:=fg}+ VMARG_LIST=${VMARG_LIST:="-Djava.awt.headless=true -Xshare:off"}+ mkdir -p $DATADIR_PATH+ /ghidra/support/launch.sh "$LAUNCH_MODE" jdk BSimControl "$MAXMEM" "$VMARG_LIST" ghidra.features.bsim.query.BSimControlLaunchable start $@+ # need to do this since the launched process is not blocking terminal exit+ while ! tail -f $DATADIR_PATH/logfile; do sleep 1 ; done+elif [[ $MODE == "pyghidra" ]] then+ # Add optional JVM args inside the quotes+ VMARG_LIST=${VMARG_LIST:=""}+ PYGHIDRA_LAUNCHER="/ghidra/Ghidra/Features/PyGhidra/support/pyghidra_launcher.py"+ set -e+ source /ghidra/venv/bin/activate+ /ghidra/venv/bin/python3 "${PYGHIDRA_LAUNCHER}" "/ghidra" ${VMARG_LIST} "$@"+else+ echo "Unknown MODE: $MODE. Valid MODE's are gui, headless, ghidra-server, bsim, bsim_ctl, or pyghidra."+fidiff --git a/settings.gradle b/settings.gradleindex ed753c9816..b890a0bcd3 100644--- a/settings.gradle+++ b/settings.gradle@@ -33,6 +33,7 @@ includeProjects('GPL')/******************************************************************************************** Include miscellaneous support modules*******************************************************************************************/+includeProject('docker', '.', true)includeProject('Doclets', 'GhidraBuild/BuildFiles', true)includeProject('LaunchSupport', 'GhidraBuild', true)includeProject('MarkdownSupport', 'GhidraBuild', true)