# 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
```bash
# 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
```bash
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
```bash
# 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):
# 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
```bash
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:
```bash
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`](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)).
## 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.