black-bag

black-bag is a zero-trace, no-compromise command-line vault for high-risk operators. It ships as a single Rust binary with opinionated, high-security defaults (Argon2id time=10, lanes≥4 by default; configurable), ML-KEM-1024 cascaded wrapping, XChaCha20‑Poly1305 payload encryption, zeroization of every secret buffer, and page-locked memory on Unix. There is no optional telemetry, no cloud, no GUI—just a laser-focused CLI that keeps secrets safe even under hostile conditions.

Highlights

• Zero-trace posture – secrets never touch stdout, logs, temp files, or the clipboard. All input happens via hidden TTY prompts and is stored only after AEAD encryption.
• Modern crypto pipeline – Argon2id → ML-KEM-1024 → random 32-byte DEKs sealed with XChaCha20‑Poly1305. Writes are atomic/fdatasync’d with strict permissions and zeroized in memory on drop.
• Rich record catalogue – logins, contacts, identity docs, secure notes, payment cards, SSH keys, PGP keys, TOTP seeds, recovery kits, bank accounts, Wi-Fi profiles, API credentials, and crypto wallets. Every record supports tagging and full-text queries.
• Cross-platform parity – builds cleanly on macOS, Linux, and Windows. mlock is enabled automatically on supported Unix platforms and degrades gracefully elsewhere.
• Security by default – all protective features are enabled in every binary; there are no configuration flags that weaken the threat posture.

Quick start

# Install from crates.io (recommended)
# Crate name: black-bagg (binary installs as `black-bag`)
cargo install --locked black-bagg --features pq

# Or build locally
cargo build --release
install -m 0755 target/release/black-bag ~/.local/bin/black-bag

black-bag --help

Recommended hygiene:

• Run from an encrypted disk.
• Disable shell history or use HISTCONTROL=ignorespace with leading spaces.
• Set RUST_BACKTRACE=0 in operational shells.

Creating your vault

black-bag init --mem-kib 262144 --argon-lanes auto

You’ll be prompted for the master passphrase twice. The passphrase must contain at least 14 characters (normalized) and either score highly in our zxcvbn-based estimator or be a long diceware-style phrase. Existing vaults created with earlier releases continue to unlock, but rotating to a new passphrase will enforce the policy. The vault stores under the platform data directory (e.g., ~/.config/black_bag/vault.cbor).

Adding records

# login
black-bag add login --title "Ops Portal" --username phoenix --url https://ops.example --tags mission

# contact
black-bag add contact --full-name "Analyst Zero" --emails a0@example --phones "mobile:+1-555-0101,desk:+1-555-0110" --tags handler

# identity document
black-bag add id --id-type passport --name-on-doc "Alex Smith" --number X1234567 --issuing-country US --expiry 2032-08-01

# secure note
black-bag add note --title "Fallback Protocol" --tags red-team

# bank account
black-bag add bank --institution "First Federal" --account-name "Ops budget" --routing-number 021000021 --tags finance

# Wi-Fi profile
black-bag add wifi --ssid "safehouse-net" --security WPA2 --location Berlin --tags infrastructure

# API credential
black-bag add api --service intel-api --environment production --access-key AKIA-123 --scopes read,write --tags automation

# crypto wallet
black-bag add wallet --label btc-cold --asset BTC --address bc1q... --network mainnet --tags treasury

# totp secret (enter when prompted, or supply via --secret-file / --secret-stdin)
# Tip: prefer --algorithm sha256 when provisioning new records
black-bag add totp --title "GitHub MFA" --issuer GitHub --account you@example --secret-file ./github-totp.txt --algorithm sha256
# or provide an otpauth:// URI via stdin (safer):
printf '%s' "otpauth://totp/..." | black-bag add totp --title "GitHub MFA" --otpauth-stdin --qr --confirm-qr

# totp codes
black-bag totp code <UUID> --time 59
> Note: records with non-zero skew also print `code(offset ±n)` entries so you can see the slack window.

Sensitive fields (passwords, passphrases, API secrets, private keys) are collected via hidden prompts or stdin/file; no CLI arguments accept secrets. Avoid recording shell history and disable command logging in operational shells.

Listing, filtering, and querying

black-bag list                      # masked summaries
black-bag list --kind bank_account  # filter by record family
black-bag list --tag mission        # filter by tag
black-bag list --query opsnet       # full-text search across metadata

Inspect a specific record:

black-bag get <UUID>
black-bag get <UUID> --reveal      # requires an interactive TTY

Rotation, health, and recovery

• black-bag rotate – rewraps the master DEK with fresh randomness.
• black-bag doctor – prints health info (Argon2 params, feature flags, item counts).
• black-bag recovery split / combine – manage Shamir shares for catastrophic recovery (combine prints base64 to TTY by default; add --raw to emit binary directly to TTY).
• black-bag backup verify --path <vault.cbor> – verify integrity sidecar without passphrase (bit-rot check).
• black-bag passwd [--mem-kib N] [--argon-lanes auto|N] – change master passphrase and/or Argon2 parameters.
• black-bag migrate – migrate the vault file to the latest on-disk version.
• black-bag export csv --fields id,kind,title,summary – export to CSV (requires --unsafe-stdout).
• black-bag tui – minimal TUI (build with --features tui).

Threat model (summary)

See docs/THREAT_MODEL.md for assumptions, adversary capabilities, and residual risks. Treat the vault ciphertext as sensitive and keep backups offline.

Building and testing

cargo fmt
cargo clippy --all-targets --all-features
cargo test

CI should run the same three commands on every commit. Tests cover cryptographic round-trips, helper utilities, and zero-trace guarantees.

Mission-ready checklist

• Argon2id + ML-KEM-1024 + XChaCha20‑Poly1305 enabled by default
• No GUI, clipboard, or plaintext log exposure
• Cross-platform parity (Windows/macOS/Linux)
• Comprehensive record catalogue with search & tagging
• Lint/tests clean with zero warnings
• Operator docs and threat model committed

For production roll-out, schedule an independent cryptography/code audit and set up fuzzing pipelines (see docs/FURTHER_HARDENING.md).

Recent Security Improvements

• Removed all command-line secret parameters (file/stdin/prompt only)
• Timing-attack hardening:
  • Shamir sharing now uses constant-time GF operations (fixed-round multiply; fixed addition-chain inverse)
  • Error paths sanitized to reduce information/timing oracles
• Migrated to ML-KEM-1024 with runtime size verification
• Added input size limits before CBOR deserialization + schema caps
• Increased Argon2 defaults (time=10; lanes auto with minimum of 4)

See SECURITY_CHANGES.md for a detailed summary.