guara/README.pt-BR.md

Guará

Recuperação de arquivos livre e gratuita para HD, SSD e pendrive.
Terminal e interface gráfica · Windows e Linux · somente leitura na origem.

O que suporta · Interface · Terminal · Arquitetura · Roadmap · Changelog

English · Português

_{A interface de verdade rodando sobre uma imagem de teste sintética (fotos geradas, sem dados reais).}

---

O Guará junta, numa única varredura, o que ferramentas como Recuva, PhotoRec, TestDisk e Disk Drill fazem separadamente:

• Metadados do sistema de arquivos: acha arquivos apagados com nome, pasta e data em NTFS, FAT12/16/32, exFAT, ext2/3/4, HFS+, Btrfs, XFS e APFS.
• Carving por estrutura no espaço livre, em partições danificadas e no espaço não particionado. Os detectores leem a estrutura real de dezenas de formatos para saber o tamanho exato e a confiança.
• Volumes cifrados: abre BitLocker, LUKS e FileVault 2 com a sua senha ou chave e varre por dentro.
• RAID e LVM: remonta arrays a partir de discos soltos (RAID 0, 1, 4, 5, 6, 10, LVM2), descobrindo nível, faixa e ordem sozinho quando não há metadados.
• Arquivos fragmentados: remonta JPEG em pedaços e refaz o índice de vídeos MP4/MOV sem moov.
• Imagens forenses: lê e grava imagem bruta, E01/Ex01 e AFF4, e lê discos virtuais QCOW2, VMDK, VHD, VHDX e DMG.
• Partições perdidas: lê MBR/GPT e procura volumes por assinatura onde a tabela falhou.
• Fusão sem duplicatas: um arquivo achado por mais de um método aparece uma vez, com a melhor evidência.
• Confiança por arquivo (alta, média, baixa): estrutura íntegra, clusters reutilizados, conteúdo zerado (TRIM) ou que não confere com a extensão.

Matriz completa, com limites de cada item, em docs/pt-BR/suporte.md.

Segurança dos dados

• A origem é aberta somente para leitura. Nada no núcleo escreve no dispositivo recuperado.
• A recuperação recusa destinos no mesmo disco da origem (Linux e macOS).
• Imagem forense tolerante a setores ruins, com mapa de erros e hash: trabalhe sempre na cópia de um disco com defeito.
• Cada recuperação grava guara-manifesto.json com MD5, SHA-1 e SHA-256 de todos os arquivos.
• Senhas nunca vão para o arquivo de sessão.

Instalação

Baixe o pacote do seu sistema em Releases:

	CLI	App gráfico
Windows	—	instalador .msi / .exe
Linux	guara-*-linux-{x86_64,aarch64}.tar.gz	.AppImage / .deb

O CLI é só para Linux; o app desktop sai para Linux e Windows. Cada pacote do CLI tem um .sha256 ao lado. Compilar do código: cargo build --release -p guara-cli (Rust 1.80+, Linux).

Atualizações: o app desktop (AppImage e Windows) consulta o Gitea ao abrir; havendo versão nova, um cartão oferece Atualizar agora: ele baixa, confere a assinatura do pacote, instala e reabre, e você deixa de trocar o AppImage na mão. A consulta é uma única requisição ao latest.json da release e nada seu é enviado; desligue em Configurações. Instalações por .deb/.rpm só mostram o aviso, porque quem manda nesses arquivos é o gerenciador de pacotes.

Os binários ainda não são assinados: o Windows SmartScreen vai avisar. Confira o SHA-256.

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.

Começando

sudo guara devices                                  # que discos existem
sudo guara scan /dev/sdb --session s.json --list    # varredura profunda
guara recover s.json /mnt/outro-disco/Recuperados   # recupera, em OUTRO disco

Disco com defeito? Faça a imagem primeiro e trabalhe na cópia:

sudo guara image /dev/sdb /mnt/outro-disco/sdb.img
guara scan /mnt/outro-disco/sdb.img --session s.json

Outros comandos (inspect, health, hash, search, export, report, verify, ui, volumes cifrados, RAID) estão em docs/pt-BR/cli.md.

Interface gráfica

App desktop (Tauri) no estilo de um gerenciador de arquivos, pensado para quando o Guará acha milhares de itens. O mesmo front-end roda no navegador com guara ui. Mais telas e detalhes em docs/pt-BR/interface.md.

• Grade de miniaturas ou lista, agrupamento por dia ou mês e rolagem virtual para dezenas de milhares de arquivos.
• Navegação lateral por tipo, data real da foto (EXIF), pasta, câmera, confiança e GPS, com opção de ocultar duplicadas.
• Seleção como no Finder ou Explorer e visualização rápida em tela cheia (Espaço, Enter ou duplo clique).
• Painel de detalhes com pré-visualização, datas e metadados.
• Campos para senha, RAID, vídeo de referência e formato da imagem; saúde do disco (SMART); pausar e continuar; temas Auto, Claro e Escuro; interface em português e inglês.

Pré-visualização antes de recuperar, lida direto do disco sem gravar nada: imagens, vídeo, áudio, PDF, texto, Word/Excel/PowerPoint/OpenDocument, conteúdo de ZIP, bancos SQLite (com linhas apagadas) e hexadecimal. No Linux, a reprodução de vídeo depende dos plugins gstreamer1.0-libav e gstreamer1.0-plugins-good; sem eles, o botão "Abrir no player do sistema" cobre o caso.

Recursos periciais

• Hashes MD5, SHA-1 e SHA-256 de cada arquivo recuperado, da imagem e do dispositivo.
• Metadados: EXIF (câmera, lente, número de série, GPS), PDF, Office e OpenDocument, MP4/MOV.
• Linha do tempo: datas de criação, modificação e acesso do NTFS, FAT e exFAT.
• Busca de texto no disco inteiro, inclusive espaço livre, em UTF-8 e UTF-16.
• CSV (abre no Excel) e relatório HTML imprimível com caso, examinador, origem, partições, resumo e hashes.
• Sessões automáticas e reconexão: o Guará reconhece o mesmo disco que volta com outro nome.
• Detecção de duplicadas por assinatura de conteúdo.

Atenção: o Guará ainda não foi validado externamente (por exemplo, nos testes do NIST CFTT) e suas assinaturas não têm carimbo de tempo de terceiros (RFC 3161). Serve bem para recuperação e triagem; para uso em juízo, confira os resultados por outro meio. O caminho para isso está no ROADMAP.

Limites conhecidos

• Dados sobrescritos não voltam. Em SSD com TRIM o disco pode zerar blocos apagados; o Guará avisa, mas não faz milagre.
• Fragmentos: só JPEG (até três pedaços) e MP4 sem índice são remontados. Os demais formatos, se fragmentados, saem truncados com confiança baixa.
• ReFS e Storage Spaces não são suportados (ReFS só é detectado).
• APFS: sem mapa de espaço livre. XFS e APFS: recuperação de exclusão testada só em simulação.
• NTFS: arquivos comprimidos, EFS e registros muito fragmentados são ignorados ou marcados como incompletos.
• exFAT: validado com imagem sintética; faltam mídias reais.
• Celulares: o Guará trabalha com mídias de armazenamento e não desbloqueia aparelhos nem contorna senhas.
• Windows: o código compila e é testado em CI, mas os testes com imagens reais rodam só no Linux. Não há build para macOS: o Tauri precisa do SDK do macOS e de assinatura, os dois presos a hardware Apple e a uma conta Apple Developer, que o CI deste projeto (um único runner Linux) não tem. O código-fonte continua compilando para macOS; só não é compilado nem testado.
• GUI: no Linux e macOS o app reinicia inteiro como administrador (pkexec ou osascript) em vez de usar um processo auxiliar.

Para onde vai

Resumo do ROADMAP:

Feito	Metadados de 8 sistemas de arquivos, BitLocker, LUKS, FileVault 2, RAID, LVM, E01, Ex01, AFF4, JPEG fragmentado, MP4 sem índice, leitor de SQLite, SMART, QCOW2/VMDK/VHD/VHDX/DMG, trilha de auditoria encadeada por hash, relatório em PDF, assinaturas Ed25519, mapa livre do APFS
Próximo	Carimbo de tempo de terceiros (RFC 3161), mais testes em Windows
Fora de plano	Um build para macOS — veja Limites conhecidos
Depois	NSRL e listas de hashes, busca em conteúdo, linha do tempo unificada, interpretação de navegadores, registro do Windows e apps de mensagem, ataque de dicionário e força bruta a volumes cifrados
Sem imagem de referência	ReFS e Storage Spaces: só entram com validação
Longo prazo	Backups de iOS e Android (iTunes, ADB), OCR, validação NIST CFTT, acesso físico a celulares por exploit de bootloader/chip

Desenvolvimento

crates/guara-core   núcleo: leitura, partições, sistemas de arquivos, cifra, RAID, carving, recuperação
crates/guara-cli    binário `guara` (CLI + servidor local da UI)
apps/gui            interface (ui/ = HTML, CSS e JS; src-tauri/ = app desktop)
scripts/            imagens de teste e dados de referência
docs/               suporte, terminal e arquitetura

cargo test --workspace        # no Linux gera imagens reais com mtools, ntfs-3g, e2fsprogs
scripts/fetch-testdata.sh     # opcional: imagens de referência (BitLocker, FileVault 2, dfvfs, AFF4)
cargo clippy --workspace --all-targets

Veja CONTRIBUTING.md e docs/pt-BR/arquitetura.md. Versões seguem SemVer; mudanças em CHANGELOG.md. Para publicar: git tag vX.Y.Z && git push --tags (o workflow release compila e publica tudo). Vulnerabilidades: SECURITY.md.

Licença

MIT ou Apache-2.0, à sua escolha.