463 lines
13 KiB
Markdown
463 lines
13 KiB
Markdown
# Stegasoo
|
||
|
||
A secure steganography system for hiding encrypted messages and files in images using hybrid multi-factor authentication.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
## Features
|
||
|
||
- 🔐 **AES-256-GCM** authenticated encryption
|
||
- 🧠 **Argon2id** memory-hard key derivation (256MB RAM requirement)
|
||
- 🎲 **Pseudo-random pixel selection** defeats statistical steganalysis
|
||
- 📅 **Daily key rotation** with BIP-39 passphrases (3-12 words)
|
||
- 🔑 **Multi-factor authentication**: Reference photo + phrase + PIN/RSA key
|
||
- 📁 **File embedding** - Hide any file type (PDF, ZIP, documents, etc.)
|
||
- 📊 **Large capacity** - Up to 6MB payload in 24MP images
|
||
- 🔍 **QR code support** - Store RSA keys in QR code images
|
||
- 🚀 **Three complete interfaces**: CLI, REST API, and Web UI
|
||
|
||
## Quick Links
|
||
|
||
- **Command Line Interface**: [CLI Documentation](CLI.md)
|
||
- **REST API**: [API Documentation](API.md)
|
||
- **Web Interface**: [Web UI Documentation](WEB_UI.md)
|
||
- **About Page**: Detailed security model and usage guide
|
||
|
||
## Installation
|
||
|
||
### From PyPI (Production Ready)
|
||
|
||
```bash
|
||
# Core library only
|
||
pip install stegasoo
|
||
|
||
# With CLI (recommended)
|
||
pip install stegasoo[cli]
|
||
|
||
# With REST API (FastAPI)
|
||
pip install stegasoo[api]
|
||
|
||
# With Web UI (Flask)
|
||
pip install stegasoo[web]
|
||
|
||
# With QR code support
|
||
pip install stegasoo[cli,qr]
|
||
|
||
# Everything including all frontends
|
||
pip install stegasoo[all]
|
||
From Source
|
||
bash
|
||
git clone https://github.com/yourusername/stegasoo.git
|
||
cd stegasoo
|
||
|
||
# Install with all extras
|
||
pip install -e ".[all]"
|
||
|
||
# Development setup
|
||
pip install -e ".[dev]"
|
||
Docker (Production Deployment)
|
||
bash
|
||
# Run the complete stack (API + Web UI)
|
||
docker-compose up -d
|
||
|
||
# Run specific services
|
||
docker-compose up api # REST API only (port 8000)
|
||
docker-compose up web # Web UI only (port 5000)
|
||
|
||
# View logs
|
||
docker-compose logs -f
|
||
Quick Start Examples
|
||
1. Command Line Interface (CLI)
|
||
bash
|
||
# Generate credentials (memorize the output!)
|
||
stegasoo generate --pin --words 3
|
||
|
||
# Encode a text message
|
||
stegasoo encode \
|
||
--ref secret_photo.jpg \
|
||
--carrier meme.png \
|
||
--phrase "apple forest thunder" \
|
||
--pin 123456 \
|
||
--message "Meet at midnight"
|
||
|
||
# Encode a file
|
||
stegasoo encode \
|
||
--ref secret_photo.jpg \
|
||
--carrier meme.png \
|
||
--phrase "apple forest thunder" \
|
||
--pin 123456 \
|
||
--embed-file secret_document.pdf
|
||
|
||
# Decode a message
|
||
stegasoo decode \
|
||
--ref secret_photo.jpg \
|
||
--stego stego_abc123_20251227.png \
|
||
--phrase "apple forest thunder" \
|
||
--pin 123456
|
||
2. REST API (FastAPI)
|
||
bash
|
||
# Start the API server
|
||
uvicorn stegasoo.api.main:app --host 0.0.0.0 --port 8000
|
||
|
||
# Interactive documentation: http://localhost:8000/docs
|
||
|
||
# Encode with multipart upload
|
||
curl -X POST http://localhost:8000/encode/multipart \
|
||
-F "day_phrase=apple forest thunder" \
|
||
-F "pin=123456" \
|
||
-F "reference_photo=@photo.jpg" \
|
||
-F "carrier=@meme.png" \
|
||
-F "message=secret" \
|
||
--output stego.png
|
||
|
||
# Decode with multipart upload
|
||
curl -X POST http://localhost:8000/decode/multipart \
|
||
-F "day_phrase=apple forest thunder" \
|
||
-F "pin=123456" \
|
||
-F "reference_photo=@photo.jpg" \
|
||
-F "stego_image=@stego.png"
|
||
3. Web UI (Flask)
|
||
bash
|
||
# Start the Web UI
|
||
python -m stegasoo.web.app
|
||
|
||
# Visit http://localhost:5000
|
||
# Features: Drag-and-drop, image previews, mobile-responsive
|
||
Security Model
|
||
Multi-Factor Authentication
|
||
Stegasoo combines multiple authentication factors for unprecedented security:
|
||
|
||
Factor Type Entropy Description
|
||
Reference Photo Something you have 80-256 bits A photo both parties secretly share
|
||
Daily Phrase Something you know 33-132 bits Rotating passphrase (BIP-39 words)
|
||
Static PIN Something you know 20-30 bits 6-9 digit number (optional)
|
||
RSA Key Something you have 112-256 bits 2048-4096 bit key (optional)
|
||
Combined Hybrid 133-400+ bits Computational infeasibility
|
||
Security Configurations
|
||
Configuration Total Entropy Use Case
|
||
Photo + 3-word phrase + 6-digit PIN ~133 bits Casual communication
|
||
Photo + 6-word phrase + 9-digit PIN ~186 bits Business communication
|
||
Photo + 3-word phrase + RSA 2048 ~241 bits High-security documents
|
||
Photo + 6-word phrase + PIN + RSA 4096 ~400+ bits Military-grade secrecy
|
||
Cryptographic Guarantees
|
||
AES-256-GCM: Authenticated encryption prevents tampering
|
||
|
||
Argon2id: Memory-hard KDF (256MB) defeats GPU/ASIC attacks
|
||
|
||
Random salt per message: Prevents rainbow table attacks
|
||
|
||
Pseudo-random pixel selection: Defeats statistical steganalysis
|
||
|
||
Date-based key rotation: Limits exposure if credentials leak
|
||
|
||
Technical Specifications
|
||
Parameter Specification
|
||
Encryption AES-256-GCM (authenticated)
|
||
Key Derivation Argon2id (256MB, 3 iterations) or PBKDF2-SHA512 (600k iterations)
|
||
Steganography LSB with pseudo-random pixel selection
|
||
Image Formats PNG, BMP (lossless required)
|
||
Max Carrier Size 24 megapixels (4000×6000)
|
||
Max Text Payload 250,000 characters (~250 KB)
|
||
Max File Payload 6,144 KB (6 MB)
|
||
Max Upload Size 10 MB (configurable)
|
||
PIN Length 6-9 digits (cannot start with zero)
|
||
Phrase Length 3-12 BIP-39 words
|
||
RSA Key Sizes 2048, 3072, 4096 bits
|
||
Temp File Retention 5 minutes (auto-cleanup)
|
||
API Documentation Swagger UI (/docs) and ReDoc (/redoc)
|
||
Project Structure
|
||
text
|
||
stegasoo/
|
||
├── src/stegasoo/ # Core library
|
||
│ ├── __init__.py # Public API
|
||
│ ├── constants.py # Configuration constants
|
||
│ ├── crypto.py # AES-256-GCM encryption
|
||
│ ├── steganography.py # LSB embedding/extraction
|
||
│ ├── keygen.py # Credential generation
|
||
│ ├── key_derivation.py # Argon2id/PBKDF2 KDF
|
||
│ ├── models.py # Data classes (FilePayload, etc.)
|
||
│ ├── validation.py # Input validation
|
||
│ ├── utils.py # Utilities (date parsing, etc.)
|
||
│ ├── qr_utils.py # QR code generation/reading
|
||
│ └── exceptions.py # Custom exceptions
|
||
│
|
||
├── frontends/
|
||
│ ├── cli/ # Command-line interface (Click)
|
||
│ │ └── main.py # Complete CLI implementation
|
||
│ ├── api/ # FastAPI REST API
|
||
│ │ └── main.py # Full REST API with QR support
|
||
│ └── web/ # Flask web interface
|
||
│ ├── app.py # Flask application
|
||
│ ├── templates/ # HTML templates (Bootstrap 5)
|
||
│ └── static/ # CSS/JS assets
|
||
│
|
||
├── data/
|
||
│ └── bip39-words.txt # BIP-39 English wordlist
|
||
│
|
||
├── tests/ # Comprehensive test suite
|
||
├── pyproject.toml # Modern Python packaging
|
||
├── Dockerfile # Multi-stage Docker build
|
||
├── docker-compose.yml # Production deployment
|
||
├── requirements.txt # Dependencies
|
||
├── LICENSE # MIT License
|
||
└── README.md # This file
|
||
|
||
Advanced Features
|
||
|
||
QR Code Support
|
||
|
||
Store RSA keys as QR code images for physical key storage:
|
||
|
||
bash
|
||
# Generate RSA key and create QR code
|
||
stegasoo generate --rsa --output key.pem -p "password"
|
||
|
||
# Encode using QR code key
|
||
stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --key-qr keyqr.png -m "secret"
|
||
|
||
# API: Extract key from QR code
|
||
curl -X POST http://localhost:8000/extract-key-from-qr -F "qr_image=@keyqr.png"
|
||
File Embedding
|
||
Hide any file type (PDF, ZIP, documents, etc.):
|
||
|
||
bash
|
||
# Embed a PDF document
|
||
stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --pin 123456 -e document.pdf
|
||
|
||
# Embed an archive
|
||
stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --pin 123456 -e archive.zip
|
||
|
||
# Decode automatically detects file vs text
|
||
stegasoo decode -r ref.jpg -s stego.png -p "phrase" --pin 123456 -o extracted.pdf
|
||
Piping and Automation
|
||
bash
|
||
# Pipe messages from stdin
|
||
echo "Secret" | stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --pin 123456 > stego.png
|
||
|
||
# JSON output for scripting
|
||
creds=$(stegasoo generate --json)
|
||
pin=$(echo "$creds" | jq -r '.pin')
|
||
monday_phrase=$(echo "$creds" | jq -r '.phrases.Monday')
|
||
|
||
# Batch processing with quiet mode
|
||
for file in secrets/*.txt; do
|
||
stegasoo encode -r ref.jpg -c carriers/${file}.png -p "phrase" --pin 123456 -f "$file" -q
|
||
done
|
||
Development
|
||
Setup Development Environment
|
||
bash
|
||
git clone https://github.com/yourusername/stegasoo.git
|
||
cd stegasoo
|
||
|
||
# Install development dependencies
|
||
pip install -e ".[dev]"
|
||
|
||
# Run tests
|
||
pytest tests/ -v
|
||
|
||
# Code formatting
|
||
black src/ frontends/
|
||
ruff check src/ frontends/ --fix
|
||
|
||
# Type checking
|
||
mypy src/
|
||
|
||
# Security audit
|
||
bandit -r src/
|
||
Running All Services
|
||
bash
|
||
# Terminal 1: Start the REST API
|
||
cd frontends/api
|
||
python main.py
|
||
# API available at http://localhost:8000
|
||
# Documentation at http://localhost:8000/docs
|
||
|
||
# Terminal 2: Start the Web UI
|
||
cd frontends/web
|
||
python app.py
|
||
# Web UI available at http://localhost:5000
|
||
|
||
# Terminal 3: Use the CLI
|
||
stegasoo --help
|
||
Testing
|
||
bash
|
||
# Run unit tests
|
||
pytest tests/unit/
|
||
|
||
# Run integration tests
|
||
pytest tests/integration/
|
||
|
||
# Run security tests
|
||
pytest tests/security/
|
||
|
||
# Generate coverage report
|
||
pytest --cov=stegasoo --cov-report=html
|
||
Performance Benchmarks
|
||
Operation 1MP Image 8MP Image 16MP Image
|
||
Encode Text 120ms 450ms 850ms
|
||
Encode File 180ms 680ms 1.2s
|
||
Decode Text 100ms 380ms 720ms
|
||
Decode File 150ms 580ms 1.1s
|
||
Key Generation 850ms (Argon2id) N/A N/A
|
||
Benchmarks on AMD Ryzen 7 5800X, 32GB RAM, SSD
|
||
|
||
Production Deployment
|
||
Docker Compose (Recommended)
|
||
yaml
|
||
version: '3.8'
|
||
|
||
services:
|
||
api:
|
||
build:
|
||
context: .
|
||
target: api
|
||
ports:
|
||
- "8000:8000"
|
||
environment:
|
||
- PYTHONUNBUFFERED=1
|
||
restart: unless-stopped
|
||
|
||
web:
|
||
build:
|
||
context: .
|
||
target: web
|
||
ports:
|
||
- "5000:5000"
|
||
environment:
|
||
- FLASK_ENV=production
|
||
- API_BASE_URL=http://api:8000
|
||
depends_on:
|
||
- api
|
||
restart: unless-stopped
|
||
Nginx Configuration
|
||
nginx
|
||
# API Gateway
|
||
server {
|
||
listen 443 ssl;
|
||
server_name api.stegasoo.example.com;
|
||
|
||
ssl_certificate /path/to/cert.pem;
|
||
ssl_certificate_key /path/to/key.pem;
|
||
|
||
location / {
|
||
proxy_pass http://localhost:8000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_read_timeout 120s;
|
||
client_max_body_size 10M;
|
||
}
|
||
}
|
||
|
||
# Web UI
|
||
server {
|
||
listen 443 ssl;
|
||
server_name stegasoo.example.com;
|
||
|
||
ssl_certificate /path/to/cert.pem;
|
||
ssl_certificate_key /path/to/key.pem;
|
||
|
||
location / {
|
||
proxy_pass http://localhost:5000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_read_timeout 120s;
|
||
client_max_body_size 10M;
|
||
}
|
||
}
|
||
Documentation
|
||
Complete documentation is available:
|
||
|
||
CLI: CLI.md - Complete command-line reference with examples
|
||
|
||
REST API: API.md - Full API documentation with endpoints and examples
|
||
|
||
Web UI: WEB_UI.md - Web interface guide with screenshots
|
||
|
||
About Page: Detailed security model, features, and usage guide
|
||
|
||
Contributing
|
||
Fork the repository
|
||
|
||
Create a feature branch (git checkout -b feature/amazing-feature)
|
||
|
||
Commit your changes (git commit -m 'Add amazing feature')
|
||
|
||
Push to the branch (git push origin feature/amazing-feature)
|
||
|
||
Open a Pull Request
|
||
|
||
Development Guidelines
|
||
Write tests for new functionality
|
||
|
||
Maintain backward compatibility
|
||
|
||
Follow PEP 8 style guide
|
||
|
||
Add type hints for new functions
|
||
|
||
Update documentation for new features
|
||
|
||
License
|
||
MIT License - See LICENSE file for details.
|
||
|
||
⚠️ Security Disclaimer
|
||
This software is intended for:
|
||
|
||
Legitimate privacy protection
|
||
|
||
Secure communication between trusted parties
|
||
|
||
Educational purposes about cryptography and steganography
|
||
|
||
Users are responsible for:
|
||
|
||
Complying with all applicable laws in their jurisdiction
|
||
|
||
Using the tool only for legal purposes
|
||
|
||
Securely storing and transmitting credentials
|
||
|
||
Understanding that steganography is detectable with advanced analysis
|
||
|
||
Acknowledgments
|
||
BIP-39 wordlist for daily phrases
|
||
|
||
cryptography.io for Python crypto primitives
|
||
|
||
Pillow for image processing
|
||
|
||
FastAPI for the excellent REST API framework
|
||
|
||
Click for the CLI framework
|
||
|
||
Flask for the web interface
|
||
|
||
Argon2 team for the memory-hard KDF
|
||
|
||
Support
|
||
Documentation: CLI.md, API.md, WEB_UI.md
|
||
|
||
Issues: GitHub Issues
|
||
|
||
Security Issues: Please disclose responsibly via email
|
||
|
||
Stegasoo v2.1.0 - Production-ready secure steganography with multi-factor authentication and three complete interfaces.
|
||
|
||
text
|
||
|
||
You can copy and paste this entire content into your `README.md` file. It includes:
|
||
1. Updated installation instructions with current package names
|
||
2. Current project structure with all three frontends (CLI, API, Web UI)
|
||
3. Updated examples reflecting the current implementation
|
||
4. All security model information
|
||
5. Technical specifications
|
||
6. Development and deployment guides
|
||
7. Links to the other documentation files you provided
|
||
|