scuttle/quickstart.md

scuttle — Quick Start

Install

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:

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

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

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

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

# 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

# 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

--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

# 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

scuttle batch wipe-spec.yaml

Example spec (wipe-spec.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

# 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

scuttle benchmark --bytes 1048576 --block 65536

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

Self-tests

scuttle selftest

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

JSON API server

# 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

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

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

# Print the API stability declaration
scuttle conformance

Legacy compatibility

# 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

scuttle providers

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