ghidra

# Dockerized Ghidra

## Сборка

Из корневой директории вашего релиза Ghidra выполните следующую команду:

```
./docker/build-docker-image.sh
```

Будет собран docker-образ ghidra с тегом, соответствующим версии релиза Ghidra.

## Переменная окружения MODE

Docker-контейнер Ghidra поддерживает следующие режимы (`MODE`) выполнения:
- gui
- headless
- ghidra-server
- bsim
- bsim-server
- pyghidra

Переменная окружения `MODE` указывает, какую точку входа Ghidra следует выполнить.

Скрипт `entrypoint.sh` выполняется при запуске контейнера.

## Настройка контейнера

Настройка контейнера выполняется так же, как и любого другого docker-контейнера.
Монтируются тома, задаются переменные окружения, пробрасываются порты из контейнера на хост и т.д.
Шаги настройки сильно зависят от того, с каким режимом запускается контейнер.

Базовая директория для Ghidra внутри контейнера находится по пути `/ghidra`.
Все стандартные расположения файлов, конфигураций и т.д. Ghidra внутри этой директории остаются прежними.
Ghidra запускается от пользователя `ghidra` внутри контейнера, с uid `1001` и guid `1001`.

Пользователь `ghidra` имеет права только на следующие директории внутри контейнера:
- `/ghidra`
- `/home/ghidra`

Если контейнеру не передаются никакие аргументы через команду `docker run`,
будет показана справка по использованию соответствующего интерфейса командной строки (CLI) для выбранного режима.

### Отображение локальных томов в контейнере

С томами внутри контейнера могут возникнуть проблемы с правами доступа, если они недоступны для пользователей с идентификатором группы `1001`.

UID и GUID по умолчанию для контейнера — `1001:1001`. Тома, которые отображаются в контейнер, должны быть доступны для этого uid/guid.

Добавление пользователя хост-машины в группу `1001` на хосте упрощает управление томами, которые будут использоваться в контейнере.
Это легко сделать, выполнив `sudo usermod -aG 1001 <user>` в Linux.

### Пример режима headless

```
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
```

Разберём эту команду построчно:
- `docker run` запускает docker-контейнер с образом `ghidra/ghidra<:<version>`
- `--env MODE=headless` задаёт переменную окружения `MODE` внутри контейнера со значением `headless`
- `--rm` удаляет контейнер после завершения команды
- `--volume /path/to/myproject:/home/ghidra/myproject` монтирует локальный том 
	`/path/to/myproject` на хосте в `/home/ghidra/myproject` внутри контейнера
- `--volume /path/to/mybinary:/home/ghidra/mybinary` монтирует локальный том 
	`/path/to/mybinary` на хосте в `/home/ghidra/mybinary` внутри контейнера
- `ghidra/ghidra:<version>` — полная ссылка на docker-образ, где `ghidra/ghidra` — группа и имя образа, а `<version>` — тег.
- `/home/ghidra/myproject programFolder -import /home/ghidra/mybinary` — аргументы, передаваемые интерфейсу командной строки безголового анализатора Ghidra

Если не передавать аргументы, будет показана справка по безголовому анализатору.

`/path/to/myproject` на хосте должен быть доступен для guid `1001` с правами `rwx`.

### Пример режима gui

Запуск графического интерфейса пользователя (GUI) Ghidra в docker-контейнере не рекомендуется.
Графические интерфейсы не являются типичным вариантом использования для docker-изолированных приложений.

```
docker run \
    --env MODE=gui \
    -it \
    --rm \
    --net host \
    --env DISPLAY \
    --volume "$HOME/.Xauthority:/home/ghidra/.Xauthority" \
    ghidra/ghidra:<version>
```

В этом режиме контейнер использует X11-forwarding для отображения графического интерфейса. Настройки X11 могут различаться, но в данном случае
файл Xauthority хоста монтируется в контейнер, контейнер настроен на использование сети хоста, а переменная окружения DISPLAY
передаётся контейнеру. Это позволяет перенаправить GUI обратно на дисплей хост-машины. Также потребуется смонтировать тома с бинарными файлами и проектами Ghidra.

Файл `.Xauthority` на хосте должен иметь соответствующие права — принадлежать группе `:1001` с правами `rw` для группы.

### Пример режима ghidra-server

```
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>
```

Необходимо смонтировать тома в контейнер сервера, чтобы сохранять репозитории, пользователей и настроить сервер.

Для использования svrAdmin выполните вход в запущенный контейнер сервера ghidra с помощью `docker exec -it <container-id> bash`. После входа администрирование и управление сервером Ghidra выполняется так же, как и в среде без контейнера.

Для остановки контейнера выполните команду `docker stop <container-id>`.

ПРИМЕЧАНИЕ: порты, которые вы пробрасываете с хоста в docker-контейнер, должны совпадать. Вы можете изменить базовый порт сервера (например, `13100`) в файле `server.conf`, используя опцию `-p<port>`.

## Пример режима BSIM Server

```
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` — это директория для хранения данных bsim в контейнере. Можно использовать и другие директории в контейнере,
но убедитесь, что папка на хост-машине имеет соответствующие права и принадлежит группе `:1001`.

Этот пример просто запускает сервер bsim. Настройка сервера bsim и наполнение его данными
может быть выполнена после запуска внутри контейнера аналогично администрированию сервера ghidra.
Администратору нужно выполнить вход в запущенный контейнер сервера bsim (`docker exec -it <container-id> bash`),
после чего администрирование и управление сервером Bsim выполняется так же, как и в среде без контейнера.

Для остановки контейнера выполните команду `docker stop <container-id>`.

## Пример режима BSIM CLI

```
docker run \
		--env MODE=bsim \
		--rm \
		 -it \
		 ghidra/ghidra:<version> \
		 generatesigs ghidra://ghidrasvr/demo /home/ghidra \
			 --bsim postgresql://bsimsvr/demo \
			 --commit --overwrite \
			 --user ghidra
```

В этом примере CLI bsim используется для подключения к серверу ghidra, размещённому на `ghidrasvr`,
генерации сигнатур для репозитория `demo` на этом сервере ghidra и сохранения их в `/home/ghidra`,
а затем отправки сигнатур на сервер BSIM, размещённый на `bsimsvr`, в базу данных `demo`.

## Пример режима Pyghidra Gui

Запуск графического интерфейса пользователя (GUI) Ghidra в docker-контейнере не рекомендуется.
Графические интерфейсы не являются типичным вариантом использования для docker-изолированных приложений.

```
docker run \
    --env MODE=pyghidra \
    -it \
    --rm \
    --net host \
    --env DISPLAY \
    --volume="$HOME/.Xauthority:/home/ghidra/.Xauthority:rw" \
    ghidra/ghidra:<version> -c
```

В этом режиме контейнер использует X11-forwarding для отображения графического интерфейса. Настройки X11 могут различаться, но в данном случае
файл Xauthority хоста монтируется в контейнер, контейнер настроен на использование сети хоста, а переменная окружения DISPLAY
передаётся контейнеру. Это позволяет перенаправить GUI обратно на дисплей хост-машины. Также потребуется смонтировать тома с бинарными файлами и проектами Ghidra.

Файл `.Xauthority` на хосте должен иметь соответствующие права — быть владельцем группы `:1001` с правами `rw` для группы.

## Пример режима Pyghidra Headless

```
docker run \
    --env MODE=pyghidra \
    --rm \
    --volume /path/to/myproject:/myproject \
    --volume /path/to/mybinary:/mybinary \
    ghidra/ghidra:<version> -H \
    /myproject programFolder -import /mybinary
```

Если не передавать аргументы безголовому анализатору pyghidra, будет показано меню справки, так же, как и для безголового анализатора.

Этот вариант использования очень похож на пример безголового режима, но с дополнительным преимуществом — возможностью использовать python3 для скриптов Ghidra.

Опять же, в этом примере необходимы соответствующие права и назначение группы для `/path/to/myproject` и `/path/to/mybinary`,
чтобы избежать проблем с правами доступа.