Recuperação de arquivos livre e gratuita para HD, SSD e pendrive.
Terminal e interface gráfica · Windows, Linux e macOS · somente leitura na origem.
O que suporta · Terminal · Arquitetura · Roadmap · Changelog
+ --- O Guará junta, numa única varredura, o que ferramentas como Recuva, PhotoRec, TestDisk e Disk Drill fazem separadamente: -- **Metadados do sistema de arquivos** (NTFS, FAT12/16/32, exFAT): acha arquivos apagados **com nome, pasta e data**. -- **Carving por assinatura/estrutura** no espaço livre, em partições danificadas e no **espaço não particionado**: acha arquivos mesmo quando o sistema de arquivos sumiu. Os detectores leem a estrutura real (JPEG, PNG, GIF, BMP, PDF, ZIP/DOCX/XLSX/PPTX/ODF/EPUB, MP4/MOV/HEIC, AVI/WAV/WebP, SQLite, 7z, OLE (DOC/XLS/PPT), MP3, EXE/DLL) para saber o **tamanho exato** e a **confiança**. -- **Partições perdidas:** lê MBR/GPT e procura volumes (NTFS, FAT, exFAT, ext, APFS, HFS+, BitLocker, LUKS) por assinatura onde a tabela falhou. -- **Fusão sem duplicatas:** um arquivo achado pelos dois métodos 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. +- **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**. +- **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/suporte.md](docs/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/macOS). -- **Imagem forense** (`guara image`) tolerante a setores ruins, com mapa de erros e SHA-256: trabalhe sempre na cópia de um disco com defeito. +- 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. -- **Volumes cifrados** (BitLocker, LUKS) são **detectados e avisados**; a v1 não desbloqueia nem varre dentro deles. +- **Senhas nunca vão para o arquivo de sessão.** ## Instalação @@ -34,103 +42,91 @@ Cada arquivo tem um `.sha256` ao lado. Compilar do código: `cargo build --relea > Os binários ainda **não são assinados**: o Windows SmartScreen e o Gatekeeper do macOS vão avisar. Confira o SHA-256. -Ler discos brutos exige privilégios: **administrador** (Windows), `sudo` (Linux/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. +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. -## Uso (terminal) +## Começando ```bash -sudo guara devices # discos e pendrives (avisa TRIM e volumes montados) -sudo guara inspect /dev/sdb # partições, espaço não particionado, cifragem -sudo guara health /dev/sdb # saúde do disco (SMART), requer smartmontools -sudo guara scan /dev/sdb --session s.json --list # varredura profunda -sudo guara scan /dev/sdb --quick # só metadados (segundos) -guara scan disco.img --category image,document --min-confidence medium -guara scan disco.img --recover /mnt/outro-disco/Recuperados -guara recover s.json /mnt/outro-disco/Recuperados --category image -guara resume s.json # continua após Ctrl+C (religa o disco mesmo com outro nome) -guara sessions # sessões salvas automaticamente -sudo guara image /dev/sdb /mnt/outro-disco/sdb.img # imagem com mapa de erros -sudo guara hash /dev/sdb # MD5, SHA-1 e SHA-256 do dispositivo -sudo guara search /dev/sdb "contrato" "cpf" # texto em todo o disco (UTF-8 e UTF-16) -guara export s.json achados.csv --category image # planilha dos achados -guara report s.json relatorio.html --case 2026-001 --examiner "Nome" --hash-source -guara ui # interface no navegador (127.0.0.1 + token) +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 ``` -`--json` está disponível em `devices`, `inspect` e `scan` para automação. +Disco com defeito? Faça a imagem primeiro e trabalhe na cópia: + +```bash +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/cli.md](docs/cli.md)**. ## Interface gráfica -App desktop (Tauri) no estilo de um gerenciador de arquivos, pensado para quando o Guará acha milhares de itens: +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`. -- **Grade de miniaturas** (gerada pelo núcleo, rápida mesmo com milhares de fotos) ou **lista**, com controle de tamanho, agrupamento por dia ou mês e rolagem virtual que aguenta dezenas de milhares de arquivos. -- **Navegação lateral** por tipo, **data real da foto (EXIF)**, pasta, **câmera**, confiança, com localização GPS e ocultando duplicadas. -- **Seleção como no Finder/Explorer:** clique, Ctrl/Cmd, Shift, setas, Ctrl+A. Espaço, Enter ou duplo clique abrem a **visualização rápida** em tela cheia com navegação por ← →. -- **Painel de detalhes** com pré-visualização, datas (tirada, modificada, criada, acessada) e metadados. -- Pausar/continuar, salvar sessão, tema **Auto / Claro / Escuro** (lembrado também ao reiniciar como administrador) e layout responsivo. O mesmo front-end roda em `guara ui`. +- **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 (MP4/MOV/WebM)** e áudio com player, **PDF** página a página, texto, documentos Word/Excel/PowerPoint/OpenDocument (texto extraído), conteúdo de ZIP e visão hexadecimal para o resto. Quando um arquivo não abre, o aviso ajuda a julgar se ele está danificado. A reprodução de vídeo depende dos codecs do seu sistema (no Linux, instale os plugins `gstreamer1.0-libav` e `gstreamer1.0-plugins-good`). +**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 -Pensados para quem precisa documentar o que fez: - -- **Hashes MD5, SHA-1 e SHA-256** de cada arquivo recuperado, da imagem forense e do dispositivo inteiro (`guara hash`). -- **Metadados:** EXIF (câmera, lente, número de série, data, **GPS**), informações de PDF (autor, programa, datas), propriedades de documentos Office e OpenDocument (autor, última modificação por, empresa) e dados de vídeo MP4/MOV (data de gravação, duração, resolução). -- **Linha do tempo:** datas de criação, modificação e acesso lidas do NTFS, FAT e exFAT. -- **Sessões salvas sozinhas e disco que volta com outro nome:** a varredura é salva automaticamente, pausa se o disco for desconectado e o Guará reconhece o mesmo disco ao reconectar. -- **Pesquisa de texto no disco inteiro** (`guara search`), inclusive espaço livre e fora de partições, em UTF-8 e UTF-16, mostrando posição, partição e contexto. -- **Exportação CSV** (abre no Excel) e **relatório HTML** pronto para imprimir (`guara report`), com identificação do caso, origem, partições, resumo, hashes e lista dos arquivos. +- **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. -Escopo: o Guará trabalha com **mídias de armazenamento** (HD, SSD, pendrive, cartões e imagens de disco). Ele **não** desbloqueia celulares nem contorna senhas ou travas de segurança, e não substitui ferramentas de extração de dispositivos móveis. +> **Atenção:** o Guará ainda **não foi validado externamente** (por exemplo, nos testes do NIST CFTT) e não tem registro de auditoria nem relatório assinado. 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](ROADMAP.md). -## Limites conhecidos (v0.1) +## Limites conhecidos -Seja realista sobre o que dá para esperar: +- **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 e macOS:** o código compila e é testado em CI, mas os testes com imagens reais rodam só no Linux. Relatos de mídias reais são muito bem-vindos. +- **GUI:** no Linux e macOS o app reinicia inteiro como administrador (`pkexec` ou `osascript`) em vez de usar um processo auxiliar. -- **Dados sobrescritos não voltam.** Em **SSD com TRIM** o próprio disco pode zerar blocos apagados; o Guará avisa, mas não faz milagre. -- **Carving só acha arquivos contíguos.** Arquivos fragmentados sem metadados podem sair truncados (marcados com confiança baixa). -- **ext2/3/4, APFS e HFS+:** só varredura por assinatura (no ext, apenas no espaço livre). Não há leitura de inodes/journal ainda. -- **NTFS:** arquivos comprimidos/EFS e registros com lista de atributos (arquivos muito fragmentados) são ignorados ou marcados como incompletos. -- **exFAT:** coberto por teste com imagem sintética; falta validar em mais mídias reais. -- **Cifragem:** somente detecção. -- **Windows/macOS:** o código compila e é testado em CI, mas os testes com imagens reais rodam só no Linux. Relatos de mídias reais são muito bem-vindos. -- **GUI:** no Linux/macOS o app reinicia inteiro como administrador (via `pkexec`/`osascript`) em vez de usar um processo auxiliar separado (melhoria planejada). +## Para onde vai + +Resumo do [ROADMAP](ROADMAP.md): + +| | | +|---|---| +| **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 | +| **Próximo** | Registro de auditoria, relatório assinado e em PDF, mapa livre do APFS, testes em Windows e macOS | +| **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, carving, fusão, recuperação +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/JS; src-tauri/ = app desktop) -scripts/ geração de imagens de teste (FAT32, NTFS, ext4, exFAT) +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 ``` ```bash -cargo test --workspace # no Linux gera imagens reais com mtools/ntfs-3g/e2fsprogs (veja scripts/) +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](CONTRIBUTING.md). Versões seguem [SemVer](https://semver.org/lang/pt-BR/); mudanças em [CHANGELOG.md](CHANGELOG.md). Para publicar: `git tag vX.Y.Z && git push --tags` (o workflow `release` compila e publica tudo). +Veja [CONTRIBUTING.md](CONTRIBUTING.md) e [docs/arquitetura.md](docs/arquitetura.md). Versões seguem [SemVer](https://semver.org/lang/pt-BR/); mudanças em [CHANGELOG.md](CHANGELOG.md). Para publicar: `git tag vX.Y.Z && git push --tags` (o workflow `release` compila e publica tudo). Vulnerabilidades: [SECURITY.md](SECURITY.md). ## Licença [MIT](LICENSE-MIT) ou [Apache-2.0](LICENSE-APACHE), à sua escolha. - -## Novidades da 1.0.0 - -Metadados de ext4, HFS+, Btrfs, XFS e APFS; abertura de volumes BitLocker, LUKS e FileVault 2 com senha ou chave; RAID (0/1/4/5/6/10) e LVM remontados, com parâmetros descobertos sozinhos; imagens E01, Ex01 e AFF4; JPEG fragmentado e MP4 sem índice. Detalhes e limitações no [CHANGELOG](CHANGELOG.md). - -## Novidades da 0.6.0 - -- Saúde do disco completa, no estilo do CrystalDiskInfo: estado com % de vida útil, temperatura, horas e vezes ligado, total lido e gravado, ficha do dispositivo (modelo, firmware, interface, modo de transferência, rotação, recursos) e a tabela inteira de atributos SMART (ATA e NVMe). -- Novo comando `guara health` no terminal. -- Nova logo: a cabeça do guará recortada das trilhas de um disco. - -## Novidades da 0.5.0 - -- Visualizador de bancos SQLite com recuperação de linhas apagadas. -- Aviso de saúde do disco (SMART) antes da varredura profunda. -- Notificações do sistema, retomada de recuperação interrompida e mapa de fotos com GPS (opcional). -- Interface em inglês e janela de Configurações. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..39d67ee --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,178 @@ +# Roadmap + +Onde o Guará esteve, onde está e para onde vai. O que está marcado como feito existe no código e tem teste; o que está planejado é intenção, não promessa, e não tem data. + +Legenda: ✅ feito · 🟡 parcial · 🔜 planejado · 🔭 ideia a longo prazo · ⛔ fora do escopo + +## Princípios que não mudam + +1. **A origem é somente leitura.** Nada no núcleo escreve no dispositivo recuperado. +2. **Não entregar sem validar.** Um recurso só entra com teste contra imagem real ou de referência. Por isso ReFS e Storage Spaces ainda não existem: não há imagem de referência para conferir. +3. **Confiança honesta.** Se o conteúdo não pôde ser conferido, a confiança é baixa ou média, nunca alta. +4. **Livre e auditável.** Código aberto (MIT ou Apache-2.0), sem telemetria, e cada resultado pode ser reproduzido. + +## Histórico + +| Versão | Data | Marco | +|---|---|---| +| 0.1.0 | 2026-10-18 | Núcleo somente leitura, MBR/GPT, NTFS, FAT, exFAT, carving por estrutura, imagem forense, sessões, CLI e interface | +| 0.2.0 | 2026-10-18 | Pré-visualização completa (imagem, vídeo, áudio, PDF, Office, ZIP, hexadecimal) e temas | +| 0.3.0 | 2026-10-18 | Explorador com miniaturas, metadados (EXIF, GPS), hashes, busca no disco, CSV, relatório HTML e duplicadas | +| 0.4.0 | 2026-10-18 | Reconexão de disco, sessões automáticas, organização ao recuperar | +| 0.5.0 | 2026-10-18 | Visualizador de SQLite com linhas apagadas, SMART, interface em inglês, retomada de recuperação | +| 0.6.0 | 2026-10-18 | Saúde do disco completa (SMART ATA e NVMe), `guara health`, nova logo | +| 1.0.0 | 2026-10-19 | ext4, HFS+, Btrfs, XFS, APFS; BitLocker, LUKS, FileVault 2; RAID e LVM; E01, Ex01, AFF4; JPEG fragmentado; MP4 sem moov | + +Detalhes de cada versão no [CHANGELOG](CHANGELOG.md). + +## Situação atual (1.0.0) contra o que se espera de uma suíte forense + +### 1. Sistemas de arquivos com metadados + +| Item | Estado | Observação | +|---|---|---| +| NTFS, FAT12/16/32, exFAT | ✅ | Desde a 0.1.0. NTFS ignora arquivos comprimidos e EFS | +| ext2/3/4 | ✅ | Inodes apagados e cópias antigas no diário | +| HFS+ | ✅ | Sobras de nós da árvore e diário | +| Btrfs | ✅ | Versões antigas das árvores; extensões zlib, zstd e lzo | +| XFS | ✅ | Inodes liberados e nomes de entradas liberadas. Testado só com exclusão simulada | +| APFS | 🟡 | Contêiner, mapa de objetos, instantâneos e nós antigos. **Falta o mapa de espaço livre**; exclusão testada só em simulação | +| ReFS | 🔜 | Hoje só é detectado; a recuperação depende do carving. Falta imagem de referência | +| Storage Spaces | 🔜 | Não feito. Falta imagem de referência | +| NTFS: atributos comprimidos, EFS, lista de atributos | 🔜 | Hoje marcados como incompletos | +| Validação de XFS e APFS com exclusão real | 🔜 | Trocar a simulação por imagens de dispositivos reais | + +### 2. Volumes cifrados + +| Item | Estado | +|---|---| +| BitLocker (senha, chave de recuperação, .BEK, chave limpa) | ✅ | +| LUKS1 e LUKS2 | ✅ | +| FileVault 2 (Core Storage) | ✅ | +| FileVault 2 em APFS com volume cifrado | 🔜 | +| Chave a partir de memória (hibernação, despejo de RAM) | 🔭 | +| Ataque de dicionário e força bruta (BitLocker, LUKS, FileVault, RAR, ZIP e demais volumes/arquivos cifrados) | 🔜 | + +Hoje o Guará abre volumes quando você **já tem** a senha ou a chave. Recuperação de senha por dicionário e força bruta (com GPU, como Hashcat) é um recurso planejado, central no uso pericial. + +### 3. Imagens forenses + +| Item | Estado | +|---|---| +| Imagem bruta (dd) tolerante a setores ruins, com mapa de erros | ✅ | +| E01 e Ex01: leitura, gravação e `guara verify` | ✅ | +| AFF4: leitura e gravação | ✅ | +| Outros contêineres (VMDK, VHD/VHDX, QCOW2, DMG) | 🔜 | +| Imagem de dispositivo móvel (ver item 7) | 🔭 | + +### 4. Montagem de discos soltos + +| Item | Estado | +|---|---| +| RAID 0, 1, 4, 5, 6, 10 e linear (mdadm), inclusive degradado | ✅ | +| Descoberta automática de nível, faixa, layout e ordem sem metadados | ✅ | +| LVM2 (linear, em faixas, espelhado e RAID) | ✅ | +| Storage Spaces | 🔜 | +| Btrfs e ZFS multidisco (RAID do próprio sistema de arquivos) | 🔭 | +| RAID de controladoras proprietárias (Dell PERC, HP Smart Array) | 🔭 | + +### 5. Carving + +| Item | Estado | +|---|---| +| Detecção pela estrutura real, com tamanho exato e confiança | ✅ Desde a 0.1.0 (JPEG, PNG, GIF, BMP, PDF, ZIP e derivados, MP4/MOV/HEIC, AVI/WAV/WebP, SQLite, 7z, OLE, MP3, PE) e, na 1.0.0, mais 24 (gzip, zstd, Matroska/WebM, Ogg, MPEG-TS, FLV, ASF, MIDI, RAR, ar, SWF, ELF, TIFF, ICO, registro do Windows, EVTX, PST, RTF, pcap e outros) | +| JPEG fragmentado remontado (até três fragmentos) | ✅ | +| MP4/MOV sem `moov` reconstruído (H.264 e HEVC) a partir de um vídeo de referência | ✅ | +| Fragmentos: mais de três, e formatos além de JPEG (PNG, DOC, ZIP, SQLite) | 🔜 | +| Reconstrução de vídeo sem referência, áudio em MP4 sem `moov`, vídeos de drone e câmeras de ação em outros contêineres | 🔜 | +| Mais formatos validados por estrutura | 🔜 contínuo | + +### 6. Interpretação de artefatos + +O Guará **identifica e recupera** esses arquivos, mas só interpreta alguns. + +| Item | Estado | +|---|---| +| Banco SQLite: esquema, tabelas, blobs, datas e linhas apagadas | ✅ | +| Metadados: EXIF e GPS, PDF, Office e OpenDocument, MP4/MOV | ✅ | +| Carving de registro do Windows (`regf`), EVTX, PST, pcap | 🟡 só reconhece e recupera, não interpreta | +| Interpretar o registro do Windows (usuários, programas, USB, histórico de execução) | 🔜 | +| Histórico, cookies e downloads de navegadores (Chrome, Firefox, Safari) | 🔜 base no leitor de SQLite | +| Mensagens, contatos e localização de apps (WhatsApp, Telegram, Signal e outros) | 🔜 base no leitor de SQLite | +| Logs do sistema e eventos do Windows (EVTX) | 🔜 | +| **Linha do tempo unificada** de todos os artefatos | 🔜 | + +### 7. Extração de dispositivos móveis + +Aqui o salto é de natureza, não de recurso. Hoje o Guará trabalha com **mídias de armazenamento**. + +| Item | Estado | +|---|---| +| Android por ADB e backups | 🔭 | +| iOS por backups do iTunes ou Finder (inclusive cifrados com senha) | 🔭 | +| Acesso físico por exploits de bootloader e de chip | 🔭 | + +O acesso físico é o diferencial de ferramentas comerciais como a Cellebrite. Depende de equipes de pesquisa de vulnerabilidades em tempo integral e muitas dessas técnicas não são publicáveis em código aberto, o que torna esse item o mais distante do roadmap. A direção mais próxima é ler o que o usuário ou o perito consegue exportar de forma legítima (backups e ADB) e interpretar esses dados com o item 6; o acesso físico por exploit fica como ideia de longo prazo, a perseguir conforme o projeto crescer. + +### 8. Cadeia de custódia e validade em tribunal + +| Item | Estado | +|---|---| +| MD5, SHA-1 e SHA-256 de cada arquivo, da imagem e do dispositivo | ✅ | +| Manifesto `guara-manifesto.json` em toda recuperação | ✅ | +| Relatório HTML com caso, examinador, origem, partições, resumo e hashes | ✅ | +| Verificação de imagem E01/Ex01 contra o hash gravado | ✅ | +| **Registro de auditoria** de cada ação do perito (quem, quando, o quê) | 🔜 | +| **Relatórios assinados** digitalmente e manifesto com carimbo de tempo | 🔜 | +| **Reprodutibilidade:** repetir o procedimento gravado e obter o mesmo resultado | 🔜 | +| Relatório em PDF | 🔜 | +| **Validação externa:** testes do NIST CFTT (Computer Forensic Tool Testing) e publicação dos resultados | 🔭 | +| Binários assinados (Windows e macOS) | 🔜 | + +A validação externa é o que faz um laudo ser aceito. Sem ela, o Guará serve para triagem, recuperação e apoio, e o perito deve conferir os resultados por outro meio. + +### 9. Análise + +| Item | Estado | +|---|---| +| Busca por texto em todo o disco, UTF-8 e UTF-16, inclusive espaço livre | ✅ `guara search` | +| Detecção de duplicadas | ✅ | +| Busca por expressão regular e por palavra-chave em **conteúdo de arquivos** (Office, PDF, e-mail) | 🔜 | +| Hashes conhecidos: **NSRL** para ignorar arquivos de sistema | 🔜 | +| Listas de hashes de material ilícito (importadas pelo perito) | 🔜 | +| Detecção de imagens por conteúdo (similaridade, classificação) | 🔭 | +| **OCR** em imagens e PDF digitalizados | 🔭 | + +### 10. Plataforma e distribuição + +| Item | Estado | +|---|---| +| CLI e interface para Windows, Linux e macOS | ✅ | +| CI em três sistemas, release automática por tag | ✅ | +| Testes com imagens reais em Windows e macOS (hoje só Linux) | 🔜 | +| GUI: processo auxiliar privilegiado em vez de reiniciar o app inteiro como administrador | 🔜 | +| Binários assinados e notarizados | 🔜 | +| Pacotes em gerenciadores (winget, Homebrew, Flatpak) | 🔭 | + +## Próximos marcos sugeridos + +Sem datas, na ordem em que fazem mais sentido. + +**1.1: confiança e custódia** +Registro de auditoria, relatório em PDF, manifesto assinado, mapa de espaço livre do APFS, validação de XFS e APFS com exclusões reais, testes com imagens reais no Windows e macOS. + +**1.2: análise** +NSRL e listas de hashes, busca em conteúdo de arquivos, linha do tempo unificada. + +**1.3: artefatos** +Registro do Windows, navegadores, EVTX e os apps de mensagem mais comuns, apoiados no leitor de SQLite. + +**1.4: mais estrutura** +ReFS e Storage Spaces (quando houver imagem de referência), outros contêineres de imagem (VMDK, VHD, QCOW2), carving fragmentado ampliado. + +**2.0: dispositivos móveis e validação** +Backups do iTunes, ADB e backups do Android; submissão aos testes do NIST CFTT. + +## Como ajudar + +O gargalo mais comum é **imagem de referência**: um volume ReFS, um pool de Storage Spaces ou um XFS com exclusão real, de preferência pequeno e sem dados pessoais. Se você tem um, abra uma issue. Veja também o [CONTRIBUTING](CONTRIBUTING.md). diff --git a/docs/arquitetura.md b/docs/arquitetura.md new file mode 100644 index 0000000..6618a4a --- /dev/null +++ b/docs/arquitetura.md @@ -0,0 +1,95 @@ +# Arquitetura + +O Guará é um workspace Rust com três partes: um núcleo (`guara-core`), um binário de terminal (`guara-cli`) e uma interface (`apps/gui`) que é a mesma página web servida de duas formas. + +``` +crates/guara-core biblioteca: tudo que lê, interpreta e recupera +crates/guara-cli binário `guara`: comandos e servidor local da interface +apps/gui/ui HTML, CSS e JS da interface +apps/gui/src-tauri casca desktop (Tauri) que carrega a mesma interface +``` + +## Fluxo de uma varredura + +``` +origem (dispositivo ou imagem) + │ source / device leitura somente leitura, setores ruins tolerados + ▼ +disco virtual (opcional) + │ assemble junta imagem E01/AFF4, RAID, LVM e volumes cifrados + ▼ +partições e volumes + │ partition, volume MBR, GPT, volumes perdidos por assinatura + ▼ +duas buscas em paralelo + ├─ fs/* metadados: NTFS, FAT, exFAT, ext, HFS+, Btrfs, XFS, APFS + └─ carve + signatures estrutura dos arquivos no espaço livre e fora de partições + + formats, jpegscan, defrag, mp4rebuild + ▼ +scan funde sem duplicatas e atribui a confiança + ▼ +sessão salva retomar, exportar, relatar + ▼ +recover copia com MD5, SHA-1 e SHA-256 e grava o manifesto +``` + +## Módulos do núcleo + +### Acesso e montagem +| Módulo | Função | +|---|---| +| `source`, `device` | Abrir dispositivos e imagens somente para leitura; listar discos | +| `image` | Imagem bruta tolerante a setores ruins, com mapa de erros | +| `ewf`, `aff4` | Ler e gravar E01/Ex01 e AFF4 | +| `assemble` | Monta o disco virtual: imagem, RAID, LVM e volume cifrado | +| `raid`, `raid_detect`, `lvm` | Remontagem de RAID (com descoberta automática de parâmetros) e LVM2 | +| `crypt/` | BitLocker, LUKS e FileVault 2 | +| `reconnect` | Reconhecer o mesmo disco que voltou com outro nome | + +### Interpretação +| Módulo | Função | +|---|---| +| `partition`, `volume` | Tabelas de partição e detecção de volumes | +| `fs/` | Um leitor por sistema de arquivos | +| `signatures`, `formats` | Detectores de formato pela estrutura | +| `carve`, `scan` | Varredura por assinatura e fusão com os metadados | +| `jpegscan`, `defrag`, `mp4rebuild` | JPEG fragmentado e MP4 sem `moov` | +| `meta`, `sqlite`, `thumb` | Metadados, leitor de SQLite, miniaturas | + +### Resultado e perícia +| Módulo | Função | +|---|---| +| `recover` | Copia os arquivos, confere os hashes, grava o manifesto, retoma recuperação | +| `hashing`, `search` | Hashes e busca de texto no disco inteiro | +| `report`, `explorer` | Relatório HTML, CSV, filtros e agrupamentos do explorador | +| `health`, `external` | SMART e ferramentas externas (`smartctl`) | + +### Serviço +`service`, `http`, `settings`, `notify`, `owner`: a camada que a interface usa (API local, configurações, notificações, e gravação com o dono certo quando roda como administrador). + +## Interface + +A interface é uma página só (`apps/gui/ui`). Há duas formas de rodá-la: + +- **App desktop (Tauri):** a janela carrega a página e fala com o núcleo diretamente. +- **`guara ui`:** o binário sobe um servidor em `127.0.0.1` protegido por token e abre o navegador. + +Como o front-end é o mesmo, tudo que existe em um existe no outro. + +## Decisões de projeto + +- **Somente leitura na origem, por construção.** Todo acesso a dispositivo passa por `source::open_path`. Revisão de código recusa qualquer escrita na origem. +- **Recusa de destino no mesmo disco** da origem (Linux e macOS), para não sobrescrever o que se quer recuperar. +- **Confiança por arquivo.** Cada detector declara o quanto conseguiu conferir; a fusão fica com a melhor evidência. +- **Leitores próprios.** Sistemas de arquivos, cifras, SQLite e contêineres de imagem são implementados no núcleo, para tolerar estruturas corrompidas, que é exatamente o caso de uso. +- **Segredos fora da sessão.** Senhas nunca são gravadas; no máximo a chave do volume, e só com `--remember-keys`. +- **Privilégios.** Ler disco bruto exige administrador, mas tudo que o Guará grava (sessões, relatórios, recuperados) fica com o dono e as permissões do usuário que o abriu. + +## Testes + +Cerca de cem testes, em `crates/guara-core/tests/` (um arquivo por área: `ext4`, `xfs`, `apfs`, `bitlocker`, `raid`, `ewf`, `jpegscan`, `mp4rebuild`, `sqlite` e outros). + +- **Imagens geradas na hora** com `mtools`, `ntfs-3g`, `e2fsprogs` e afins (`scripts/make-fixtures.sh`). +- **Imagens de referência** de projetos externos (cryptsetup, dfvfs, AFF4) baixadas por `scripts/fetch-testdata.sh` para `target/testdata`. Sem elas, os testes correspondentes são pulados. +- Os testes de BitLocker levam cerca de 75 s por causa da derivação de chave. +- No CI os testes com imagens reais rodam só no Linux. diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..c34ffbe --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,124 @@ +# Referência do terminal + +Ler disco bruto exige privilégios: administrador no Windows, `sudo` no Linux e no macOS. Use `guara