scuttle/quickstart.md

# scuttle — Quick Start

## Install

```bash
cargo build --workspace --release
sudo cp target/release/scuttle /usr/local/bin/
sudo ln -s /usr/local/bin/scuttle /usr/local/bin/nwipe  # optional nwipe compat
```

### Runtime dependencies

Install these tools for firmware erase and SMART support:

```bash
sudo apt install hdparm nvme-cli smartmontools sg3-utils
# Optional: tpm2-tools for TPM erase
sudo apt install tpm2-tools
```

Scuttle detects each tool at runtime. Missing tools produce a clear error
message; the wipe continues with overwrite-only methods when firmware erase
is unavailable.

## List devices

```bash
scuttle list
```

Output:

```
DEVICE         BUS        MODEL              SIZE           SERIAL         DRIVER
/dev/sda       sata       Samsung SSD 860    500.11 GiB     S3Z8NB0K       ahci
/dev/nvme0n1   nvme       Samsung 980 Pro    1.00 TiB       S5GXNX0T       nvme
/dev/loop0     loop                          4.00 MiB
```

## Inspect a device

```bash
scuttle inspect /dev/sda
```

Prints the full device descriptor (path, bus, model, serial, firmware,
size, block sizes, rotational flag, SMART capabilities, HPA/DCO status)
plus the Layer 2 media classification (NIST 800-88 Clear/Purge/Destroy
recommendation with rationale).

## Read SMART data

```bash
scuttle smart /dev/sda
```

Output:

```
SMART data for /dev/sda
  Health:          PASSED
  Temperature:     32 °C
  Wear Level:      87%
  Model:           Samsung SSD 860 EVO 500GB
  Serial:          S3Z8NB0K123456W
  Firmware:        2B6Q
  Error Count:     0
```

For NVMe drives, additional health log fields appear (percentage used,
power-on hours, power cycles, available spare).

## Wipe a device

### With a method

```bash
# Wipe a loopback file (no safety flag needed)
scuttle wipe /tmp/test.bin --method zero --certificate json

# Wipe a real block device (requires safety flag)
sudo scuttle wipe /dev/sda --method dod --prng "ChaCha20 (CSPRNG)" \
    --hash sha-256 --verify final --certificate both \
    --i-know-this-destroys-data
```

Available methods: `zero`, `one`, `random`, `dod`, `dodshort`, `gutmann`,
`ops2`, `is5enh`, `schneier`, `bmb`.

Legacy aliases: `dod522022m` → `dod`, `dod3pass` → `dodshort`, `quick` →
`zero`, `prng`/`stream` → `random`, `bruce7` → `schneier`.

### With a profile

```bash
# Modern profile (policy-driven — method selected based on device type)
sudo scuttle wipe /dev/sda --profile paranoid --certificate all \
    --i-know-this-destroys-data

# Quick clear for ITAD throughput
sudo scuttle wipe /dev/sda --profile quick_clear \
    --i-know-this-destroys-data

# NIST Purge with firmware erase
sudo scuttle wipe /dev/nvme0n1 --profile nist_purge \
    --i-know-this-destroys-data
```

Available profiles: `legacy_zero`, `legacy_one`, `legacy_random`,
`legacy_dod`, `legacy_gutmann`, `legacy_rcmp`, `legacy_hmg`,
`legacy_schneier`, `legacy_bmb`, `quick_clear`, `modern_random`,
`nist_clear`, `nist_purge`, `enterprise`, `paranoid`, `research`,
`forensic`, `government`, `air_gap`, `custom`.

### Certificate formats

```bash
--certificate json    # canonical JSON (default)
--certificate pdf     # A4 single-page PDF
--certificate xml     # well-formed XML
--certificate csv     # single-row CSV
--certificate html    # self-contained HTML page
--certificate yaml    # YAML
--certificate both    # JSON + PDF
--certificate all     # all six formats
--certificate none    # no certificate
```

### Free-space-only mode

```bash
# Wipe free space on a mounted filesystem — user data is untouched
sudo scuttle wipe /mnt/data --freespace-only --method zero \
    --max-file-mib 1024
```

This mode detects the filesystem type via `/proc/mounts`, probes free
space via `statvfs(2)`, creates temp files filled with the wipe pattern,
then deletes them. The audit certificate records the filesystem type and
free space before/after.

## Batch mode

```bash
scuttle batch wipe-spec.yaml
```

Example spec (`wipe-spec.yaml`):

```yaml
mode: parallel
max_concurrency: 4
jobs:
  - device: /dev/sda
    method: dod
    prng: "ChaCha20 (CSPRNG)"
    hash: sha-256
    verify: final
    priority: 10
  - device: /dev/sdb
    method: gutmann
    hash: blake3
    verify: every
    group: fleet-a
  - device: /dev/sdc
    method: zero
    hash: sha-256
    group: fleet-a
```

Modes: `sequential`, `parallel`, `priority`, `groups`.

## TPM operations

```bash
# Detect TPM 2.0
scuttle tpm detect

# List persistent TPM key handles
scuttle tpm list

# Read PCR values
scuttle tpm pcrread --bank sha256

# Erase a TPM-sealed key (crypto-erase)
scuttle tpm erase --handle 0x81000001
```

## Benchmark

```bash
scuttle benchmark --bytes 1048576 --block 65536
```

Prints a sorted leaderboard of all 12 PRNGs and 4 hashes by throughput
(MB/s).

## Self-tests

```bash
scuttle selftest
```

Runs KAT self-tests for all 12 PRNGs and 4 hashes. Reports pass/fail and
duration.

## JSON API server

```bash
# Start the server
scuttle serve --socket /tmp/scuttle.sock

# Query it (from another terminal)
echo '{"cmd":"list"}' | nc -U /tmp/scuttle.sock
echo '{"cmd":"providers"}' | nc -U /tmp/scuttle.sock
echo '{"cmd":"profiles"}' | nc -U /tmp/scuttle.sock
echo '{"cmd":"selftest"}' | nc -U /tmp/scuttle.sock
echo '{"cmd":"version"}' | nc -U /tmp/scuttle.sock
echo '{"cmd":"quit"}' | nc -U /tmp/scuttle.sock
```

## TUI

```bash
scuttle tui
```

Interactive terminal UI with:
- Device list pane (left) — use j/k or arrow keys to navigate.
- Detail pane (right) — shows device info.
- Command palette — press `:` then type `refresh`, `providers`, `profiles`,
  `quit`.
- Mouse support — click to cycle device selection.
- Press `q` to quit.

## SBOM and conformance

```bash
# Generate a CycloneDX SBOM
scuttle sbom > scuttle-sbom.json

# Print the API stability declaration
scuttle conformance
```

## Legacy compatibility

```bash
# Create the symlink
sudo ln -s /usr/local/bin/scuttle /usr/local/bin/nwipe

# Use legacy flags — scuttle accepts them with deprecation warnings
sudo nwipe --method dod522022m --prng chacha20 --autonuke /dev/sda \
    --i-know-this-destroys-data

# nwipe with no args prints the legacy help text
nwipe
```

## Providers

```bash
scuttle providers
```

Lists all 12 PRNGs, 4 hashes, 10 methods, and 20 profiles.