wipe/README.md

# wipe

Secure block device wipe and hardware erase orchestration for Linux — a safer, stricter alternative to `shred` for whole-disk operations.

> **Warning: This tool performs irreversible destructive operations.** Always verify the target device with `--dry-run` first.

## Features

- Strict destructive-operation safety: `/dev` validation, symlink escape prevention, whole-disk confirmation, mount/swap/holder checks, running system protection
- HDD overwrite: `zero`, `ones`, `alternating`, `random` (ChaCha20 deterministic stream, per-chunk unique, verifiable)
- SSD/NVMe hardware erase: `secure-discard` (`blkdiscard --secure`), `nvme-sanitize` (block erase), `nvme-crypto` (crypto erase) via `nvme-cli`
- Progress, ETA, throughput, sync control, `--verify` (`OVERWRITE_VERIFIED`)
- Human and JSON output, typed exit codes (0-15), SIGINT-safe

## Installation

```bash
cargo install --path .
```

Or build release binary:

```bash
cargo build --release
# binary at target/release/wipe
```

## Build

```bash
cargo build --release
```

## Basic Usage

```bash
# Dry run first!
sudo wipe /dev/sdb --whole-disk --dry-run

# Wipe HDD (1 pass zero overwrite, sync)
sudo wipe /dev/sdb --whole-disk

# Multiple passes
sudo wipe /dev/sdb --whole-disk --passes 3

# With verify
sudo wipe /dev/sdb --whole-disk --verify

# JSON output
sudo wipe /dev/sdb --whole-disk --json --yes
```

### Methods

```bash
# Auto (HDD -> zero, SSD/NVMe -> require explicit method)
sudo wipe /dev/sdb --whole-disk --method auto

# Explicit overwrite methods
sudo wipe /dev/sdb --whole-disk --method zero
sudo wipe /dev/sdb --whole-disk --method random
sudo wipe /dev/sdb --whole-disk --method ones
sudo wipe /dev/sdb --whole-disk --method alternating

# SSD / NVMe hardware erase
sudo wipe /dev/nvme0n1 --whole-disk --method nvme-sanitize
sudo wipe /dev/nvme0n1 --whole-disk --method nvme-crypto
sudo wipe /dev/sda --whole-disk --method secure-discard
```

- `auto` will not silently fallback from hardware erase to overwrite on SSD/NVMe; it returns an error requiring explicit `--method`.
- NVMe sanitize is asynchronous; `wipe` polls `nvme sanitize-log` (`SSTAT`) every second.

## Common Options

| Option | Description |
|---|---|
| `-n, --passes <N>` | HDD overwrite passes (default 1) |
| `-m, --method <METHOD>` | `auto` (default), `zero`, `random`, `ones`, `alternating`, `secure-discard`, `nvme-sanitize`, `nvme-crypto` |
| `-y, --yes` | Skip interactive `WIPE` confirmation (does NOT bypass system-disk protection) |
| `--whole-disk` | Explicitly allow whole-disk wipe |
| `--unmount` | Auto unmount filesystems / swapoff |
| `--force` | Override non-system safety checks (never bypasses running system device) |
| `--dry-run` | No data modification; shows device, partitions, mounts, method, passes |
| `--verify` | Read-back verification after overwrite |
| `--no-sync` | Skip final `sync` |
| `--buffer-size <SIZE>` | e.g. `64M` (default), `16M`, `32M`, `128M` |
| `--json` | Machine-readable output |
| `-v, --verbose` | Verbose logging |

Exit codes: `0` success, `1` generic, `2` invalid args, `3` perm denied, `4` not found, `5` not block device, `6` mounted, `7` dependency, `8` running system, `9` unsupported method, `10` capability unavailable, `11` unmount failed, `12` overwrite failed, `13` verification failed, `14` external command failed, `15` interrupted.

## Dry Run Example

```bash
sudo wipe /dev/sdb --whole-disk --dry-run
```

```
Device
  Path       /dev/sdb
  Type       HDD
  Size       3.64 TiB
  Model      ST4000...
  Serial     XXXXX
  Rotational yes

Partitions
  /dev/sdb1
  /dev/sdb2

Mounted
  /data

Action
  unmount /data

Method
  zero overwrite

Passes
  1

Estimated operation
  destructive: YES

DRY RUN
No data will be modified.
```

## JSON Example

Success:

```json
{
  "device": "/dev/sdb",
  "type": "hdd",
  "size": 4000787030016,
  "method": "zero",
  "passes": 3,
  "verification": true,
  "result": "overwrite_verified",
  "success": true
}
```

Error:

```json
{
  "device": "/dev/sda",
  "success": false,
  "error": {
    "code": "RUNNING_SYSTEM_DEVICE",
    "message": "target device contains the running system"
  }
}
```

## SSD / NVMe vs HDD

- **HDD** (`ROTA=1`): `zero` overwrite is the default for `auto`. Use `--passes` for multiple passes.
- **SSD** (`ROTA=0`, SATA): Prefer `secure-discard` if supported; otherwise explicit `zero` overwrite with the caveat that logical overwrite ≠ NAND erasure.
- **NVMe**: Check `nvme id-ctrl` `SANICAP` (bit 0 crypto, bit 1 block, bit 2 overwrite). Use `nvme-sanitize` / `nvme-crypto` for controller-level erase. `auto` requires explicit method for SSD/NVMe to avoid silent fallback.

## Safety Notes

See [SECURITY.md](SECURITY.md). Logical verification (`OVERWRITE_VERIFIED`) confirms the LBA range reads back as written, but does not prove forensic irrecoverability for remapped sectors or NAND cells.

## Development

```bash
make fmt
make check
make test
make lint
make build
make verify

# Loop device integration (needs sudo)
sudo ./scripts/loop-test.sh
./scripts/verify.sh
```

## License

MIT