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.

__init__(tag_length=2)[source]
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.
chunkMessageToStr(payload)[source]
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.
reset()[source]

Resets all partially assembled messages.

setChunkSize(chunk_size)[source]

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.
chunkMessageToStr(payload)[source]
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.
reset()[source]

Resets all partially assembled messages.

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.

__init__()[source]
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:
runAll(pkt, template=None)[source]

Runs all Tranformations in the transformation_list that relate to the specified template.

Parameters:
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]
__init__(stego_template, hex_inject=False)[source]
blankifyPacketFields(pkt, template, zero=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

extractByTag(pkt, template)[source]
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 }
getTemplate(template)[source]
getTemplates()[source]
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

covertutils.datamanipulation.stegoinjector2 module

Module contents