stegasoo/frontends/CLI.md

Stegasoo CLI Documentation (v3.2.0)

Complete command-line interface reference for Stegasoo steganography operations.

Table of Contents

• Installation
• What's New in v3.2.0
• Quick Start
• Commands
  • generate
  • encode
  • decode
  • verify
  • info
  • compare
  • modes
  • strip-metadata
• Embedding Modes
• Security Factors
• Workflow Examples
• Piping & Scripting
• Error Handling
• Exit Codes

---

Installation

From PyPI

# CLI only
pip install stegasoo[cli]

# CLI with DCT support
pip install stegasoo[cli,dct]

# With all extras
pip install stegasoo[all]

From Source

git clone https://github.com/example/stegasoo.git
cd stegasoo
pip install -e ".[cli,dct]"

Verify Installation

stegasoo --version
stegasoo --help

# Check DCT support
python -c "from stegasoo import has_dct_support; print('DCT:', 'available' if has_dct_support() else 'requires scipy')"

---

What's New in v3.2.0

Version 3.2.0 brings major simplifications to the authentication system:

Change	Before (v3.1)	After (v3.2.0)
Passphrase	Daily rotation (7 phrases)	Single passphrase
Date parameter	Required for encode/decode	Removed entirely
Default words	3 words per phrase	4 words
Terminology	day_phrase, phrase	passphrase

Key benefits:

• ✅ No need to remember which day a message was encoded
• ✅ True asynchronous communication
• ✅ Simpler credential management
• ✅ Stronger default security (4 words = ~44 bits entropy)

Migration: Old stego images encoded with v3.1.x cannot be decoded with v3.2.0 due to the removed date-based key derivation. Keep v3.1.x installed if you need to access old images.

---

Quick Start

# 1. Generate credentials (do this once, memorize results)
stegasoo generate

# 2. Encode a message (LSB mode - default)
stegasoo encode \
  --ref secret_photo.jpg \
  --carrier meme.png \
  --passphrase "apple forest thunder mountain" \
  --pin 123456 \
  --message "Meet at midnight"

# 3. Encode for social media (DCT mode)
stegasoo encode \
  --ref secret_photo.jpg \
  --carrier meme.png \
  --passphrase "apple forest thunder mountain" \
  --pin 123456 \
  --message "Meet at midnight" \
  --mode dct \
  --dct-format jpeg

# 4. Decode a message (auto-detects mode)
stegasoo decode \
  --ref secret_photo.jpg \
  --stego stego_abc123.png \
  --passphrase "apple forest thunder mountain" \
  --pin 123456

---

Commands

Generate Command

Generate credentials for encoding/decoding operations. Creates a passphrase and optionally a PIN and/or RSA key.

Synopsis

stegasoo generate [OPTIONS]

Options

Option	Short	Type	Default	Description
--pin/--no-pin		flag	--pin	Generate a PIN
--rsa/--no-rsa		flag	--no-rsa	Generate an RSA key
--pin-length		6-9	6	PIN length in digits
--rsa-bits		choice	2048	RSA key size (2048, 3072, 4096)
--words		3-12	4	Words in passphrase (v3.2.0: default increased to 4)
--output	-o	path		Save RSA key to file
--password	-p	string		Password for RSA key file
--json		flag		Output as JSON

Examples

Basic generation with PIN (default):

stegasoo generate

Output:

============================================================
  STEGASOO CREDENTIALS (v3.2.0)
============================================================

⚠️  MEMORIZE THESE AND CLOSE THIS WINDOW
    Do not screenshot or save to file!

─── STATIC PIN ───
    847293

─── PASSPHRASE ───
    abandon ability able about

─── SECURITY ───
    Passphrase entropy: 44 bits (4 words)
    PIN entropy:        19 bits
    Combined:           63 bits
    + photo entropy:    80-256 bits

✓ v3.2.0: Use this passphrase anytime - no date needed!

Generate with more words for higher security:

stegasoo generate --words 6

Generate with RSA key:

stegasoo generate --rsa --rsa-bits 4096

Save RSA key to encrypted file:

stegasoo generate --rsa -o mykey.pem -p "mysecretpassword"

Maximum security (longer passphrase + both factors):

stegasoo generate --pin --rsa --words 6 --pin-length 9

JSON output for scripting:

stegasoo generate --json

Output:

{
  "passphrase": "abandon ability able about",
  "pin": "847293",
  "rsa_key": null,
  "entropy": {
    "passphrase": 44,
    "pin": 19,
    "rsa": 0,
    "total": 63
  }
}

Extract passphrase from JSON:

stegasoo generate --json | jq -r '.passphrase'

RSA only (no PIN):

stegasoo generate --no-pin --rsa -o key.pem -p "password123"

---

Encode Command

Encode a secret message or file into an image using steganography.

Synopsis

stegasoo encode [OPTIONS]

Options

Option	Short	Type	Required	Default	Description
--ref	-r	path	✓		Reference photo (shared secret)
--carrier	-c	path	✓		Carrier image to hide message in
--passphrase	-p	string	✓		Passphrase (v3.2.0: single, no date needed)
--message	-m	string			Message to encode
--message-file	-f	path			Read message from file
--embed-file	-e	path			Embed a binary file
--pin		string	*		Static PIN (6-9 digits)
--key	-k	path	*		RSA key file
--key-qr		path	*		RSA key from QR code image
--key-password		string			Password for RSA key
--output	-o	path			Output filename
--mode		choice		lsb	Embedding mode: lsb or dct
--dct-format		choice		png	DCT output: png or jpeg
--dct-color		choice		grayscale	DCT color: grayscale or color
--quiet	-q	flag			Suppress output

* At least one of --pin, --key, or --key-qr is required.

Message Input Methods

1. Command line argument:

   stegasoo encode -r ref.jpg -c carrier.png -p "four word passphrase" --pin 123456 -m "Secret message"
   

2. From file:

   stegasoo encode -r ref.jpg -c carrier.png -p "four word passphrase" --pin 123456 -f message.txt
   

3. From stdin (pipe):

   echo "Secret message" | stegasoo encode -r ref.jpg -c carrier.png -p "four word passphrase" --pin 123456
   

4. Embed binary file:

   stegasoo encode -r ref.jpg -c carrier.png -p "four word passphrase" --pin 123456 -e secret.pdf
   

Examples

Basic encoding with PIN (LSB mode - default):

stegasoo encode \
  --ref photos/vacation.jpg \
  --carrier memes/funny_cat.png \
  --passphrase "correct horse battery staple" \
  --pin 847293 \
  --message "The package arrives Tuesday"

Output:

Mode: LSB (12.4% capacity)
✓ Encoded successfully!
  Output: a1b2c3d4.png
  Size: 245,832 bytes
  Capacity used: 12.4%

DCT mode for social media (JPEG output):

stegasoo encode \
  --ref photos/vacation.jpg \
  --carrier memes/funny_cat.png \
  --passphrase "correct horse battery staple" \
  --pin 847293 \
  --message "The package arrives Tuesday" \
  --mode dct \
  --dct-format jpeg

Output:

Mode: DCT (grayscale, JPEG) (45.2% capacity)
✓ Encoded successfully!
  Output: a1b2c3d4.jpg
  Size: 89,432 bytes
  Capacity used: 45.2%
  DCT output: JPEG (grayscale)

DCT mode with color preservation:

stegasoo encode \
  -r ref.jpg \
  -c carrier.png \
  -p "phrase words here now" \
  --pin 123456 \
  -m "Message" \
  --mode dct \
  --dct-color color \
  --dct-format png

With RSA key:

stegasoo encode \
  -r reference.jpg \
  -c carrier.png \
  -p "apple forest thunder mountain" \
  -k mykey.pem \
  --key-password "secretpassword" \
  -m "Encrypted with RSA"

Both PIN and RSA (maximum security):

stegasoo encode \
  -r ref.jpg \
  -c carrier.png \
  -p "word1 word2 word3 word4" \
  --pin 123456 \
  -k mykey.pem \
  --key-password "pass" \
  -m "Double-locked message"

Custom output filename:

stegasoo encode \
  -r ref.jpg \
  -c carrier.png \
  -p "phrase words here now" \
  --pin 123456 \
  -m "Message" \
  -o holiday_photo.png

Embed a binary file:

stegasoo encode \
  -r ref.jpg \
  -c large_image.png \
  -p "secure phrase words here" \
  --pin 123456 \
  -e secret_document.pdf \
  -o output.png

Quiet mode for scripting:

stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --pin 123456 -m "msg" -q -o out.png
# No output, just creates the file

---

Decode Command

Decode a secret message or file from a stego image. Automatically detects LSB vs DCT mode.

Synopsis

stegasoo decode [OPTIONS]

Options

Option	Short	Type	Required	Description
--ref	-r	path	✓	Reference photo (same as encoding)
--stego	-s	path	✓	Stego image to decode
--passphrase	-p	string	✓	Passphrase used for encoding
--pin		string	*	Static PIN
--key	-k	path	*	RSA key file
--key-qr		path	*	RSA key from QR code image
--key-password		string		Password for RSA key
--output	-o	path		Save message to file
--mode		choice		Extraction mode: auto, lsb, or dct
--quiet	-q	flag		Output only the message
--force		flag		Overwrite existing output file

* Must provide the same security factors used during encoding.

Examples

Basic decoding with PIN:

stegasoo decode \
  --ref photos/vacation.jpg \
  --stego received_image.png \
  --passphrase "correct horse battery staple" \
  --pin 847293

Output:

✓ Decoded successfully!

The package arrives Tuesday

Decoding DCT image (auto-detected):

stegasoo decode \
  --ref photos/vacation.jpg \
  --stego received_image.jpg \
  --passphrase "correct horse battery staple" \
  --pin 847293

With RSA key:

stegasoo decode \
  -r reference.jpg \
  -s stego_image.png \
  -p "apple forest thunder mountain" \
  -k mykey.pem \
  --key-password "secretpassword"

Save decoded message to file:

stegasoo decode \
  -r ref.jpg \
  -s stego.png \
  -p "passphrase words here now" \
  --pin 123456 \
  -o decoded_message.txt

Output:

✓ Decoded successfully!
  Saved to: decoded_message.txt

Quiet mode (message only):

stegasoo decode -r ref.jpg -s stego.png -p "phrase" --pin 123456 -q

Output:

The package arrives Tuesday

Pipe to another command:

stegasoo decode -r ref.jpg -s stego.png -p "phrase" --pin 123456 -q | gpg --decrypt

Force specific extraction mode:

stegasoo decode -r ref.jpg -s stego.png -p "phrase" --pin 123456 --mode dct

---

Verify Command

Verify that a stego image can be decoded without extracting the actual message content.

Synopsis

stegasoo verify [OPTIONS]

Options

Option	Short	Type	Required	Description
--ref	-r	path	✓	Reference photo
--stego	-s	path	✓	Stego image to verify
--passphrase	-p	string	✓	Passphrase
--pin		string	*	Static PIN
--key	-k	path	*	RSA key file
--key-qr		path	*	RSA key from QR code
--key-password		string		Password for RSA key
--mode		choice		Extraction mode: auto, lsb, or dct
--json		flag		Output as JSON

Examples

Basic verification:

stegasoo verify -r photo.jpg -s stego.png -p "my passphrase here" --pin 123456

Output:

✓ Valid stego image
  Payload:  text (142 bytes)
  Size:     142 bytes

JSON output:

stegasoo verify -r photo.jpg -s stego.png -p "words here" --pin 123456 --json

Output:

{
  "valid": true,
  "stego_file": "stego.png",
  "payload_type": "text",
  "payload_size": 142
}

Failed verification:

stegasoo verify -r photo.jpg -s stego.png -p "wrong passphrase" --pin 123456

Output:

✗ Verification failed
  Error: Decryption failed: Invalid authentication tag

---

Info Command

Display information about an image's capacity for both LSB and DCT modes.

Synopsis

stegasoo info IMAGE [OPTIONS]

Options

Option	Type	Description
--json	flag	Output as JSON

Examples

Check carrier image capacity:

stegasoo info vacation_photo.png

Output:

Image: vacation_photo.png
  Dimensions:  1920 × 1080
  Pixels:      2,073,600
  Mode:        RGB
  Format:      PNG

  Capacity:
    LSB mode:  ~776,970 bytes (758.8 KB)
    DCT mode:  ~64,800 bytes (63.3 KB) ✓
    DCT ratio: 8.3% of LSB
    DCT options: grayscale/color, png/jpeg

JSON output:

stegasoo info photo.png --json

Output:

{
  "file": "photo.png",
  "width": 1920,
  "height": 1080,
  "pixels": 2073600,
  "mode": "RGB",
  "format": "PNG",
  "capacity": {
    "lsb": {
      "bytes": 776970,
      "kb": 758.8
    },
    "dct": {
      "bytes": 64800,
      "kb": 63.3,
      "available": true,
      "ratio_vs_lsb": 8.3,
      "output_formats": ["png", "jpeg"],
      "color_modes": ["grayscale", "color"]
    }
  }
}

---

Compare Command

Compare LSB and DCT embedding modes for an image with recommendations.

Synopsis

stegasoo compare IMAGE [OPTIONS]

Options

Option	Short	Type	Description
--payload-size	-s	int	Check if specific payload size fits
--json		flag	Output as JSON

Examples

Basic comparison:

stegasoo compare carrier.png

Output:

=== Mode Comparison: carrier.png ===
  Dimensions: 1920 × 1080

  ┌─── LSB Mode ───
  │ Capacity:  776,970 bytes (758.8 KB)
  │ Output:    PNG
  │ Status:    ✓ Available
  │
  ├─── DCT Mode ───
  │ Capacity:  64,800 bytes (63.3 KB)
  │ Ratio:     8.3% of LSB capacity
  │ Status:    ✓ Available
  │ Formats:   PNG (lossless), JPEG (smaller)
  │ Colors:    Grayscale (default), Color
  │
  └─── Recommendation ───
    LSB for larger payloads, DCT for better stealth
    DCT supports color output with --dct-color color

Check if payload fits:

stegasoo compare carrier.png --payload-size 50000

Output:

=== Mode Comparison: carrier.png ===
  Dimensions: 1920 × 1080

  ┌─── LSB Mode ───
  │ Capacity:  776,970 bytes (758.8 KB)
  │ Output:    PNG
  │ Status:    ✓ Available
  │
  ├─── DCT Mode ───
  │ Capacity:  64,800 bytes (63.3 KB)
  │ Ratio:     8.3% of LSB capacity
  │ Status:    ✓ Available
  │ Formats:   PNG (lossless), JPEG (smaller)
  │ Colors:    Grayscale (default), Color
  │
  ├─── Payload Check ───
  │ Size:      50,000 bytes
  │ LSB mode:  ✓ Fits
  │ DCT mode:  ✓ Fits
  │
  └─── Recommendation ───
    DCT mode for better stealth (payload fits both modes)
    Use --dct-color color to preserve original colors

---

Modes Command

Show available embedding modes and their status.

Synopsis

stegasoo modes

Example Output

=== Stegasoo Embedding Modes (v3.2.0) ===

  LSB Mode (Spatial LSB)
    Status:      ✓ Always available
    Output:      PNG/BMP (full color)
    Capacity:    ~375 KB per megapixel
    Use case:    Larger payloads, color preservation
    CLI flag:    --mode lsb (default)

  DCT Mode (Frequency Domain)
    Status:      ✓ Available
    Capacity:    ~75 KB per megapixel (~20% of LSB)
    Use case:    Better stealth, frequency domain hiding
    CLI flag:    --mode dct

  DCT Options
    Output format:
      --dct-format png     Lossless, larger file (default)
      --dct-format jpeg    Lossy, smaller, more natural

    Color mode:
      --dct-color grayscale   Traditional DCT (default)
      --dct-color color       Preserves original colors

  v3.2.0 Changes:
    ✓ No date parameters needed
    ✓ Single passphrase (no daily rotation)
    ✓ Default passphrase increased to 4 words
    ✓ True asynchronous communications

  Examples:
    # Traditional DCT (grayscale PNG)
    stegasoo encode ... --mode dct

    # Color-preserving DCT with JPEG output
    stegasoo encode ... --mode dct --dct-color color --dct-format jpeg

    # Compare modes for an image
    stegasoo compare carrier.png

---

Strip-Metadata Command

Remove all metadata (EXIF, GPS, etc.) from an image.

Synopsis

stegasoo strip-metadata IMAGE [OPTIONS]

Options

Option	Short	Type	Default	Description
--output	-o	path		Output file (default: overwrites as PNG)
--format	-f	choice	PNG	Output format: PNG or BMP
--quiet	-q	flag		Suppress output

Examples

# Strip metadata, save as PNG
stegasoo strip-metadata photo.jpg -o clean.png

# Overwrite in place (converts to PNG)
stegasoo strip-metadata photo.jpg

Output:

✓ Metadata stripped
  Input:  photo.jpg (2,456,789 bytes)
  Output: clean.png (1,234,567 bytes)

---

Embedding Modes

Stegasoo supports two steganography algorithms.

LSB Mode (Default)

Least Significant Bit embedding modifies pixel values directly.

stegasoo encode ... --mode lsb
# or just omit --mode (LSB is default)

Aspect	Details
Capacity	~3 bits/pixel (~375 KB for 1920×1080)
Output	PNG only (lossless required)
Resilience	❌ Destroyed by JPEG compression
Best For	Maximum capacity, controlled channels

DCT Mode

Discrete Cosine Transform embedding hides data in frequency coefficients.

stegasoo encode ... --mode dct --dct-format jpeg --dct-color color

Aspect	Details
Capacity	~0.25 bits/pixel (~65 KB for 1920×1080)
Output	PNG or JPEG
Resilience	✅ Better resistance to analysis
Best For	Social media, stealth requirements

DCT Options

Option	Values	Default	Description
--dct-format	png, jpeg	png	Output image format
--dct-color	grayscale, color	grayscale	Color processing

Choosing the Right Mode

Need maximum capacity?
           │
    ┌──────┴──────┐
    ▼             ▼
   YES           NO
    │             │
    ▼             ▼
Use LSB       Need stealth?
(default)          │
           ┌──────┴──────┐
           ▼             ▼
          YES           NO
           │             │
           ▼             ▼
        Use DCT       Use LSB
        --mode dct    (default)

Capacity Comparison

Mode	1920×1080 Capacity
LSB (PNG)	~375 KB
DCT (PNG)	~65 KB
DCT (JPEG)	~50 KB

---

Security Factors

Stegasoo uses multiple authentication factors:

Factor	Description	Entropy
Reference Photo	A photo both parties have	~80-256 bits
Passphrase	BIP-39 word phrase	~44 bits (4 words)
Static PIN	Numeric PIN (6-9 digits)	~20 bits (6 digits)
RSA Key	Shared key file	~128 bits effective

Minimum Requirements

• At least one of PIN or RSA key must be provided
• Reference photo is always required
• Passphrase is always required

Security Configurations

Configuration	Entropy (excl. photo)	Use Case
4-word passphrase + 6-digit PIN	~63 bits	Standard use
6-word passphrase + 6-digit PIN	~85 bits	Enhanced security
4-word passphrase + RSA 2048	~172 bits	File-based auth
6-word passphrase + PIN + RSA	~213 bits	Maximum security

---

Workflow Examples

Basic Secure Communication

Setup (once):

# Both parties generate credentials
stegasoo generate

# Or share RSA key securely
stegasoo generate --rsa -o shared_key.pem -p "agreedpassword"
# Securely transfer shared_key.pem to recipient

Sender:

# For email, file transfer, etc. (no recompression)
stegasoo encode \
  -r our_shared_photo.jpg \
  -c random_meme.png \
  -p "our shared passphrase here" \
  --pin 847293 \
  -m "Meeting moved to 3pm"

Sender (social media):

# For platforms that may recompress
stegasoo encode \
  -r our_shared_photo.jpg \
  -c random_meme.png \
  -p "our shared passphrase here" \
  --pin 847293 \
  -m "Meeting moved to 3pm" \
  --mode dct \
  --dct-format jpeg

Recipient:

# Works for both LSB and DCT (auto-detected)
stegasoo decode \
  -r our_shared_photo.jpg \
  -s received_image.png \
  -p "our shared passphrase here" \
  --pin 847293

Batch Processing

Encode multiple messages:

#!/bin/bash
PASSPHRASE="apple forest thunder mountain"
PIN="123456"
REF="reference.jpg"

for file in messages/*.txt; do
  name=$(basename "$file" .txt)
  stegasoo encode \
    -r "$REF" \
    -c "carriers/${name}.png" \
    -p "$PASSPHRASE" \
    --pin "$PIN" \
    -f "$file" \
    -o "output/${name}_stego.png" \
    -q
  echo "Encoded: $name"
done

Encode for social media (DCT):

#!/bin/bash
for file in messages/*.txt; do
  name=$(basename "$file" .txt)
  stegasoo encode \
    -r "$REF" \
    -c "carriers/${name}.png" \
    -p "$PASSPHRASE" \
    --pin "$PIN" \
    -f "$file" \
    --mode dct \
    --dct-format jpeg \
    -o "output/${name}_social.jpg" \
    -q
  echo "Encoded for social: $name"
done

---

Piping & Scripting

Stdin/Stdout Support

Encode from pipe:

cat secret.txt | stegasoo encode -r ref.jpg -c carrier.png -p "phrase words" --pin 123456 -o out.png

Decode to pipe:

stegasoo decode -r ref.jpg -s stego.png -p "phrase words" --pin 123456 -q | less

Chain with encryption:

# Encode GPG-encrypted content
gpg -e -r recipient@email.com secret.txt
cat secret.txt.gpg | base64 | stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --pin 123456

# Decode and decrypt
stegasoo decode -r ref.jpg -s stego.png -p "phrase" --pin 123456 -q | base64 -d | gpg -d

JSON Output for Scripts

# Get credentials as JSON
creds=$(stegasoo generate --json)

# Extract specific fields
passphrase=$(echo "$creds" | jq -r '.passphrase')
pin=$(echo "$creds" | jq -r '.pin')
entropy=$(echo "$creds" | jq -r '.entropy.total')

echo "Passphrase: $passphrase"
echo "PIN: $pin"
echo "Total entropy: $entropy bits"

Error Handling in Scripts

#!/bin/bash
set -e

if ! stegasoo decode -r ref.jpg -s stego.png -p "phrase" --pin 123456 -q 2>/dev/null; then
  echo "Decryption failed - check credentials"
  exit 1
fi

---

Error Handling

Common Errors

Error	Cause	Solution
"Must provide --pin or --key"	No security factor given	Add --pin or --key option
"PIN must be 6-9 digits"	Invalid PIN format	Use numeric PIN, 6-9 chars
"Payload too large for LSB mode"	Message exceeds capacity	Use larger carrier or shorter message
"Payload too large for DCT mode"	DCT has less space	Use LSB mode or shorter message
"Decryption failed"	Wrong credentials	Verify passphrase, PIN, ref photo
"DCT mode requires scipy"	Missing library	Install: pip install scipy

Troubleshooting Decryption Failures

1. Check passphrase: Must be exact match (case-sensitive)
2. Verify reference photo: Must be the exact same file, not a resized copy
3. Check stego image:
   • LSB: Ensure it wasn't resized, recompressed, or converted
   • DCT: More resilient but not immune to heavy processing
4. Verify PIN/key: Must match exactly what was used for encoding

v3.2.0 Migration Note

If you're trying to decode images created with v3.1.x:

• v3.2.0 cannot decode v3.1.x images (date-based key derivation removed)
• Keep v3.1.x installed to access old images
• Re-encode old messages with v3.2.0 for forward compatibility

---

Exit Codes

Code	Meaning
0	Success
1	General error / decryption failed
2	Invalid arguments/options

---

Environment Variables

Variable	Description
PYTHONPATH	Include src/ for development
STEGASOO_DEBUG	Enable debug output (set to 1)

---

Dependencies

Core Dependencies

• pillow - Image processing
• cryptography - Encryption
• argon2-cffi - Key derivation
• click - CLI framework

DCT Mode Dependencies

• scipy - DCT transformations

Install DCT dependencies:

pip install scipy

Check availability:

stegasoo modes
# or
python -c "from stegasoo import has_dct_support; print('DCT:', has_dct_support())"

---

See Also

• API Documentation - Python API reference
• Web UI Documentation - Browser interface guide
• README - Project overview and security model