# 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
```bash
# prerequisites:
# 1. Install Rust toolchain (1.81+ recommended) via rustup:
# curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 2. Install a standard build environment (e.g., build-essential on Debian/Ubuntu):
# sudo apt-get update && sudo apt-get install -y build-essential
# 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
```bash
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
```bash
# 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
```bash
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:
```bash
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`](docs/THREAT_MODEL.md) for assumptions, adversary capabilities, and residual risks. Treat the vault ciphertext as sensitive and keep backups offline.
## Building and testing
```bash
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
- [x] Argon2id + ML-KEM-1024 + XChaCha20-Poly1305 enabled by default
- [x] No GUI, clipboard, or plaintext log exposure
- [x] Cross-platform parity (Windows/macOS/Linux)
- [x] Comprehensive record catalogue with search & tagging
- [x] Lint/tests clean with zero warnings
- [x] 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`](docs/FURTHER_HARDENING.md)).