Documentação: inglês como versão principal e português em *.pt-BR.md
README, ROADMAP, CHANGELOG, CONTRIBUTING, SECURITY e docs/ passam a ter a versão principal em inglês. As versões em português ficam em *.pt-BR.md e docs/pt-BR/, com seletor de idioma no topo de cada arquivo. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RRZm8uTVN3WLTwcbrDQAUM
This commit is contained in:
Lucas RayanandClaude Sonnet 5.5 committed
1 parent
3755fc7d2a
commit
b93ad02a0e
16 files changed
+1192
-369
No files matched your search
@@ -0,0 +1,97 @@
|
||||
# Arquitetura
|
||||
|
||||
[English](../architecture.md) · **Português**
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,126 @@
|
||||
# Referência do terminal
|
||||
|
||||
[English](../cli.md) · **Português**
|
||||
|
||||
Ler disco bruto exige privilégios: administrador no Windows, `sudo` no Linux e no macOS. Use `guara <comando> --help` para a lista completa de opções.
|
||||
|
||||
## Comandos
|
||||
|
||||
| Comando | Para que serve |
|
||||
|---|---|
|
||||
| `devices` | Lista discos e pendrives, avisa TRIM e volumes montados |
|
||||
| `inspect <origem>` | Partições, espaço não particionado, cifragem |
|
||||
| `health <origem>` | Saúde do disco (SMART); requer `smartmontools` |
|
||||
| `scan <origem>` | Varredura de arquivos apagados e perdidos |
|
||||
| `resume <sessão>` | Continua uma varredura pausada |
|
||||
| `recover <sessão> <destino>` | Recupera os arquivos de uma sessão |
|
||||
| `image <origem> <destino>` | Imagem forense (bruta, E01 ou AFF4) |
|
||||
| `verify <imagem>` | Confere uma imagem E01 ou Ex01 contra o hash gravado |
|
||||
| `hash <origem>` | MD5, SHA-1 e SHA-256 do dispositivo |
|
||||
| `search <origem> <termos...>` | Texto no disco inteiro, UTF-8 e UTF-16 |
|
||||
| `export <sessão> <csv>` | Planilha dos achados |
|
||||
| `report <sessão> <html>` | Relatório HTML imprimível |
|
||||
| `sessions` | Sessões salvas automaticamente |
|
||||
| `ui` | Interface no navegador (127.0.0.1, com token) |
|
||||
|
||||
`--json` existe em `devices`, `inspect`, `health` e `scan`.
|
||||
|
||||
## Varredura
|
||||
|
||||
```bash
|
||||
sudo guara scan /dev/sdb --session s.json --list # profunda, com lista
|
||||
sudo guara scan /dev/sdb --quick # só metadados, em segundos
|
||||
guara scan disco.img --category image,document --min-confidence medium
|
||||
guara scan disco.img --recover /mnt/outro-disco/Recuperados
|
||||
```
|
||||
|
||||
Filtros (valem em `scan`, `recover`, `export` e `report`):
|
||||
|
||||
| Opção | Efeito |
|
||||
|---|---|
|
||||
| `--category` | `image`, `document`, `video`, `audio`, `archive`, `database`, `other` (separe por vírgula) |
|
||||
| `--min-confidence` | `low`, `medium` ou `high` |
|
||||
| `--name` | só nomes e caminhos que contenham o texto |
|
||||
| `--organize` | como gravar: `folders` (pastas originais), `type`, `date` ou `flat` |
|
||||
|
||||
## Recuperação
|
||||
|
||||
```bash
|
||||
guara recover s.json /mnt/outro-disco/Recuperados --category image
|
||||
guara resume s.json
|
||||
```
|
||||
|
||||
O destino precisa estar em **outro disco**. Cada recuperação grava `guara-manifesto.json` com MD5, SHA-1 e SHA-256 de todos os arquivos. Se a recuperação for interrompida, repetir o comando pula o que já foi copiado e conferido.
|
||||
|
||||
## Volumes cifrados
|
||||
|
||||
```bash
|
||||
sudo guara scan /dev/sdb1 --ask-password
|
||||
sudo guara scan /dev/sdb1 --recovery-key 111111-222222-333333-444444-555555-666666-777777-888888
|
||||
sudo guara scan /dev/sdb1 --key-file chave.BEK
|
||||
sudo guara scan /dev/sdb1 --volume-key 4f2a...
|
||||
```
|
||||
|
||||
| Opção | Uso |
|
||||
|---|---|
|
||||
| `--ask-password` | Pergunta no terminal, sem mostrar. **Preferida** |
|
||||
| `GUARA_PASSWORD` | Variável de ambiente com a senha |
|
||||
| `--password` | Senha na linha de comando (fica no histórico do shell) |
|
||||
| `--recovery-key` | Chave numérica do BitLocker |
|
||||
| `--key-file` | `.BEK` do BitLocker ou keyfile do LUKS |
|
||||
| `--volume-key` | Chave do volume em hexadecimal (a que o Guará mostra ao abrir um volume) |
|
||||
| `--remember-keys` | Guarda na sessão as chaves dos volumes abertos (nunca a senha) |
|
||||
|
||||
## RAID e LVM
|
||||
|
||||
Passe o disco principal e os outros membros com `--member`, repetido. Use `-` para um disco ausente.
|
||||
|
||||
```bash
|
||||
# Com metadados do mdadm ou do LVM: o Guará lê tudo sozinho
|
||||
guara inspect disco1.img --member disco2.img --member disco3.img
|
||||
|
||||
# Sem metadados: descobre nível, faixa, layout e ordem
|
||||
guara scan disco1.img --member disco2.img --member disco3.img --raid
|
||||
|
||||
# Fixando o que você já sabe
|
||||
guara scan disco1.img --member disco2.img --member - --raid \
|
||||
--raid-level 5 --raid-chunk-kb 64 --raid-layout left-symmetric --raid-order 0,1,2
|
||||
```
|
||||
|
||||
## Imagem forense
|
||||
|
||||
```bash
|
||||
sudo guara image /dev/sdb /mnt/outro-disco/sdb.img # bruta, com mapa de erros
|
||||
sudo guara image /dev/sdb /mnt/outro-disco/sdb --format e01 \
|
||||
--case 2026-001 --examiner "Nome" --evidence E1 --description "HD do notebook"
|
||||
sudo guara image /dev/sdb /mnt/outro-disco/sdb --format aff4
|
||||
guara verify /mnt/outro-disco/sdb.E01
|
||||
```
|
||||
|
||||
Para E01: `--segment-mib` (tamanho de cada segmento, padrão 1500, 0 para um arquivo só) e `--compression` (0 a 9, padrão 1).
|
||||
|
||||
## Vídeo sem índice (MP4 sem moov)
|
||||
|
||||
Passe um vídeo **íntegro da mesma câmera ou drone** para o Guará refazer o índice:
|
||||
|
||||
```bash
|
||||
guara scan cartao.img --reference VIDEO_BOM.MP4 --category video
|
||||
```
|
||||
|
||||
`--reference` pode ser repetido. O áudio não é reconstruído.
|
||||
|
||||
## Busca de texto
|
||||
|
||||
```bash
|
||||
sudo guara search /dev/sdb "contrato" "cpf" --case-sensitive --max 500
|
||||
```
|
||||
|
||||
Procura em UTF-8 e UTF-16 (`--no-utf16` desliga), inclusive no espaço livre e fora de partições. Mostra posição, partição e contexto. `--max` limita os resultados (padrão 200).
|
||||
|
||||
## Relatório
|
||||
|
||||
```bash
|
||||
guara report s.json relatorio.html --case 2026-001 --examiner "Nome" --hash-source
|
||||
```
|
||||
|
||||
Traz identificação do caso, origem, partições, resumo, hashes e a lista dos arquivos. `--hash-source` inclui o hash da origem inteira.
|
||||
@@ -0,0 +1,104 @@
|
||||
# O que o Guará suporta
|
||||
|
||||
[English](../support.md) · **Português**
|
||||
|
||||
Matriz do que existe hoje (versão 1.0.0). Para o que vem a seguir, veja o [ROADMAP](../../ROADMAP.pt-BR.md).
|
||||
|
||||
## Tabelas de partição
|
||||
|
||||
MBR e GPT. Quando a tabela falha, o Guará procura volumes por assinatura (NTFS, FAT, exFAT, ext, APFS, HFS+, BitLocker, LUKS) e também examina o **espaço não particionado**.
|
||||
|
||||
## Sistemas de arquivos
|
||||
|
||||
"Metadados" significa que o Guará lê a estrutura do sistema de arquivos e devolve **nome, pasta e datas**. Sem isso, a recuperação depende só do carving, que devolve o conteúdo sem nome.
|
||||
|
||||
| Sistema | Metadados | O que é aproveitado | Limites |
|
||||
|---|---|---|---|
|
||||
| NTFS | ✅ | MFT, registros apagados, datas de criação, modificação e acesso | Comprimidos e EFS são ignorados ou marcados como incompletos; lista de atributos tratada de forma parcial |
|
||||
| FAT12/16/32 | ✅ | Entradas apagadas, nomes longos, datas | |
|
||||
| exFAT | ✅ | Entradas apagadas, datas | Coberto por imagem sintética; falta validar em mais mídias reais |
|
||||
| ext2/3/4 | ✅ | Inodes apagados, cópias antigas no diário (ext4), mapa de blocos livres | |
|
||||
| HFS+ | ✅ | Sobras de nós da árvore de catálogo, diário | |
|
||||
| Btrfs | ✅ | Versões antigas das árvores; extensões zlib, zstd e lzo | |
|
||||
| XFS | ✅ | Inodes liberados, nomes de entradas liberadas, espaço livre por grupo | Exclusão testada só em simulação |
|
||||
| APFS | 🟡 | Contêiner, mapa de objetos, árvore de arquivos, instantâneos, nós antigos | Sem mapa de espaço livre; exclusão testada só em simulação |
|
||||
| ReFS | ❌ | Apenas detectado | Recuperação por carving |
|
||||
| Storage Spaces | ❌ | Não suportado | |
|
||||
|
||||
Em todos os casos o carving continua rodando no espaço livre e o resultado é fundido sem duplicatas.
|
||||
|
||||
## Volumes cifrados
|
||||
|
||||
O Guará abre o volume com a **senha ou a chave que você fornece**, monta um disco virtual e varre por dentro. Ele não quebra senhas.
|
||||
|
||||
| Formato | Credenciais aceitas |
|
||||
|---|---|
|
||||
| BitLocker | Senha, chave de recuperação (8 grupos de 6 dígitos), arquivo `.BEK`, chave limpa |
|
||||
| LUKS1 e LUKS2 | Senha, arquivo de chave, chave do volume |
|
||||
| FileVault 2 (Core Storage) | Senha, chave de recuperação, chave do volume |
|
||||
|
||||
As senhas **nunca** vão para o arquivo de sessão. Com `--remember-keys` a sessão guarda a chave do volume já derivada, não a senha. No terminal, prefira `--ask-password` ou a variável `GUARA_PASSWORD` a `--password`, que fica no histórico do shell.
|
||||
|
||||
## RAID e LVM
|
||||
|
||||
| Item | Suporte |
|
||||
|---|---|
|
||||
| RAID 0, 1, 4, 5, 6, 10 e linear a partir de superblocos do mdadm | ✅ inclusive degradado (use `-` em `--member` para um disco ausente) |
|
||||
| RAID sem metadados | ✅ `--raid` descobre nível, faixa, layout e ordem; `--raid-level`, `--raid-chunk-kb`, `--raid-layout` e `--raid-order` fixam o que você já sabe |
|
||||
| LVM2 | ✅ linear, em faixas, espelhado e RAID |
|
||||
| Storage Spaces | ❌ |
|
||||
|
||||
## Imagens forenses
|
||||
|
||||
| Formato | Ler | Gravar |
|
||||
|---|---|---|
|
||||
| Bruta (dd, `.img`) | ✅ | ✅ com mapa de erros de setores ruins |
|
||||
| E01 e Ex01 (Expert Witness) | ✅ | ✅ com metadados do caso e segmentação |
|
||||
| AFF4 | ✅ | ✅ |
|
||||
|
||||
`guara verify` recalcula o MD5 de uma imagem E01 ou Ex01 e compara com o gravado nela.
|
||||
|
||||
## Carving: formatos reconhecidos pela estrutura
|
||||
|
||||
Os detectores leem cabeçalhos, blocos e tamanhos internos para devolver o **tamanho exato** e uma **confiança**, em vez de cortar em um número fixo de bytes.
|
||||
|
||||
| Família | Formatos |
|
||||
|---|---|
|
||||
| Imagem | JPEG, PNG, GIF, BMP, TIFF, ICO, HEIC, WebP |
|
||||
| Documento | PDF, DOC/XLS/PPT (OLE), DOCX/XLSX/PPTX/ODF/EPUB (ZIP), RTF |
|
||||
| Vídeo e áudio | MP4/MOV, AVI, WAV, MP3, Matroska/WebM, Ogg, MPEG-TS, FLV, ASF/WMV, MIDI |
|
||||
| Compactado | ZIP, 7z, RAR, gzip, zstd, ar |
|
||||
| Banco e sistema | SQLite, registro do Windows (regf), EVTX, PST, pcap/pcapng, EXE/DLL (PE), ELF, SWF |
|
||||
|
||||
### Arquivos fragmentados
|
||||
|
||||
- **JPEG:** remontado a partir de até três fragmentos (`jpegscan.rs`, `defrag.rs`).
|
||||
- **MP4/MOV sem índice (`moov`):** o índice é refeito a partir de um vídeo íntegro da **mesma câmera ou drone**, passado com `--reference`. Funciona com H.264 e HEVC. O áudio não é reconstruído.
|
||||
- Os demais formatos só saem inteiros se estiverem contíguos; do contrário saem truncados com confiança baixa.
|
||||
|
||||
## Metadados e pré-visualização
|
||||
|
||||
| Tipo | O que é lido |
|
||||
|---|---|
|
||||
| Fotos | EXIF: câmera, lente, número de série, data, GPS |
|
||||
| PDF | Autor, programa, datas |
|
||||
| Office e OpenDocument | Autor, última modificação por, empresa |
|
||||
| MP4/MOV | Data de gravação, duração, resolução |
|
||||
| SQLite | Esquema, tabelas, blobs, datas, linhas apagadas do espaço livre das páginas |
|
||||
|
||||
A pré-visualização é lida direto do disco, sem gravar nada: imagem, vídeo, áudio, PDF, texto, Office, ZIP e hexadecimal.
|
||||
|
||||
## Plataformas
|
||||
|
||||
| | CLI | Interface | Testes com imagens reais |
|
||||
|---|---|---|---|
|
||||
| Linux | ✅ | ✅ AppImage e deb | ✅ |
|
||||
| Windows | ✅ | ✅ msi e exe | só compilação e testes sintéticos |
|
||||
| macOS | ✅ | ✅ dmg | só compilação e testes sintéticos |
|
||||
|
||||
## O que o Guará não faz
|
||||
|
||||
- Recuperar dados **sobrescritos**. Em SSD com TRIM o próprio disco pode zerar blocos apagados.
|
||||
- Desbloquear celulares ou contornar senhas e travas de segurança.
|
||||
- Substituir uma ferramenta de extração de dispositivos móveis.
|
||||
- Produzir laudo com validade pericial por si só: ainda não passou por validação externa (NIST CFTT). Veja o [ROADMAP](../../ROADMAP.pt-BR.md).
|
||||
Reference in new issue
Block a user