covertutils.datamanipulation package¶
Submodules¶
covertutils.datamanipulation.adhocchunker module¶
-
class
covertutils.datamanipulation.adhocchunker.
AdHocChunker
(tag_length=2)[source]¶ The AdHocChunker class is a special chunker that doesn’t tag each chunk that creates. It works by concatenating the actual byte size of the message that is to be chunked with the message itself. It splits the message into even chunks of size that is passed in the
chunkMessage()
method.The dechunking works by first identifying the byte length of the whole message and waiting until all bytes are received, discarding any padding bytes.
-
chunkMessage
(payload, chunk_size=None)[source]¶ Parameters: payload (str) – The raw data to be chunked in bytes. Return type: list Returns: A list of chunks containing the chunked payload.
-
deChunkMessage
(chunk)[source]¶ Parameters: chunk (str) – A part of a chunked message to be assembled. Return type: tuple Returns: The method return a tuple of (status, message). If status is False or None the provided chunk isn’t the last part of the message and the message contains an empty string. Else, the assembled message can be found in message.
-
covertutils.datamanipulation.chunker module¶
-
class
covertutils.datamanipulation.chunker.
Chunker
(chunk_length, dechunk_length=None, reverse=False)[source]¶ The Chunker class is used to initialize chunk and de-chunk messages.
-
__init__
(chunk_length, dechunk_length=None, reverse=False)[source]¶ Parameters: - chunk_length (int) – This parameter defines the size of the output chunks, containing tagging.
- dechunk_length (int) – This parameter defines the size of the input chunks, containing tagging.
- reverse (bool) – If True the chunk_length and dechunk_length are swapped. Useful when setting up 2 instances that have to match.
-
chunkMessage
(payload)[source]¶ Parameters: payload (str) – The raw data to be chunked in bytes. Return type: list Returns: A list of chunks containing the chunked payload.
-
deChunkMessage
(chunk, ret_chunk=False)[source]¶ Parameters: chunk (str) – A part of a chunked message to be assembled. Return type: tuple Returns: The method return a tuple of (status, message). If status is False the provided chunk isn’t the last part of the message and the message contains an empty string. Else, the assembled message can be found in message.
-
covertutils.datamanipulation.compressor module¶
-
class
covertutils.datamanipulation.compressor.
Compressor
[source]¶ The Compressor class initializes the bz2 and zlib compression routines. It detects the used compression on a trial and error base, eliminating the need of flag bytes containing such information.
-
compress
(message)[source]¶ This funtion performs all provided compression algorithm to the message parameter and decides which does the most efficient compression. It does so by comparing the output lengths.
Parameters: message (str) – The data to be compressed in raw bytes. Return type: str Returns: Data compressed by most efficient available algorithm.
-
decompress
(zipped)[source]¶ This funtion performs all provided decompression algorithm to the provided data. Based on the assumption that any decompression algorithm raises an Exception if the compressed data is not compatible, it finds the used compression algorithm and returns the decompressed data.
Parameters: message (str) – The data to be compressed in raw bytes. Return type: str Returns: Data compressed by most efficient available algorithm.
-
covertutils.datamanipulation.datatransformer module¶
-
class
covertutils.datamanipulation.datatransformer.
DataTransformer
(stego_configuration, transformation_list)[source]¶ This class provides automated data transformations. It uses the
covertutils.datamanipulation.stegoinjector.StegoInjector
class to create alterations to existing data chunks.Transformation List
The Transformation List argument is a specially structured list to dictate to the DataTranformer which changes should be done to data packet. Specifically, for a SYN - (RST, ACK) sequence to be simulated, the following configuration should be used:
X:_data_: L:_data_: K:_data_: ip_tcp_syn = '''45000028LLLL000040067ccd7f0000017f000001XXXX0050KKKKKKKK0000000050022000917c0000''' ip_tcp_rst_ack = '''450000280001000040067ccd7f0000017f0000010014005000000000XXXXXXXXXX50142000916a0000'''
The Transformation List that has to be used should dictate the class to:
- Unpack Sequence Number from ip_tcp_syn template (K tag)
- Increment it by 1
- Place it to a ip_tcp_rst_ack template (X tag)
- All the above while handling endianess, integer overflow checks, etc
The transformation_list is declared below:
transformation_list = [ ( # Tranformation #1 ( 'ip_tcp_syn:K', 'ip_tcp_rst_ack:X' ), # From template:tag to template:tag ('!I','!I') # Unpack as an 4-byte Integer (reverse Endianess as of network Endianess) and pack it to 4-byte Integer (reverse Endianess again) '_data_ + 1' # Eval this string (with the extracted/unpacked data as '_data_') and pack the result. ), # No other transformations ]
-
__init__
(stego_configuration, transformation_list)[source]¶ Parameters: - stego_configuration (str) – The Stego Configuration to initialize the internal
covertutils.datamanipulation.stegoinjector.StegoInjector
object. - transformation_list (list) – The Tranformation List as described above.
- stego_configuration (str) – The Stego Configuration to initialize the internal
-
runAll
(pkt, template=None)[source]¶ Runs all Tranformations in the transformation_list that relate to the specified template.
Parameters: - pkt (str) – The data packet to run the Tranformations on. In Raw Bytes.
- template (str) – The template string that describes the given data packet. If None the
covertutils.datamanipulation.stegoinjector.StegoInjector.guessTemplate()
function will try to guess the correct template.
Return type: str
Returns: Returns the pkt with all the related tranformations applied.
covertutils.datamanipulation.stegoinjector module¶
This module provides functionality for steganography. It uses a configuration string with custom syntax to describe where and how will data be injected in a template.
Stego Configuration Syntax Description
- Tags
- Tags are used to specify the functions that will be applied on each byte at injection and extraction.
- Templates
- Templates are hex strings containing the Tag Letters wherever arbitrary data can be injected.
Example Syntax:
# Comments symbol is traditionally the '#'
# -- Tags --
# Those are the tags. Declared as:
# Letter:<InjectionFunction>:<ExtractionFunction>
# Functions get evaluated with python 'eval' under the following context:
# _data_: byte to be injected, extracted
# _len_: packet length
# _index_: index of the byte injected/extracted
# _capacity_: Byte capacity of the packet as declared below
# _sxor_: Function that gets 2 char bytes and returns their XOR'd value
#
# Data functions that are reflective [applied twice to an input returns the input (e.g XOR operation)], do not need the <ExtractionFunction> part.
# Do need the last colon (:) though.
#
# Examples:
X:_data_: # inject the data as provided
K:_sxor_(_data_, '\xaa'): # inject the data xor'd with '\xaa' byte. Use the same function for extraction
L:chr(ord(_data_) + 1):chr(ord(_data_) - 1) # inject each byte incremented by 1. Decrement each byte before extraction.
# -- Packet Templates --
# Packet Templates, declared as:
# packet_template_name = '''Hex of the template packet with Tag Letters among the valid bytes''' []<groups>
# Groups are declared as:
# TagLetter[start:end]
# and will automatically replace all bytes between 'start' and 'end' with the given Tag Letter
#
# Those two templates are identical (Notice the Tag Letters between the Hex Values in `ip_tcp_syn2`)
ip_tcp_syn1 = '''450000280001000040067ccd7f0000017f00000100140050000000000000000050022000917c0000'''L[4:6],K[24:28],X[20:22]
ip_tcp_syn2 = '''45000028LLLL000040067ccd7f0000017f000001XXXX0050KKKKKKKK0000000050022000917c0000'''
# Whitespace and comments won't break the Strings
mac_ip_tcp_syn = '''ffffffffffff0000000000000800 # MAC header
450000280001000040067ccd7f0000017f000001 # IP header
00140050000000000000000050022000917c0000'''K[18:20],K[38:42],K[34:36]
-
class
covertutils.datamanipulation.stegoinjector.
StegoInjector
(stego_template, hex_inject=False)[source]¶ -
-
extract
(pkt, template)[source]¶ Parameters: - pkt (str) – A packet that matches the template in size, that contains covert data the way the template provides.
- template (str) – The template that will be used to extract the data from. It must be the same with the one used to inject the data in the pkt.
Return type: str
Returns: The data extracted from the pkt
-
getCapacity
(template, tag=None)[source]¶ Parameters: template (str) – The name of the template whose capacity is desired. Return type: int Returns: The template’s capacity in bytes
-
getCapacityDict
(template)[source]¶ Parameters: template (str) – The name of the template whose capacity dict is desired. Return type: dict Returns: The template’s capacity dict containing Tag Letters as keys and capacity of each Tag in bytes as values. A sample configuration :
X:_data_: Y:_data_: sample='''4141XX4242YYYY'''
Example
psi = StegoInjector( configuration ) psi.getCapacityDict( 'sample1' ) { 'X' : 1, 'Y' : 2 }
-
guessTemplate
(pkt)[source]¶ This method tries to guess the used template of a data packet by computing similarity of all templates against it.
Parameters: pkt (str) – The data packet whose template is guessed. Return type: str Returns: A tuple containing the template name that matches best with the given packets and the similarity ratio.
-
inject
(data, template, pkt=None)[source]¶ Parameters: - data (str) – The data to be injected in raw bytes
- template (str) – The template that will be used to inject the data into.
- pkt (str) – A packet that matches the template is size, to inject the data instead of the template. A copy of the template will be used if this argument is not provided.
Return type: str
Returns: Template or packet with the given data injected.
-
injectByTag
(data_dict, template, pkt=None)[source]¶ Parameters: - data_dict (dict) – The data to be injected in a dict format, with Tag Letters as keys and Data to be injected where the specific Tag Letters are placed, as values.
- template (str) – The template that will be used to inject the data into.
- pkt (str) – A packet that matches the template is size, to inject the data instead of the template. A copy of the template will be used if this argument is not provided.
Return type: str
Returns: Template or packet with the given data injected.
A sample configuration :
X:_data_: Y:_data_: sample='''4141XX4242YY'''
Example
data_dict = { 'X' : '0', 'Y' : '1' } psi = StegoInjector( configuration ) psi.injectByTag( data_dict, 'sample1' ) 'AA0BB1'
-
-
covertutils.datamanipulation.stegoinjector.
asciiToHexTemplate
(pkt, marker='~', substitute='X')[source]¶ This module function converts an ASCII chunk with single-byte markers and returns a template.
Parameters: - pkt (str) – The data packet in ASCII with marker byte where arbitrary bytes can be injected.
- marker (str) – The byte that will be interpreted as marker
- substitute (str) – The byte that will be replace the marker bytes in the hex-template representation.
Return type: str
Returns: The template representation populated with the substitute wherever the marker byte was placed.
Example:
req = 'GET /search.php?q=~~~~~~~~\n\n' template = asciiToHexTemplate( req ) print template 474554202f7365617263682e7068703f713dXXXXXXXXXXXXXXXX0a0a