Lucas RayanandClaude Sonnet 5
cdda2bc45f
update_apply used to flatly refuse to run for the GUI binary and point
the user to a manual download instead. Since both desktop apps already
elevate to root/administrator before showing their window, the
process applying the update already has everything it needs — no
second authentication round is required.
- New guara_core::update::apply_desktop[_with_progress], alongside the
existing CLI-only apply() (left untouched): detects the install kind
at runtime (AppImage via the APPIMAGE env var — current_exe() is
unreliable there, same FUSE-mount issue elevated_exe() already works
around and this reuses; Deb otherwise on Linux; WindowsInstaller on
Windows), matches the right release asset by the GUI bundle naming
(_amd64/_aarch64.AppImage, _amd64/_arm64.deb, _x64-setup.exe — a
different suffix convention than the CLI tarballs), verifies SHA-256
when a sidecar is published, and installs:
- AppImage: downloads to a temp file in the same directory (same
filesystem, atomic rename), renames over the running file, execs
it in place (same PID, same already-root privileges — no elevation
dance needed).
- .deb: runs `dpkg -i` directly (already root), then execs
current_exe() again now that dpkg replaced it on disk.
- Windows: runs the downloaded installer with /S (silent) detached,
then exits immediately to release the file lock on our own .exe.
Does NOT claim to relaunch the app afterwards — there is no
documented NSIS or Tauri flag for that (verified against NSIS's
and Tauri's own docs: Tauri's own updater restarts the app from its
own Rust code after the installer exits, not via a command-line
switch), and blocking here on the installer's exit status risks a
self-deadlock if its script waits for this process to close before
it can overwrite the running .exe. Needs a real Windows machine to
confirm the actual post-install behavior.
- Engine::update_apply_desktop wires it into the Tauri `update_apply`
command, which now also takes AppHandle and emits `update-progress`
events (downloading/verifying/installing/restarting) for the UI.
- Sabiá: the existing #btnUpdate handler changed the button's label to
"update to X" but never actually called apply — wired it for real,
with the same progress feedback.
- Guará: restored the "Update now" action in the update card (removed
during the updater-unification migration), wired to the new command.
- scripts/build-gui.sh: generates a .sha256 next to every file in
dist-gui/, matching the existing convention for CLI release
archives, so apply_desktop can verify downloads the same way CLI
update --apply already does.
- 3 new unit tests per repo: install-kind detection, GUI asset suffix
matching against real release naming, and the existing CLI-refusal
test still passes unchanged.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VAyr8d7HuAdUGB6aA5xmDD
Guará
Free file recovery for hard drives, SSDs and USB sticks.
Terminal and graphical interface · Windows and Linux · read-only on the source.
What it supports · Interface · Terminal · Architecture · Roadmap · Changelog
English · Português
The real interface running on a synthetic test image (generated photos, no real data).
In a single scan, Guará does what tools like Recuva, PhotoRec, TestDisk and Disk Drill do separately:
- File system metadata: finds deleted files with name, folder and date on NTFS, FAT12/16/32, exFAT, ext2/3/4, HFS+, Btrfs and APFS (on XFS only the content comes back, by carving, see below).
- Structure-aware carving in free space, damaged partitions and unpartitioned space. The detectors read the real structure of dozens of formats to learn the exact size and a confidence level.
- Encrypted volumes: opens BitLocker, LUKS and FileVault 2 with your password or key and scans inside.
- RAID and LVM: reassembles arrays from loose disks (RAID 0, 1, 4, 5, 6, 10, LVM2), working out level, stripe size and order by itself when there is no metadata.
- Fragmented files: reassembles JPEGs stored in pieces and rebuilds the index of MP4/MOV videos that lost their
moov. - Forensic images: reads and writes raw images, E01/Ex01 and AFF4, and reads QCOW2, VMDK, VHD, VHDX and DMG virtual disks.
- Lost partitions: reads MBR/GPT and searches for volumes by signature where the table failed.
- Merge without duplicates: a file found by more than one method appears once, with the best evidence.
- Per-file confidence (high, medium, low): intact structure, reused clusters, zeroed content (TRIM) or content that does not match the extension.
The full matrix, with the limits of each item, is in docs/support.md.
Data safety
- The source is opened read-only. Nothing in the core writes to the device being recovered.
- Recovery refuses destinations on the same disk as the source (Linux and macOS).
- Forensic imaging tolerates bad sectors, with an error map and hash: always work on the copy of a failing disk.
- Every recovery writes
guara-manifesto.jsonwith the MD5, SHA-1 and SHA-256 of every file. - Passwords are never written to the session file.
Installation
Download the package for your system from Releases:
| CLI | Graphical app | |
|---|---|---|
| Windows | — | .msi / .exe installer |
| Linux | guara-*-linux-{x86_64,aarch64}.tar.gz |
.AppImage / .deb |
The CLI is Linux-only; the desktop app ships for Linux and Windows. Every CLI
package has a .sha256 next to it. To build from source: cargo build --release -p guara-cli (Rust 1.80+, Linux).
Updates: the desktop app checks Gitea on startup; when a new version exists, a notice offers the release link. The CLI updates the same way (guara update); it downloads the right binary for your platform, verifies the SHA-256 and swaps the running executable — no manual download. The check is a single request to the releases API and sends nothing of yours.
The binaries are not signed yet: Windows SmartScreen will warn you. Check the SHA-256.
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.
Getting started
sudo guara devices # which disks exist
sudo guara scan /dev/sdb --session s.json --list # deep scan
guara recover s.json /mnt/other-disk/Recovered # recover, onto ANOTHER disk
Failing disk? Make the image first and work on the copy:
sudo guara image /dev/sdb /mnt/other-disk/sdb.img
guara scan /mnt/other-disk/sdb.img --session s.json
Other commands (inspect, health, hash, search, export, report, verify, ui, encrypted volumes, RAID) are in docs/cli.md.
Graphical interface
A desktop app (Tauri) in the style of a file manager, designed for when Guará finds thousands of items. The same front end runs in the browser with guara ui. More screenshots and details in docs/interface.md.
- Thumbnail grid or list, grouping by day or month and virtual scrolling for tens of thousands of files.
- Sidebar navigation by type, real photo date (EXIF), folder, camera, confidence and GPS, with an option to hide duplicates.
- Finder or Explorer style selection and full-screen quick look (Space, Enter or double click).
- Details panel with preview, dates and metadata.
- Fields for password, RAID, reference video and image format; disk health (SMART); pause and resume; Auto, Light and Dark themes; interface in English and Portuguese, chosen in Settings.
Preview before recovering, read straight from the disk without writing anything: images, video, audio, PDF, text, Word/Excel/PowerPoint/OpenDocument, ZIP contents, SQLite databases (with deleted rows) and hex. On Linux, video playback depends on the gstreamer1.0-libav and gstreamer1.0-plugins-good plugins; without them, the "Open in system player" button covers the case.
Forensic features
- Hashes MD5, SHA-1 and SHA-256 of every recovered file, of the image and of the device.
- Metadata: EXIF (camera, lens, serial number, GPS), PDF, Office and OpenDocument, MP4/MOV.
- Timeline: creation, modification and access dates from NTFS, FAT and exFAT.
- Text search across the whole disk, including free space, in UTF-8 and UTF-16.
- CSV (opens in Excel) and a printable HTML report with case, examiner, source, partitions, summary and hashes.
- Automatic sessions and reconnection: Guará recognizes the same disk coming back under another name.
- Duplicate detection by content signature.
Warning: Guará has not been externally validated yet (for example, in the NIST CFTT tests) and has no trusted timestamp (RFC 3161) on its signatures. It is well suited to recovery and triage; for use in court, check the results by other means. The path to get there is in the ROADMAP.
Known limits
- Overwritten data does not come back. On an SSD with TRIM the disk may zero deleted blocks; Guará warns you, but it cannot work miracles.
- Fragments: only JPEG (up to three pieces) and MP4 without an index are reassembled. Other formats, if fragmented, come out truncated with low confidence.
- ReFS and Storage Spaces are not supported (ReFS is only detected).
- XFS: on a real XFS (v5, kernel deletion) the inode and its extent list are wiped, so Guará recovers the content of files with a recognizable structure by carving, but not their name or folder; reading names needs the file system journal, which is not implemented. The old inode-based path only works on simulated deletions. APFS: deletion recovery tested only in simulation.
- NTFS: compressed files, EFS and heavily fragmented records are skipped or marked as incomplete.
- exFAT: validated with a synthetic image; real media are still missing.
- Phones: Guará works with storage media and does not unlock devices or bypass passwords.
- Windows: the code builds and is tested in CI, but the tests with real images run only on Linux. There is no macOS build: Tauri needs the macOS SDK and code signing, both tied to Apple hardware and an Apple Developer account, which this project's CI (a single Linux runner) does not have. The source still compiles for macOS; it is just not built or tested.
- GUI: on Linux and macOS the app restarts entirely as administrator (
pkexecorosascript) instead of using a helper process.
Where it is going
Summary of the ROADMAP:
| Done | Metadata from 8 file systems, BitLocker, LUKS, FileVault 2, RAID, LVM, E01, Ex01, AFF4, fragmented JPEG, MP4 without an index, SQLite reader, SMART, QCOW2/VMDK/VHD/VHDX/DMG, hash-chained audit trail, PDF report, Ed25519 signatures, APFS free map |
| Next | Trusted timestamps (RFC 3161), more tests on Windows |
| Not planned | A macOS build — see Known limits |
| Later | NSRL and hash lists, content search, unified timeline, browser interpretation, Windows registry and messaging apps, dictionary and brute-force attacks on encrypted volumes |
| No reference image | ReFS and Storage Spaces: they only land with validation |
| Long term | iOS and Android backups (iTunes, ADB), OCR, NIST CFTT validation, physical phone access through bootloader/chip exploits |
Development
crates/guara-core core: reading, partitions, file systems, encryption, RAID, carving, recovery
crates/guara-cli `guara` binary (CLI + local UI server)
apps/gui interface (ui/ = HTML, CSS and JS; src-tauri/ = desktop app)
scripts/ test images and reference data
docs/ support, terminal and architecture
cargo test --workspace # on Linux this builds real images with mtools, ntfs-3g, e2fsprogs
scripts/fetch-testdata.sh # optional: reference images (BitLocker, FileVault 2, dfvfs, AFF4)
cargo clippy --workspace --all-targets
See CONTRIBUTING.md and docs/architecture.md. Versions follow SemVer; changes are in CHANGELOG.md. To publish: git tag vX.Y.Z && git push --tags (the release workflow builds and publishes everything). Vulnerabilities: SECURITY.md.
License
MIT or Apache-2.0, at your option.