alee/stegasoo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

New README

Browse Source
This commit is contained in:
Aaron D. Lee
2025-12-29 12:14:13 -05:00
parent 9559a3c39f
commit 3bad80361a
2 changed files with 1 additions and 565 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
README.md
View File

@@ -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 ```bash
# Generate credentials # Generate credentials
stegasoo generate --pin --words 3 stegasoo generate --pin --words 3
@@ -271,3 +168,4 @@ MIT License - Use responsibly.
## ⚠️ Disclaimer ## ⚠️ Disclaimer
This tool is for educational and legitimate privacy purposes only. Users are responsible for complying with applicable laws in their jurisdiction. This tool is for educational and legitimate privacy purposes only. Users are responsible for complying with applicable laws in their jurisdiction.

462
README_NEW.md
View File

@@ -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