stegosphere package

Subpackages

Submodules

stegosphere.io module

Utilities for converting between file, string, and binary formats, and for encoding/decoding payloads with optional framing.

Functions include: - Encoding/decoding binary payloads with framing - Conversion between files, strings, bytes, hex, and binary - Type checks for binary and hexadecimal strings

stegosphere.io.binary_to_data(binary)

Converts binary string to data.

Parameters:: binary (str) – Binary string to convert
Returns:: Data as bytes
Return type:: bytes

stegosphere.io.binary_to_file(binary_data, output_path)

Write binary data into a file.

Parameters:

binary_data (str) – Binary data to store
output_path (str) – Path to save the output file

Returns:

None

stegosphere.io.check_type(data)

Check whether data is binary, hexadecimal or neither.

Parameters:: data (str) – data to be checked
Returns:: 0 meaning binary, 1 meaning hex, 2 meaning neither
Return type:: int

stegosphere.io.data_to_binary(data)

Converts data (string or bytes) to a binary string.

Parameters:: data – Data to convert
Returns:: Binary string
Return type:: str
Raises:: TypeError – If data could not be converted

stegosphere.io.decode_binary_payload(payload, framing, framing_kwargs=None)

Decodes binary payload by removing payload framing.

Parameters:

payload (str) – Payload to be decoded
framing (stegosphere.payloader.PayloadFrame | None, optional) – Framing method to use
framing_kwargs (dict | None) – specific framing arguments

Returns:

Decoded binary payload

Return type:

str

stegosphere.io.encode_binary_payload(payload, framing=None, framing_kwargs=None)

Converts payload into binary and applies payload framing.

Parameters:

payload (str) – Payload to be encoded
framing (stegosphere.payloader.PayloadFrame | None, optional) – Framing method to use
framing_kwargs (dict | None) – specific framing arguments

Returns:

Encoded binary payload

Return type:

str

stegosphere.io.file_to_binary(path)

Converts a file into its binary representation.

Parameters:: path (str) – Path to the input file
Returns:: Binary data of the file
Return type:: str

stegosphere.io.hex_to_binary(data)

Convert hexadecimal str to binary str.

Parameters:: data (str) – data to be converted
Returns:: Binary data
Return type:: str

stegosphere.io.is_binary(data)

Check if string only contains binary data.

Parameters:: data (str) – data to be checked
Returns:: True, if data is binary. False, if not.
Return type:: bool

stegosphere.payloader module

Payload framing utilities for binary data encoding.

Defines framing schemes for prefixing or delimiting binary payloads to allow reliable extraction. Includes abstract base class PayloadFrame and implementations: - RawData (no framing) - FixedLength (known payload size) - FixedHeader (length prefix) - Delimiter (sentinel-based) - Unary and EliasGamma (self-delimiting codes)

Used for lossless transmission or embedding of binary payloads.

class stegosphere.payloader.Delimiter

Bases: PayloadFrame

Delimiter-based framing: appends a sentinel bit-pattern to mark the payload end.

static decode(payload, **kwargs)

Decode by splitting at the sentinel and returning data before it.

Parameters:

payload (str) – Payload to be extracted from
**kwargs – use sentinel as additional argument

Returns:

Original payload

Return type:

str

Raises:

ValueError – If sentinel is not found in the payload

Warns:

UserWarning – If the sentinel occurs inside the payload data as well.

static encode(payload, **kwargs) → str

Encode by appending the sentinel after the payload.

Parameters:

payload (str) – Payload to be framed
**kwargs – use sentinel as additional argument

Returns:

Framed payload

Return type:

str

class stegosphere.payloader.EliasGamma

Bases: PayloadFrame

Elias Gamma framing: unary-encodes floor(log2(L)), appends binary suffix, then payload. No extra parameters needed.

static decode(payload: str, **kwargs) → str

Decode by:

Read unary prefix to get N (count of leading ‘1’s)
Skip zero
Read N bits as suffix, reconstruct L = 2^N + int(suffix,2)
Read next L bits as payload

Parameters:: payload (str) – Framed payload
Returns:: Original payload
Return type:: str
Raises:: ValueError –

static encode(payload: str, **kwargs) → str

Encode by:

Let L = len(payload)
Compute N = floor(log2(L))
Unary prefix = ‘1’*N + ‘0’
Binary suffix = binary(L) without leading ‘1’
Result = prefix + suffix + payload

Parameters:: payload (str) – Payload to be framed
Returns:: Framed payload
Return type:: str
Raises:: ValueError – If length of payload is <=0

class stegosphere.payloader.FixedHeader

Bases: PayloadFrame

Fixed-header framing prefixes the payload with a binary length of fixed bit width. Use fixed_header_length in **kwargs to specify length. Defaults to stegosphere.payloader.FIXED_HEADER_LENGTH_DEFAULT. 32 bit for metadata length should be sufficient for almost all usecases (payload size below 0.5GB).

static decode(payload: str, **kwargs) → str

Decode by reading the fixed-width header, extracting that many bits as payload.

Parameters:

payload (str) – Payload to be extracted from
**kwargs – use fixed_header_length as additional argument

Returns:

Original payload

Return type:

str

Raises:

ValueError – If payload is shorter than the fixed_header_length

Warns:

UserWarning – If framed payload is shorter than the indicated length. Will return entire payload.

static encode(payload, **kwargs)

Encode by prepending the payload length as a binary string of fixed width.

Parameters:

payload (str) – Payload to be framed
**kwargs – use fixed_header_length as additional argument

Returns:

Framed payload

Return type:

str

Raises:

TypeError – If fixed_header_length is not a positive integer

class stegosphere.payloader.FixedLength

Bases: PayloadFrame

Fixed length is needed in decoding.

static decode(payload: str, n_bits=None, **kwargs) → str

Decode a framed payload and extract the original data bits.

Parameters:

payload (str) – A framed string to decode.
**kwargs – Method-specific parameters.

Returns:

The original payload.

Return type:

str

static encode(payload, n_bits=None, **kwargs)

Frame and encode a binary payload string.

Parameters:

payload (str) – Payload string, often binary
**kwargs – Method-specific parameters.

Returns:

The framed string.

Return type:

str

class stegosphere.payloader.PayloadFrame

Bases: ABC

Abstract base class for payload framing methods. Subclasses must implement static encode() and decode() methods.

abstractmethod static decode(payload: str, **kwargs) → str

Decode a framed payload and extract the original data bits.

Parameters:

payload (str) – A framed string to decode.
**kwargs – Method-specific parameters.

Returns:

The original payload.

Return type:

str

abstractmethod static encode(payload: str, **kwargs) → str

Frame and encode a binary payload string.

Parameters:

payload (str) – Payload string, often binary
**kwargs – Method-specific parameters.

Returns:

The framed string.

Return type:

str

class stegosphere.payloader.RawData

Bases: PayloadFrame

Equivalent to not using any payload framing

static decode(payload)

Decode a framed payload and extract the original data bits.

Parameters:

payload (str) – A framed string to decode.
**kwargs – Method-specific parameters.

Returns:

The original payload.

Return type:

str

static encode(payload)

Frame and encode a binary payload string.

Parameters:

payload (str) – Payload string, often binary
**kwargs – Method-specific parameters.

Returns:

The framed string.

Return type:

str

class stegosphere.payloader.Unary

Bases: PayloadFrame

Unary framing: prefixes the payload with a unary-coded length (n ‘1’s and a ‘0’). This self-delimiting code requires no extra parameters.

static decode(payload: str, **kwargs) → str

Decode by counting leading ‘1’s up to the first ‘0’, then reading that many bits.

Parameters:: payload (str) – Payload to be extracted from
Returns:: Original payload
Return type:: str
Raises:: ValueError – If terminator is not found

static encode(payload: str, **kwargs) → str

Encode by prefixing with unary length.

Parameters:: payload (str) – Payload to be framed
Returns:: Framed payload
Return type:: str

stegosphere.payloader.decode_framing(payload, framing=None, framing_kwargs=None)

Decodes payload by removing payload framing.

Parameters:

payload (str) – Payload to be decoded
framing (stegosphere.payloader.PayloadFrame | None, optional) – Framing method to use
framing_kwargs (dict | None) – specific framing arguments

Returns:

Decoded binary payload

Return type:

str

stegosphere.payloader.encode_framing(payload, framing=None, framing_kwargs=None)

Encodes a binary payload using specified framing method.

Parameters:

payload (str) – Payload to be encoded
framing (stegosphere.payloader.PayloadFrame | None, optional) – Framing method to use
framing_kwargs (dict | None) – specific framing arguments

Returns:

Encoded binary payload

Return type:

str

stegosphere.selector module

Index selection methods for data embedding.

Provides deterministic and probabilistic strategies for selecting embedding locations based on cost metrics or pseudorandom generators.

Includes: - Greedy selection by cost - PRNG-based shuffling and sampling (PCG64DXSM) - Weighted random sampling from inverse-costs or arbitrary weights

stegosphere.selector.greedy_indices(costs, n=-1)

Sorts indices by cost and returns the n smallest costs’s indices.

Parameters:

costs (numpy.ndarray) – Cost-function output
n (optional) – Return n indices, defaults to -1 for all indices

Returns:

Array of indices

Return type:

numpy.ndarray

stegosphere.selector.inverse_cost_greedy_prng_indices(costs, n, key)

Samples n distinct indices from costs, with probability proportional to 1/costs (lower‐cost positions more likely).

Parameters:

costs (numpy.ndarray) – Array of embedding costs
n – Number of indices to pick
key – Seed for PRNG

Returns:

Flat array of indices

Return type:

numpy.ndarray

stegosphere.selector.prng_indices(size, key)

Shuffles indices of array using PCG64DXSM.

Parameters:

size – size of array to be shuffled
key – seed to use for PRNG

Returns:

Shuffled indices

Return type:

numpy.ndarray

stegosphere.selector.prng_indices_choice(size, key, length): Randomly selects length indices using a key as a seed, with size as upper-bound. More efficient for most scenarios than prng_indices. Will be merged in the future.

stegosphere.selector.weighted_greedy_prng_indices(max_index, weights, n, key)

Samples n distinct indices using a PRNG with a specified weight distribution.

Parameters:

max_index – Upper bound of indices used
weights (numpy.ndarray) – Weights used for sampling
n – Number of indices to pick
key – Seed for PRNG

Returns:

Flat array of indices

Return type:

numpy.ndarray

stegosphere.utils module

Module for various utilities

stegosphere.utils.dtype_range(dtype)

Gets minimum/maximum value of numpy datatype.

Parameters:: dtype – dtype to be checked
Returns:: Containing minimum and maximum value
Return type:: tuple
Raises:: TypeError – if dtype is not numpy.integer or numpy.floating

stegosphere.utils.generate_binary_payload(length)

Generates a binary payload.

Parameters:: length – Length of the payload
Returns:: Payload
Return type:: str

Module contents

Stegosphere is a versatile library for both applying steganography (hiding data within media) and performing steganalysis (detecting hidden data). It provides a flexible framework for any data representable as a NumPy array, including images, videos, audios and TrueType fonts. Furthermore, multi-file embedding, Hamming codes, payload compression, encryption and visualization are available, as well as a research toolbox for evaluating method performance and security.

stegosphere.binary_to_data(binary)

Converts binary string to data.

Parameters:: binary (str) – Binary string to convert
Returns:: Data as bytes
Return type:: bytes

stegosphere.binary_to_file(binary_data, output_path)

Write binary data into a file.

Parameters:

binary_data (str) – Binary data to store
output_path (str) – Path to save the output file

Returns:

None

stegosphere.data_to_binary(data)

Converts data (string or bytes) to a binary string.

Parameters:: data – Data to convert
Returns:: Binary string
Return type:: str
Raises:: TypeError – If data could not be converted

stegosphere.file_to_binary(path)

Converts a file into its binary representation.

Parameters:: path (str) – Path to the input file
Returns:: Binary data of the file
Return type:: str