black-bagg 0.1.3

Ultra-secure, zero-trace, pure-Rust CLI vault for spies, journalists, and privacy maximalists.
Documentation

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 the strongest defaults we can provide: Argon2id hardening, ML-KEM-1024 cascaded wrapping (Kyber), 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 (Kyber) → 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

# prerequisites:
# 1. Install Rust toolchain (1.81+ recommended) via rustup:
#    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o rustup-init.sh
#    sh rustup-init.sh -y
#    source "$HOME/.cargo/env"
# 2. Install a standard build environment:
#    - Debian/Ubuntu: sudo apt-get update && sudo apt-get install -y build-essential
#    - macOS: xcode-select --install (installs Xcode Command Line Tools)
#    - Windows: Install "Desktop development with C++" workload from Visual Studio Build Tools
# 3. Ensure your shell has cargo in its PATH (usually done by sourcing ~/.cargo/env):
#    source "$HOME/.cargo/env"
cargo build --release
install -m 0755 target/release/black-bagg ~/.local/bin/black-bagg

black-bagg --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-bagg init --mem-kib 262144

You’ll be prompted for the master passphrase twice. The vault stores under the platform data directory (e.g., ~/.config/black_bag/vault.cbor).

Adding records

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

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

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

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

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

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

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

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

# totp secret
black-bagg add totp --title "GitHub MFA" --issuer GitHub --account you@example --secret JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP

# totp codes
black-bagg totp code <UUID> --time 59

Sensitive fields (passwords, passphrases, API secrets, private keys) are collected via hidden prompts after the command issues—nothing sensitive ever appears in argv or shell history.

Listing, filtering, and querying

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

Inspect a specific record:

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

Rotation, health, and recovery

  • black-bagg rotate – rewraps the master DEK with fresh randomness.
  • black-bagg doctor – prints health info (Argon2 params, feature flags, item counts).
  • black-bagg recovery split / combine – manage Shamir shares for catastrophic recovery.

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