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: Rust toolchain 1.81+ (via rustup) and a standard build environment
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

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-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
black-bag add totp --title "GitHub MFA" --issuer GitHub --account you@example --secret JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP

# totp codes
black-bag 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-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.

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

black-bagg 0.1.0