StegaPy: A Python-Based Steganography Tool

Language: 中文 | English

StegaPy is a Python-based image steganography and digital watermarking tool. Steganography conceals secret data within an ordinary cover image so that it remains visually indistinguishable from the original; digital watermarking embeds an invisible mark for ownership verification.

This project is a Python rewrite of OpenStego, reproducing its core algorithms while adding a plugin architecture, randomized LSB steganography, a web interface, and a command-line tool.

✨ Features

• Plugin Architecture: LSB, RandomLSB, and DWT-Dugad are integrated through a unified interface, making it straightforward to add new algorithms
• Random LSB (RandomLSB): Uses a cryptographic PRNG to randomize bit placement, resisting chi-square statistical steganalysis attacks
• AES Encryption + Gzip Compression: Supports AES-128/256 payload encryption; adaptive Gzip compression significantly increases effective payload capacity
• Web Interface: Streamlit-based interactive UI with drag-and-drop upload and before/after image difference visualization
• Command-Line Interface (CLI): Full coverage of embed, extract, and watermark workflows — suitable for scripting and batch processing
• Cross-platform: Runs locally via conda or pip, and supports one-click Docker deployment

🚀 Quick Start

Installation

Conda (Recommended)

conda env create -f environment.yml
conda activate StegaPy

pip

pip install -r requirements.txt

---

Web Interface

streamlit run app.py

Then open http://localhost:8501 in your browser.

---

Command-Line Interface (CLI)

Interactive mode — no arguments; menu-driven with Tab path completion.

python cli.py

Scripting mode — pass arguments directly, suitable for automation.

# Embed data
python cli.py embed -i cover.png -m message.txt -o stego.png
python cli.py embed -i cover.png -m message.txt -o stego.png --algo randlsb -p <password>

# Extract data (--algo must match what was used at embed time)
python cli.py extract -i stego.png -o output/ --algo lsb
python cli.py extract -i stego.png -o output/ --algo randlsb -p <password>

# Watermark: generate signature → embed → verify
python cli.py wm generate-sig -o sig.bin -p <password>
python cli.py wm embed        -i cover.png -s sig.bin -o stego.png -p <password>
python cli.py wm verify       -i stego.png -s sig.bin -p <password>

Full usage: python cli.py --help or python cli.py embed --help

---

Docker Deployment

docker-compose up -d    # build and start in background
docker-compose ps       # check status
docker-compose down     # stop and remove

The image is built automatically on first run (a few minutes). Then visit http://localhost:8501.

CLI inside Docker: the docker-compose setup mounts the project directory into /app.

# Run CLI via the live web container
docker exec stegapy python cli.py embed \
  -i /app/cover.png -m /app/message.txt -o /app/stego.png

# Standalone one-off run (no web container needed)
docker run --rm -v $(pwd):/app stegapy \
  python cli.py embed -i /app/cover.png -m /app/message.txt -o /app/stego.png

Use container-side paths (/app/...). Output files are written back to the mounted directory and immediately accessible on the host.

---

🧪 Running Tests

End-to-end tests cover both the Python API and CLI:

# Run all tests
pytest tests/test_e2e.py -v

# Run a specific group
pytest tests/test_e2e.py -v -k "LSB"
pytest tests/test_e2e.py -v -k "CLI"

Coverage: LSB / RandomLSB / DWT-Dugad full roundtrips, AES encryption, PSNR image quality assertion, wrong-password exception, all CLI subcommands.

-k "LSB" filter results:

-k "CLI" filter results:

📁 Project Structure

StegaPy/
├── StegaPy/              # Core package
│   ├── StegaPy.py        # Main dispatcher (compression/encryption/plugin)
│   ├── config.py         # Global configuration
│   ├── plugin_manager.py # Plugin registry
│   ├── plugin/           # Algorithm plugins (LSB, RandomLSB, DWT-Dugad)
│   └── util/             # Utilities (image processing, AES, DWT, etc.)
├── app.py                # Streamlit web application
├── cli.py                # CLI (no args = interactive TUI, with args = scripting mode)
├── tests/                # End-to-end tests (pytest)
├── data/                 # Sample cover image and test text
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

📄 License

This project is licensed under the GNU General Public License v2.0 (GPL-2.0). See LICENSE for details.

🙏 Acknowledgments

This project is a rewrite of OpenStego. Thanks to the original authors: - Samir Vaidya (@syvaidya) - Zelong Zhang (@superzhangzl)

Digital watermarking algorithm based on: Peter Meerwald, Digital Image Watermarking in the Wavelet Transfer Domain, University of Salzburg, 2001.

📧 Contact

Questions or suggestions? Open a GitHub Issue.

---

This project is intended for educational and lawful purposes only.