From f00ab2102bc730b16470e9af000db6c2d30e40af Mon Sep 17 00:00:00 2001 From: Lucas Rayan Date: Tue, 20 Oct 2026 09:56:04 -0300 Subject: [PATCH] =?UTF-8?q?Docker:=20imagem=20do=20terminal=20e=20document?= =?UTF-8?q?a=C3=A7=C3=A3o=20de=20uso?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Dockerfile em dois estágios (compila guara-cli e copia o binário para debian-slim com smartmontools). Serve para hospedeiros Linux, servidores sem desktop e arquivos de imagem forense. A interface gráfica fica de fora de propósito: o guara ui só aceita 127.0.0.1. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01RRZm8uTVN3WLTwcbrDQAUM --- .dockerignore | 11 ++++++++ Dockerfile | 25 +++++++++++++++++ README.md | 2 ++ README.pt-BR.md | 2 ++ docs/docker.md | 65 ++++++++++++++++++++++++++++++++++++++++++++ docs/pt-BR/docker.md | 65 ++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 170 insertions(+) create mode 100644 .dockerignore create mode 100644 Dockerfile create mode 100644 docs/docker.md create mode 100644 docs/pt-BR/docker.md diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..808bf59 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,11 @@ +.git +target +**/node_modules +apps/gui/src-tauri +docs +scripts +*.img +*.guara-session.json +.claude +.wolf +.superpowers diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..e966213 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,25 @@ +# syntax=docker/dockerfile:1 +# Guará CLI image. Intended for Linux hosts, headless servers and forensic image files. +# The graphical interface is not served from the container (see docs/docker.md). + +FROM rust:1-slim-bookworm AS build +WORKDIR /src +# The CLI embeds the web interface at compile time (include_str!), so it needs apps/gui/ui. +COPY Cargo.toml Cargo.lock ./ +COPY crates crates +COPY apps/gui/ui apps/gui/ui +RUN cargo build --release --locked -p guara-cli + +FROM debian:bookworm-slim +# smartmontools gives `guara health` access to SMART data. +RUN apt-get update \ + && apt-get install -y --no-install-recommends smartmontools ca-certificates \ + && rm -rf /var/lib/apt/lists/* +COPY --from=build /src/target/release/guara /usr/local/bin/guara +LABEL org.opencontainers.image.title="Guará" \ + org.opencontainers.image.description="File recovery for hard drives, SSDs and USB sticks (CLI)" \ + org.opencontainers.image.source="https://github.com/lucasrguerra/guara" \ + org.opencontainers.image.licenses="MIT OR Apache-2.0" +WORKDIR /data +ENTRYPOINT ["guara"] +CMD ["--help"] diff --git a/README.md b/README.md index 5ee56db..1d15109 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,8 @@ Every file has a `.sha256` next to it. To build from source: `cargo build --rele Reading raw disks requires privileges: **administrator** (Windows), `sudo` (Linux and macOS). Even as root, Guará writes sessions, reports and recovered files with the owner and permissions of the user who launched it. +There is also a Docker image of the command line tool, for Linux hosts and for working on image files: see [docs/docker.md](docs/docker.md). + ## Getting started ```bash diff --git a/README.pt-BR.md b/README.pt-BR.md index 7247e35..aaeb32c 100644 --- a/README.pt-BR.md +++ b/README.pt-BR.md @@ -46,6 +46,8 @@ Cada arquivo tem um `.sha256` ao lado. Compilar do código: `cargo build --relea Ler discos brutos exige privilégios: **administrador** (Windows), `sudo` (Linux e macOS). Mesmo como root, o Guará grava sessões, relatórios e arquivos recuperados com o dono e as permissões do usuário que o abriu. +Há também uma imagem Docker do terminal, para hospedeiros Linux e para trabalhar com arquivos de imagem: veja [docs/pt-BR/docker.md](docs/pt-BR/docker.md). + ## Começando ```bash diff --git a/docs/docker.md b/docs/docker.md new file mode 100644 index 0000000..ccc9b78 --- /dev/null +++ b/docs/docker.md @@ -0,0 +1,65 @@ +# Running Guará with Docker + +[English](docker.md) · [Português](pt-BR/docker.md) + +The image contains the `guara` command line tool and `smartctl`. It is useful in three cases: + +1. **A Linux server or NAS without a desktop**, with the damaged disk plugged in. +2. **Forensic image files** (`.img`, E01, AFF4) on any system with Docker, because no device access is needed. +3. **A reproducible environment** for scripts and CI. + +It is **not** the recommended way for most people. For a desktop, use the packages from [Releases](../../../releases). + +## Limits + +- **Raw devices only work on Linux hosts.** On Windows and macOS, Docker runs inside a virtual machine and does not pass physical disks through. Use an image file instead. +- **The graphical interface is not served from the container.** `guara ui` listens only on `127.0.0.1` and accepts only that `Host`, by design; opening it to the outside would weaken that protection, so it is not part of the image. +- Files written to a mounted folder belong to root unless you pass `--user` (possible when you work on image files). + +## Build + +```bash +docker build -t guara . +``` + +## Image files (any system) + +Mount the folder with the image read-only and a separate folder for the results: + +```bash +docker run --rm \ + -v "$PWD/images:/images:ro" \ + -v "$PWD/out:/out" \ + --user "$(id -u):$(id -g)" \ + guara scan /images/disk.img --session /out/s.json --list + +docker run --rm \ + -v "$PWD/images:/images:ro" -v "$PWD/out:/out" \ + --user "$(id -u):$(id -g)" \ + guara recover /out/s.json /out/recovered +``` + +## A physical disk (Linux host) + +Pass the device **read-only** with the `:r` flag. Docker then blocks writes to it at the kernel level, in addition to Guará never writing to the source: + +```bash +docker run --rm \ + --device=/dev/sdb:/dev/sdb:r \ + -v /mnt/other-disk/out:/out \ + guara scan /dev/sdb --session /out/s.json --list +``` + +- The destination must be on **another disk** than `/dev/sdb`. +- Reading a raw device needs root inside the container, so do not pass `--user` here. +- To read SMART, `--device` is not enough on some systems; `--cap-add=SYS_RAWIO` is the usual extra. +- Avoid `--privileged`: it gives the container access to every device. + +## Other commands + +Everything in the [terminal reference](cli.md) works the same way, for example: + +```bash +docker run --rm --device=/dev/sdb:/dev/sdb:r guara devices +docker run --rm --device=/dev/sdb:/dev/sdb:r guara health /dev/sdb +``` diff --git a/docs/pt-BR/docker.md b/docs/pt-BR/docker.md new file mode 100644 index 0000000..5bf4f85 --- /dev/null +++ b/docs/pt-BR/docker.md @@ -0,0 +1,65 @@ +# Usando o Guará com Docker + +[English](../docker.md) · **Português** + +A imagem traz o terminal `guara` e o `smartctl`. Ela serve em três casos: + +1. **Servidor ou NAS Linux sem desktop**, com o disco danificado conectado. +2. **Arquivos de imagem forense** (`.img`, E01, AFF4) em qualquer sistema com Docker, porque não precisa acessar dispositivo. +3. **Ambiente reproduzível** para scripts e CI. + +**Não** é o caminho recomendado para a maioria das pessoas. No desktop, use os pacotes de [Releases](../../../../releases). + +## Limites + +- **Dispositivos brutos só funcionam em hospedeiros Linux.** No Windows e no macOS o Docker roda dentro de uma máquina virtual e não repassa discos físicos. Use um arquivo de imagem. +- **A interface gráfica não é servida pelo container.** O `guara ui` escuta só em `127.0.0.1` e só aceita esse `Host`, de propósito; abrir isso para fora enfraqueceria a proteção, então não faz parte da imagem. +- Arquivos gravados numa pasta montada pertencem ao root, a menos que você passe `--user` (possível ao trabalhar com arquivos de imagem). + +## Construir + +```bash +docker build -t guara . +``` + +## Arquivos de imagem (qualquer sistema) + +Monte a pasta da imagem somente para leitura e outra pasta para os resultados: + +```bash +docker run --rm \ + -v "$PWD/imagens:/imagens:ro" \ + -v "$PWD/saida:/saida" \ + --user "$(id -u):$(id -g)" \ + guara scan /imagens/disco.img --session /saida/s.json --list + +docker run --rm \ + -v "$PWD/imagens:/imagens:ro" -v "$PWD/saida:/saida" \ + --user "$(id -u):$(id -g)" \ + guara recover /saida/s.json /saida/recuperados +``` + +## Disco físico (hospedeiro Linux) + +Passe o dispositivo **somente para leitura** com a opção `:r`. O Docker passa a bloquear escritas nele no nível do kernel, além de o Guará nunca gravar na origem: + +```bash +docker run --rm \ + --device=/dev/sdb:/dev/sdb:r \ + -v /mnt/outro-disco/saida:/saida \ + guara scan /dev/sdb --session /saida/s.json --list +``` + +- O destino precisa estar em **outro disco** que não seja o `/dev/sdb`. +- Ler dispositivo bruto exige root dentro do container, então não use `--user` aqui. +- Para ler o SMART, em alguns sistemas `--device` não basta; o complemento usual é `--cap-add=SYS_RAWIO`. +- Evite `--privileged`: ele dá ao container acesso a todos os dispositivos. + +## Outros comandos + +Tudo da [referência do terminal](cli.md) funciona do mesmo jeito, por exemplo: + +```bash +docker run --rm --device=/dev/sdb:/dev/sdb:r guara devices +docker run --rm --device=/dev/sdb:/dev/sdb:r guara health /dev/sdb +```