polished items from the re-audit report by Claude, add Ubuntu live ISO method to README

2026-03-07 01:47:52 +08:00 · 2026-02-19 22:58:34 +08:00
parent 4da39b7b89
commit f1b0c0738e
8 changed files with 2196 additions and 1875 deletions
--- a/README.md
+++ b/README.md
@@ -36,11 +36,13 @@ make serve-local
 |----------------|-------------------|---------------|------|
 | **Testing** (<$100) | Any computer, local mode | `make build-offline` | 5 min |
 | **Real Use** ($100–$10K) | Clean computer, network disabled | `make build-offline` | 15 min |
-| **Serious** ($10K–$100K) | **TailsOS airgapped** | `make full-build-tails` | 30 min |
+| **Serious** ($10K–$100K) | **TailsOS or Ubuntu Live (airgapped)** | `make full-build-tails` | 30 min |
 | **Vault** (>$100K) | TailsOS + hardware wallet + multisig | `make full-build-tails` | 1+ hour |

 **The more funds at stake, the more security precautions you take.**

+**Note:** TailsOS and Ubuntu Live USB provide equivalent security for offline seed operations. See Path 1 (TailsOS) and Path 3 (Ubuntu Live) below for detailed workflows.
+
 ---

 ## 🔧 Makefile Commands Reference
@@ -172,6 +174,8 @@ make install
 make full-build-tails
 ```

+**Note:** All builds include a baseline CSP in index.html, but the `make full-build-tails` pipeline injects a stricter, WASM-compatible CSP tailored for TailsOS.
+
 **What `make full-build-tails` does:**

 1. **Cleans** all previous build artifacts
@@ -270,6 +274,282 @@ make serve-local

 ---

+## 🐧 Path 3: Ubuntu Live USB (Alternative to TailsOS)
+
+**Ubuntu Live USB provides equivalent security to TailsOS** for offline seed operations. It's RAM-only, amnesic (data erased on shutdown), and may be more familiar if you're already comfortable with Ubuntu.
+
+### When to Use Ubuntu Live USB
+
+- ✅ You're already familiar with Ubuntu/Linux workflows
+- ✅ You only need offline operations (no Tor required)
+- ✅ You want faster boot time (~1 min vs Tails ~2 min)
+- ✅ You might need to install additional tools during the session
+
+### Security Properties
+
+| Feature | Ubuntu Live USB | TailsOS |
+|---------|-----------------|---------|
+| RAM-only execution | ✅ Yes | ✅ Yes |
+| Amnesic (data erased on poweroff) | ✅ Yes | ✅ Yes |
+| Network isolation | ⚠️ Manual disable | ✅ Automatic (Tor-only) |
+| Pre-installed crypto tools | ❌ Need Python | ✅ GPG, KeePassXC built-in |
+| Boot time | ~1 min | ~2 min |
+| Best for | Offline seed ops | Offline + Tor workflows |
+
+**For your use case (offline seed blending): Both are equivalent.**
+
+---
+
+### Step 1: Prepare Ubuntu Live USB
+
+**On your regular computer:**
+
+```bash
+# Download Ubuntu Desktop LTS ISO
+wget https://releases.ubuntu.com/24.04/ubuntu-24.04-desktop-amd64.iso
+
+# Verify SHA256 checksum
+sha256sum ubuntu-24.04-desktop-amd64.iso
+# Compare against official checksum from ubuntu.com/download
+
+# Create bootable USB (Linux/Mac)
+sudo dd if=ubuntu-24.04-desktop-amd64.iso of=/dev/sdX bs=4M status=progress
+# ⚠️ Replace /dev/sdX with your USB device (check with 'lsblk')
+
+# Windows: Use Rufus or balenaEtcher instead
+```
+
+**Prepare SeedPGP on a separate USB drive:**
+
+```bash
+# Clone and build on your trusted computer
+git clone https://github.com/kccleoc/seedpgp-web.git
+cd seedpgp-web
+make install
+make full-build-tails  # Creates dist-tails/ with embedded CSP
+
+# Generate checksum file
+cd dist-tails
+sha256sum index.html > CHECKSUM.txt
+cd ..
+
+# Copy to second USB drive (label it "SEEDPGP-OFFLINE")
+cp -r dist-tails/ /media/your-usb/seedpgp-offline/
+```
+
+**You now have:**
+1. **USB #1:** Ubuntu Live bootable installer
+2. **USB #2:** Pre-verified SeedPGP build with checksums
+
+---
+
+### Step 2: Boot Ubuntu Live (Network Disabled)
+
+**Physical security checklist:**
+
+```
+□ Unplug Ethernet cable from computer
+□ Remove SIM card (if using a laptop with cellular)
+□ Put phone in airplane mode (away from desk)
+□ Close curtains (prevent shoulder surfing)
+```
+
+**Boot process:**
+
+1. Insert Ubuntu Live USB (#1)
+2. Reboot computer and press **F12/F2/ESC** during startup
+3. Select USB drive from boot menu
+4. Choose **"Try Ubuntu"** (NOT "Install Ubuntu")
+5. **IMMEDIATELY after desktop loads:** Click network icon → **Disable Wi-Fi**
+6. Verify network status in terminal:
+
+```bash
+ip link show
+# All interfaces should show 'state DOWN' except 'lo' (loopback)
+
+# Confirm no external routes
+ip route
+# Should ONLY show: 127.0.0.0/8 dev lo
+```
+
+---
+
+### Step 3: Verify Clean State
+
+```bash
+# Open Terminal (Ctrl+Alt+T)
+
+# Check no mounted writable drives
+mount | grep -v "ro,"
+# Should only show read-only mounts (iso9660, squashfs)
+
+# Check no swap space
+swapon --show
+# Should return nothing
+
+# Verify RAM usage
+free -h
+# Should show ~2-4GB used (OS running entirely in RAM)
+```
+
+---
+
+### Step 4: Load and Verify SeedPGP
+
+```bash
+# Insert USB #2 (SEEDPGP-OFFLINE)
+# It will auto-mount to /media/ubuntu/SEEDPGP-OFFLINE or similar
+
+# Navigate to the build folder
+cd /media/ubuntu/*/seedpgp-offline/
+# Or use: cd /media/ubuntu/SEEDPGP-OFFLINE/seedpgp-offline/
+
+# Verify integrity before running
+sha256sum -c CHECKSUM.txt
+# Should output: index.html: OK
+
+# If verification fails → STOP! Do not proceed.
+# Re-build on your trusted computer and copy again.
+```
+
+---
+
+### Step 5: Serve Locally with Python
+
+**Important:** You cannot open `file://` URLs directly in modern browsers due to CORS restrictions. You must serve over HTTP on localhost.
+
+```bash
+# Start Python HTTP server (Python 3 is pre-installed)
+python3 -m http.server 8000 &
+# The '&' runs it in background
+
+# You'll see:
+# Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+```
+
+**Security verification: Localhost is safe**
+
+Even though the server listens on `0.0.0.0:8000` (all interfaces), there are **no active network interfaces** to reach it from outside:
+
+```bash
+# Verify localhost-only access
+sudo ss -tlnp | grep 8000
+# Shows: LISTEN 0.0.0.0:8000 (looks exposed, but...)
+
+# Check which interfaces exist
+ip addr show
+# Should ONLY show 'lo' (loopback 127.0.0.1) with status UP
+# No eth0, wlan0, or other interfaces should be UP
+
+# Try accessing from "outside" (this should fail)
+curl http://192.168.1.100:8000  # Use any typical LAN IP
+# Should instantly fail: "Network unreachable"
+```
+
+**The key:** Even though Python binds to `0.0.0.0`, there are no physical network paths to reach it. Localhost is a kernel-internal loopback interface.
+
+---
+
+### Step 6: Open in Firefox
+
+```bash
+# Launch Firefox with localhost URL
+firefox http://localhost:8000 &
+```
+
+**Verify the app loaded correctly:**
+
+1. SeedPGP interface appears
+2. Check browser console (F12) for CSP enforcement:
+   - Should see no CSP violation errors
+   - Network tab should show only localhost requests
+3. Verify "Network BLOCKED" indicator in app header
+
+---
+
+### Step 7: Use SeedPGP
+
+Now proceed with your seed operations (see "Using SeedPGP: The Workflow" section below):
+
+- Generate entropy (dice rolls recommended)
+- Blend multiple hardware wallet seeds (if applicable)
+- Encrypt to PGP key or password
+- Export QR backup
+- **Write final seed to paper immediately**
+
+**⚠️ CRITICAL:** Never save anything to disk. All data stays in RAM.
+
+---
+
+### Step 8: Shutdown and Verify Data Erasure
+
+```bash
+# Stop the Python server (not strictly necessary, but good practice)
+killall python3
+
+# Power off Ubuntu Live
+sudo poweroff
+
+# Physical verification:
+□ Remove both USB drives
+□ All RAM contents are erased (power loss = data loss)
+□ No trace left on computer's hard drive
+```
+
+**What just happened:**
+
+- ✅ All seed operations occurred in RAM only
+- ✅ Python HTTP server never had external network access
+- ✅ SeedPGP never wrote to persistent storage
+- ✅ Shutdown wiped all RAM contents
+- ✅ Computer's hard drive was never touched (read-only boot)
+
+---
+
+### Optional: Advanced Hardening
+
+If you want to match TailsOS-level security:
+
+**1. Disable swap (already disabled by default, but verify):**
+```bash
+sudo swapoff -a
+```
+
+**2. Clear clipboard before shutdown:**
+```bash
+# If you copied anything sensitive
+echo "" | xclip -selection clipboard
+```
+
+**3. Wipe RAM on shutdown (paranoid mode):**
+```bash
+# For protection against cold-boot attacks (freezing RAM with liquid nitrogen)
+sudo apt install secure-delete
+sudo sdmem -v  # Takes ~2 min, overwrites RAM with random data
+```
+
+**Note:** For your threat model (protecting seeds from remote attackers, not physical access to frozen RAM), step 3 is unnecessary.
+
+---
+
+### Ubuntu Live vs TailsOS: Summary
+
+**Use Ubuntu Live USB if:**
+- You're already comfortable with Ubuntu
+- You only need offline seed operations
+- You want faster boot time
+- You value familiarity over maximum security
+
+**Use TailsOS if:**
+- You want zero-config maximum security
+- You might need Tor for other operations
+- You're handling $100K+ and want the most audited option
+- You want automatic MAC randomization and anti-forensics
+
+**For your use case (three-hardware-wallet blend on Ubuntu Live): ✅ Perfectly safe.**
+
+---
+
 ## 🔐 Using SeedPGP: The Workflow

 ### Step 1: Generate Entropy (New Seed)