shard

Storage Health, Audit & Recovery Device

v1.10.1

NixOS x86_64

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.

Compliance crosswalk

This table lists controls where shard's output may form part of the evidence set presented to an assessor. It does not claim shard alone satisfies any framework — every control still requires assessor judgment and typically evidence from other sources.

Schema: compliance-crosswalk/v1 · Machine-readable: tools/shard/compliance.json

GDPR — General Data Protection Regulation (Reg. 2016/679)

Ref	Name	How	Coverage
`Art. 17`	Right to erasure	Certificate of destruction is a written record of secure erasure per operator/data-subject request.	evidences

HIPAA — HIPAA (45 CFR §164)

Ref	Name	How	Coverage
`§164.310(d)(2)(i)`	Disposal	Certificate of destruction documents disposal of media containing ePHI.	evidences
`§164.310(d)(2)(ii)`	Media re-use	wipefs + erase modes prepare media for safe re-use.	evidences

PCI-DSS — PCI-DSS v4.0

Ref	Name	How	Coverage
`Req. 9.8.1`	Media destruction	Certificate of destruction documents destruction of media containing cardholder data.	evidences

ISO27001 — ISO/IEC 27001:2022

Ref	Name	How	Coverage
`A.7.14`	Secure disposal or re-use of equipment	Certificate of destruction + audit-log chain evidences the control.	evidences

Release artefacts & provenance

Every signed release ships with checksum + signature sidecars plus a CycloneDX SBOM. Enterprise procurement can pin third-party components without unpacking the binary.

manifest.json — pinned SHA-256 + .sig URL + SBOM URL per platform
johlem-release.pub — Ed25519 public key used by signify -V (fingerprint: 4532510f…6748, pinned in jcli verify)
CHANGELOG.md — semver-tagged release notes
Security contact: security@johlem.net