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

Version 3.0.2 full expirimental DCT support, jpegio for better jpg manipulation, etc.

Browse Source
This commit is contained in:
Aaron D. Lee
2025-12-31 15:43:29 -05:00
parent 4eefc946c4
commit 34376b2dfe
19 changed files with 2954 additions and 2200 deletions
Download Patch File Download Diff File Expand all files Collapse all files

323
README.md
View File

@@ -5,6 +5,7 @@ A secure steganography system for hiding encrypted messages in images using hybr
![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)
![Version](https://img.shields.io/badge/Version-3.0.2-purple)
## Features
@@ -17,50 +18,40 @@ A secure steganography system for hiding encrypted messages in images using hybr
- 🌐 **Multiple interfaces**: CLI, Web UI, REST API
- 📁 **File embedding** - Hide any file type (PDF, ZIP, documents)
- 📱 **QR code support** - Encode/decode RSA keys via QR codes
- 🆕 **DCT steganography** - JPEG-resilient embedding for social media (v3.0+)
## What's New in v3.0.2
| Feature | Description |
|---------|-------------|
| **DCT Mode** | Frequency-domain embedding survives JPEG recompression |
| **JPEG Output** | Native JPEG output using jpegio library |
| **Color Preservation** | DCT color mode preserves carrier image colors |
| **Auto-Detection** | Decoder automatically detects LSB vs DCT mode |
### Embedding Mode Comparison
| Mode | Capacity (1080p) | JPEG Resilient | Best For |
|------|------------------|----------------|----------|
| **LSB** (default) | ~770 KB | ❌ No | Email, file transfer |
| **DCT** (experimental) | ~65 KB | ✅ Yes | Social media, messaging apps |
## WebUI Preview
Front Page | Encode | Decode | Generate |
:-------------------------:|:-------------------------:|:------------------------:|:--------:|
![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Encode.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Decode.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Generate.webp)
| Front Page | Encode | Decode | Generate |
|:----------:|:------:|:------:|:--------:|
| ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Encode.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Decode.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Generate.webp) |
## Installation
### From Source
## Quick Start
```bash
# Clone the repository
git clone https://github.com/adlee-was-taken/stegasoo.git
cd stegasoo
# Install core library
pip install -e .
# Install with CLI
pip install -e ".[cli]"
# Install with Web UI
pip install -e ".[web]"
# Install with REST API
pip install -e ".[api]"
# Install everything
# Install with all features
pip install -e ".[all]"
```
### CLI Usage
```bash
# Generate credentials
# Generate credentials (memorize these!)
stegasoo generate --pin --words 3
# With RSA key
stegasoo generate --rsa --rsa-bits 4096 -o mykey.pem -p "secretpassword"
# Encode
# Encode a message (LSB mode - default)
stegasoo encode \
--ref photo.jpg \
--carrier meme.png \
@@ -68,88 +59,171 @@ stegasoo encode \
--pin 123456 \
--message "Secret message"
# Decode
# Encode for social media (DCT mode)
stegasoo encode \
--ref photo.jpg \
--carrier meme.png \
--phrase "apple forest thunder" \
--pin 123456 \
--message "Secret message" \
--mode dct \
--format jpeg
# Decode (auto-detects mode)
stegasoo decode \
--ref photo.jpg \
--stego stego.png \
--phrase "apple forest thunder" \
--pin 123456
# Pipe-friendly
echo "secret" | stegasoo encode -r photo.jpg -c meme.png -p "words" --pin 123456 > stego.png
stegasoo decode -r photo.jpg -s stego.png -p "words" --pin 123456 -q
```
### Web UI
For detailed installation instructions, see **[INSTALL.md](INSTALL.md)**.
```bash
# Development
cd frontends/web
python app.py
# Production
gunicorn --bind 0.0.0.0:5000 app:app
```
Visit http://localhost:5000
### REST API
```bash
# Development
cd frontends/api
python main.py
# Production
uvicorn main:app --host 0.0.0.0 --port 8000
```
API docs at http://localhost:8000/docs
#### Example API Calls
```bash
# Generate credentials
curl -X POST http://localhost:8000/generate \
-H "Content-Type: application/json" \
-d '{"use_pin": true, "use_rsa": false}'
# Encode (multipart)
curl -X POST http://localhost:8000/encode/multipart \
-F "message=Secret" \
-F "day_phrase=apple forest thunder" \
-F "pin=123456" \
-F "reference_photo=@photo.jpg" \
-F "carrier=@meme.png" \
--output stego.png
# Decode (multipart)
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"
```
---
## Security Model
Stegasoo uses multiple authentication factors combined with strong cryptography:
```
┌─────────────────────────────────────────────────────────────────┐
│ AUTHENTICATION LAYERS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Reference Photo ──┐ │
│ (~80-256 bits) │ │
│ ├──► Argon2id KDF ──► AES-256-GCM Key │
│ Day Phrase ───────┤ (256MB RAM) │
│ (~33-132 bits) │ │
│ │ │
│ Static PIN ───────┤ │
│ (~20-30 bits) │ │
│ │ │
│ RSA Key ──────────┘ │
│ (~128 bits) (optional, adds another factor) │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Entropy Summary
| Component | Entropy | Purpose |
|-----------|---------|---------|
| Reference Photo | ~80-256 bits | Something you have |
| Day Phrase (3-12 words) | ~33-100+ bits | Something you know (rotates daily) |
| PIN (6-9 digits) | ~20+ bits | Something you know (static) |
| RSA Key (2048-bit) | ~128 bits | Something you have |
| **Combined** | **~133-400+ bits** | **Beyond brute force** |
| Day Phrase (3-12 words) | ~33-132 bits | Something you know (rotates daily) |
| PIN (6-9 digits) | ~20-30 bits | Something you know (static) |
| RSA Key (2048-4096 bit) | ~112-128 bits | Something you have (optional) |
| **Combined** | **133-400+ bits** | **Beyond brute force** |
### Attack Resistance
| Attack | Protection |
|--------|------------|
| Brute force | 2^133+ combinations |
| Rainbow tables | Random salt per message |
| Steganalysis | Random pixel selection |
| Brute force | 2^133+ combinations minimum |
| Rainbow tables | Random 16-byte salt per message |
| Steganalysis | Pseudo-random pixel/coefficient selection |
| GPU cracking | Argon2id requires 256MB RAM per attempt |
| Side-channel | Constant-time operations in crypto |
| Side-channel | Constant-time operations in cryptography library |
| JPEG recompression | DCT mode embeds in frequency domain (v3.0+) |
### Security Configurations
| Configuration | Entropy | Use Case |
|--------------|---------|----------|
| 3-word phrase + 6-digit PIN | ~133 bits | Casual private messaging |
| 6-word phrase + 9-digit PIN | ~176 bits | Standard security |
| 3-word phrase + RSA 2048 | ~241 bits | File-based authentication |
| 6-word phrase + PIN + RSA 4096 | ~304 bits | Maximum security |
---
## Interfaces
### Command-Line Interface (CLI)
Full-featured CLI with piping support:
```bash
# Generate with RSA key
stegasoo generate --rsa --rsa-bits 4096 -o mykey.pem -p "password"
# Encode from file
stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --pin 123456 -f secret.txt
# Encode for social media (DCT + JPEG)
stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --pin 123456 \
-m "Message" --mode dct --format jpeg
# Decode to stdout (quiet mode)
stegasoo decode -r ref.jpg -s stego.png -p "phrase" --pin 123456 -q
# Check image capacity (shows both LSB and DCT)
stegasoo info carrier.png
```
📖 Full documentation: **[CLI.md](CLI.md)**
### Web UI
Browser-based interface with drag-and-drop uploads:
```bash
# Start the server
cd frontends/web
python app.py
# Visit http://localhost:5000
```
Features:
- Drag-and-drop image uploads
- Real-time entropy calculator
- Native mobile sharing (Web Share API)
- DCT mode with advanced options panel
- Automatic day-of-week detection
📖 Full documentation: **[WEB_UI.md](WEB_UI.md)**
### REST API
FastAPI-powered REST API with OpenAPI documentation:
```bash
# Start the server
cd frontends/api
uvicorn main:app --host 0.0.0.0 --port 8000
# Docs at http://localhost:8000/docs
```
Example API calls:
```bash
# Generate credentials
curl -X POST http://localhost:8000/generate \
-H "Content-Type: application/json" \
-d '{"use_pin": true, "words_per_phrase": 3}'
# Encode with DCT mode
curl -X POST http://localhost:8000/encode/multipart \
-F "message=Secret" \
-F "day_phrase=apple forest thunder" \
-F "pin=123456" \
-F "embedding_mode=dct" \
-F "output_format=jpeg" \
-F "reference_photo=@photo.jpg" \
-F "carrier=@meme.png" \
--output stego.jpg
# Decode (auto-detects mode)
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.jpg"
```
📖 Full documentation: **[API.md](API.md)**
---
## Project Structure
@@ -159,11 +233,13 @@ stegasoo/
│ ├── __init__.py # Public API
│ ├── constants.py # Configuration
│ ├── crypto.py # Encryption/decryption
│ ├── steganography.py # Image embedding
│ ├── steganography.py # LSB image embedding
│ ├── dct_steganography.py # DCT embedding (v3.0+)
│ ├── keygen.py # Credential generation
│ ├── validation.py # Input validation
│ ├── models.py # Data classes
│ ├── exceptions.py # Custom exceptions
│ ├── qr_utils.py # QR code utilities
│ └── utils.py # Utilities
│
├── frontends/
@@ -176,18 +252,19 @@ stegasoo/
│
├── pyproject.toml # Package configuration
├── Dockerfile # Multi-stage Docker build
└── docker-compose.yml # Container orchestration
├── docker-compose.yml # Container orchestration
│
├── README.md # This file
├── INSTALL.md # Installation guide
├── CLI.md # CLI documentation
├── API.md # API documentation
└── WEB_UI.md # Web UI documentation
```
---
## Configuration
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `FLASK_ENV` | production | Flask environment |
| `PYTHONPATH` | - | Include src/ for development |
### Limits
| Limit | Value |
@@ -199,6 +276,15 @@ stegasoo/
| Phrase length | 3-12 words |
| RSA key sizes | 2048, 3072, 4096 bits |
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `FLASK_ENV` | production | Flask environment |
| `PYTHONPATH` | - | Include `src/` for development |
---
## Development
```bash
@@ -214,13 +300,42 @@ ruff check src/ frontends/
# Type checking
mypy src/
# Check DCT support
python -c "from stegasoo import has_dct_support; print(has_dct_support())"
python -c "from stegasoo.dct_steganography import has_jpegio_support; print(has_jpegio_support())"
```
---
## Version History
| Version | Changes |
|---------|---------|
| **3.0.2** | Fixed JPEG output with jpegio integration |
| **3.0.1** | Added DCT color mode, JPEG output (broken) |
| **3.0.0** | Added DCT steganography mode |
| **2.2.x** | QR code support, file embedding |
| **2.0.x** | Web UI, REST API, RSA keys |
| **1.0.x** | Initial release, CLI only |
---
## License
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.
---
## See Also
- **[INSTALL.md](INSTALL.md)** - Detailed installation instructions
- **[CLI.md](CLI.md)** - Command-line interface reference
- **[API.md](API.md)** - REST API documentation
- **[WEB_UI.md](WEB_UI.md)** - Web interface guide