Skip to content

quickstart.md

Latest commit

 

History

History
159 lines (116 loc) · 3.98 KB

quickstart.md

File metadata and controls

159 lines (116 loc) · 3.98 KB
Raw

Quick start

Five minutes from "I just cloned the repo" to "I recovered a deleted file."

1. Install

The fastest path on any platform is to build from source — the project is a single Rust crate with minimal dependencies:

git clone https://github.com/your-org/nullveil
cd nullveil
cargo build --release

The two binaries land at target/release/nullveil and target/release/gen-samples.

For OS-specific install paths (Homebrew on macOS, apt/dnf notes on Linux, prebuilt artefacts on Windows) see Install.

2. Generate a sample image

Don't have a corrupted drive handy? NullVeil ships a deterministic sample generator that builds a small FAT32 image with both live and freshly-deleted files:

./target/release/gen-samples --out samples/

You'll get:

samples/
├── fat32-mixed.img          # FAT32 with live + deleted files
├── ntfs-mixed.img           # NTFS analogue
├── ext2-mixed.img           # ext2 analogue
└── carve-jpegs.img          # raw JPEG bytes for the carving demo

3. Inspect

Before touching anything, ask NullVeil what's there:

./target/release/nullveil info samples/fat32-mixed.img
Use only on devices and systems you own or are authorized to analyze.
source     samples/fat32-mixed.img
size       64.0 MiB (67108864 bytes)
sector     512 B
scheme     MBR
partitions
  #1  start=2048   sectors=129024  type=0x0c (FAT32 LBA)
      filesystem  FAT32  label="NULLVEIL"  cluster=4 KiB  total=63 MiB

This step never writes a byte; the original image's SHA-256 is unchanged.

4. List what's recoverable

./target/release/nullveil ls samples/fat32-mixed.img
hello.txt           17 B   live
readme.md           28 B   live

Now show the deleted entries:

./target/release/nullveil ls --deleted samples/fat32-mixed.img
?otes.txt           29 B   deleted  (orig: notes.txt)

The ? is the FAT-deletion marker (the first byte of the name is overwritten with 0xE5); NullVeil flags it but keeps the suffix for human readability.

5. Recover

Pick an output directory on a different filesystem from the source. NullVeil refuses to land on the same device — see Read-only by construction for why.

./target/release/nullveil recover samples/fat32-mixed.img \
    --include-deleted \
    --out /tmp/recovered/
Use only on devices and systems you own or are authorized to analyze.
recovering live entries…
  → /tmp/recovered/hello.txt        17 B  sha256:5b6df…
  → /tmp/recovered/readme.md        28 B  sha256:a92ee…
recovering deleted entries…
  → /tmp/recovered/notes.txt        29 B  sha256:7b1cf…  (originally deleted)
done: 3 files, 74 B total, 0 errors
manifest written to /tmp/recovered/manifest.json

Verify what you got:

cat /tmp/recovered/notes.txt
# these are some deleted notes

The manifest.json includes the SHA-256 of every recovered file, the source offset, and whether the entry was live or deleted — perfect for chain of custody.

6. Try the TUI

For drives you actually want to explore, the terminal UI is dramatically nicer than ls --deleted | grep | recover --path …:

./target/release/nullveil tui samples/fat32-mixed.img --out /tmp/tui-recover/

You get a partition list, a directory browser, a hex-and-ASCII preview, a multi-select basket (Space), and batch recovery (R). Full key-map in the tui command page.

What's next