binsearch

A fast binary search tool for scanning disk images and block devices. Useful for data recovery and forensic analysis — locates patterns, known data structures, and hash-verified blocks anywhere in raw storage.

Features

Mode	Flag	Description
Binary pattern	(default)	Search for hex, integer, ASCII, Unicode, or multi-encoding patterns
Zero regions	-z	Map continuous zero regions
Little2 hash	--find-l2hash	Find blocks matching a 64-bit lookup3 hash
MD5 hash	--find-md5	Find blocks matching an MD5 hash
Ext4 extents	--find-ext4	Find ext4 extent tree headers
Veeam pages	--find-veeam-pages	Find Veeam VBlob 4KB pages (MD5-prefixed)
Veeam slots	--find-veeam-slots	Find Veeam VBK CSlotHdr records (CRC32-prefixed)
ZFS blkptr	--find-zfs-blkptr	Find ZFS blkptr_t structures

Build

CMake (recommended)

cmake -B build
cmake --build build
cmake --build build --target binsearch_tests
ctest --test-dir build

Make (legacy)

Linux:

make -f Makefile

macOS (requires Homebrew OpenSSL):

brew install openssl
make -f Makefile

FreeBSD:

gmake -f Makefile

Usage

binsearch [options] <image_or_device> <pattern1> [patternN...]

Pattern types (-t)

Type	Description
bin	Hex bytes, e.g. deadbeef (default)
int	Hex integer — bytes reversed, e.g. efbeadde finds deadbeef
ascii	Literal ASCII string
unicode	ASCII argument encoded as UCS-2 (16-bit)
text	Tries both ascii and unicode

Options

-t, --pattern-type TYPE        bin|int|ascii|unicode|text (default: bin)
    --start OFFSET             start offset (default: 0)
    --block-size BLOCK_SIZE    block size for hash/structured finders
    --step SIZE                scan stride (default: 1)
    --shift OFFSET             pattern offset within block (default: 0)
-H, --hexdump-width WIDTH      bytes shown on match (default: 32)
-w, --write-bin-offsets FILE   write found offsets as uint64 to file
-a, --append                   append to offsets file instead of overwriting
-q, --quiet                    less output
-v, --verbose                  more output

-z, --find-zeroes              find zero regions
    --find-l2hash              find block by little2 hash
    --find-md5                 find block by MD5 hash
    --find-ext4                find ext4 extent headers
    --find-veeam-pages         find Veeam VBlob pages
    --find-veeam-slots         find Veeam VBK slot headers
    --find-zfs-blkptr          find ZFS blkptr_t structures
    --zfs-blkptr-level LVL     filter by blkptr level
    --zfs-blkptr-max-psize X   filter by max physical size

Examples

# Find a 4-byte magic number in a disk image
binsearch disk.img deadbeef

# Find a little-endian 32-bit integer
binsearch -t int disk.img 0badcafe

# Scan from 1GB offset with 512-byte stride
binsearch --start 1gb --step 512 disk.img cafebabe

# Find all zero regions
binsearch -z /dev/sdb

# Find Veeam slot headers and write offsets to file
binsearch --find-veeam-slots -w offsets.bin /dev/sdb

# Find ZFS block pointers at level 0, physical size ≤ 128KB
binsearch --find-zfs-blkptr --zfs-blkptr-level 0 --zfs-blkptr-max-psize 128kb disk.img

License

MIT License — Copyright (c) 2024-2026 Andrey "Zed" Zaikin. See LICENSE.