Disclaimer

This toolkit is developed solely for ethical and educational purposes to deepen understanding of malware creation and analysis. Using this tool to target other users, conduct attacks without prior consent, or apply it in unauthorized environments is strictly forbidden. The responsibility for proper use rests entirely on the user. Caution is advised! Misuse could harm your system or other users. We highly recommend using this tool within isolated virtual machines.

About

Draconus is composed of two core components that work together to create a flexible, modular experimentation environment.

Draconus itself runs quietly in the background, creating servers, managing connections, and handling all automated tasks. Once launched, it can operate indefinitely without user interaction, maintaining listeners and managing clients on its own.

The second component, Commander, serves as the interactive interface for communicating with the background service. Through a console-style command system built with Python Click, users can issue commands, manage servers, inspect connections, and generate payloads.

Commander also provides access to the Hive section, a workspace dedicated to creating payloads, modules, shellcode, and various building blocks used throughout the project. Hive simplifies the creation process, enabling users to assemble complex components from ready-made modules.

Although Draconus is not as advanced or extensive as large-scale professional frameworks such as Metasploit, it takes inspiration from some of their ideas. The project is developed as a hobby initiative, exploring different approaches, techniques, and learning opportunities. Features like shellcode generation and payload embedding are present, but implemented in a way suited to the project’s unique design and philosophy.

Contents

• Draconus
• Disclaimer
• About
• Install
• Start
• First Run
• Hive
• Module Types
• Variables
• Hive Commands
• Hive Examples
• Tips and Tricks
• Modules List
• Contributing
• Changelog

Installation

1. Ensure you have Python 3.11.2 or a newer version installed on your system.
2. Install Docker (e.g., using the following command):

   sudo apt install docker.io

3. To allow the program to interact with Docker, you need to set the appropriate permissions. Run:

   sudo usermod -aG docker $USER

   Afterward, log out and back in (or restart your system) to apply the new permissions.
4. Due to the recent policy changes in Python modules on Linux, make sure you have Python’s virtual environment package, venv, installed. If not, install it with:

   sudo apt install python3.11-venv

The installation is complete, and your environment is ready to use.

Start

Before launching Draconus for the first time, review the CONFIG.ini file. This file defines the core runtime parameters of the project. One of the most important settings is the IP value, which should be set to your machine’s IP address. It will be used automatically when generating servers and payloads.

The configuration file also allows you to customize message colors, adjust maximum console width, and modify various other visual and functional options. All available parameters are documented directly inside the file.

1. Starting Draconus

The main background service is Draconus. It is designed to run continuously and independently, either in a separate console window or in the background.

To start it normally, run:

python3 Draconus.py

During the first launch, a built-in loader will automatically create a virtual environment and install all required packages.

To run Draconus in the background, you can use:

nohup python3 Draconus.py &

Draconus will continue running until manually terminated.

2. Starting Commander

Once Draconus is running, you can launch the control interface: Commander. The program will not start unless it detects an active Draconus instance.

Start Commander using:

python3 c2.py

If the connection succeeds, you will see a confirmation message indicating that Commander has successfully linked with Draconus. From here, you can manage servers, inspect connections, and access the Hive section for creating payloads, modules, and shellcode.

First Run

When you start Draconus, a directory named OUTPUT will appear in its main directory. This is a critical folder where Draconus stores its logs, downloaded files, created worms, and more. Do not delete this directory while the program is running. You can safely delete it only when both Draconus and Commander are stopped.

Contents of the OUTPUT Directory:

• Logs - This folder contains log files. Every message displayed by Draconus is saved here, along with a timestamp. Similarly, any message received from clients is also logged.
• Loot - This folder stores files downloaded from or sent by clients. It will contain subdirectories named after the IP addresses of clients, which will hold the files sent by them. Think of the Loot folder as the treasure chest for files received from clients.
• Hive - This folder contains files related to worms, source code, shellcodes, and ready-to-use executables. If you create a worm, it will be stored here.
  
  Starting from version 2.2, the Hive directory is implemented as a shortcut pointing to a directory located in the user's home folder. The actual Hive workspace is now created there, while the folder inside the project serves only as a link.
  This change allows Draconus and its Docker images to be updated independently without requiring a full reinstallation or risking the loss of previously created worms, payloads, and build artifacts.
  

  

• Links - This folder provides shortcuts to various useful resources in the project, so you don't have to search for them manually. It includes:
  • A folder with icons where you can add your own icons and use them when creating worms.
  • A shortcut to files where you can add custom code, for example, to payloads.

  

Using Commands

This README does not describe every Draconus command in detail, because the program itself provides extensive, built-in documentation.

By typing help inside Commander, you will see a full list of available commands together with their explanations. Many commands also include additional documentation available through the --help parameter, for example:

server --help

This will show descriptions of available server types, their parameters, and usage examples.

Each connected client is automatically assigned a unique ID. To interact directly with a client, simply use:

conn <ID>

All of this is clearly documented inside the built-in help system.

The Hive section, which will be described later in this README, is more advanced than the basic command layer. Since Hive enables building payloads, modules, shellcode, worms, and more, its structure and commands are explained here in additional detail.

--------- Hive ----------

Module Types

Hive is built around different module types, each serving a specific role in the construction process:

• worm The primary module and the starting point of every project. It defines the type of worm being created, such as shellcode, Python script, standalone executable, or DLL. The selected worm type determines whether additional modules or payloads can be embedded.
• module Optional extensions that enhance or modify the behavior of a worm. Not every worm template supports modules, while some templates are built entirely from modular components. Modules may consist of raw code snippets, dynamic DLLs, or static libraries.
• payload Prebuilt functional components written in various languages. Worms or modules may expose dedicated injection points for payloads. Payloads are handled differently by the build system than modules, which is why similar functionality may exist in both forms.
• shadow Code obfuscation components. These modules transform source code into a heavily obscured and difficult-to-analyze form.
• scode Templates for the shellcode generator. This category contains predefined shellcode types that can be generated on demand. Generated shellcode is exported in three popular formats for easy integration.
• rscript Resource script (.rc) files included during the compilation process. They define metadata such as version number, application description, and other resource information, allowing the resulting executable to resemble a legitimate application. Most values are generated automatically using data from food, but users may override them with custom values.
• compiler Compiler and linker scripts used during the build process. Each worm template has a default compiler configuration, but it can be replaced or modified. For example, Python-based worms can be compiled using either PyInstaller or Nuitka.
• food Supporting data used by worms and modules. This includes text databases, link collections, naming resources, and specialized string sequences required by certain libraries. Draconus uses food when generating application names, descriptions, metadata, and other contextual elements.
• support Internal helper modules automatically added and managed by Draconus. These components provide auxiliary functionality required by other modules and are not intended to be modified manually.
• sfile (support file) Additional files automatically attached during the build process. These may include auxiliary binaries, configuration files, or data blobs required by the final executable.
• wprocess Defines the complete build workflow of a worm. This component controls how modules, payloads, compilers, and resources are combined. It is added and managed automatically by Draconus and represents the internal build pipeline.

Variables (var)

Variables (var) are one of the most important elements in the worm creation process. They are responsible for configuring behavior, parameters, and runtime values used by worms, modules, and payloads.

Every added template—whether it is a main worm template or a regular module—may define its own configurable variables. These variables are used to control things such as network settings, execution behavior, payload options, and build-time parameters.

To view the current configuration and state of the worm being built, use the command:

worm

This command displays all active modules and their associated variables. Many variables come with default values that can be modified as needed. The most common examples include IP addresses, port numbers, and execution options.

Setting Variables

Variables are set using the following command syntax:

var [variable_name] "[value]"

Important: Always enclose the value in double quotes (" "). This prevents parsing errors, especially when the value contains spaces or special characters.

Using Food as Variable Input

Variables can also be populated using entries from the food section. This is especially useful when assigning large datasets or complex values that would be impractical or error-prone to paste directly into the console.

To assign a food entry to a variable, use:

var -f [variable_name] [food_name]

This allows Draconus to automatically inject predefined content into the variable, such as text blocks, link lists, or specialized string sequences.

Additional Help

For a full list of options and advanced usage, use:

var --help

Hive Commands

The Hive section provides a dedicated set of commands used to create, configure, and build worms, payloads, modules, and other components. These commands control the entire build lifecycle, from initialization to final compilation.

Available Commands

• install
  Downloads and installs the required Docker image containing all necessary compilers and build tools. This command is only required if the image is not already present on the system.
• reset
  Creates a new worm template. Removes all currently added modules, variables, and settings, effectively resetting the build process and starting a new project from scratch.
• name [name]
  Assigns a name to the worm being created. This name is used during the build process and may appear in metadata, output files, and logs.
• icon [name]
  Assigns an icon to the worm. Draconus includes a set of built-in icons, but custom icons can also be added. This command provides additional options and usage examples via --help.
• mods
  Displays all available module types along with their descriptions. Use this command to explore what kinds of components can be added to a worm.
• show [module_type]
  Lists all available modules of the specified type. To view all valid module types, use the mods command or refer to the Module Types section in this README.
• add [module_type] [module_name]
  Adds the specified module to the current worm template. This is the core command used during worm construction.
  
  Examples:

  add worm DuckHunt

  Creates and assigns the main worm template of type worm named DuckHunt.

  add module PyRawTcp

  Adds the PyRawTcp module to the current worm template.
• var [options] [name] "[value]"
  Creates or modifies variables used by the worm and its modules. See the Variables section in this README or use var --help for detailed usage.
• worm
  Displays the complete configuration of the currently built worm. This includes all added modules, variable values, and build settings. It is the primary command for inspecting the current build state.
• build [options]
  Finalizes and compiles the worm. Depending on the selected template, the output may be an EXE, DLL, shellcode, or another artifact. After a successful build, the worm can optionally be added to the Draconus library. See build --help for available options.
• scan
  Scans the local library for newly added modules and updates the internal module database. The module database is automatically refreshed only on the first entry into Hive. After that, this command must be used manually whenever new modules are added.

Build Examples

1) Building a Windows x64 Shellcode

To generate shellcode, you must start with a dedicated worm template designed for shellcode builds. First, list all available main worm templates:

show worm

Find the shellcode worm template named WShellcode, then add it as the main template:

add worm WShellcode

Draconus will display a confirmation message and automatically assign the correct compiler/build pipeline for shellcode generation.

Next, list available shellcode templates (scode):

show scode

Add a test shellcode that spawns a classic “Hello World” message box:

add scode MsgBoxA

At this point, the worm template is ready. Build it using:

build

After a short moment, the generated shellcode will appear in OUTPUT/Hive, exported in several popular formats for easy integration into other projects.

2) Building a Custom Python Worm Using Modules

This example demonstrates how to build a Python-based worm that does not provide functionality on its own. Instead, all behavior is defined by added modules and additional components. This approach is well suited for Python, as the prepared template can later be compiled into an EXE or saved into the Draconus library for reuse in other projects (for example, embedding it into custom shellcode or combining it with other payloads).

First, add the worm template designed for Python-based worms:

add worm Montezuma

Next, display the list of available modules:

show module

Using the Tags associated with each module (their descriptions are always shown when running the worm command), locate modules implemented in Python and add them to the template.

Add a module that scans directories for files matching specific extensions and name patterns:

add module PyAnts

Now add a module responsible for sending collected files to a Discord server:

add module PyDcWeb

With the modules added, inspect the current build state:

worm

This command displays the complete configuration of the worm, including all active modules and variables. Use the var command to configure required settings such as the Discord webhook URL, file extensions to search for, naming patterns, and other module-specific options. You can repeatedly run worm to verify updated variable values.

Once the template is fully configured, compile the worm using:

build

After compilation completes, the resulting executable will be available in the OUTPUT/Hive directory.

Saving the Worm as a Reusable Payload

If you do not want to compile the script immediately and instead wish to add it to your personal library for later reuse, use the following command:

build --no_compile --payload "My first payload"

This will save the prepared template into the payload section of the Draconus library. From that point on, it can be reused like any other payload and embedded into future worms, shellcode projects, or executable builds.

Tips & Tricks

Below are a few practical tips that may help you avoid common issues and better understand how to work with Draconus.

Draconus reports that it is already running

If Draconus reports that it is already running, but you are certain that it is not, this usually means the program was not closed properly.

To fix this, navigate to the following directory:

app/_sys_files

Remove all files inside this directory, then start Draconus again. These files are used internally to track runtime state and may remain after an improper shutdown.

Build Incrementally

Remember that Draconus is designed to support incremental and modular building. You do not need to create everything in a single step.

A common workflow might look like this:

• Create a custom Python script using a dedicated worm template
• Save it as a reusable payload
• Create a new shellcode-based worm and embed your payload
• Save the shellcode as another payload
• Create an injector and attach the previously created payload

This layered approach allows you to mix, reuse, and recombine components in many different ways, building increasingly complex setups from simple elements.

Nuitka Compilation Takes Time

When using the Nuitka compiler, compilation times can be significantly longer than expected. During this process, it may appear as if Draconus has frozen or stopped responding.

In most cases, this is normal behavior. Be patient and allow the compilation process to complete.

Module List:

Below is a list of selected modules (tools) available in the current version of Draconus. Not all module types are presented here. For a complete and up-to-date overview, refer to the Hive section inside the program.

Module list for version 2.2:

Join the Project

Draconus is a hobby-driven project developed in spare time and focused on learning, experimentation, and responsible research in offensive security. The project is open to collaboration and welcomes contributions from people interested in malware analysis, shellcoding, reverse engineering, and tool development.

If you would like to contribute, you can help by creating:

• Reverse shells written in various languages (for testing and educational purposes)
• New Hive modules or payloads
• Shellcode templates
• Support tools for analysis, obfuscation, or automation
• Documentation improvements or usage examples

Contributions do not need to be large or complex. Even small, focused tools or experimental ideas are welcome if they help explore techniques or improve the learning value of the project.

As the community grows, contributors will be listed here along with links to their profiles or repositories.

If you are interested in contributing, feel free to reach out or submit your ideas. Collaboration, experimentation, and knowledge sharing are core goals of Draconus.

Changelog

Version 2.0

This release marks the beginning of a new version of the Draconus project. At this stage, the focus is not on the number of available tools, but on rebuilding the entire system architecture, improving stability, and validating the new build and compilation pipelines.

Version 2.0 introduces a redesigned internal structure and scripting system, with significant effort spent on testing, automation, and compiler workflows.

Included in this version:

• 4 shellcode generators
• 2 injectors based on the new version of the DuckTales library, which dynamically resolves and imports WinAPI functions
• 2 Python payloads, including reverse shell implementations
• Several Python modules, such as TCP socket communication, Discord webhook integration, and ransomware logic
• Support for compiling custom Python code
• Ability to add and manage custom payloads within the Draconus library

The current development focus will shift toward expanding the available toolset, adding new payloads, modules, and experimental components.

If you are interested in contributing or extending the project, feel free to join and add your own tools, ideas, or experiments.

Version 2.01

This update focuses on expanding language support, improving internal stability, and cleaning up the codebase.

Changes and Improvements:

• Added full C language support along with an integrated C compiler toolchain
• Replaced the Montezuma worm template with Tetris, a newer and more stable implementation
• Improved all Python modules to ensure better interoperability and internal consistency
• Added a new section in the README showcasing the current list of available modules
• Fixed multiple minor bugs and removed obsolete or redundant code

Version 2.1

This release focuses heavily on stability, performance improvements, and expanding the worm-building system.

Fixes & Improvements:

• Resolved multiple issues occurring during worm creation, including:
• Obfuscation method problems within the DuckTales library
• Errors during linking of libraries and modules
• Improved compilation speed, especially in cases requiring multiple library builds
• Expanded the worm-building system with additional configuration combinations
• Fixed encoding issues affecting incoming messages on server listeners
• General cleanup and numerous minor bug fixes

New Additions:

• DarkWingDuck – DLL Injector. Accepts a DLL module, converts it into a COFF (BIN) object, embeds it internally, and upon execution extracts the DLL and searches for a specified target process to inject into.
• PongDll – DLL module. Upon loading, attempts to connect to a host via TCP socket and launches a specified program. Functions as a reverse shell with selectable execution target.

As always, many small bugs were fixed — and likely a few new ones were born in the process.

Version 2.2

This release introduces major changes to storage handling, expands low-level capabilities, and improves flexibility of the build environment.

Changes & Improvements:

• Redesigned worm storage system. The Hive workspace is now created inside the user's home directory (customizable via CONFIG.ini), while the original project directory contains a symbolic link. This allows updating Draconus without reinstalling Docker images or losing existing data.
• Added support for installing additional Python libraries inside the compiler environment. A new file Python_Library is available in OUTPUT/Links, where custom PIP dependencies can be listed. Running the update command in the Hive section installs these libraries for both PyInstaller and Nuitka.
• Improved overall stability and fixed numerous minor issues across the system.

New Additions:

• Chip and Dale – New low-level library used by worms and modules. Locates kernel32 and ntdll in memory and manually resolves function addresses by parsing export tables (without using GetProcAddress). Function names are stored in an encrypted form. Designed primarily for working with NT functions from ntdll.
• River Raid – Shellcode injector worm. Uses NT functions via the Chip and Dale library. Supports multiple target processes and continuously waits until one of them appears, then injects shellcode into it. Static and dynamic analysis (e.g., sandbox environments) does not flag it as malicious during testing.

As always, many bugs were fixed — and, naturally, a few new ones probably joined the party.

Version 2.21

This update focuses on shellcode flexibility, polymorphism, and expanding payload capabilities.

Changes & Improvements:

• Added support for importing custom shellcode into the payload section. A new file MyShellcode is available in OUTPUT/Links, where users can place their own shellcode and use it directly within Draconus.
• Extensive testing performed across multiple components, resulting in numerous bug fixes and overall stability improvements.

New Modules & Templates:

• Archon – shadow module Introduces polymorphism to shellcode by encoding it with an XOR key, altering its appearance without changing functionality. Increases shellcode size by approximately 50–60 bytes. Can be used to obfuscate shellcode generated within Draconus.
• Morpheus – worm template Applies polymorphism to already existing shellcode. Allows importing custom shellcode and transforming it using XOR-based encryption. The shellcode self-decrypts at runtime and executes normally. Increases size by approximately 50–60 bytes.
• PyRevTcp – payload module Lightweight TCP reverse shell written in Python. One of the most common and minimal implementations. Designed for Windows environments.
• PyRevTcp2 – payload module An extended and more advanced version of the original Python reverse shell. Larger in size, but offers improved functionality and flexibility.

A lot of bugs were eliminated during testing… and, as tradition dictates, a few new ones were probably introduced along the way.

Version 2.3

This update introduces a new encrypted TCP server type, new DLL injection templates, and a new DLL-based module designed to work with the Robbo TCP protocol.

Changes & Improvements:

• Added a new server type: Robbo TCP – rtcp. This server uses TCP sockets with XOR-encrypted communication. It supports sending commands, uploading files, and downloading files.
• Improved stability across multiple components and fixed several bugs discovered during testing.

New Worms & Templates:

• Zybex – DLL injector written in C Uses NT functions that are dynamically resolved through the ChipAndDale library. The DLL is embedded inside the injector itself. Zybex allows selecting multiple target processes by name. After execution, it extracts the DLL and searches for the specified process before performing the injection.
• DropZone – DLL injector written in C Uses NT functions and allows defining multiple process targets. Includes additional options such as executing a function from the injected DLL, using time delays, and passing arguments. During testing, Windows 10 Defender did not flag it as a malicious file.

New Modules:

• DrMario – DLL module A lightweight mini-RAT style module that communicates through the Robbo TCP protocol, making it designed specifically for the rtcp server. DrMario provides three launch options, including execution through DllMain and execution through exported functions. More information is available in the Draconus help menu.
  
  The module supports directory navigation, listing files and processes, uploading and downloading files, injecting additional RevTcp payloads into processes, injecting DLLs into processes, and several other experimental features from the darker corners of the toolbox.

Several bugs were fixed during development and testing… and, as always, a few fresh ones probably moved in to keep the old ones company.