stegvault 0.5.0

Password manager using steganography to embed encrypted credentials in images

StegVault

Secure password manager using steganography to embed encrypted credentials within images

StegVault is a full-featured password manager that combines modern cryptography with steganography. It can store either a single password or an entire vault of credentials, all encrypted using battle-tested algorithms (XChaCha20-Poly1305 + Argon2id) and hidden within ordinary PNG images using LSB steganography.

Latest Features (v0.5.0): Gallery Foundation - Manage multiple vaults with centralized metadata storage, cross-vault search, and SQLite-backed organization!

Features

Core Features

• 🔐 Strong Encryption: XChaCha20-Poly1305 AEAD with Argon2id KDF
• 🖼️ Invisible Storage: LSB steganography with sequential pixel ordering
• 🔒 Zero-Knowledge: All operations performed locally, no cloud dependencies
• ✅ Authenticated: AEAD tag ensures data integrity
• 🧪 Well-Tested: 346 unit tests with 78% overall coverage (all passing)
• ⏱️ User-Friendly: Progress indicators for long operations

Vault Mode

• 🗄️ Multiple Passwords: Store entire password vault in one image
• 🎯 Key-Based Access: Retrieve specific passwords by key (e.g., "gmail", "github")
• 🔑 Password Generator: Cryptographically secure password generation
• 📋 Rich Metadata: Username, URL, notes, tags, timestamps for each entry
• 🔄 Dual-Mode: Choose single password OR vault mode
• ♻️ Auto-Detection: Automatically detects format on restore (backward compatible)
• 📤 Import/Export: Backup and restore vaults via JSON
• 📋 Clipboard Support: Copy passwords to clipboard with auto-clear
• 🔐 TOTP/2FA: Built-in authenticator with QR code support
• 🛡️ Password Strength: Realistic validation using zxcvbn with actionable feedback
• 🔍 Search & Filter: Find entries by query or filter by tags/URL

Gallery Mode (v0.5.0)

• 🖼️ Multi-Vault Management: Organize multiple vault images in one gallery
• 🗄️ SQLite Metadata: Centralized database for vault information and entry cache
• 🔍 Cross-Vault Search: Search across all vaults simultaneously
• 🏷️ Tagging System: Organize vaults with custom tags
• ⚡ Fast Search: Cached entry metadata for instant results
• 📊 Vault Statistics: Track entry counts, last accessed times
• 🔄 Auto-Refresh: Update cache when vault contents change

Quick Start

Installation

# Install from PyPI (recommended)
pip install stegvault

# Or install from source
git clone https://github.com/kalashnikxvxiii-collab/stegvault.git
cd stegvault
pip install -e .

Usage

Mode 1: Single Password (Simple Backup)

1. Check Image Capacity

stegvault check -i myimage.png

2. Create Backup

stegvault backup -i cover.png -o backup.png

3. Restore Password

stegvault restore backup.png

Mode 2: Vault (Multiple Passwords) - NEW!

1. Create Vault with First Entry

stegvault vault create -i cover.png -o vault.png -k gmail --generate
# Automatically generates a secure password for Gmail

2. Add More Passwords

stegvault vault add vault.png -o vault_v2.png -k github -u myusername --generate
stegvault vault add vault_v2.png -o vault_v3.png -k aws

3. Retrieve Specific Password

stegvault vault get vault_v3.png -k gmail
# Output:
# Entry: gmail
# Username: [e-mail]
# URL: https://gmail.com
# Password: X7k$mP2!qL5@wN

4. List All Keys

stegvault vault list vault_v3.png
# Output:
# Vault contains 3 entries:
#   1. gmail ([e-mail])
#   2. github (myusername)
#   3. aws

5. Update Entry

stegvault vault update vault_v3.png -o vault_v4.png -k gmail --password newpass123

6. Export Vault

stegvault vault export vault_v4.png -o backup.json --pretty

7. Import Vault

stegvault vault import backup.json -i cover.png -o restored_vault.png

8. Delete Entry

stegvault vault delete vault_v4.png -o vault_v5.png -k oldservice

9. Copy Password to Clipboard

stegvault vault get vault.png -k gmail --clipboard
# Password copied to clipboard (not displayed on screen)

# Auto-clear clipboard after 30 seconds
stegvault vault get vault.png -k gmail --clipboard --clipboard-timeout 30

10. Setup TOTP/2FA

# Add TOTP secret to entry
stegvault vault add vault.png -o vault_v2.png -k github -u myuser --totp

# Generate TOTP code
stegvault vault totp vault_v2.png -k github
# Output: Current TOTP code for 'github': 123456 (valid for 25 seconds)

# Show QR code for authenticator app
stegvault vault totp vault_v2.png -k github --qr

# Search vault entries
stegvault vault search vault.png --query "github"
# Search specific fields only
stegvault vault search vault.png -q "work" --fields key --fields notes

# Filter entries by tags
stegvault vault filter vault.png --tag work
stegvault vault filter vault.png --tag work --tag email --match-all

# Filter by URL pattern
stegvault vault filter vault.png --url github.com

Gallery Management (v0.5.0)

Manage multiple vaults in one place:

# Initialize gallery database
stegvault gallery init
# Creates ~/.stegvault/gallery.db

# Add vaults to gallery
stegvault gallery add work_vault.png --name work-vault --tag work
stegvault gallery add personal_vault.png --name personal-vault --tag personal

# List all vaults
stegvault gallery list
# Output:
# 2 vault(s) in gallery:
#
# Name: personal-vault
# Path: /path/to/personal_vault.png
# Entries: 5
# Tags: personal
#
# Name: work-vault
# Path: /path/to/work_vault.png
# Entries: 12
# Tags: work

# Search across ALL vaults
stegvault gallery search "github"
# Output:
# Found 2 matching entries:
#
# [work-vault]
# Key: github-work
# Username: [e-mail]
# URL: https://github.com
#
# [personal-vault]
# Key: github-personal
# Username: myusername
# URL: https://github.com

# Search in specific vault only
stegvault gallery search "email" --vault work-vault

# Refresh vault metadata after changes
stegvault gallery refresh work-vault

# Remove vault from gallery (doesn't delete the image)
stegvault gallery remove old-vault

How It Works

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    StegVault Workflow                    │
└─────────────────────────────────────────────────────────┘

        BACKUP CREATION                 PASSWORD RECOVERY
               ↓                                ↓
    1. User Input                    1. Load Stego Image
       • Master Password                 • backup.png
       • Passphrase                      • Enter Passphrase
       • Cover Image
                                      2. Extract Payload
    2. Encryption                        • LSB Extraction
       • Generate Salt (16B)             • Sequential Order
       • Derive Key (Argon2id)           • Parse Binary Format
       • Encrypt (XChaCha20)
                                      3. Decryption
    3. Payload Format                    • Verify AEAD Tag
       • Magic: "SPW1"                   • Derive Key (Argon2id)
       • Salt + Nonce                    • Decrypt Ciphertext
       • Ciphertext + Tag
                                      4. Recover Password
    4. LSB Embedding                     • Display/Save Password
       • Sequential Pixels
       • Modify LSB of R,G,B
       • Save Stego Image

    5. Output: backup.png

Cryptographic Stack

Component	Algorithm	Parameters
AEAD Cipher	XChaCha20-Poly1305	256-bit key, 192-bit nonce
KDF	Argon2id	3 iterations, 64MB memory, 4 threads
Salt	CSPRNG	128 bits (16 bytes)
Nonce	CSPRNG	192 bits (24 bytes)
Tag	Poly1305	128 bits (16 bytes)

Payload Format

Binary structure embedded in images:

┌────────────────────────────────────────────────────┐
│  Offset  │  Size  │  Field         │  Description  │
├──────────┼────────┼────────────────┼───────────────┤
│  0       │  4B    │  Magic Header  │  "SPW1"       │
│  4       │  16B   │  Salt          │  For Argon2id │
│  20      │  24B   │  Nonce         │  For XChaCha20│
│  44      │  4B    │  CT Length     │  Big-endian   │
│  48      │  N     │  Ciphertext    │  Variable     │
│  48+N    │  16B   │  AEAD Tag      │  (appended)   │
└────────────────────────────────────────────────────┘

Steganography Technique

LSB (Least Significant Bit) Embedding:

1. Sequential Pixel Ordering: All payload bits stored left-to-right, top-to-bottom for reliability and simplicity
2. Distributed Embedding: Payload bits spread across R, G, B channels
3. Minimal Visual Impact: Only LSB modified (imperceptible to human eye)
4. Security Philosophy: Cryptographic strength (XChaCha20-Poly1305 + Argon2id) provides security, not pixel ordering

# Simplified example
for y in range(height):
    for x in range(width):
        for channel in [R, G, B]:
            channel_value = (channel_value & 0xFE) | payload_bit

Security Considerations

✅ Strong Security Features

• Modern Cryptography: XChaCha20-Poly1305 is a modern AEAD cipher resistant to various attacks
• Strong KDF: Argon2id winner of Password Hashing Competition, resistant to GPU/ASIC attacks
• Authenticated Encryption: Poly1305 MAC ensures integrity; tampering detected automatically
• Cryptographic Security: Security provided by strong cryptography, not by hiding embedding pattern
• No Key Reuse: Fresh nonce generated for each encryption

⚠️ Limitations & Warnings

• Not Invisible: Advanced steganalysis may detect embedded data
• No Deniability: Payload has identifiable magic header
• JPEG Lossy: Recompressing JPEG images destroys payload (use PNG)
• Both Required: Losing either image OR passphrase = permanent data loss
• Offline Attacks: Attacker with image can attempt brute-force (mitigated by Argon2id)

🔒 Best Practices

1. Strong Passphrase: Use 16+ character passphrase with mixed case, numbers, symbols
2. Multiple Backups: Store copies in different locations
3. PNG Format: Always use PNG (lossless) not JPEG (lossy)
4. Verify Backups: Test restore process after creating backup
5. Secure Storage: Protect image files as you would protect passwords

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=stegvault --cov-report=html

# Run specific module tests
pytest tests/unit/test_crypto.py -v

Code Quality

# Format code
black stegvault tests

# Type checking
mypy stegvault

Project Structure

stegvault/
├── stegvault/           # Source code
│   ├── crypto/          # Cryptography (Argon2id + XChaCha20)
│   │   ├── __init__.py
│   │   └── core.py
│   ├── stego/           # Steganography (PNG LSB)
│   │   ├── __init__.py
│   │   └── png_lsb.py
│   ├── utils/           # Payload format handling
│   │   ├── __init__.py
│   │   ├── payload.py
│   │   └── config.py
│   ├── vault/           # Password vault management (NEW in v0.4.0)
│   │   ├── __init__.py
│   │   ├── core.py       # Vault and VaultEntry classes
│   │   ├── operations.py # Vault CRUD operations + import
│   │   ├── generator.py  # Password generator
│   │   └── totp.py       # TOTP/2FA support
│   ├── batch/           # Batch operations
│   │   ├── __init__.py
│   │   └── processor.py
│   ├── gallery/         # Multi-vault management (v0.5.0)
│   │   ├── __init__.py
│   │   ├── core.py      # Gallery and metadata classes
│   │   ├── db.py        # SQLite database operations
│   │   ├── operations.py # Gallery CRUD operations
│   │   └── search.py    # Cross-vault search
│   ├── __init__.py
│   └── cli.py           # Command-line interface
├── tests/               # Test suite (346 tests, 78% coverage)
│   ├── unit/
│   │   ├── test_crypto.py              # 26 tests
│   │   ├── test_payload.py             # 22 tests
│   │   ├── test_stego.py               # 16 tests
│   │   ├── test_config.py              # 28 tests
│   │   ├── test_batch.py               # 20 tests
│   │   ├── test_vault.py                  # 49 tests (vault module)
│   │   ├── test_cli.py                    # 53 tests (core CLI)
│   │   ├── test_vault_cli.py              # 46 tests (vault CLI + TOTP)
│   │   ├── test_totp.py                   # 19 tests (TOTP/2FA)
│   │   ├── test_password_strength.py      # 24 tests (password validation)
│   │   ├── test_vault_search.py           # 24 tests (search/filter backend)
│   │   ├── test_vault_search_filter_cli.py # 5 tests (search/filter CLI)
│   │   ├── test_vault_update_delete_cli.py # 12 tests (update/delete CLI)
│   │   └── test_gallery.py                # 22 tests (gallery management)
│   └── __init__.py
├── docs/                # Documentation
├── examples/            # Example images
├── .gitignore
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE              # MIT License
├── README.md            # This file
├── ROADMAP.md
├── pyproject.toml
└── requirements.txt

Roadmap

See ROADMAP.md for planned features and development timeline.

Coming Soon

• GUI application (Electron or Qt)
• JPEG DCT steganography (more robust)
• Multi-vault operations and search
• Gallery foundation for multi-file vault management
• Optional cloud storage integration

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Make changes with tests
4. Commit (git commit -m 'feat: add amazing feature')
5. Push (git push origin feature/amazing-feature)
6. Open Pull Request

License

This project is licensed under the MIT License - see LICENSE file for details.

Disclaimer

StegVault is provided "as-is" for educational and personal use. The authors are not responsible for any data loss or security breaches. Always maintain multiple backups of critical passwords.

Security Notice: While StegVault uses strong cryptography, no system is perfect. This tool is best used as a supplementary backup method alongside traditional password managers.

Acknowledgments

• PyNaCl - libsodium bindings for Python
• argon2-cffi - Argon2 password hashing
• Pillow - Python Imaging Library