Getting Started

🚀 Getting Started with StegX

This guide walks you through installing StegX, understanding image capacity, and performing your first encode/decode cycle.

---

1. Installation

1.1 PyPI (Recommended)

Requires Python ≥ 3.8 and pip.

pip install stegx-cli

To include compression codecs (Brotli, Zstandard) and password-strength checking (zxcvbn):

pip install stegx-cli[compression,strength]

1.2 Arch Linux (AUR)

yay -S stegx

The AUR package pulls all required dependencies including python-pillow, python-cryptography, and python-argon2-cffi. Optional dependencies (python-zstandard, python-brotli, python-zxcvbn, python-numpy, yubikey-manager) are listed as optdepends.

1.3 Docker

docker pull ayhamasfoor/stegx:latest

The Docker image is multi-architecture (linux/amd64, linux/arm64), runs as a non-root user (stegx), pre-installs all optional extras ([all]), and exposes stegx as its ENTRYPOINT.

1.4 Snap

sudo snap install stegx

1.5 From Source (Development)

git clone https://github.com/Delta-Sec/StegX.git
cd StegX
pip install -e '.[all]'
pip install -r requirements/dev.txt

---

2. Understanding Image Capacity

Not every image can hold the same amount of data. StegX uses Laplacian Edge-Detection (or optionally HILL cost maps) to determine which pixels are safe for embedding. Highly textured images (forests, cityscapes, fabric) have significantly more capacity than smooth images (clear skies, studio portraits).

Check the capacity of any cover image before encoding:

stegx info cover_image.png

Example output:

Image:      cover_image.png
Dimensions: 1920 × 1080 (6,220,800 sub-pixels)
Mode:       RGB
Adaptive:   Laplacian (top 60% texture density)
Capacity:   ~450.5 KB (with LSB Matching)
Capacity:   ~150.2 KB (with Matrix Embedding / --extreme)

Why does --extreme reduce capacity? Matrix Embedding uses Hamming(7,3) codes, which consume 7 pixel positions to embed 3 message bits. Standard LSB uses a 1:1 ratio. The trade-off is drastically lower detectability.

---

3. Hiding Data (Encoding)

3.1 Basic Encoding

stegx encode -i cover.png -f secret_document.pdf -o stego_output.png

You will be prompted to enter a strong password interactively. StegX will:

1. Compress the file using the best available codec (zstd, brotli, lzma, zlib).
2. Derive a master key using Argon2id (≈112ms cryptographic delay).
3. Encrypt the compressed payload with AES-256-GCM.
4. Generate a Non-Linear PRNG pixel sequence and embed into textured regions.

3.2 Supplying Passwords Non-Interactively

For scripts and CI/CD pipelines, pass the password via stdin:

echo "MyStrongPassword" | stegx encode -i cover.png -f secret.txt -o out.png --password-stdin

Or via a password file (ensure the file is chmod 600):

stegx encode -i cover.png -f secret.txt -o out.png --password-file /path/to/pw.txt

Security Note: Never pass passwords as plain CLI arguments (e.g., --password "xyz"). They will be logged in your shell history (~/.bash_history) and visible in ps aux output.

3.3 Enabling Advanced Modes

Extreme Mode — F5 Matrix Embedding for minimal modification:

stegx encode -i cover.png -f secret.txt -o out.png --extreme

Dual-Cipher — AES-256-GCM layered with ChaCha20-Poly1305:

stegx encode -i cover.png -f secret.txt -o out.png --dual-cipher

HILL Cost Map — more advanced pixel selection than Laplacian:

stegx encode -i cover.png -f secret.txt -o out.png --cost-mode hill

YubiKey Hardware 2FA:

stegx encode -i cover.png -f secret.txt -o out.png --yubikey

Keyfile Factor (2FA via file):

stegx encode -i cover.png -f secret.txt -o out.png --keyfile /path/to/keyfile.bin

---

4. Extracting Data (Decoding)

stegx decode -i stego_output.png -o extracted_document.pdf

StegX will prompt for the password and then:

1. Regenerate the PRNG sequence to locate the embedded bits.
2. Search for the HKDF-derived Magic Sentinel in the LSB stream.
3. Parse the binary header (version, flags, KDF params, salt, nonce).
4. Decrypt and authenticate the AEAD ciphertext.
5. Decompress and write the original file.

If you omit -o, StegX will automatically restore the original filename that was stored inside the encrypted container.

Decoding with Additional Factors

If the image was encoded with a keyfile:

stegx decode -i stego.png --keyfile /path/to/keyfile.bin

If the image was encoded with YubiKey (the same physical key must be present):

stegx decode -i stego.png --yubikey

---

5. Shamir Split and Merge

Distribute a secret across multiple images. See Advanced Features for the mathematical foundation.

Split across 5 images, require any 3 to reconstruct:

stegx split -f secret.txt \
    -i c1.png c2.png c3.png c4.png c5.png \
    -o s1.png s2.png s3.png s4.png s5.png \
    --quorum 3

Merge using any 3 of the 5 shares:

stegx merge -i s1.png s3.png s5.png -o recovered.txt

---

6. Panic Mode (Emergency Destruction)

Irreversibly destroy all steganographic payloads in a directory while leaving the visible images intact:

stegx panic /path/to/images/

See Advanced Features § Panic Mode for the cryptographic destruction mechanism and decoy architecture.

---

Next Steps

• Advanced Features — Deep dive into Matrix Embedding, Shamir, YubiKey, Panic, and FIPS.
• Security and Cryptography — The full cryptographic pipeline with mathematical proofs.
• Architecture — Binary container format, cost maps, and compression heuristics.