ghidra

# Ghidra Dockerizado

## Construir

A partir do diretório raiz da sua versão do Ghidra, execute o seguinte comando.

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

Isto irá construir a imagem docker do Ghidra com uma tag correspondente à versão de lançamento do Ghidra.

## A variável de ambiente MODE

O Container Docker do Ghidra suporta os seguintes `MODE`'s de execução:
- gui
- headless
- ghidra-server
- bsim
- bsim-server
- pyghidra

A variável de ambiente `MODE` designa qual ponto de entrada do Ghidra deve ser executado.

O script `entrypoint.sh` é executado na inicialização do container.

## Configurando um Container

A configuração de um container é feita da mesma forma que qualquer outro container docker seria configurado.
Volumes podem ser montados, variáveis de ambiente podem ser definidas, portas podem ser mapeadas do container para o host, e assim por diante.
As etapas de configuração variam muito dependendo do `MODE` com o qual o container é iniciado.

O diretório base para o Ghidra dentro do container está localizado em `/ghidra`.
Todos os locais padrão do Ghidra para arquivos, configurações, etc., são os mesmos dentro dele.
O Ghidra é executado como o usuário `ghidra` dentro do container, com uid `1001` e guid `1001`.

O usuário `ghidra` tem permissões apenas para os seguintes diretórios dentro do container:
- `/ghidra`
- `/home/ghidra`

Quando um container não recebe nenhum argumento passado a ele com o comando `docker run`,
a Interface de Linha de Comando (CLI) correspondente ao `MODE` executado exibirá sua declaração de uso.

### Mapeando Volumes Locais para um Container

Volumes dentro do container podem encontrar problemas de permissão se os volumes não estiverem acessíveis por usuários no grupo id `1001`.

O uid e guid padrão para o container é `1001:1001`. Volumes que são mapeados para o container devem ser acessíveis por este uid/guid.

Adicionar o usuário da máquina host ao grupo `1001` no host ajuda a gerenciar volumes que serão usados no container.
Isso pode ser facilmente feito executando `sudo usermod -aG 1001 <user>` no Linux.

### Exemplo do Modo 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
```

Detalhando linha por linha:
- `docker run` vai iniciar um container docker usando a imagem `ghidra/ghidra<:<version>`
- `--env MODE=headless` configura a variável de ambiente `MODE` dentro do container com o valor `headless`
- `--rm` remove o container após o comando ser concluído
- `--volume /path/to/myproject:/home/ghidra/myproject` monta o volume local 
	`/path/to/myproject` no host para `/home/ghidra/myproject` dentro do container
- `--volume /path/to/mybinary:/home/ghidra/mybinary` monta o volume local 
	`/path/to/mybinary` no host para `/home/ghidra/mybinary` dentro do container
- `ghidra/ghidra:<version>` é a referência completa para a imagem docker, onde `ghidra/ghidra` é o grupo e nome da imagem, e `<version>` é a tag.
- `/home/ghidra/myproject programFolder -import /home/ghidra/mybinary` são argumentos passados para a interface de linha de comando do analisador headless do Ghidra

Passar nenhum argumento resultará na exibição do uso do analisador headless.

`/path/to/myproject` no host deve estar acessível ao guid `1001` com permissões `rwx`.

### Exemplo do Modo Gui

Executar a Interface Gráfica do Usuário (GUI) do Ghidra no container docker não é um método recomendado para executar o Ghidra.
GUIs não são um caso de uso típico para aplicações dockerizadas.

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

Neste modo, o container depende do encaminhamento X11 para exibir a GUI. A configuração do X11 pode variar, mas neste caso,
o arquivo Xauthority do host é montado dentro do container, o container é configurado para usar a rede do host, e a variável de ambiente DISPLAY
é passada para o container. Isso permite encaminhar a GUI de volta para o display da máquina host. Volumes 
contendo binários ainda precisariam ser montados no container, assim como volumes para projetos Ghidra.

O arquivo `.Xauthority` do host deve ter permissões apropriadas - atribuídas ao grupo `:1001` com permissões de grupo `rw`.

### Exemplo do Modo 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>
```

Volumes precisariam ser montados no container do servidor para salvar os repositórios, usuários, e também para configurar o servidor.

Para utilizar o svrAdmin, execute um exec no container do servidor Ghidra em execução (`docker exec -it <container-id> bash`) para um shell bash no container.
Após fazer exec no container, a administração e gerenciamento do servidor Ghidra é a mesma que fora de um ambiente containerizado.

Para parar o container, execute o comando `docker stop <container-id>`.

NOTA: as portas que você mapeia do host para o container docker devem corresponder. Você pode alterar a porta base padrão do servidor (ex.: `13100`) no arquivo `server.conf` usando a opção `-p<port>`.

## Exemplo do Modo 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` é o diretório usado para armazenar os dados do bsim no container. Outros diretórios poderiam ser usados no container,
mas certifique-se de que a pasta na máquina host tenha permissões apropriadas, atribuídas ao grupo `:1001`.

Este exemplo simplesmente inicia um servidor bsim. Configurar o servidor bsim e populá-lo com dados 
poderia ser feito após a inicialização dentro do container de forma semelhante à administração do servidor Ghidra.
Um administrador teria que executar exec no container do servidor bsim em execução (`docker exec -it <container-id> bash`), 
e após fazer exec no container, a administração e gerenciamento do servidor Bsim é a mesma que fora de um ambiente containerizado.

Para parar o container, execute o comando `docker stop <container-id>`.

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

Neste exemplo, a CLI bsim é usada para conectar a um servidor Ghidra hospedado em `ghidrasvr`, 
gerar assinaturas para o repositório `demo` naquele servidor Ghidra e salvá-las em `/home/ghidra`. 
e então confirmar as assinaturas no servidor BSIM hospedado em `bsimsvr` no banco de dados `demo`.

## Exemplo do Modo Pyghidra Gui

Executar a Interface Gráfica do Usuário (GUI) do Ghidra no container docker não é um método recomendado para executar o Ghidra.
GUIs não são um caso de uso típico para aplicações dockerizadas.

```
docker run \
    --env MODE=pyghidra \
    -it \
    --rm \
    --net host \
    --env DISPLAY \
    --volume="$HOME/.Xauthority:/home/ghidra/.Xauthority:rw" \
    ghidra/ghidra:<version> -c
```
Neste modo, o container depende do encaminhamento X11 para exibir a GUI. A configuração do X11 pode variar, mas neste caso,
o arquivo Xauthority do host é montado dentro do container, o container é configurado para usar a rede do host, e a variável de ambiente DISPLAY
é passada para o container. Isso permite encaminhar a GUI de volta para o display da máquina host. Volumes 
contendo binários ainda precisariam ser montados no container, assim como volumes para projetos Ghidra.

O arquivo `.Xauthority` do host deve ter permissões apropriadas - pertencentes a `:1001` com permissões de grupo `rw`.

## Exemplo do Modo 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
```
Passar nenhum argumento para o analisador headless pyghidra resultará na exibição do menu de ajuda, assim como o analisador headless.

Este caso de uso é muito semelhante ao exemplo do modo headless, com o benefício adicional de poder utilizar python3 para Scripts Ghidra.

Novamente, neste exemplo, permissões apropriadas e atribuição de grupo para `/path/to/myproject` e `/path/to/mybinary` são necessárias 
para não encontrar problemas de permissão.