shard

Storage Health, Audit & Recovery Device

v1.10.0

Linux

Quick Start

Install via jcli (recommended)

jcli install shard

Eight subcommands, one binary

# READ-ONLY — no auth required
sudo shard list                                  # eligible devices (USB in laptop mode, all in server mode)
sudo shard info --device /dev/sdb                # model, serial, SMART, mounts, port topology
sudo shard benchmark --device /dev/sdb           # 256 MB read throughput sample
sudo shard doctor                                # dependency + posture check

# DESTRUCTIVE — require --i-am-authorized
sudo shard --i-am-authorized erase --device /dev/sdb --mode thorough
sudo shard --i-am-authorized format --device /dev/sdb --fs luks-ext4 --label vault
sudo shard --i-am-authorized flash --device /dev/sdb --iso ./debian.iso --verify
sudo shard --i-am-authorized repair --device /dev/sdb --badblocks
sudo shard --i-am-authorized --really-yes panic  # wipe all removable USB devices

What it does

shard is a unified front-end for block-device hygiene on Linux: enumerate visible disks, read SMART health, securely erase, format (ext4 / exFAT / FAT32 / LUKS+ext4), flash ISOs with SHA-256 verify, run fsck and badblocks scans, and — under explicit two-flag authorization — emergency-wipe every removable USB stick currently attached. It orchestrates lsblk, smartctl, dd, cryptsetup, mkfs.*, fsck, and badblocks; it does not reimplement them.

Mode-aware enumeration. Auto-detects laptop (battery present in /sys/class/power_supply/BAT*) and shows only USB-transport removable devices. server mode shows every disk except the host's root device. Override with --mode laptop|server.
Three-layer safety on every destructive subcommand. --i-am-authorized (or SHARD_AUTHORIZED=1) + refuses the host's root device + refuses a mounted device (unless --force-unmount is passed) + a pre-flight prompt where the operator types the device path verbatim. --yes / SHARD_YES=1 skips that prompt for scripted use.
--dry-run prints every command without executing. Useful for engagement docs, change-control reviews, or just sanity-checking the generated dd / mkfs / cryptsetup invocations.
SMART classification follows the spec: OK / DEGRADED / CRITICAL / N/A based on reallocated sectors, pending sectors, NVMe percent used, available spare, temperature, power-on hours.
LUKS format defaults are conservative. cryptsetup luksFormat --type luks2 --pbkdf argon2id --iter-time 3000 --use-random. These aren't tunable flags — lowering them quietly burns offline-attack resilience.
ISO flash verifies the device read-back. Compares SHA-256 of the source ISO against SHA-256 of the first iso_size bytes of the device after the write. Catches silent USB write corruption on cheap sticks.
Tamper-evident JSONL audit log. Every authorized action appends one row to ~/.local/share/shard/audit.log (chmod 600): timestamp, operator, action, device, detail, mode, dry-run flag.
Panic wipe is double-gated. --i-am-authorized AND --really-yes. Refuses to run in server mode (the non-USB devices in server mode are too risky for a one-shot bulk wipe). Limits writes to the first 2 GiB of each USB stick.

Subcommands

Command	Class	What it does
`list`	read-only	Enumerate eligible block devices
`info --device PATH`	read-only	Model, serial, SMART, mounts, port topology, partitions
`benchmark --device PATH`	read-only	256 MB direct-IO read throughput
`doctor`	read-only	Dependency + root posture check
`erase --device PATH --mode quick\|thorough`	destructive*	dd /dev/urandom (1 pass) or random+zeros+random (3 passes)
`format --device PATH --fs ext4\|exfat\|fat32\|luks-ext4`	destructive*	mkfs (+ cryptsetup for luks-ext4)
`flash --device PATH --iso FILE --verify`	destructive*	dd ISO + SHA-256 verify read-back
`repair --device PATH [--badblocks]`	destructive*	fsck -y + optional read-only badblocks scan
`panic --really-yes`	destructive*	Wipe first 2 GiB of every removable USB device

* destructive subcommands require --i-am-authorized (or SHARD_AUTHORIZED=1) and won't act on the root filesystem device, mounted devices (without --force-unmount), or non-removable devices in laptop mode. panic additionally requires --really-yes.

SMART classifications

Class	Triggers
`OK`	`smart_status.passed = true` and no other red flags
`DEGRADED`	Temperature > 65 °C, power-on hours > 50 000, or NVMe percent used 80–89
`CRITICAL`	SMART self-test failed; reallocated / pending / uncorrectable sector count > 0; NVMe percent used ≥ 90; NVMe available spare < 10; NVMe media errors > 0
`N/A`	smartctl couldn't be invoked or returned no `smart_status` field (typical on raw USB without root)

External tool requirements

Run shard doctor for a host posture report. Required tools are checked at every invocation; optional tools only matter for the corresponding subcommand.

Tool	Required for
`lsblk`, `blkid`	device enumeration
`dd`	erase, benchmark, ISO flash, panic
`smartctl`	SMART health classification
`cryptsetup`	`format --fs luks-ext4`
`mkfs.ext4`	`format --fs ext4` (and `luks-ext4`)
`mkfs.exfat`	`format --fs exfat` (optional)
`mkfs.vfat`	`format --fs fat32` (optional)
`fsck`, `badblocks`	`repair`

shard performs destructive operations on block devices. Always verify the target with shard info --device /dev/sdX before running erase, format, flash, or panic. The pre-flight prompt asks you to retype the exact device path because typos here lose data. --dry-run prints every command without executing if you want to see the exact dd / mkfs / cryptsetup invocations before committing.