From 3bad80361a6b38e039b92a74e06d868d724a58ef Mon Sep 17 00:00:00 2001 From: "Aaron D. Lee" Date: Mon, 29 Dec 2025 12:14:13 -0500 Subject: [PATCH] New README --- README.md | 104 +----------- README_NEW.md | 462 -------------------------------------------------- 2 files changed, 1 insertion(+), 565 deletions(-) delete mode 100644 README_NEW.md diff --git a/README.md b/README.md index 9dd4688..4fc9128 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,3 @@ -# Stegasoo - -A secure steganography system for hiding encrypted messages in images using hybrid authentication. - -![Python](https://img.shields.io/badge/Python-3.10+-blue) -![License](https://img.shields.io/badge/License-MIT-green) -![Security](https://img.shields.io/badge/Security-AES--256--GCM-red) - -## Features - -- 🔐 **AES-256-GCM** authenticated encryption -- 🧠 **Argon2id** memory-hard key derivation (256MB RAM requirement) -- 🎲 **Pseudo-random pixel selection** defeats steganalysis -- 📅 **Daily key rotation** with BIP-39 passphrases -- 🔑 **Multi-factor authentication**: PIN, RSA key, or both -- 🖼️ **Reference photo** as "something you have" -- 🌐 **Multiple interfaces**: CLI, Web UI, REST API - -## Installation - -### From PyPI (coming soon) - -```bash -# Core library only -pip install stegasoo - -# With CLI -pip install stegasoo[cli] - -# With Web UI -pip install stegasoo[web] - -# With REST API -pip install stegasoo[api] - -# Everything -pip install stegasoo[all] -``` - -### From Source - -```bash -git clone https://github.com/example/stegasoo.git -cd stegasoo - -# Install with all extras -pip install -e ".[all]" -``` - -### Docker - -```bash -# Web UI only -docker-compose up web - -# REST API only -docker-compose up api - -# Both -docker-compose up -``` - -## Quick Start - -### Python Library - -```python -import stegasoo - -# Generate credentials -creds = stegasoo.generate_credentials(use_pin=True, use_rsa=False) -print(f"Today's phrase: {creds.phrases['Monday']}") -print(f"PIN: {creds.pin}") - -# Encode a message -with open('secret_photo.jpg', 'rb') as f: - ref_photo = f.read() -with open('meme.png', 'rb') as f: - carrier = f.read() - -result = stegasoo.encode( - message="Meet at midnight", - reference_photo=ref_photo, - carrier_image=carrier, - day_phrase="apple forest thunder", - pin="123456" -) - -with open('stego.png', 'wb') as f: - f.write(result.stego_image) - -# Decode a message -message = stegasoo.decode( - stego_image=result.stego_image, - reference_photo=ref_photo, - day_phrase="apple forest thunder", - pin="123456" -) -print(message) # "Meet at midnight" -``` - -### CLI - ```bash # Generate credentials stegasoo generate --pin --words 3 @@ -271,3 +168,4 @@ MIT License - Use responsibly. ## ⚠️ Disclaimer This tool is for educational and legitimate privacy purposes only. Users are responsible for complying with applicable laws in their jurisdiction. + diff --git a/README_NEW.md b/README_NEW.md deleted file mode 100644 index e485fdb..0000000 --- a/README_NEW.md +++ /dev/null @@ -1,462 +0,0 @@ -# Stegasoo - -A secure steganography system for hiding encrypted messages and files in images using hybrid multi-factor authentication. - -![Python](https://img.shields.io/badge/Python-3.10+-blue) -![License](https://img.shields.io/badge/License-MIT-green) -![Security](https://img.shields.io/badge/Security-AES--256--GCM-red) -![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green) -![Status](https://img.shields.io/badge/Status-Production_Ready-success) - -## 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 -