mirror of
https://github.com/NationalSecurityAgency/ghidra.git
synced 2026-04-26 09:45:15 +02:00
GP-3579 Added docker image generation to Ghidra distribution. Use from development source repo is not supported.
This commit is contained in:
ghidraffe
203
docker/README.md
Normal file
203
docker/README.md
Normal file
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user