Exegol: professional hacking setup

Exegol is a community-driven hacking environment, powerful and yet simple enough to be used by anyone in day to day engagements. Exegol is the best solution to deploy powerful hacking environments securely, easily, professionally. No more unstable, not-so-security-focused systems lacking major offensive tools. Kali Linux (and similar alternatives) are great toolboxes for learners, students and junior pentesters. But professionals have different needs, and their context require a whole new design.

Exegol fits pentesters, CTF players, bug bounty hunters, researchers, beginners and advanced users, defenders, from stylish macOS users and corporate Windows pros to UNIX-like power users.

Warning

This documentation is a work in progress. We are actively writing it, but if there are things you’d like to be documented in priority, feel free to request in on the GitHub Repo or in the Discord server.

The Exegol project

Exegol is many things in one. Try it, and you’ll stop using your old, unstable and risky environment, no more monolithic system that gets messier, buggier and more at risk with time.

• Python wrapper: makes everyone’s life easier. This entrypoint to the whole Exegol project handles all docker and git operations so you don’t have to. Now’s the time to have a clean environment with one Docker container per engagement without the effort. Exegol handles multiple images and multiple containers. GUI apps, Wi-Fi, USB accessories, volume mounting and many more features are supported and easier to use than ever.

• Docker images: a set of pre-built docker images and dockerfiles that include a neat choice of tools, zsh plugins for power users, pre-filled history ready to use with environment variables, awesome resources, custom configs and many more. Images can either be built locally or pulled from the official Dockerhub registry.

• Offline resources: Tired of always having to search github for your favorite privesc enumeration script? Exegol includes a set of resources, shared with all exegol containers and your host, including LinPEAS, WinPEAS, LinEnum, PrivescCheck, SysinternalsSuite, mimikatz, Rubeus, PowerSploit and many more.

Getting started

Wanna try Exegol and join our great community? You need to install requirements first, then proceed to the OS-specific instructions: Linux | macOS | Windows

Community

Have a bug report or feature request? Either open an issue on the Exegol repo or open a ticket on the Exegol discord (preferred, easier, more flexible).

Wanna chat? Need help? Join us on the Exegol discord!

Install Exegol

Installing Exegol starts with installing the entrypoint to the whole project: the Python wrapper. Once the wrapper is installed, everything else can be managed from it.

Hint

It is strongly advised to install Exegol on a Linux host, especially when planning on using Exegol for internal penetration tests. This is because Docker Desktop on Windows and macOS lacks a few features, mainly due to how these operating systems run Docker containers within an internal VM that doesn’t share the host’s network interfaces and USB accessories.

Once the wrapper is installed, the second step in setting up Exegol on a device is to install at least one Exegol image, either with exegol start (documentation here), or with exegol install (documentation here). Both actions will guide the user in installing an image if needed.

Requirements

The following elements are required before Exegol can be installed, whatever the host’s operating system is:

• git (Linux | macOS | Windows)

• python3 (Linux | macOS | Windows)

• docker (Linux) or Docker Desktop (macOS | Windows)

• at least 100GB of free storage recommended (a minimum of 20GB could be enough, but only for the light image).

Additional dependencies may be required depending on the host OS.

LinuxmacOSWindows

No additional dependencies for Linux environments.

Tip

From Linux systems, Docker can be installed quickly and easily with the following command-line:

curl -fsSL "https://get.docker.com/" -o get-docker.sh
sh get-docker.sh

Warning

By default, sudo will be required when running docker, hence needed as well for Exegol. For security reasons, it should stay that way, but it’s possible to change that. In order to run exegol from the user environment without sudo, the user must have the appropriate rights. You can use the following command to grant them to the current user:

# add the sudo group to the user
sudo usermod -aG docker $(id -u -n)

# "reload" the user groups with the newly added docker group
newgrp docker

For more information, official Docker documentation shows how to manage docker as a non root user.

Warning

Docker “Rootless mode” is not supported by Exegol as of yet. Please follow the install procedure mentionned above.

Installation

The installation of Exegol on Linux, macOS and Windows are very similar. It can either be installed from pip (easiest, most user-friendly, but with a few missing features) or from sources (easy as well, fully featured).

1. Installation of exegol

Installing with pipInstalling from sourcesInstalling with pipx

Exegol’s wrapper can be installed from pip. While this is the easiest and most user-friendly technique, for more advanced users it is advised to install from sources, as it allows to switch from release to dev branches easily and the auto-update feature is supported.

python3 -m pip install exegol

Warning

You may want to disable Windows Defender during the installation, as Exegol will download pre-built remote shells (or temporarily exclude C:\Users\<username>\AppData\Local\Temp).

You should also add the folder C:\Users\<user>\.exegol\exegol-resources to the exclution list.

2. Adding Exegol to the PATH

Installing with pipInstalling from sources

If your pip installation is correct and functional, you have nothing more to do and you can already use the command exegol.

If not, remember that pip installs binaries in a dedicated local folder, which then must be in the PATH environment variable. Try to fix your pip installation: Linux | MacOS | Windows

3. (Optional) Using Exegol auto-completion

Exegol (wrapper) supports auto-completion in many shell environments but there is a configuration to add (on the host) for this feature to work.

Tip

If you have a source installation, make sure you have installed (or updated) the requirements.txt packages before using the completer.

Important

The following configurations must be made in your host environment.

BashZshFishTcshPowerShell

You can enable Exegol auto-completion for your current user with your .bashrc or you can enable the auto-completion system-wide with bash-completion.

Via bash-completionVia .bashrc

To setup the auto-completion system-wide you first need to install bash-completion on your system (if not already installed).

sudo apt update && sudo apt install bash-completion

At this point you should have a /etc/bash_completion.d/ folder. It’s in there that you can add any auto-completion module that you want.

To generate and install the exegol completion configuration you can execute the following command with register-python-argcomplete:

register-python-argcomplete --no-defaults exegol | sudo tee /etc/bash_completion.d/exegol > /dev/null

Tip

If you have multiple tools using argcomplete you can also use the global completion method (need bash >= 4.2).

4. Installation of the first Exegol image

Once the exegol wrapper is installed, you can download your first docker image with the following command:

exegol install

Updates

The whole Exegol can be updated through its own wrapper with exegol update (documentation here).

Hint

Wrappers installed with pip don’t support auto-update. The wrapper itself can then can be updated as follows.

python3 -m pip install --upgrade exegol

Frequently asked questions

Below are the frequently asked questions regarding either features, the overall project or troubleshooting matters.

What tools are installed in Exegol?

The list of tools is dynamically generated for all Exegol images and available here.

Unable to connect to Docker

There are multiple checks to do to make sure Docker works properly.

Docker serviceDocker permissionsDocker socketSymbolic link

The Docker service must installed up and running.

• For Windows users: Docker Desktop for Windows must be up and running.

• For macOS users: Docker Desktop for Mac (or OrbStack) must be up and running.

Can I contribute to the project?

Yes, please refer to the contributors section.

Can I run Exegol on a macOS?

Yes. And both CPU architectures are supported (Intel X86_64 (AMD64) and Apple Silicon M1/M2 (ARM64).

Tip

We strongly advised macOS users to replace Docker Desktop with OrbStack, allowing host network mode to work for instance, this it’s not supported by Docker Desktop for Mac.

Can I use a VPN with Exegol?

Yes. And you have multiple choices.

• The “YOLO” choice: at the container creation (i.e. when “starting” a container for the first time), give all permissions to the container so that you’re able to run openvpn in it and start the vpn. The command should look like exegol start <container_name> <image_name> --privileged.

• The better choice: use the --vpn option at the container creation: exegol start <container_name> <image_name> --vpn <myconf.ovpn>. It’s the easiest and more secure choice. See the start help here).

Warning

Creating a privileged container (c.f. the “YOLO” choice) exposes you to higher security risks. This should be avoided.

Can I customize Exegol?

Yes, please refer to the “my-resources” documentation that explains how to automatically setup your changes to your Exegol containers. Also, see the “wrapper’s advanced-uses” documentation to see how to edit Exegol’s conf among other things. You could also want to make your own Exegol image

Can I make my own Exegol image?

Yes. You will need to create a dockerfile (e.g. CUSTOM.dockerfile) at the root of the exegol-images module next to the other dockerfiles (i.e. /path/to/Exegol/exegol-docker-build/) containing the instructions you want the build process to follow.

Then, run something like exegol install "myimagename" "CUSTOM" to build the image locally. See the install documentation: install action.

How to install Exegol on an external drive?

Exegol’s wrapper is lightweight, but it’s Docker images can take up some space, and users may not have enough room in their internal HDD/SSD, hence the question. This usually comes down to “how can I install Docker on an external drive?”, and the answer depends on the host.

Tip

Use a fast drive, otherwise Exegol will get real slow.

For macOS and Windows users, this can be configured in the Docker Desktop dashboard (in Settings > Resources > Advanced > Disk image location).

How to add a new tool?

“Adding a tool” can mean many things. Depending on that, you’ll get a different answer. So let’s answer most of them.

If you want to add a tool:

• in the official Exegol images: refer to the contribution guidance.

• in your own custom local image: refer to the contribution guidance as well, but instead of creating a Pull Request at the end to offer your contribution, just build the image locally with the wrapper and enjoy your custom local image.

• in a live container: that’s your container, you can do whatever you whish in it ;)

• automatically in all containers at their creation: refer to the “my-resources” documentation.

How do I get X11 to work on a non-Linux host?

X11, or X Window System, is a graphical windowing system that provides a framework for creating and managing graphical user interfaces (GUIs) in Unix-like operating systems.

X11 sharing between an Exegol container and a host allows a graphical application running within the container to display its GUI on the host’s X11 server. This means you can run graphical applications in Exegol containers and have them appear as if they were running directly on the host machine. It enables the execution of GUI-based applications in isolated containers while interacting with them through the host’s graphical interface.

For macOS users, XQuartz is needed. It’s listed in the install requirements.

Note

Exegol’s wrapper automatically starts XQuartz on macOS hosts when needed. But if for some reason it gets manually closed by the users while a container is running, X11 sharing will not work. Restarting the container with exegol restart <container> will restart XQuartz automatically if needed.

Can I install docker directly on my WSL2 distro instead of Docker Desktop ?

Yes, it’s possible to install docker directly on WSL2 rather than using Docker Desktop, but you’ll be restricted to your WSL2 environment and its constraints.

Although Docker Desktop is incomplete, it does offer a few advantages (exegol can be used from powershell / cmd, windows folder sharing with the exegol workstation, etc). We therefore recommend Docker Desktop as the official support for Exegol.

We do not guarantee wrapper stability with a directly installed WSL docker.

Tips & tricks

Below are some of the tips and tricks that are good to keep in mind when using Exegol.

Change a container’s time

Changing a container’s time with date requires elevated permissions on the container, and messes up with the host’s time. There is however and alternative, using faketime (see faketime ubuntu manpage) that allows to change the time of the container easily, without needing particular permissions, without affecting the host. This is especially useful when working with Kerberos targets that are out of sync.

Faketime manipulates the system time for a given child command. For example with zsh, a new shell is opened with a spoofed time that will only be spoofed for this extact shell session and commands executed in it.

faketime 'YYYY-MM-DD hh:mm:ss' zsh

Note

Here is an example of how faketime can be used.

When doing Active Directory attacks against Kerberos targets, a clock skew error could be raised such as KRB_AP_ERR_SKEW. This means the authenticating machine (operator) and the destination (Key Distribution Center, a.k.a. KDC) are not in sync, clock-wise.

Running any Impacket with the -debug flag will print the server time. The operator can then use faketime to open a new zsh shell with the right time and timezone and conduct the scenario as previously intended.

The following command can be used to print the time in UTC format and compare it with the server time: date --utc.

Note: careful with the timezones. If they differ between the operator and the KDC, the delta needs to be taken into account

Share files or notes with targets and collaborators

The following tools or commands can be used to pop a temporary file or http server: updog, goshs, http-server, http-put-server, ftp-server, smbserver.py. In order to shares notes during an engagement, trilium (https://github.com/zadam/trilium) can be used.

Dynamic history commands

Many commands in the pre-filled history rely on environment variables such as $DOMAIN, $USER, $PASSWORD, etc. Those variables can be set manually or by using the profile.sh file in /opt/tools/Exegol-history/. The proper lines can be filled and uncommented, and then the shell can be reloaded with exec zsh in order to apply the changes. This allows users to easily look for, and use, commands in the history, without changing the values every time.

The best reverse shells

• shellerator can be used to generate a reverse shell command dynmically

• on the attacker’s side, a reverse shell obtained through a netcat tunnel can be improved (see ropnop.com or 0xffsec.com)

• simple alternative way to have an upgrade netcat reverse shell: use rlwrap <netcat listener command>

• instead of using netcat and “upgrade” the shell manually, pwncat-cs (calebstewart/pwncat) can be used to obtain an even better reverse shell experience (especially with UNIX-like targets).

Keyboard shortcuts

• ctrl+q: when writing a command, let’s say a user misses an information (e.g. IP address). The shortcut can be used to save the half-typed command, look for the value, and then finish the command. The user doesn’t have to cancel the command, look for the info, and write the command all over again. This is known as the push-line feature (see sgeb.io).

• ctrl + r: look for something in the history

• ctrl + t: look for a file or directory with a fuzzy finder

• ctrl + a: move to the beginning of the line

• ctrl + e: move to the end of the line

• ctrl + ←: move one word backward

• ctrl + →: move one word forward

• ctrl + l: clear the screen

Python Wrapper

The Exegol project regroups many things (docker images, offline resources, custom configurations, aliases, history commands, multi-architecture support and many others). In order to make all the tech involved easy to use, and provide some unique entrypoint to the whole setup, a Python wrapper was created.

The Python wrapper handles all Docker and Git operations, can manage multiple images and containers at once and give the user the best experience possible, suited for beginners as well as advanced people.

The wrapper knows multiple actions.

• Install an image : exegol install

• Create/start/enter a container : exegol start

• Show info on containers and images : exegol info

• Stop a container : exegol stop

• Remove a container : exegol remove

• Uninstall an image : exegol uninstall

• Get help and advanced usage : exegol --help

• Help and examples can be obtained for each action directly from the wrapper with the following command: exegol <action> -h (action: install/start/stop/etc.).

All actions are documented in the exegol-wrapper part of this doc (e.g. info, start, version, …)

Below is a, non-exhaustive, list of what the wrapper supports:

Note

Exegol uses Docker images and containers. Understanding the difference is essential to understand Exegol.

• image: think of it as an immutable template. They cannot be executed as-is and serve as input for containers. It’s not possible to open a shell in an image.

• container: a container rests upon an image. A container is created for a certain image at a certain time. It’s possible to open a shell in a container. Careful though, once a container is created, updating the image it was created upon won’t have any impact on the container. In order to enjoy the new things, a new container must be created upon that updated image.

Features

The Exegol wrapper has many features to automatically and transparently manage different configurations to facilitate the use and creation of docker containers.

X11 sharing (GUI)

By default exegol configures the new container and host to allow the execution to the display of graphical window launched from an exegol container. This is achieved through X11 sharing.

For example, if bloodhound is launched in an exegol container, the graphical window (GUI) will be displayed in the user’s graphic environment.

This feature can be disabled manually with the option --disable-X11 of the start action.

Desktop

On some systems, it may be difficult to have or share an X11 environment. Some users prefer to have a full graphical desktop environment rather than just graphical applications.

To meet this need, Exegol is able to host a complete graphical environment within its container since version 4.3.0 of the wrapper and 3.1.2 of the images.

This environment can then be made available to others in a variety of ways. The default protocol is currently HTTP, but the user can change the configuration to use the VNC alternative.

This feature can be enabled manually with the option --desktop of the start action.

Tip

The default behavior and configuration of the desktop mode can be changed in the configuration of Exegol.

Workspace

Exegol always creates within a container a persistent workspace (even after deleting the container) and shared with the host.

By default a folder will be created on the host and shared with the container. This folder will be created in ~/.exegol/workspaces/ with the name of the exegol container.

Tip

The default location of workspace volumes can be changed in the configuration of Exegol.

The user can also create an Exegol container with an existing custom workspace folder (with already existing data) regardless of its location in the file system.

See the options -w WORKSPACE_PATH and -cwd of the start action for more details.

Update-fs

The root user is used by default in Exegol containers which poses problems of permissions when accessing the project documents from the host. To remedy this without compromising, a shared permission system exists allowing the host user to have read and write access to files created from the container.

This system is automatically activated when a new default workspace is created.

Warning

When the user uses an existing custom folder as workspace, this system is disabled by default! This feature can be enabled by default by changing the configuration of Exegol.

Its activation is possible manually (see the option --update-fs of the start action) but it will lead to the modification of the folder and its sub-folders permissions (as g+rws).

If the user does not have the rights to perform such an operation, a sudo command will be proposed to the user that he will have to execute manually to apply the necessary permissions for the proper functioning of the functionality (as chgrp + g+rws).

Tip

When the default configuration of this feature is changed and the update will be enabled by default, the option --update-fs can still be used to manually disable the feature in specific cases.

OpenVPN connection

Exegol supports OpenVPN tunnel configuration to automatically establish a VPN tunnel at container startup.

Exegol supports certificate authentication (all files should preferably be included in a single ovpn file) but also user/password authentication through an authentication file (to allow non-interactive and transparent authentication).

Tip

A folder can also be used in the case of a multi-file configuration (with relative paths!) and the configuration file must have the .ovpn extension (Only one .ovpn file will be loaded by exegol).

See the options --vpn VPN and --vpn-auth VPN_AUTH of the start action for more details.

Tip

In case of problem, to troubleshoot a VPN connection, the log of OpenVPN can be retrieved within the container in the /var/log/exegol/vpn.log file

Shell logging

Within the framework of a mission, it is necessary to log all actions performed during a pentest, red team etc. To meet this need, Exegol has a feature to automatically record everything that is displayed (stdout / stderr) but also all entries (stdin).

See the option --log of the start action to enable the feature.

Hint

When the option is enabled upon creation of a new container, all shells created for this container will be automatically logged.

If the container was created without this option, the shells can still be logged individually by adding the option in the start command of each shell.

The date and time of each command is displayed thanks to the PS1 of zsh.

The logs are automatically saved in the /workspace/logs folder. Each log file is automatically compressed with gzip at the end of the session to optimize disk space. The automatic compression of log files can be disabled manually with the start action --log-compress parameter or change the default behavior in the Exegol configuration file.

Hint

When the default configuration of the log compression is changed from the config file and the feature will be disabled by default, the option --log-compress can still be used to manually enable the feature in specific cases.

Warning

The logs should NOT be consulted from the exegol container but from the host to avoid loops and duplication of data in the logs.

There are (since exegol images version 3.0.0) different methods of shell logging. The shell logging method can be selected manually with the start action --log-method parameter or by default in the configuration file of Exegol.

asciinema (default)script

The shell logging method asciinema is available from exegol images version 3.0.0. This new mode allows to consult sessions in video format taking into account the interactive environment. It is also possible to manually upload and share recordings, useful for demonstrations for example

Here is a quick demonstration:

Tip

Logs in .gz format can be replay directly without unpacking them with the command: gunzip -c <filename_shell.asciinema.gz> | asciinema play -

Hint

To display the whole session without the “video” mode, it is possible to use the command: asciinema cat <filename_shell.asciinema>

Warning

Major disadvantage of this method, to view the logs from your host, you must install asciinema on your host machine to replay or share your records.

Tip

When you share or play an asciinema video, you can copy and paste any command/text it contains.

Shared network

By default, containers created by Exegol are in host mode which means that the network interfaces of the host are shared with the container.

This configuration is useful to:

• dynamically open ports and services

• have a low level access on a physical network (some operation might need privileged mode)

• share a unique ip address on the target network

• share a MAC address on the target network (to be considered as a single physical machine)

This mode can be disabled with the option --disable-shared-network of the start action to create a dedicated and isolated network instead.

Tip

When host network sharing is disabled, ports can be to expose services on the host machine’s networks.

Warning

This mode is only available on Linux installations! Windows and MacOS installations are subject to the constraints and limitations of Docker Desktop .

You can still use the port publishing feature instead.

Shared timezones

For convenience and precision in the date and time of the logs of each command, exegol allows to share the timezone of the host in the container.

This feature is active by default and can be disabled with the option --disable-shared-timezones of the start action.

Exegol-resources

To save time and have at hand many tools, scripts and other resources, exegol maintains a repository exegol-resources contains many updated tools that are available to the host and exegol containers.

This module is not mandatory and can be downloaded later.

Hint

If an antivirus is present on your host, be careful to exclude the destination folder of the exegol-resources module before downloading it.

This feature is active and shared by default and can be disabled with the option --disable-exegol-resources of the start action.

My-resources

The my-resources feature is a space dedicated to the user and shared with all the containers. This space allows to store configurations and to install personal tools.

More details on the functionality of the wrapper here and how to take advantage of the customization system here.

Volume sharing

For specific needs, the exegol wrapper allows to add additional custom volumes (type bind mounts) when creating an exegol container.

See the option --volume VOLUMES of the action start for more details.

Port sharing

When the host network is not shared, it is still possible to publish specific ports to expose services or port ranges.

Hint

This configuration is compatible even with installations based on Docker Desktop.

This feature allows the user to select:

• a specific network interface (for example 127.0.0.1) or by default all interfaces (0.0.0.0).

• the port to open on the host interface.

• the destination port to be linked in the container.

• the protocol to use, docker supports TCP, UDP and SCTP protocols (default is TCP).

See the option --port PORTS of the start action for more details.

Env. variables

Exegol can configure custom environment variables defined by the user.

When the environment variables are defined at the first time of the container creation, these variables will be:

• accessible in the container by all processes

• present during the whole lifetime of the container

The environment variables can be defined when opening a shell in an existing container and will be available only in the user’s shell until it is closed.

See the option --env ENVS of the start action for more details.

Device sharing

For the needs of some applications running on physical hardware (such as proxmark3), exegol can supply the container with one or more physical devices.

See the option --device DEVICES of the start action for more details.

Warning

This feature is only available on Linux installations!

Windows and MacOS installations are subject to the constraints and limitations of Docker Desktop.

Custom hostname

In some environments with OPSEC requirements, it may be necessary to change the hostname of your exegol container.

See the option --hostname HOSTNAME of the start action for more details.

Comments

To add more context information about an exegol container, it is possible to add comments to each Exegol container. The comment of an exegol container can be displayed with the command exegol info <container_name>

See the option --comment COMMENT of the start action for more details.

Capabilities

Exegol supports adding Linux capabilities to the Exegol container to perform tasks that require administrative rights without allowing everything.

This feature gives control to the user to configure his container but giving administrator rights remains a dangerous practice and should be used by experienced users only.

For more details on the capabilities supported by docker check here.

Warning

Not all Linux capabilities are allowed by the Exegol wrapper, here is the list of available capabilities:

NET_ADMIN, NET_BROADCAST, SYS_MODULE, SYS_PTRACE, SYS_RAWIO, SYS_ADMIN, LINUX_IMMUTABLE, MAC_ADMIN, SYSLOG

For all other needs, consider the privileged mode.

Privileged

For particular needs, it is sometimes necessary to have privileged rights to perform certain actions. If Exegol does not allow you to have specifically the rights necessary, you can configure your container in privileged mode to get full administrator rights.

Warning

This configuration is particularly dangerous because it gives the container full admin control over the kernel of the host machine.

Use this option only if you know exactly what you are doing!!

If the need is specifically identified, consider adding capabilities instead!

See the option --privileged of the start action for more details.

Multi-architecture

Exegol supports ARM64 architecture (in addition to the classic AMD64) since version 4.1.0 of the wrapper and 3.0.0 of the images.

This support allows you to fully use exegol on hardware equipped with an ARM processor (such as Mac M1 / M2 but also some Raspberry Pi).

Warning

Exegol only supports 64-bit ARM architecture! If your ARM processor supports 64-bit, make sure your OS is also installed in 64-bit version to use exegol!

Tip

For experienced users or developers, it is possible to explicitly modify the architecture used by the Exegol wrapper with the general option --arch ARCH.

But be careful, the modification of this parameter can lead to malfunctions!

Local image building

The wrapper allows users to locally build their images from the exegol-images sources.

More information in the advanced uses section.

Remote image pulling

To save time, pre-built images are available for download from DockerHub. These images can be downloaded and installed / updated from the exegol wrapper with the install and update actions.

Command execution

The Exegol wrapper does not only allow the opening of interactive shells, it is also possible to execute single commands in several ways.

Tip

To see the execution logs of the command, the user must add the parameter -v.

The details of this functionality are detailed in the exec action.

Daemon execution

One of the execution modes can be in the background like a daemon service. In this way the wrapper executes the user’s command, for example an application such as bloodhound. The wrapper launches the task in an exegol container and finishes immediately without occupying the user’s terminal, leaving the application open.

See the option --background of the exec action for more details.

Temporary containers

Another feature of the exec action is the execution in a temporary container.

In this mode, a temporary container will be created and dedicated to the execution of the command specified by the user.

This mode can be useful to run a given command with the most up-to-date image already installed on the host, for any test or for special privacy needs.

See the option --tmp of the exec action for more details.

Docker images

The Docker images are the heart of the Exegol project. A neat choice of tools, configurations, aliases, history commands, and various customizations are prepared in multiple images adapted for multiple uses: web hacking, Active Directory, OSINT (Open Source INTelligence), etc.

All images are available on the official Dockerhub registry. This allows to offer pre-built, compressed images, so that users don’t have to build their own image, but users that choose to do so can. Pulling pre-built images, or building one, can be done with exegol install (documentation here).

Image name	Description
full	Includes all the tools supported by Exegol (warning: this is the heaviest image)
ad	Includes tools for Active Directory / internal pentesting only.
web	Includes tools for Web pentesting only.
light	Includes the lightest and most used tools for various purposes.
osint	Includes tools for OSINT.
nightly	(for developers and advanced users) contains the latest updates. This image can be unstable!

Note

Exegol uses Docker images and containers. Understanding the difference is essential to understand Exegol.

• image: think of it as an immutable template. They cannot be executed as-is and serve as input for containers. It’s not possible to open a shell in an image.

• container: a container rests upon an image. A container is created for a certain image at a certain time. It’s possible to open a shell in a container. Careful though, once a container is created, updating the image it was created upon won’t have any impact on the container. In order to enjoy the new things, a new container must be created upon that updated image.

Offline resources

Exegol’s “offline resources” are a neat choice of standalone tools and scripts that are often used during penetration tests, CTFs and red-teams, like LinPEAS, WinPEAS, LinEnum, PrivescCheck, SysinternalsSuite, mimikatz, Rubeus, PowerSploit and many more. Exegol users don’t have to download those resources again every time they’re needed anymore. Everything is managed by the wrapper and they are shared with every container (at /opt/resources).

install action

This action can be used to install an Exegol image. At least one Exegol image is required to create and start a container and enjoy Exegol.

When this action is used, the image can either be:

• downloaded (i.e. “pulled” in Docker terms) from the official Dockerhub registry. In this case, a compressed and pre-built image is downloaded in the form of layers, and then uncompressed.

• built locally by following the instructions of a Dockerfile offered on the Exegol-images GitHub repo. Here again, no need to download the dockerfile manually, all of them are already at /path/to/Exegol/exegol-docker-build/.

Hint

The install action can be used without any particular argument or option. the wrapper will then enter in an interactive TUI (Text-based User Interface) mode where the user will be asked to choose what image to install or build.

exegol install

Options

Option	Description
IMAGE	Optional positional argument to indicate the image to install (if downloading), or the name of the image to build (if building locally).
BUILD_PROFILE	Optional positional argument to indicate the source profile to use if building locally.
--build-log	Write logs to the path specified if building locally.
--build-path	Custom path to the dockerfiles and sources.

Command examples

#Install or build interactively an exegol image
exegol install

#Install or update the full image
exegol install full

#Build interactively a local image named myimage
exegol install myimage

#Build the myimage image based on the full profile and log the operation
exegol install myimage full --build-log "/tmp/build.log"

start action

This action can be used to start a container. At least one Exegol image is required to create and start a container and enjoy Exegol. Installing an image can be done with exegol install (documentation here).

When this action is used, the following process is applied:

• if no Exegol image is installed, the user is asked to specify which one to install of build, and the process continues

• then, if the container to start doesn’t already exist, it is created based on an Exegol image and a few settings to specify, and the process continues

• then, the container is started and a shell is opened

Hint

The start action can be used without any additional argument or option. the wrapper will then enter in an interactive TUI (Text-based User Interface) mode where the user will be asked to choose a few settings.

exegol start

Options

A single option exist to target an Exegol container. If this container exists, it will be started if it is not already the case and a shell will be spawned to offer an interactive console to the user

Option	Description
CONTAINER	Tag used to target an Exegol container

Many options exist to customize the creation of exegol container.

Tip

The default options of some commands can be changed in the exegol configuration file.

Global options

Option	Description
IMAGE	Tag of the exegol image to use to create a new exegol container
-w WORKSPACE_PATH, --workspace WORKSPACE_PATH	The specified host folder will be linked to the /workspace folder in the container.
-cwd, --cwd-mount	This option is a shortcut to set the /workspace folder to the user’s current working directory (pwd).
-fs, --update-fs	Modifies the permissions of folders and sub-folders shared in your workspace to access the files created within the container using your host user account. (default: Disabled)
-V VOLUMES, --volume VOLUMES	Share a new volume between host and exegol (format: –volume /path/on/host/:/path/in/container/[:ro|rw]).
-p PORTS, --port PORTS	Share a network port between host and exegol (format: –port [<host_ipv4>:]<host_port>[:<container_port>][:<protocol>]. This configuration will disable the shared network with the host.
--hostname HOSTNAME	Set a custom hostname to the exegol container (default: exegol-<name>)
--cap CAPABILITIES	(dangerous) Capabilities allow to add specific privileges to the container (e.g. need to mount volumes, perform low-level operations on the network, etc).
--privileged	(dangerous) give extended privileges at the container creation (e.g. needed to mount things, to use wifi or bluetooth)
-d DEVICES, --device DEVICES	Add host device(s) at the container creation (example: -d /dev/ttyACM0 -d /dev/bus/usb/).
--disable-X11	Disable X11 sharing to run GUI-based applications. (default: Enabled)
--disable-my-resources	Disable the mount of the shared resources (/opt/my-resources) from the host (/home/dramelac/.exegol/my-resources) (default: Enabled)
--disable-exegol-resources	Disable the mount of the exegol resources (/opt/resources) from the host (/home/dramelac/Documents/tools/Exegol/exegol-resources) (default: Enabled)
--disable-shared-network	Disable the sharing of the host’s network interfaces with exegol (default: Enabled)
--disable-shared-timezones	Disable the sharing of the host’s time and timezone configuration with exegol (default: Enabled)

Virtual desktop

In addition to the X11 sharing functionality, Exegol can generate its own graphical environment and make it available to the user in a variety of ways. By default, a web interface gives users access to their own containerized graphical desktop.

Option	Description
--desktop	Enable or disable the Exegol desktop feature (default: Disabled)
--desktop-config	Configure your exegol desktop (vnc or http) and its exposure (format: proto[:ip[:port]]) (default: http:127.0.0.1:<random>)

VPN

An additional feature of Exegol is the VPN tunnel option (OpenVPN). Just provide an ovpn configuration to exegol and the container will take care of starting the tunnel at each startup.

Option	Description
--vpn VPN	Setup an OpenVPN connection at the container creation (example: –vpn /home/user/vpn/conf.ovpn)
--vpn-auth VPN_AUTH	Enter the credentials with a file (first line: username, second line: password) to establish the VPN connection automatically (example: –vpn-auth /home/user/vpn/auth.txt)

Warning

All the options seen previously are taken into account only for the creation of a new container. It is not possible to modify the configuration of an existing container. These options will be ignored if a container with the same name already exists.

Shell logging

One of the functions of exegol very useful in a professional context is the shell logging. This feature allows the user to record everything that happens in the exegol container (commands typed and responses).

Option	Description
-l, --log	Enable shell logging (commands and outputs) on exegol to /workspace/logs/ (default: Disabled)
--log-method	Select a shell logging method used to record the session (default: asciinema)
--log-compress	Enable or disable the automatic compression of log files at the end of the session (default: Enabled)

Tip

When the -l/--log option is enabled during the creation of a new container, all future shells will be automatically logged for this container.

Session specific

The options specific to the start of the interactive session

Option	Description
-e ENVS, --env ENVS	And an environment variable on Exegol (format: –env KEY=value). The variables configured during the creation of the container will be persistent in all shells. If the container already exists, the variable will be present only in the current shell.
-s SHELL, --shell SHELL	Select a shell environment to launch at startup (default: zsh)

Tip

The environment variables configured with --env ENVS during the creation of a new container will be available to all processes of the container during the entire life cycle of the container.

Command examples

# Start interactively a container
exegol start

# Create a demo container using full image
exegol start demo full

# Spawn a shell from demo container
exegol start demo

# Create a container test with a custom shared workspace
exegol start test full -w "./project/pentest/"

# Create a container test sharing the current working directory
exegol start test full -cwd

# Create a container htb with a VPN
exegol start htb full --vpn "~/vpn/lab_Dramelac.ovpn"

# Create a container app with custom volume
exegol start app full -V "/var/app/:/app/"

# Get a shell based on tmux
exegol start --shell tmux

# Share a specific hardware device (like Proxmark)
exegol start -d "/dev/ttyACM0"

# Share every USB device connected to the host
exegol start -d "/dev/bus/usb/"

info action

The info action aims at displaying all the information specific to the Exegol project on the current system. This action can also be used by targeting a specific container to display its configuration in detail.

Depending on the verbosity level specified in the command-line, the information displayed will be more or less detailed accordingly.

Standard (default)VerboseAdvancedDebug

exegol info

• List of available Exegol Images

  • Name of the image

  • Size of each image (disk space if the image is installed, otherwise its compressed size to download for installation)

  • Status of each image

    • Not installed (Image available for download from dockerhub)

    • Up to date (The latest version of the image is installed and ready to be used)

    • Update available (A new version is available for download on dockerhub)

    • Outdated (Old version of an image that has been updated since)

    • Local image (Locally built image)

    • Discontinued (if your image is no longer available on dockerhub)

• List of Exegol Containers

  • Name of each container

  • Container status (Stopped or running)

  • Image name (Exegol image used as a base to create the container)

  • Configurations (Display of non-default configurations)

Options

The info action does not have many parameters, its use is relatively simple. This action can either be used to gather general information (available images, containers, user configs, etc.), or gather information about a specific container and display its configuration.

Option	Description
CONTAINER	Optional positional argument to indicate the container tag of which to display the configuration.

Global options can still be used, like for any action.

Option	Description
-h, --help	Show the help message of any action
-v, --verbose	Verbosity level (-v for verbose, -vv for advanced, -vvv for debug)
-q, --quiet	Show no information at all
-k, --insecure	Allow insecure server connections for web requests, e.g. when fetching info from DockerHub (default: Secure)
--offline	Run exegol in offline mode, no request will be made on internet (default: Disable)
--arch {arm64,amd64}	Overwrite default image architecture (default: host’s arch)

Command examples

# Print containers and images essentials information:
exegol info

# Print the detailed configuration of the "demo" container:
exegol info demo

# Print verbose information:
exegol info -v

# Print advanced information:
exegol info -vv

# Print debug information:
exegol info -vvv

exec action

This action allows to run a single command in a single container instead of loading a full interactive shell.

When this action is used it is possible to execute a command either in:

• a temporary container created especially to execute the command, and automatically deleted at the end of the execution: the name of an exegol image must be provided from which a temporary container will be created

• a standard Exegol container (already existing, or not): the name of an exegol container must then be provided. This container will be created in interactive mode if it does not already exist

The executed command can be executed either:

• in the background mode (i.e. like a daemon): exegol terminates immediately after the command is launched and does not wait for its execution to be completed. No process is left hanging (useful when running GUI apps for instance).

• in standard mode: exegol will wait for the end of the process to stop the container (and delete it if

Tip

In standard execution mode, it is possible to ask exegol to display the command output (stdout/stderr) in the terminal by adding -v parameter.

Options

Since the exec action can also create containers, it shares the same parameters as the start action.

There are also additional parameters, unique to the exec action:

Option	Description
CONTAINER or IMAGE	This option indicates the container name to use to execute the command. If the --tmp parameter is used, this name will be used to target an image.
COMMAND	Single command to execute in the container.
-b, --background	Executes the command in background as a daemon.
--tmp	Creates a dedicated and temporary container to execute the command.

Command examples

# Execute the command bloodhound in the container demo:
exegol exec demo bloodhound

# Execute the command 'nmap -h' with console output in the container demo:
exegol exec -v demo 'nmap -h'

# Execute a command in background within the demo container:
exegol exec -b demo bloodhound

# Execute the command bloodhound in a temporary container based on the full image:
exegol exec --tmp full bloodhound

# Execute a command in background with a temporary container:
exegol exec -b --tmp full bloodhound

# Execute Wireshark in background, in a privileged temporary container:
exegol exec --background --tmp --privileged "nightly" "wireshark"

# Execute the command wireshark with network admin privileged:
exegol exec -b --tmp --cap NET_ADMIN full wireshark

update action

The update process

The exegol wrapper has an update action dedicated to updating the different modules (wrapper, resources, etc.) of the project as well as the (docker) Exegol images.

Modules updates

This action make sure the local copies of the following repositories are up to date:

• Exegol (wrapper code). If the wrapper has been installed with Pip, it will not be able to self-update, updating the package through Pip will be required (e.g. python3 -m pip install --upgrade exegol).

• Exegol-images (docker building files)

• Exegol-resources (offline resources, exegol-resources). This module is optional, and users can choose to install/update it at any time.

Tip

When running exegol update -v, the user will be able to choose from what branch them module should be synchronized with, allowing to switch easily between release and dev versions.

Images updates

Once the local code base is updated, the wrapper compares the installed Exegol images with those offered on the Dockerhub registry. If no parameters have been provided at command-line, an interactive selection will be possible to choose the images to update (if updates are available).

Hint

Older versions of images will be automatically deleted if they are no longer used by any container and if a newer version of the same image is installed. This automatic deletion behavior is a default configuration that can be modified in the configuration file if needed, but it’s advised not to change it as disk space is not unlimited and Exegol image can take up to 30GB.

Options

The options of the update action are the following.

Option	Description
IMAGE	This option specifies what image to update.
--skip-git	Skip modules updates.
--skip-images	Skip images updates.

Command examples

# Update interactively an exegol image:
exegol update

# Update the full image:
exegol update full

# Update the full image without updating exegol modules:
exegol update --skip-git full

# Update exegol modules and have the option to change branch without updating docker image:
exegol update -v --skip-images

stop action

The purpose of the stop action is to stop one or more Exegol containers.

If these containers have a VPN configuration, shutting down the container will cause the VPN tunnel to be disconnected.

Options

The options of the stop action are limited to selecting the container(s) to be stopped.

Option	Description
CONTAINER	Tag used to target one or more Exegol containers

Command examples

# Stop interactively one or more containers:
exegol stop

# Stop the "demo" container:
exegol stop "demo"

# Stop the "demo", "test" and "dev" container:
exegol stop "demo" "test" "dev"

restart action

The purpose of the restart action is to stop and directly restart an Exegol container.

If these containers have a privileged or device configuration, restarting the container will refresh the available devices inside the container.

Warning

Restarting a container will reset the hosts, resolv.conf files (and probably more).

Options

The options of the restart action are limited to selecting the container to be restarted and some starting options that can be also found on the start action.

Option	Description
CONTAINER	Tag used to target the Exegol containers to restart

Command examples

# Restart interactively one container:
exegol restart

# Restart the "demo" container:
exegol restart "demo"

remove action

The purpose of the remove action is to remove one or more Exegol container.

If the deleted container was using an outdated image, the wrapper will (by default) try to delete that outdated image automatically (unless this default behavior is changed in the exegol configuration file, which is not advised since disk space is not limited and Exegol images can take up to 30GB).

When deleting the container, the wrapper will check if the content of the /workspace volume is empty. If the workspace is empty, exegol will automatically delete the folder on the host, otherwise it will explicitly ask the user if the workspace content should be deleted or not.

Options

The options of the remove action are limited to selecting the container(s) to be removed and forcing the removal without asking the user for interactive confirmation.

Option	Description
CONTAINER	Tag used to target one or more Exegol containers
-F, --force	Remove container without interactive user confirmation (confirmation will still be required for removing non-empty workspaces).

Command examples

# Remove interactively one or more containers:
exegol remove

# Remove the "demo" container:
exegol remove "demo"

# Remove the "demo", "test" and "dev" container without asking for user confirmation:
exegol remove -F "demo" "test" "dev"

uninstall action

The purpose of the uninstall action is to remove one or more Exegol images.

Warning

The wrapper will try to delete the selected exegol images but this can only work if the selected images are not used by any container anymore. A container based on an image that doesn’t exist anymore cannot run.

Options

The options of the uninstall action are limited to selecting the image(s) to be removed, and forcing the removal without asking the user for interactive confirmation.

Option	Description
IMAGE	Tag used to target one or more Exegol images
-F, --force	Remove image without interactive user confirmation.

Command examples

# Remove interactively one or more containers:
exegol uninstall

# Remove the "full" container:
exegol uninstall "full"

# Remove the "full", "ad" and "web" container without asking for user confirmation:
exegol uninstall -F "full" "ad" "web"

version action

The version action is mostly used for debugging purposes, it only displays information about the Exegol setup on the system.

In debug mode (-vvv), it also displays information about the system and wrapper installation context.

Options

The options available for the version action are the global options that affect the behavior of all exegol actions.

Option	Description
-h, --help	Show the help message of any action
-v, --verbose	Verbosity level (-v for verbose, -vv for advanced, -vvv for debug)
-q, --quiet	Show no information at all
-k, --insecure	Allow insecure server connections for web requests, e.g. when fetching info from DockerHub (default: Secure)
--offline	Run exegol in offline mode, no request will be made on internet (default: Disable)
--arch {arm64,amd64}	Overwrite default image architecture (default: host’s arch)

Command examples

# Show version information
exegol version

# Show version and system information
exegol version -vvv

Advanced uses

Exegol home directory

The ~/.exegol folder exists in the user’s home folder to centralize “exegol resources”, “my-resources”, volumes and also the configuration file.

• The configuration file (YAML) is located at ~/.exegol/config.yml and is generated by the wrapper during the first execution, with the default configurations.

• By default, every exegol container has a workspace volume. If the path of this volume is not specified by the user (see start parameters), a folder with the name of the container will be created in the “private workspace” folder. By default, this folder is located at ~/.exegol/workspaces/.

Exegol configuration

The Exegol wrapper is configured with many default settings. Most of them can be modified with a simple argument. For productivity purposes, setting a different default behavior once and not have to add the same options everytime is interesting. For this exact purpose, a configuration file exists that allows users to persistently change the behavior and operations to be performed by default.

The user configuration currently in place can be viewed with the command: exegol info -v. More information on the info page.

Within the ~/.exegol/config.yml file, several settings can be configured to customize the Exegol experience, all distributed in multiple sections below.

VolumesConfig

The volume section allows to change the default path for various volumes.

Warning

Volume path can be changed at any time but already existing containers will not be affected by the update and will keep the original paths they were created with.

• my_resources_path: the “my-resources” volume is a storage space dedicated to the user to customize his environment and tools. This volume is, by default, shared across all exegol containers. See details about it.

• exegol_resources_path: exegol-resources are data and static tools downloaded in addition to docker images. These tools are complementary and are accessible directly from the host. See details.

• private_workspace_path: when containers do not have an explicitly declared workspace at their creation (i.e. with --cwd-mount, or --workspace), a dedicated folder will be created at this location to share the workspace with the host but also to save the data after deleting the container.

My-resources

“My-resources” is a major feature allowing Exegol users to have a volume, shared with all Exegol containers, that can centralize their own resources and configurations. It allows users to enjoy their own tools that are not available in Exegol but also to customize their Exegol setup. More information on the dedicated documentation page My-Resources.

This volume is accessible from the host at ~/.exegol/my-resources/ and from the containers (if the feature was left enabled at the container creation) at /opt/my-resources.

To facilitate its use, a read/write access system shared (between the host user and the container root user) has been implemented.

Hint

To allow this permissions sharing, the “my-resources” folder (and all subdirectories) must have the Set-GID permission bit set. This is done automatically by the wrapper if the current user has sufficient rights. Otherwise, the wrapper will display a sudo command to be executed manually to update the relevant permissions.

The host path of this volume can be changed from the configuration file ~/.exegol/config.yml.

Warning

• Be careful not to use a folder with existing data, in which case their permissions will be automatically modified to enable access sharing.

• This change will not be applied to already existing exegol containers.

Local builds

When installing Exegol, while downloading the pre-built and compressed Docker images from Dockerhub is advised, users can build their own images locally. The wrapper has a local build feature to create and manage local exegol images.

The exegol install command can be used for that purpose. The user must specify an image name that does not match one of the remote images available from dockerhub. The wrapper will suggest to build a local image with this name. If the user chooses to build an image locally, he will then have to choose a build profile among those available. The build profile is merely the dockerfile to follow during the build process. An arbitrary dockerfile can be added in /path/to/Exegol/exegol-docker-build/name.dockerfile.

Tip

• the -v parameter can be added to have more details about the build process.

• the detailed logs of the docker build process can also be saved in a file with the --build-log parameter.

Tools list

Click here to see the lists of tools featured in the latest nightly images.

Error

[August 5th, 2023] - The lists descriptions were mostly AI-generated for this first version of the tools list in order to get the list shipped quickly. Many descriptions are wrong and will be fixed very soon.

Releases

Hint

The lists featured here are automatically generated. Exegol features CI/CD pipelines that build the images. At build, most tools are tested. If at least one test fails, the image doesn’t get published.

Image tag	Version	Arch	Build date	Tools list
nightly	8bdc0542	amd64	2024-05-06T11:15:30Z	nightly_8bdc0542_amd64.csv
nightly	8bdc0542	arm64	2024-05-06T11:14:05Z	nightly_8bdc0542_arm64.csv

AMD64ARM64

Image tag	Version	Build date	Tools list
ad	3.1.4	2024-05-05T22:35:39Z	ad_3.1.4_amd64.csv
web	3.1.4	2024-05-05T22:26:58Z	web_3.1.4_amd64.csv
full	3.1.4	2024-05-05T22:17:31Z	full_3.1.4_amd64.csv
light	3.1.4	2024-05-04T21:15:16Z	light_3.1.4_amd64.csv
osint	3.1.4	2024-05-04T20:58:48Z	osint_3.1.4_amd64.csv
full	3.1.3	2024-04-14T13:29:00Z	full_3.1.3_amd64.csv
ad	3.1.3	2024-04-14T10:34:36Z	ad_3.1.3_amd64.csv
web	3.1.3	2024-04-14T10:43:47Z	web_3.1.3_amd64.csv
osint	3.1.3	2024-04-14T10:46:46Z	osint_3.1.3_amd64.csv
light	3.1.3	2024-04-14T08:47:32Z	light_3.1.3_amd64.csv
full	3.1.2	2023-12-22T12:04:26Z	full_3.1.2_amd64.csv
ad	3.1.2	2023-12-22T11:41:22Z	ad_3.1.2_amd64.csv
web	3.1.2	2023-12-22T11:46:29Z	web_3.1.2_amd64.csv
light	3.1.2	2023-12-22T00:08:53Z	light_3.1.2_amd64.csv
osint	3.1.2	2023-12-22T00:02:50Z	osint_3.1.2_amd64.csv
full	3.1.1	2023-08-18T01:36:37Z	full_3.1.1_amd64.csv
ad	3.1.1	2023-08-18T02:59:03Z	ad_3.1.1_amd64.csv
web	3.1.1	2023-08-18T01:35:14Z	web_3.1.1_amd64.csv
osint	3.1.1	2023-08-18T01:34:47Z	osint_3.1.1_amd64.csv
light	3.1.1	2023-08-18T01:35:00Z	light_3.1.1_amd64.csv
full	3.1.0	2023-08-09T22:27:20Z	full_3.1.0_amd64.csv
ad	3.1.0	2023-08-10T00:33:47Z	ad_3.1.0_amd64.csv
web	3.1.0	2023-08-09T11:12:12Z	web_3.1.0_amd64.csv
osint	3.1.0	2023-08-09T10:50:11Z	osint_3.1.0_amd64.csv
light	3.1.0	2023-08-09T02:53:53Z	light_3.1.0_amd64.csv

Latest nightly

Below is the list of tools featured in the latest nightly (AMD64) image.

Tool	Link	Description
abuseACL	https://github.com/AetherBlack/abuseACL	A python script to automatically list vulnerable Windows ACEs/ACLs.
aclpwn	https://github.com/aas-n/aclpwn.py	Tool for testing the security of Active Directory access controls.
adidnsdump	https://github.com/dirkjanm/adidnsdump	Active Directory Integrated DNS dump utility
aircrack-ng	https://www.aircrack-ng.org	A suite of tools for wireless penetration testing
amass	https://github.com/OWASP/Amass	A DNS enumeration / attack surface mapping & external assets discovery tool
amber	https://github.com/EgeBalci/amber	Forensic tool to recover browser history / cookies and credentials
androguard	https://github.com/androguard/androguard	Reverse engineering and analysis of Android applications
android-tools-adb	https://developer.android.com/studio/command-line/adb	A collection of tools for debugging Android applications
anew	https://github.com/tomnomnom/anew	A simple tool for filtering and manipulating text data / such as log files and other outputs.
angr	https://github.com/angr/angr	a platform-agnostic binary analysis framework
apksigner	https://source.android.com/security/apksigning	arguably the most important step to optimize your APK file
apktool	https://github.com/iBotPeaches/Apktool	It is a tool for reverse engineering 3rd party / closed / binary Android apps.
arjun	https://github.com/s0md3v/Arjun	HTTP parameter discovery suite.
arsenal	https://github.com/Orange-Cyberdefense/arsenal	Powerful weapons for penetration testing.
asdf	https://github.com/asdf-vm/asdf	Extendable version manager with support for ruby python go etc
asrepcatcher	https://github.com/Yaxxine7/ASRepCatcher	Make your VLAN ASREProastable.
assetfinder	https://github.com/tomnomnom/assetfinder	Tool to find subdomains and IP addresses associated with a domain.
autoconf	https://www.gnu.org/software/autoconf/autoconf.html	Tool for producing shell scripts to configure source code packages
autorecon	https://github.com/Tib3rius/AutoRecon	Multi-threaded network reconnaissance tool which performs automated enumeration of services.
avrdude	https://github.com/avrdudes/avrdude	AVRDUDE is a command-line program that allows you to download/upload/manipulate the ROM and EEPROM contents of AVR microcontrollers using the in-system programming technique (ISP).
awscli	https://aws.amazon.com/cli/	Command-line interface for Amazon Web Services.
azure-cli	https://github.com/Azure/azure-cli	A great cloud needs great tools; we’re excited to introduce Azure CLI our next generation multi-platform command line experience for Azure.
bettercap	https://github.com/bettercap/bettercap	The Swiss Army knife for 802.11 / BLE / and Ethernet networks reconnaissance and MITM attacks.
binwalk	https://github.com/ReFirmLabs/binwalk	Binwalk is a tool for analyzing / reverse engineering / and extracting firmware images.
Blackbird	https://github.com/p1ngul1n0/blackbird	An OSINT tool to search fast for accounts by username across 581 sites.
bloodhound	https://github.com/BloodHoundAD/BloodHound	Active Directory security tool for reconnaissance and attacking AD environments.
BloodHound-CE	https://github.com/SpecterOps/BloodHound	Active Directory security tool for reconnaissance and attacking AD environments (Community Edition)
bloodhound-ce.py	https://github.com/fox-it/BloodHound.py	BloodHound-CE ingestor in Python.
bloodhound-import	https://github.com/fox-it/BloodHound.py	Import data into BloodHound for analyzing active directory trust relationships
bloodhound-quickwin	https://github.com/kaluche/bloodhound-quickwin	A tool for BloodHounding on Windows machines without .NET or Powershell installed
bloodhound.py	https://github.com/fox-it/BloodHound.py	BloodHound ingestor in Python.
bloodyAD	https://github.com/CravateRouge/bloodyAD	bloodyAD is an Active Directory privilege escalation swiss army knife.
bolt	https://github.com/s0md3v/bolt	Bolt crawls the target website to the specified depth and stores all the HTML forms found in a database for further processing.
bqm	https://github.com/Acceis/bqm	Tool to deduplicate custom BloudHound queries from different datasets and merge them in one file.
brakeman	https://github.com/presidentbeef/brakeman	Static analysis tool for Ruby on Rails applications
bruteforce-luks	https://github.com/glv2/bruteforce-luks	A tool to help recover encrypted LUKS2 containers
bully	https://github.com/aanarchyy/bully	bully is a tool for brute-forcing WPS (Wireless Protected Setup) PINs.
burpsuite	https://portswigger.net/burp	Web application security testing tool.
buster	https://github.com/sham00n/Buster	Advanced OSINT tool
byp4xx	https://github.com/lobuhi/byp4xx	A Swiss Army knife for bypassing web application firewalls and filters.
carbon14	https://github.com/Lazza/carbon14	OSINT tool for estimating when a web page was written.
Censys	https://github.com/censys/censys-python	An easy-to-use and lightweight API wrapper for Censys APIs
certipy	https://github.com/ly4k/Certipy	Python tool to create and sign certificates
certsync	https://github.com/zblurx/certsync	certsync is a tool that helps you synchronize certificates between two directories.
cewl	https://digi.ninja/projects/cewl.php	Generates custom wordlists by spidering a target’s website and parsing the results
cewler	https://github.com/roys/cewler	CeWL alternative in Python
chainsaw	https://github.com/WithSecureLabs/chainsaw	Rapidly Search and Hunt through Windows Forensic Artefacts
checksec-py	https://github.com/Wenzel/checksec.py	Python wrapper script for checksec.sh from paX.
chisel	https://github.com/jpillora/chisel	Go based TCP tunnel with authentication and encryption support
cloudfail	https://github.com/m0rtem/CloudFail	a reconnaissance tool for identifying misconfigured CloudFront domains.
cloudmapper	https://github.com/duo-labs/cloudmapper	CloudMapper helps you analyze your Amazon Web Services (AWS) environments.
cloudsplaining	https://github.com/salesforce/cloudsplaining	AWS IAM Security Assessment tool that identifies violations of least privilege and generates a risk-prioritized report.
cloudsploit	https://github.com/aquasecurity/cloudsploit	Cloud Security Posture Management
clusterd	https://github.com/hatRiot/clusterd	A tool to distribute and remotely manage Hacking Team’s RCS agents.
cmsmap	https://github.com/Dionach/CMSmap	Tool for security audit of web content management systems.
coercer	https://github.com/p0dalirius/coercer	DFS-R target coercion tool
constellation	https://github.com/constellation-app/Constellation	Find and exploit vulnerabilities in mobile applications.
corscanner	https://github.com/chenjj/CORScanner	a Python script for finding CORS misconfigurations.
cowpatty	https://github.com/joswr1ght/cowpatty	cowpatty is a tool for offline dictionary attacks against WPA-PSK (Pre-Shared Key) networks.
crackhound	https://github.com/trustedsec/crackhound	A fast WPA/WPA2/WPA3 WiFi Handshake capture / password recovery and analysis tool
crackmapexec	https://github.com/Porchetta-Industries/CrackMapExec	Network scanner.
creds	https://github.com/ihebski/DefaultCreds-cheat-sheet	One place for all the default credentials to assist pentesters during an engagement. This document has several products default login/password gathered from multiple sources.
crunch	https://github.com/crunchsec/crunch	A wordlist generator where you can specify a standard character set or a character set you specify.
cupp	https://github.com/Mebus/cupp	Cupp is a tool used to generate personalized password lists based on target information.
CyberChef	https://github.com/gchq/CyberChef/	The Cyber Swiss Army Knife
cyperoth	https://github.com/seajaysec/cypheroth	Automated extensible toolset that runs cypher queries against Bloodhound’s Neo4j backend and saves output to spreadsheets.
darkarmour	https://github.com/bats3c/darkarmour	a tool to detect and evade common antivirus products
dex2jar	https://github.com/pxb1988/dex2jar	A tool to convert Android’s dex files to Java’s jar files
dfscoerce	https://github.com/Wh04m1001/dfscoerce	DFS-R target coercion tool
dirb	https://github.com/v0re/dirb	Web Content Scanner
dirsearch	https://github.com/maurosoria/dirsearch	Tool for searching files and directories on a web site.
divideandscan	https://github.com/snovvcrash/divideandscan	Advanced subdomain scanner
dns2tcp	https://github.com/alex-sector/dns2tcp	dns2tcp is a tool for relaying TCP connections over DNS.
dnschef	https://github.com/iphelix/dnschef	Tool for DNS MITM attacks
dnsenum	https://github.com/fwaeytens/dnsenum	dnsenum is a tool for enumerating DNS information about a domain.
dnsx	https://github.com/projectdiscovery/dnsx	A tool for DNS reconnaissance that can help identify subdomains and other related domains.
donpapi	https://github.com/login-securite/DonPAPI	Dumping revelant information on compromised targets without AV detection
dploot	https://github.com/zblurx/dploot	dploot is Python rewrite of SharpDPAPI written un C#.
droopescan	https://github.com/droope/droopescan	Scan Drupal websites for vulnerabilities.
drupwn	https://github.com/immunIT/drupwn	Drupal security scanner.
eaphammer	https://github.com/s0lst1c3/eaphammer	EAPHammer is a toolkit for performing targeted evil twin attacks against WPA2-Enterprise networks.
empire	https://github.com/BC-SECURITY/Empire	post-exploitation and adversary emulation framework
enum4linux-ng	https://github.com/cddmp/enum4linux-ng	Tool for enumerating information from Windows and Samba systems.
enyx	https://github.com/trickster0/enyx	Framework for building offensive security tools.
evilwinrm	https://github.com/Hackplayers/evil-winrm	Tool to connect to a remote Windows system with WinRM.
exif	https://exiftool.org/	Utility to read / write and edit metadata in image / audio and video files
exifprobe	https://github.com/hfiguiere/exifprobe	Exifprobe is a command-line tool to parse EXIF data from image files.
exiftool	https://github.com/exiftool/exiftool	ExifTool is a Perl library and command-line tool for reading / writing and editing meta information in image / audio and video files.
exiv2	https://github.com/Exiv2/exiv2	Image metadata library and toolset
ExtractBitlockerKeys	https://github.com/p0dalirius/ExtractBitlockerKeys	A system administration or post-exploitation script to automatically extract the bitlocker recovery keys from a domain.
eyewitness	https://github.com/FortyNorthSecurity/EyeWitness	a tool to take screenshots of websites / provide some server header info / and identify default credentials if possible.
fcrackzip	https://github.com/hyc/fcrackzip	Password cracker for zip archives.
fdisk	https://github.com/karelzak/util-linux	Collection of basic system utilities / including fdisk partitioning tool
feroxbuster	https://github.com/epi052/feroxbuster	Simple / fast and recursive content discovery tool
ffuf	https://github.com/ffuf/ffuf	Fast web fuzzer written in Go.
fierce	https://github.com/mschwager/fierce	A DNS reconnaissance tool for locating non-contiguous IP space
finalrecon	https://github.com/thewhiteh4t/FinalRecon	A web reconnaissance tool that gathers information about web pages
findomain	https://github.com/findomain/findomain	The fastest and cross-platform subdomain enumerator.
finduncommonshares	https://github.com/p0dalirius/FindUncommonShares	Script that can help identify shares that are not commonly found on a Windows system.
firefox	https://www.mozilla.org	A web browser
foremost	https://doc.ubuntu-fr.org/foremost	Foremost is a forensic tool for recovering files based on their headers / footers / and internal data structures.
freeipscanner	https://github.com/scrt/freeipscanner	A simple bash script to enumerate stale ADIDNS entries
freerdp2-x11	https://github.com/FreeRDP/FreeRDP	FreeRDP is a free implementation of the Remote Desktop Protocol (RDP) released under the Apache license.
frida	https://github.com/frida/frida	Dynamic instrumentation toolkit
fuxploider	https://github.com/almandin/fuxploider	a Python tool for finding and exploiting file upload forms/directories.
fzf	https://github.com/junegunn/fzf	🌸 A command-line fuzzy finder
gau	https://github.com/lc/gau	Fast tool for fetching URLs
genusernames	https://gitlab.com/-/snippets/2480505/raw/main/bash	GenUsername is a Python tool for generating a list of usernames based on a name or email address.
GeoPincer	https://github.com/tloja/GeoPincer	GeoPincer is a script that leverages OpenStreetMap’s Overpass API in order to search for locations.
geowordlists	https://github.com/p0dalirius/GeoWordlists	tool to generate wordlists of passwords containing cities at a defined distance around the client city.
gf	https://github.com/tomnomnom/gf	A wrapper around grep to avoid typing common patterns
ghidra	https://github.com/NationalSecurityAgency/ghidra	Software reverse engineering suite of tools.
git-dumper	https://github.com/arthaud/git-dumper	Small script to dump a Git repository from a website.
githubemail	https://github.com/paulirish/github-email	a command-line tool to retrieve a user’s email from Github.
gittools	https://github.com/internetwache/GitTools	A collection of Git tools including a powerful Dumper for dumping Git repositories.
gmsadumper	https://github.com/micahvandeusen/gMSADumper	A tool for extracting credentials and other information from a Microsoft Active Directory domain.
gobuster	https://github.com/OJ/gobuster	Tool to discover hidden files and directories.
goldencopy	https://github.com/Dramelac/GoldenCopy	Copy the properties and groups of a user from neo4j (bloodhound) to create an identical golden ticket
GoMapEnum	https://github.com/nodauf/GoMapEnum	Nothing new but existing techniques are brought together in one tool.
gopherus	https://github.com/tarunkant/Gopherus	Gopherus is a simple command line tool for exploiting vulnerable Gopher servers.
gosecretsdump	https://github.com/c-sto/gosecretsdump	Implements NTLMSSP network authentication protocol in Go
goshs	https://github.com/patrickhener/goshs	Goshs is a replacement for Python’s SimpleHTTPServer. It allows uploading and downloading via HTTP/S with either self-signed certificate or user provided certificate and you can use HTTP basic auth.
gowitness	https://github.com/sensepost/gowitness	A website screenshot utility written in Golang.
GPOddity	https://github.com/synacktiv/GPOddity	Aiming at automating GPO attack vectors through NTLM relaying (and more)
gpp-decrypt	https://github.com/t0thkr1s/gpp-decrypt	A tool to decrypt Group Policy Preferences passwords
gqrx	https://github.com/csete/gqrx	Software defined radio receiver powered by GNU Radio and Qt
gron	https://github.com/tomnomnom/gron	Make JSON greppable!
h2csmuggler	https://github.com/BishopFox/h2csmuggler	HTTP Request Smuggling tool using H2C upgrade
h8mail	https://github.com/khast3x/h8mail	Email OSINT and breach hunting.
hackrf	https://github.com/mossmann/hackrf	Low cost software defined radio platform
haiti	https://github.com/noraj/haiti	haiti is a A CLI tool (and library) to identify hash types (hash type identifier).
hakrawler	https://github.com/hakluke/hakrawler	a fast web crawler for gathering URLs and other information from websites
hakrevdns	https://github.com/hakluke/hakrevdns	Reverse DNS lookup utility that can help with discovering subdomains and other information.
hashcat	https://hashcat.net/hashcat	A tool for advanced password recovery
hashonymize	https://github.com/ShutdownRepo/hashonymize	This small tool is aimed at anonymizing hashes files for offline but online cracking like Google Collab for instance (see https://github.com/ShutdownRepo/google-colab-hashcat).
Havoc	https://github.com/HavocFramework/Havoc	Command & Control Framework
hcxdumptool	https://github.com/ZerBea/hcxdumptool	Small tool to capture packets from wlan devices.
hcxtools	https://github.com/ZerBea/hcxtools	Tools for capturing and analyzing packets from WLAN devices.
hexedit	https://github.com/pixel/hexedit	View and edit binary files
holehe	https://github.com/megadose/holehe	mail osint tool finding out if it is used on websites.
hping3	https://github.com/antirez/hping	A network tool able to send custom TCP/IP packets
httpmethods	https://github.com/ShutdownRepo/httpmethods	Tool for exploiting HTTP methods (e.g. PUT / DELETE / etc.)
httprobe	https://github.com/tomnomnom/httprobe	A simple utility for enumerating HTTP and HTTPS servers.
httpx	https://github.com/projectdiscovery/httpx	A tool for identifying web technologies and vulnerabilities / including outdated software versions and weak encryption protocols.
hydra	https://github.com/vanhauser-thc/thc-hydra	Hydra is a parallelized login cracker which supports numerous protocols to attack.
ida	https://www.hex-rays.com/products/ida/	Interactive disassembler for software analysis.
ignorant	https://github.com/megadose/ignorant	holehe but for phone numbers.
imagemagick	https://github.com/ImageMagick/ImageMagick	ImageMagick is a free and open-source image manipulation tool used to create / edit / compose / or convert bitmap images.
impacket	https://github.com/ThePorgs/impacket	Set of tools for working with network protocols (ThePorgs version).
ipinfo	https://github.com/ipinfo/cli	Get information about an IP address or hostname.
iptables	https://linux.die.net/man/8/iptables	Userspace command line tool for configuring kernel firewall
jackit	https://github.com/insecurityofthings/jackit	Exploit to take over a wireless mouse and keyboard
jadx	https://github.com/skylot/jadx	Java decompiler
jd-gui	https://github.com/java-decompiler/jd-gui	A standalone Java Decompiler GUI
jdwp	https://github.com/IOActive/jdwp-shellifier	This exploitation script is meant to be used by pentesters against active JDWP service / in order to gain Remote Code Execution.
john	https://github.com/openwall/john	John the Ripper password cracker.
joomscan	https://github.com/rezasp/joomscan	A tool to enumerate Joomla-based websites
jwt	https://github.com/ticarpi/jwt_tool	a command-line tool for working with JSON Web Tokens (JWTs)
kadimus	https://github.com/P0cL4bs/Kadimus	a tool for detecting and exploiting file upload vulnerabilities
KeePwn	https://github.com/Orange-Cyberdefense/KeePwn	KeePwn is a tool that extracts passwords from KeePass 1.x and 2.x databases.
kerbrute	https://github.com/ropnop/kerbrute	A tool to perform Kerberos pre-auth bruteforcing
kiterunner	https://github.com/assetnote/kiterunner	Tool for operating Active Directory environments.
Kraken	https://github.com/kraken-ng/Kraken	Kraken is a modular multi-language webshell focused on web post-exploitation and defense evasion. It supports three technologies (PHP / JSP and ASPX) and is core is developed in Python.
krbjack	https://github.com/almandin/krbjack	A Kerberos AP-REQ hijacking tool with DNS unsecure updates abuse.
krbrelayx	https://github.com/dirkjanm/krbrelayx	a tool for performing Kerberos relay attacks
kubectl	https://kubernetes.io/docs/reference/kubectl/overview/	Command-line interface for managing Kubernetes clusters.
ldapdomaindump	https://github.com/dirkjanm/ldapdomaindump	A tool for dumping domain data from an LDAP service
ldaprelayscan	https://github.com/zyn3rgy/LdapRelayScan	Check Domain Controllers for LDAP server protections regarding the relay of NTLM authentication.
ldapsearch	https://wiki.debian.org/LDAP/LDAPUtils	Search for and display entries (ldap)
ldapsearch-ad	https://github.com/yaap7/ldapsearch-ad	LDAP search utility with AD support
LDAPWordlistHarvester	https://github.com/p0dalirius/LDAPWordlistHarvester	Generate a wordlist from the information present in LDAP in order to crack passwords of domain accounts
ldeep	https://github.com/franc-pentest/ldeep	ldeep is a tool to discover hidden paths on Web servers.
legba	https://github.com/evilsocket/legba	a multiprotocol credentials bruteforcer / password sprayer and enumerator built with Rust
libmspack	https://github.com/kyz/libmspack	C library for Microsoft compression formats.
libnfc	https://github.com/grundid/nfctools	Library for Near Field Communication (NFC) devices
libnfc-crypto1-crack	https://github.com/droidnewbie2/acr122uNFC	Implementation of cryptographic attack on Mifare Classic RFID cards
libusb-dev	https://github.com/libusb/libusb	Library for USB device access
ligolo-ng	https://github.com/nicocha30/ligolo-ng	An advanced yet simple tunneling tool that uses a TUN interface.
linkedin2username	https://github.com/initstring/linkedin2username	Generate a list of LinkedIn usernames from a company name.
linkfinder	https://github.com/GerbenJavado/LinkFinder	a Python script that finds endpoints and their parameters in JavaScript files.
lnkup	https://github.com/Plazmaz/lnkUp	This tool will allow you to generate LNK payloads. Upon rendering or being run they will exfiltrate data.
lsassy	https://github.com/Hackndo/lsassy	Windows secrets and passwords extraction tool.
ltrace	https://github.com/dkogan/ltrace	ltrace is a debugging program for Linux and Unix that intercepts and records dynamic library calls that are called by an executed process.
maigret	https://github.com/soxoj/maigret	Collects information about a target email (or domain) from Google and Bing search results
maltego	https://www.paterva.com/web7/downloads.php	A tool used for open-source intelligence and forensics
manspider	https://github.com/blacklanternsecurity/MANSPIDER	Manspider will crawl every share on every target system. If provided creds don’t work it will fall back to ‘guest’ then to a null session.
mariadb-client	https://github.com/MariaDB/server	MariaDB is a community-developed fork of the MySQL relational database management system. The mariadb-client package includes command-line utilities for interacting with a MariaDB server.
masky	https://github.com/Z4kSec/Masky	Masky is a python library providing an alternative way to remotely dump domain users’ credentials thanks to an ADCS. A command line tool has been built on top of this library in order to easily gather PFX or NT hashes and TGT on a larger scope
masscan	https://github.com/robertdavidgraham/masscan	Masscan is an Internet-scale port scanner
mdcat	https://github.com/swsnr/mdcat	Fancy cat for Markdown
metasploit	https://github.com/rapid7/metasploit-framework	A popular penetration testing framework that includes many exploits and payloads
mfcuk	https://github.com/nfc-tools/mfcuk	Implementation of an attack on Mifare Classic and Plus RFID cards
mfdread	https://github.com/zhovner/mfdread	Tool for reading/writing Mifare RFID tags
mfoc	https://github.com/nfc-tools/mfoc	Implementation of ‘offline nested’ attack by Nethemba
minicom	https://doc.ubuntu-fr.org/minicom	Minicom is a text-based serial communication program for Unix-like operating systems.
mitm6	https://github.com/fox-it/mitm6	Tool to conduct a man-in-the-middle attack against IPv6 protocols.
mobsf	https://github.com/MobSF/Mobile-Security-Framework-MobSF	Automated and all-in-one mobile application (Android/iOS/Windows) pen-testing malware analysis and security assessment framework
moodlescan	https://github.com/inc0d3/moodlescan	Scan Moodle sites for information and vulnerabilities.
mousejack	https://github.com/BastilleResearch/mousejack	Exploit to take over a wireless mouse and keyboard
msprobe	https://github.com/puzzlepeaches/msprobe	msprobe is a tool to identify Microsoft Windows hosts and servers that are running certain services.
MurMurHash	https://github.com/QU35T-code/MurMurHash	This little tool is to calculate a MurmurHash value of a favicon to hunt phishing websites on the Shodan platform.
naabu	https://github.com/projectdiscovery/naabu	A fast and reliable port scanner that can detect open ports and services.
name-that-hash	https://github.com/HashPals/Name-That-Hash	Online tool for identifying hashes.
nasm	https://github.com/netwide-assembler/nasm	NASM is an 80x86 assembler designed for portability and modularity.
nbtscan	https://github.com/charlesroelli/nbtscan	NBTscan is a program for scanning IP networks for NetBIOS name information.
neo4j	https://github.com/neo4j/neo4j	Database.
neovim	https://neovim.io/	hyperextensible Vim-based text editor
netdiscover	https://github.com/netdiscover-scanner/netdiscover	netdiscover is an active/passive address reconnaissance tool
netexec	https://github.com/Pennyw0rth/NetExec	Network scanner (Crackmapexec updated).
nfct	https://github.com/grundid/nfctools	Tool for Near Field Communication (NFC) devices
ngrok	https://github.com/inconshreveable/ngrok	Expose a local server behind a NAT or firewall to the internet
nmap	https://nmap.org	The Network Mapper - a powerful network discovery and security auditing tool
nmap-parse-ouptut	https://github.com/ernw/nmap-parse-output	Converts/manipulates/extracts data from a Nmap scan output.
noPac	https://github.com/Ridter/noPac	Exploiting CVE-2021-42278 and CVE-2021-42287 to impersonate DA from standard domain user.
nosqlmap	https://github.com/codingo/NoSQLMap	a Python tool for testing NoSQL databases for security vulnerabilities.
ntlmv1-multi	https://github.com/evilmog/ntlmv1-multi	Exploit a vulnerability in Microsoft Windows to gain system-level access.
ntlm_theft	https://github.com/Greenwolf/ntlm_theft	A tool for generating multiple types of NTLMv2 hash theft files
nuclei	https://github.com/projectdiscovery/nuclei	A fast and customizable vulnerability scanner that can detect a wide range of issues / including XSS / SQL injection / and misconfigured servers.
oaburl	https://gist.githubusercontent.com/snovvcrash/4e76aaf2a8750922f546eed81aa51438/raw/96ec2f68a905eed4d519d9734e62edba96fd15ff/oaburl.py	Find Open redirects and other vulnerabilities.
objection	https://github.com/sensepost/objection	Runtime mobile exploration
objectwalker	https://github.com/p0dalirius/objectwalker	A python module to explore the object tree to extract paths to interesting objects in memory.
oneforall	https://github.com/shmilylty/OneForAll	a powerful subdomain collection tool.
onesixtyone	https://github.com/trailofbits/onesixtyone	onesixtyone is an SNMP scanner which utilizes a sweep technique to achieve very high performance.
osrframework	https://github.com/i3visio/osrframework	Include references to a bunch of different applications related to username checking / DNS lookups / information leaks research / deep web search / regular expressions extraction and many others.
pass	https://github.com/hashcat/hashcat	TODO
PassTheCert	https://github.com/AlmondOffSec/PassTheCert	PassTheCert is a tool to extract Active Directory user password hashes from a domain controller’s local certificate store.
patator	https://github.com/lanjelot/patator	Login scanner.
pcredz	https://github.com/lgandx/PCredz	PowerShell credential dumper
pcsc	https://pcsclite.apdu.fr/	Middleware for smart card readers
pdfcrack	https://github.com/robins/pdfcrack	A tool for cracking password-protected PDF files
peepdf	https://github.com/jesparza/peepdf	peepdf is a Python tool to explore PDF files in order to find out if the file can be harmful or not.
petitpotam	https://github.com/topotam/PetitPotam	Windows machine account manipulation
phoneinfoga	https://github.com/sundowndev/PhoneInfoga	Information gathering & OSINT framework for phone numbers.
photon	https://github.com/s0md3v/Photon	a fast web crawler which extracts URLs / files / intel & endpoints from a target.
PHP filter chain generator	https://github.com/synacktiv/php_filter_chain_generator	A CLI to generate PHP filters chain / get your RCE without uploading a file if you control entirely the parameter passed to a require or an include in PHP!
phpggc	https://github.com/ambionics/phpggc	Exploit generation tool for the PHP platform.
pkcrack	https://github.com/keyunluo/pkcrack	tool to generate wordlists of passwords containing cities at a defined distance around the client city
pkinittools	https://github.com/dirkjanm/PKINITtools	Pkinit support tools
polenum	https://github.com/Wh1t3Fox/polenum	Polenum is a Python script which uses the Impacket library to extract user information through the SMB protocol.
powershell	https://github.com/PowerShell/PowerShell	a command-line shell and scripting language designed for system administration and automation
pp-finder	https://github.com/yeswehack/pp-finder	Prototype pollution finder tool for javascript. pp-finder lets you find prototype pollution candidates in your code.
pre2k	https://github.com/garrettfoster13/pre2k	pre2k is a tool to check if a Windows domain has any pre-2000 Windows 2000 logon names still in use.
pretender	https://github.com/RedTeamPentesting/pretender	an mitm tool for helping with relay attacks.
prips	https://manpages.ubuntu.com/manpages/focal/man1/prips.1.html	A utility for quickly generating IP ranges or enumerating hosts within a specified range.
privexchange	https://github.com/dirkjanm/PrivExchange	a tool to perform attacks against Microsoft Exchange server using NTLM relay techniques
prowler	https://github.com/prowler-cloud/prowler	Perform Cloud Security best practices assessments / audits / incident response / compliance / continuous monitoring / hardening and forensics readiness.
proxmark3	https://github.com/Proxmark/proxmark3	Open source RFID research toolkit.
proxychains	https://github.com/rofl0r/proxychains	Proxy chains - redirect connections through proxy servers.
pst-utils	https://manpages.debian.org/jessie/pst-utils/readpst.1	pst-utils is a set of tools for working with Outlook PST files.
pth-tools	https://github.com/byt3bl33d3r/pth-toolkit	A toolkit to perform pass-the-hash attacks
pwncat	https://github.com/calebstewart/pwncat	A lightweight and versatile netcat alternative that includes various additional features.
pwndb	https://github.com/davidtavarez/pwndb	A command-line tool for searching the pwndb database of compromised credentials.
pwndbg	https://github.com/pwndbg/pwndbg	a GDB plugin that makes debugging with GDB suck less
pwnedornot	https://github.com/thewhiteh4t/pwnedOrNot	Check if a password has been leaked in a data breach.
pwninit	https://github.com/io12/pwninit	A tool for automating starting binary exploit challenges
pwntools	https://github.com/Gallopsled/pwntools	a CTF framework and exploit development library
pygpoabuse	https://github.com/Hackndo/pyGPOAbuse	A tool for abusing GPO permissions to escalate privileges
pykek	https://github.com/preempt/pykek	PyKEK (Python Kerberos Exploitation Kit) a python library to manipulate KRB5-related data.
pylaps	https://github.com/p0dalirius/pylaps	Utility for enumerating and querying LDAP servers.
pymeta	https://github.com/m8sec/pymeta	Google and Bing scraping osint tool
pypykatz	https://github.com/skelsec/pypykatz	a Python library for mimikatz-like functionality
pyrit	https://github.com/JPaulMora/Pyrit	Python-based WPA/WPA2-PSK attack tool.
pywerview	https://github.com/the-useless-one/pywerview	A (partial) Python rewriting of PowerSploit’s PowerView.
pywhisker	https://github.com/ShutdownRepo/pywhisker	PyWhisker is a Python equivalent of the original Whisker made by Elad Shamir and written in C#. This tool allows users to manipulate the msDS-KeyCredentialLink attribute of a target user/computer to obtain full control over that object. It’s based on Impacket and on a Python equivalent of Michael Grafnetter’s DSInternals called PyDSInternals made by podalirius.
pywsus	https://github.com/GoSecure/pywsus	Python implementation of a WSUS client
radare2	https://github.com/radareorg/radare2	A complete framework for reverse-engineering and analyzing binaries
rdesktop	https://github.com/rdesktop/rdesktop	rdesktop is a client for Remote Desktop Protocol (RDP) used in a number of Microsoft products including Windows NT Terminal Server / Windows 2000 Server / Windows XP and Windows 2003 Server.
reaver	https://github.com/t6x/reaver-wps-fork-t6x	reaver is a tool for brute-forcing WPS (Wireless Protected Setup) PINs.
recon-ng	https://github.com/lanmaster53/recon-ng	External recon tool.
recondog	https://github.com/s0md3v/ReconDog	a reconnaissance tool for performing information gathering on a target.
redis-tools	https://github.com/antirez/redis-tools	redis-tools is a collection of Redis client utilities including redis-cli and redis-benchmark.
remmina	https://github.com/FreeRDP/Remmina	Remote desktop client.
responder	https://github.com/lgandx/Responder	a LLMNR / NBT-NS and MDNS poisoner.
rlwrap	https://github.com/hanslub42/rlwrap	rlwrap is a small utility that wraps input and output streams of executables / making it possible to edit and re-run input history
ROADtools	https://github.com/dirkjanm/ROADtools	ROADtools is a framework to interact with Azure AD. It consists of a library (roadlib) with common components / the ROADrecon Azure AD exploration tool and the ROADtools Token eXchange (roadtx) tool.
roastinthemiddle	https://github.com/Tw1sm/RITM	RoastInTheMiddle is a tool to intercept and relay NTLM authentication requests.
robotstester	https://github.com/p0dalirius/robotstester	Utility for testing whether a website’s robots.txt file is correctly configured.
routersploit	https://github.com/threat9/routersploit	Security audit tool for routers.
RsaCracker	https://github.com/skyf0l/RsaCracker	Powerful RSA cracker for CTFs. Supports RSA - X509 - OPENSSH in PEM and DER formats.
rsactftool	https://github.com/RsaCtfTool/RsaCtfTool	The rsactftool tool is used for RSA cryptographic operations and analysis.
rsync	https://packages.debian.org/sid/rsync	File synchronization tool for efficiently copying and updating data between local or remote locations
rtl-433	https://github.com/merbanan/rtl_433	Tool for decoding various wireless protocols/ signals such as those used by weather stations
ruler	https://github.com/sensepost/ruler	Outlook Rules exploitation framework.
rusthound (v2)	https://github.com/OPENCYBER-FR/RustHound	BloodHound-CE ingestor in Rust.
rusthound	https://github.com/OPENCYBER-FR/RustHound	BloodHound ingestor in Rust.
rustscan	https://github.com/RustScan/RustScan	The Modern Port Scanner
samdump2	https://github.com/azan121468/SAMdump2	A tool to dump Windows NT/2k/XP/Vista password hashes from SAM files
sccmhunter	https://github.com/garrettfoster13/sccmhunter	SCCMHunter is a post-ex tool built to streamline identifying profiling and attacking SCCM related assets in an Active Directory domain.
sccmwtf	https://github.com/xpn/sccmwtf	This code is designed for exploring SCCM in a lab.
scout	https://github.com/nccgroup/ScoutSuite	Scout Suite is an open source multi-cloud security-auditing tool which enables security posture assessment of cloud environments.
scrcpy	https://github.com/Genymobile/scrcpy	Display and control your Android device.
searchsploit	https://gitlab.com/exploit-database/exploitdb	A command line search tool for Exploit-DB
seclists	https://github.com/danielmiessler/SecLists	A collection of multiple types of lists used during security assessments
semgrep	https://github.com/returntocorp/semgrep/	Static analysis tool that supports multiple languages and can find a variety of vulnerabilities and coding errors.
shadowcoerce	https://github.com/ShutdownRepo/shadowcoerce	Utility for bypassing the Windows Defender antivirus by hiding a process within a legitimate process.
shellerator	https://github.com/ShutdownRepo/Shellerator	a simple command-line tool for generating shellcode
Sherlock	https://github.com/sherlock-project/sherlock	Hunt down social media accounts by username across social networks.
shuffledns	https://github.com/projectdiscovery/shuffledns	A fast and customizable DNS resolver that can be used for subdomain enumeration and other tasks.
simplyemail	https://github.com/SimplySecurity/SimplyEmail	a scriptable command line tool for sending emails
sipvicious	https://github.com/enablesecurity/sipvicious	Enumeration and MITM tool for SIP devices
sleuthkit	https://github.com/sleuthkit/sleuthkit	Forensic toolkit to analyze volume and file system data
sliver	https://github.com/BishopFox/sliver	Open source / cross-platform and extensible C2 framework
smali	https://github.com/JesusFreke/smali	A tool to disassemble and assemble Android’s dex files
smartbrute	https://github.com/ShutdownRepo/SmartBrute	The smart password spraying and bruteforcing tool for Active Directory Domain Services.
smbclient	https://github.com/samba-team/samba	SMBclient is a command-line utility that allows you to access Windows shared resources
smbmap	https://github.com/ShawnDEvans/smbmap	A tool to enumerate SMB shares and check for null sessions
smtp-user-enum	https://github.com/pentestmonkey/smtp-user-enum	A tool to enumerate email addresses via SMTP
smuggler	https://github.com/defparam/smuggler	Smuggler is a tool that helps pentesters and red teamers to smuggle data into and out of the network even when there are multiple layers of security in place.
SoapUI	https://github.com/SmartBear/soapui	SoapUI is the world’s leading testing tool for API testing.
spiderfoot	https://github.com/smicallef/spiderfoot	A reconnaissance tool that automatically queries over 100 public data sources
sprayhound	https://github.com/Hackndo/Sprayhound	Active Directory password audit tool.
sqlmap	https://github.com/sqlmapproject/sqlmap	Sqlmap is an open-source penetration testing tool that automates the process of detecting and exploiting SQL injection flaws
ssh-audit	https://github.com/jtesta/ssh-audit	ssh-audit is a tool to test SSH server configuration for best practices.
sshuttle	https://github.com/sshuttle/sshuttle	Transparent proxy server that tunnels traffic through an SSH server
sslscan	https://github.com/rbsec/sslscan	a tool for testing SSL/TLS encryption on servers
ssrfmap	https://github.com/swisskyrepo/SSRFmap	a tool for testing SSRF vulnerabilities.
steghide	https://github.com/StefanoDeVuono/steghide	steghide is a steganography program that is able to hide data in various kinds of image and audio files.
stegolsb	https://github.com/KyTn/STEGOLSB	Steganography tool to hide data in BMP images using least significant bit algorithm
stegosuite	https://github.com/osde8info/stegosuite	Stegosuite is a free steganography tool that allows you to hide data in image and audio files.
strace	https://github.com/strace/strace	strace is a debugging utility for Linux that allows you to monitor and diagnose system calls made by a process.
subfinder	https://github.com/projectdiscovery/subfinder	Tool to find subdomains associated with a domain.
sublist3r	https://github.com/aboul3la/Sublist3r	a Python tool designed to enumerate subdomains of websites.
swaks	https://github.com/jetmore/swaks	Swaks is a featureful flexible scriptable transaction-oriented SMTP test tool.
symfony-exploits	https://github.com/ambionics/symfony-exploits	Collection of Symfony exploits and PoCs.
tailscale	https://github.com/tailscale/tailscale	A secure and easy-to-use VPN alternative that is designed for teams and businesses.
targetedKerberoast	https://github.com/ShutdownRepo/targetedKerberoast	Kerberoasting against specific accounts
tcpdump	https://github.com/the-tcpdump-group/tcpdump	a powerful command-line packet analyzer for Unix-like systems
TeamsPhisher	https://github.com/Octoberfest7/TeamsPhisher	TeamsPhisher is a Python3 program that facilitates the delivery of phishing messages and attachments to Microsoft Teams users whose organizations allow external communications.
testdisk	https://github.com/cgsecurity/testdisk	Partition recovery and file undelete utility
testssl	https://github.com/drwetter/testssl.sh	a tool for testing SSL/TLS encryption on servers
theharvester	https://github.com/laramies/theHarvester	Tool for gathering e-mail accounts / subdomain names / virtual host / open ports / banners / and employee names from different public sources
tig	https://github.com/jonas/tig	Tig is an ncurses-based text-mode interface for git.
timing	https://github.com/ffleming/timing_attack	Tool to generate a timing profile for a given command.
tls-map	https://github.com/sec-it/tls-map	tls-map is a library for mapping TLS cipher algorithm names.
tls-scanner	https://github.com/tls-attacker/tls-scanner	a simple script to check the security of a remote TLS/SSL web server
tomcatwardeployer	https://github.com/mgeeky/tomcatwardeployer	Script to deploy war file in Tomcat.
tor	https://github.com/torproject/tor	Anonymity tool that can help protect your privacy and online identity by routing your traffic through a network of servers.
toutatis	https://github.com/megadose/Toutatis	Toutatis is a tool that allows you to extract information from instagrams accounts such as e-mails / phone numbers and more.
traceroute	https://github.com/iputils/iputils	Traceroute is a command which can show you the path a packet of information takes from your computer to one you specify.
trevorspray	https://github.com/blacklanternsecurity/TREVORspray	TREVORspray is a modular password sprayer with threading SSH proxying loot modules / and more
trid	https://mark0.net/soft-trid-e.html	File identifier
trilium	https://github.com/zadam/trilium	Personal knowledge management system.
tshark	https://github.com/wireshark/wireshark	TShark is a terminal version of Wireshark.
uberfile	https://github.com/ShutdownRepo/Uberfile	Uberfile is a simple command-line tool aimed to help pentesters quickly generate file downloader one-liners in multiple contexts (wget / curl / powershell / certutil…). This project code is based on my other similar project for one-liner reverseshell generation Shellerator.
updog	https://github.com/sc0tfree/updog	Simple replacement for Python’s SimpleHTTPServer.
upx	https://github.com/upx/upx	UPX is an advanced executable packer
username-anarchy	https://github.com/urbanadventurer/username-anarchy	Tools for generating usernames when penetration testing. Usernames are half the password brute force problem.
Villain	https://github.com/t3l3machus/Villain	Command & Control Framework
volatility2	https://github.com/volatilityfoundation/volatility	Volatile memory extraction utility framework
volatility3	https://github.com/volatilityfoundation/volatility3	Advanced memory forensics framework
wabt	https://github.com/WebAssembly/wabt	The WebAssembly Binary Toolkit (WABT) is a suite of tools for WebAssembly (Wasm) including assembler and disassembler / a syntax checker / and a binary format validator.
wafw00f	https://github.com/EnableSecurity/wafw00f	a Python tool that helps to identify and fingerprint web application firewall (WAF) products.
waybackurls	https://github.com/tomnomnom/waybackurls	Fetch all the URLs that the Wayback Machine knows about for a domain.
webclientservicescanner	https://github.com/Hackndo/webclientservicescanner	Scans for web service endpoints
weevely	https://github.com/epinna/weevely3	a webshell designed for post-exploitation purposes that can be extended over the network at runtime.
wfuzz	https://github.com/xmendez/wfuzz	WFuzz is a web application vulnerability scanner that allows you to find vulnerabilities using a wide range of attack payloads and fuzzing techniques
whatportis	https://github.com/ncrocfer/whatportis	Command-line tool to lookup port information
whatweb	https://github.com/urbanadventurer/WhatWeb	Next generation web scanner that identifies what websites are running.
whois	https://packages.debian.org/sid/whois	See information about a specific domain name or IP address.
wifite2	https://github.com/derv82/wifite2	Script for auditing wireless networks.
windapsearch-go	https://github.com/ropnop/go-windapsearch/	Active Directory enumeration tool.
wireshark	https://github.com/wireshark/wireshark	Wireshark is a network protocol analyzer that lets you see what’s happening on your network at a microscopic level.
wpscan	https://github.com/wpscanteam/wpscan	A tool to enumerate WordPress-based websites
wuzz	https://github.com/asciimoo/wuzz	a command-line tool for interacting with HTTP(S) web services
XSpear	https://github.com/hahwul/XSpear	a powerful XSS scanning and exploitation tool.
xsrfprobe	https://github.com/0xInfection/XSRFProbe	a tool for detecting and exploiting Cross-Site Request Forgery (CSRF) vulnerabilities
xsser	https://github.com/epsylon/xsser	XSS scanner.
xsstrike	https://github.com/s0md3v/XSStrike	a Python tool for detecting and exploiting XSS vulnerabilities.
xtightvncviewer	https://www.commandlinux.com/man-page/man1/xtightvncviewer.1.html	xtightvncviewer is an open source VNC client software.
Yalis	https://github.com/EatonChips/yalis	Yet Another LinkedIn Scraper
youtubedl	https://github.com/ytdl-org/youtube-dl	Download videos from YouTube and other sites.
ysoserial	https://github.com/frohoff/ysoserial	A proof-of-concept tool for generating payloads that exploit unsafe Java object deserialization.
yt-dlp	https://github.com/yt-dlp/yt-dlp	A youtube-dl fork with additional features and fixes
zerologon	https://github.com/SecuraBV/CVE-2020-1472	Exploit for the Zerologon vulnerability (CVE-2020-1472).
zipalign	https://developer.android.com/studio/command-line/zipalign	arguably the most important step to optimize your APK file
zsteg	https://github.com/zed-0xff/zsteg	Detect steganography hidden in PNG and BMP images

My resources

“My-resources” brings great features allowing users to make Exegol their own and customize it even further. This feature relies on a simple volume shared between the host and all exegol containers, and an advanced integration in the Exegol images directly.

Warning

The “my-resources” feature will do what it’s told to do. If users choose to use that feature to replace files or configuration, those replacements should take place. So if there are some additions to Exegol you’re not getting, it could be because you have a “my-resources” setup that replaces it.

To learn more about the volume options, details are available here.

Below are the features offered by “My-resources”, allowing users to extend Exegol beyond what is initially included (tools, resources).

• Custom tools: users can place their own custom standalone tools, binaries and scripts in the “my-resources” volume. This volume is accessible from all containers at /opt/my-resources.

• Supported setups: users can customize their exegol environments automatically and transparently without having to manually setting things up for each and every new Exegol container they create. In this functionality, a pre-set list of supported custom configuration is set, and will improve with time. It’s the easier and most user-friendly approach to customizing a few configurations.

• User setup: In this functionality, a shell script can be populated with every command a user wishes its containers to run at their creation.

Custom tools

See also

Available from version 3.0.0 of any exegol image.

In the container, the /opt/my-resources/bin/ folder (~/.exegol/my-resources/bin/ on the host) is automatically added to the PATH of the zsh shell. The user can then add tools in that folder in order to use them from the container.

Hint

The most simple approach would be to add standalone binaries, but users could also add symbolic links that would point to somewhere else in /opt/my-resources/.

# Example for a standalone binary
cp /path/to/tool ~/.exegol/my-resources/bin/

# Example for a symbolic link
git -C ~/.exegol/my-resources/ clone "https://github.com/someauthor/sometool"
ln -s ~/.exegol/my-resources/sometool/script.py ~/.exegol/my-resources/bin/script.py

Supported setups

Configuration files stored in the /opt/my-resources/setup/ directory will be deployed on the containers and allow users to customize Exegol even further. By default, the number of officially supported configuration files is limited, and it depends on the version of the image itself, not the wrapper.

Hint

In order to see what configuration files are supported in your version, the /opt/supported_setups.md documentation file can be read from any container.

This documentation will reference in detail all the supported customizations available over time, and the corresponding minimum image version required for each one.

If a user wants to deploy tools and configurations that are not supported, or more advanced, they can opt for the User setup solution.

apt (packages, sources, keys)

See also

Available from version 3.0.0 of any exegol image.

A system exists to easily install arbitrary APT packages in any new exegol container.

• Custom APT repositories can be added in exegol by filling in the /opt/my-resources/setup/apt/sources.list file

• Importing custom repositories usually requires importing GPG keys as well, which can be done by entering trusted GPG keys download URLs in the /opt/my-resources/setup/apt/keys.list file

• To install APT packages automatically (after updating the repository including the custom ones), just enter a list of package names in the /opt/my-resources/setup/apt/packages.list file

bloodhound (customqueries, config)

See also

Available from version 3.1.0 of the ad and full images.

A system exists to easily add one or several bloodhound customqueries files, or change its configuration file in any new exegol container.

To automatically:

• overwrite the ~/.config/bloodhound/config.json configuration file, simply create the file /opt/my-resources/setup/bloodhound/config.json

• replace the default exegol customqueries, place one or several valid customqueries files into the folder /opt/my-resources/setup/bloodhound/customqueries_replacement/.

• merge with the default exegol customqueries by placing one or several valid customqueries files into the folder /opt/my-resources/setup/bloodhound/customqueries_merge/

Tip

To be considered for replacing or merging, the customqueries files must be valid and bear the .json extension. The file names do not matter. The output will be saved into the single file ~/.config/bloodhound/customqueries.json.

firefox (addons, CA)

See also

Available from version 3.0.2 of any exegol image.

A system exists to easily install arbitrary firefox addons in any new exegol container.

The /opt/my-resources/setup/firefox/addons.txt file allows the user to list addons to install from online sources. It must be filled with their links in Mozilla’s shop (for example https://addons.mozilla.org/fr/firefox/addon/foxyproxy-standard/ ).

The .xpi files in /opt/my-resources/setup/firefox/addons/ folder will be installed as well.

See also

Below, available from version 3.2.0 of any exegol image.

The .der files in /opt/my-resources/setup/firefox/CA/ folder will be trusted .

python3 (pip3)

See also

Available from version 3.0.0 of any exegol image.

A system exists to easily install arbitrary PIP3 packages in any new exegol container.

The /opt/my-resources/setup/python3/requirements.txt file allows the user to list a set of packages to install with constraints just like a classic requirements.txt file.

tmux (conf)

See also

Available from version 3.0.0 of any exegol image.

Exegol supports overloading its tmux configuration to allow all users to use their personal configuration.

• To automatically overwrite the ~/.tmux.conf configuration file, simply create the file /opt/my-resources/setup/tmux/tmux.conf

Tip

It is possible to install plugins with the APT customization system, details here.

vim (vimrc, configs)

See also

Available from version 3.0.0 of any exegol image.

Exegol supports overwriting its vim configuration to allow all users to use their personal configuration.

• To automatically overwrite the ~/.vimrc configuration file, simply create the file /opt/my-resources/setup/vim/vimrc

• vim configuration folders are also automatically synchronized:

  • /opt/my-resources/setup/vim/autoload/* –> ~/.vim/autoload/

  • /opt/my-resources/setup/vim/backup/* –> ~/.vim/backup/

  • /opt/my-resources/setup/vim/colors/* –> ~/.vim/colors/

  • /opt/my-resources/setup/vim/plugged/* –> ~/.vim/plugged/

  • /opt/my-resources/setup/vim/bundle/* –> ~/.vim/bundle/

Tip

It is possible to install plugins with the APT customization system.

neovim (.config/nvim)

See also

Will be available from version 3.1.2 of any exegol image.

Exegol supports overwriting its neovim configuration to allow all users to use their personal configuration.

• To automatically overwrite the ~/.config/nvim/ configuration, copy your config in /opt/my-resources/setup/nvim/

Tip

It is possible to install plugins dependencies with the APT customization system.

zsh (aliases, zshrc, history)

See also

Available from version 3.0.0 of any exegol image.

To not change the configuration for the proper functioning of exegol but allow the user to add aliases and custom commands to zshrc, additional configuration files will be automatically loaded by zsh to take into account the customization of the user .

• aliases: any custom alias can be defined in the /opt/my-resources/setup/zsh/aliases file. This file is automatically loaded by zsh.

• zshrc: it is possible to add commands at the end of the zshrc routine in /opt/my-resources/setup/zsh/zshrc file.

• history: it is possible to automatically add history commands at the end of ~/.zsh_history from the file /opt/my-resources/setup/zsh/history.

Tip

It is possible to install plugins with the APT customization system, details here.

User setup

See also

Available from version 3.0.0 of any exegol image.

The /opt/my-resources/setup/load_user_setup.sh script is executed on the first startup of each new container that has the “my-resources” feature enabled. Arbitrary code can be added in this file, in order to customize Exegol (dependency installation, configuration file copy, etc).

Warning

It is strongly advised not to overwrite the configuration files provided by exegol (e.g. /root/.zshrc, /opt/.exegol_aliases, …), official updates will not be applied otherwise.

Troubleshooting

In case of problem, the customization system logs all actions in the /var/log/exegol/load_setups.log file.

If the whole installation went smoothly the log file will be compressed by gunzip and will have the name /var/log/exegol/load_setups.log.gz

Tip

Logs in .gz format can be viewed directly without unpacking them with the zcat, zgrep, zdiff or zmore command!

Credentials

Some tools are pre-configured with the following credentials

Element	User	Password
neo4j database	neo4j	exegol4thewin
bettercap ui	bettercap	exegol4thewin
trilium	trilium	exegol4thewin
empire	empireadmin	exegol4thewin
wso-webshell (PHP)		exegol4thewin

Services list

This section lists the services that can be used in Exegol containers and their associated default ports.

Note

Note that, as of 25/10/2023, a utility is being developped in order to randomize those ports so that multiple containers being used concurrently don’t have their services step on one another if they share a network interface. This utility will be mostly transparent, and will modify the services configuration files dynamically.

Service	Port	Commands	Comments
neo4j bolt http https	7687 7474 7373	neo4j start, neo4j stop, neo4j restart	Used by BloodHound, and BloodHound-related projects.
BloodHound-CE	1030	bloodhound-ce bloodhound-ce-reset bloodhound-ce-stop	BloodHound Community Edition Web Interface
postgresql	5432	service postgresql [...]	Used by BloodHound CE
Trilium	1991	trilium-start, trilium-stop	Collaborative note taking app. https://github.com/zadam/trilium
Burp Suite	8080	burpsuite	HTTP(S) Proxy
Starkiller (Empire)	TBD	ps-empire server	GUI for the Empire post-exploit framework (https://github.com/BC-SECURITY/Empire)
Havoc	40056	havoc client/server	C2 Framework in GO (https://github.com/HavocFramework/Havoc)
Desktop vnc websockify	6336 random	desktop-start, desktop-stop, desktop-restart	Remote graphical desktop feature (beta). Used with the --desktop from up-to-date wrapper.

Resources

Exegol’s “offline resources” are a neat choice of standalone tools and scripts that are often used during penetration tests, CTFs and red-teams. While many penetration testers download those resources again every time they need them, Exegol users don’t have to. Everything is managed by the wrapper and they are shared with every container by default (at /opt/resources).

Resources list

Hint

The list featured here is automatically generated. Exegol features CI/CD pipelines that build the images, update the resources, etc. When a change is made on the Exegol-resources repository, it’s reflected here, in the list.

Resource	Link	Description
SysInternals	https://learn.microsoft.com/en-us/sysinternals	Windows utilities signed by Microsoft
pspy	https://github.com/DominicBreuker/pspy	Monitor linux processes without root permissions
PEASS-ng	https://github.com/carlospolop/PEASS-ng	Privilege Escalation Awesome Scripts SUITE
linux-smart-enumeration (lse.sh)	https://github.com/diego-treitos/linux-smart-enumeration	Linux enumeration tool for pentesting and CTFs with verbosity levels
LinEnum	https://github.com/rebootuser/LinEnum	Scripted Local Linux Enumeration & Privilege Escalation Checks
Linux Exploit Suggester	https://github.com/The-Z-Labs/linux-exploit-suggester	Linux privilege escalation auditing tool
Mimikatz	https://github.com/gentilkiwi/mimikatz	A little tool to play with Windows security
SharpHound.exe	https://github.com/BloodHoundAD/BloodHound	C# ingestor for BloodHound
JuicyPotato.exe	https://github.com/ohpe/juicy-potato	https://github.com/ohpe/juicy-potato
PrintSpoofer	https://github.com/itm4n/PrintSpoofer	Abusing SeImpersonatePrivilege from LOCAL/NETWORK SERVICE
GodPotato	https://github.com/BeichenDream/GodPotato	Abusing SeImpersonatePrivilege on recent Windows OS (up to W11 and Server 2022)
static netcat (linux)	https://github.com/andrew-d/static-binaries	Utility to establish TCP or UDP connections
static netcat (windows)	https://gitlab.com/onemask/pentest-tools	Utility to establish TCP or UDP connections
SpoolSample.exe	https://gitlab.com/onemask/pentest-tools	PoC tool to coerce Windows hosts authenticate to other machines
DiagHub.exe	https://gitlab.com/onemask/pentest-tools	Diagnostics Hub Standard Collector Service
LaZagne	https://github.com/AlessandroZ/LaZagne	Credentials recovery project
Sublinacl.exe	https://gitlab.com/onemask/pentest-tools	Modify Access Control Entries
plink.exe	https://www.cog-genomics.org/plink/	Network connection tool
deepce	https://github.com/stealthcopter/deepce	Docker Enumeration Escalation of Privileges and Container Escapes
Some webshells		PHP and ASPX webshells
ysoserial	https://github.com/pwntester/ysoserial	A proof-of-concept tool for generating payloads that exploit unsafe Java object deserialization
http-put-server	https://gist.githubusercontent.com/mildred/67d22d7289ae8f16cae7/raw/214c213c9415da18a471d1ed04660022cce059ef/server.py	HTTP PUT Server
Chisel	https://github.com/jpillora/chisel	A fast TCP/UDP tunnel over HTTP
ligolo-ng	https://github.com/nicocha30/ligolo-ng	Advanced yet simple tunneling/pivoting tool that uses a TUN interface
bitleaker	https://github.com/kkamagui/bitleaker	This tool can decrypt a BitLocker-locked partition with the TPM vulnerability
napper	https://github.com/kkamagui/napper-for-tpm	TPM vulnerability checking tool for CVE-2018-6622
mimipenguin	https://github.com/huntergregal/mimipenguin	A tool to dump the login password from the current linux user
p0wny-shell	https://github.com/flozz/p0wny-shell	Single-file PHP shell
Inveigh	https://github.com/Kevin-Robertson/Inveigh	.NET IPv4/IPv6 machine-in-the-middle tool for penetration testers
MailSniper	https://github.com/dafthack/MailSniper	Penetration testing tool for searching through email in a Microsoft Exchange
PowerSploit	https://github.com/PowerShellMafia/PowerSploit	A PowerShell Post-Exploitation Framework
PrivescCheck	https://github.com/itm4n/PrivescCheck	Privilege Escalation Enumeration Script for Windows
SharpCollection	https://github.com/Flangvik/SharpCollection	Nightly builds of common C# offensive tools
WinEnum	https://github.com/neox41/WinEnum	Script for Local Windows Enumeration
impacket-examples-windows	https://github.com/maaaaz/impacket-examples-windows	The great impacket example scripts compiled for Windows
nishang	https://github.com/samratashok/nishang	Offensive PowerShell for red team

Users

This part of the documentation is meant for Exegol users, those who want to understand the project a bit more, open issues, get in touch with the community, etc..

Opening issues

Create an issue in the correct repository:

• For any problem concerning Exegol WRAPPER (the exegol command).

• For any problem concerning Exegol IMAGE (the exegol environment).

• For any problem concerning Exegol RESOURCE (the exegol offline resources).

• For any problem concerning Exegol DOCUMENTATION (the exegol documentation).

Roadmap

The roadmap is available on GitHub: https://github.com/orgs/ThePorgs/projects/1/views/1

Discord

An Exegol discord has been created to facilitate exchanges between the community, open tickets, share ideas, vote on future features to prioritize etc..

Contributors

This part of the documentation is meant for Exegol contributors, those who write code and open pull requests. If adds up to the users documentation.

First things first, once you know on what module you want to contribute (wrapper, images, documentation, resources, etc.) fork it, checkout to the dev branch, then come back to this page to start coding.

Documentation

A new feature, whether it’s on the wrapper, images, or any other module, must be documented accordingly. Make sure to open a pull request to the appropriate Exegol docs branch on top of your wrapper/images/whatever pull request.

Exegol-docs branches

Branch	Purpose
main	nothing gets pushed there. This branch is made to merge with the other branches.
dev-wrapper	Related to the wrapper (Exegol )
dev-images	Related to the images (Exegol-images )
dev	General purpose

Before pushing a pull request on the documentation repository, it is advised to try and compile locally to make sure there are no errors and everything renders as expected. First, the requirements listed in requirements.txt must be installed (e.g. pip install --user -r ./requirements.txt). Then, the one-liner below can be used to remove any previous build, compile again and open the build in a browser.

rm -r build; make html; open "build/html/community/contributors.html"

Nota bene: in the example above, the open command opens an Internet browser (it’s a macOS command), but it can be replaced by anything else that fits the contributor’s environement (e.g. firefox).

Images

The Docker images are the heart of the Exegol project. A neat choice of tools, configurations, aliases, history commands, and various customizations are prepared in multiple images adapted for multiple uses: web hacking, Active Directory, OSINT (Open Source INTelligence), etc.

If you want to contribute to this part of the project, there are some things you need to know and some rules you need to follow.

Adding a new tool

In order to add a new tool to an image, here is how it goes. First, you need to figure out in what package your tool installation function must go to: packages.

Function structure

When preparing the install function to the package, don’t forget to include the following functions:

• colorecho "Installing yourtool": this is needed to raise logs inside the CI/CD pipeline

• catch_and_retry <some command>: this one is optional. When a command uses the Internet and could potentially fail randomly, the catch_and_retry wrapper is here to retry that commands multiple times with increasing time intervals in order to avoid having a whole build fail because of one temporary network error. Nota bene: most standard Internet-involved commands are transparently put behind a catch_and_retry (e.g. git, wget, curl, go, etc.).

• add-aliases yourtool: if your tool needs to have one or multiple aliases to work properly. You will need to create the aliases file in /sources/assets/shells/aliases.d/ named after your tool. This file must contain the alias(es) to set as follows.

  alias tool.py='python3 /opt/tools/yourtool/tool.py'
  

• add-history yourtool: if it’s relevant to give some command example of your tool. No need to populate the history with a command that’s very short or never used. Using long arguments is preferred. Using environment variables is preferred (e.g. $USER, $PASSWORD, $TARGET, etc.). You will need to create the history file in /sources/assets/shells/history.d/ named after your tool. This file must contain the history command(s) like the example below.

  yourtool.py --user "$USER" --password "$PASSWORD" --target "$TARGET"
  yourtool.py --mode enum --user "$USER" --target "$TARGET"
  yourtool.py --mode unauthenticated
  

• add-test-command "testcommand": this is needed by the CI/CD pipeline to conduct unit tests for all tools to make sure they are installed properly before publishing new images. The test command needs to return 0 if the tool works properly, anything else if it doesn’t. For instance, something like yourtool.py --help usually works, but not always! In order to find what command can be used for unit tests, you can do something like yourtool.py --help; echo $? to see what code is returned after the command is executed. Once trick that can be used when the --help command returns something !=0 is to do some grep like yourtool.py --help|& grep 'Usage:'.

• add-to-list "yourtool,https://link.to/the/tool,description": this is used by the CI/CD pipeline to automatically export tools in the Tools list. The format of the entry is standard 3-columns CSV (comma separated values). The first column is the tool name, then the link to the tool, then the description. Be careful to not have more than 2 commas and replace any comma in the description by something else.

In case your tool doesn’t need aliases or history commands, add the following comment at the beggining of the tool install function: # CODE-CHECK-WHITELIST=. Then add a comma-separated list of the exclusions. Below are some examples.

# CODE-CHECK-WHITELIST=add-aliases
# CODE-CHECK-WHITELIST=add-aliases,add-history

TL;DR, your tool installation function should look something like this:

function install_yourtool() {
    colorecho "Installing yourtool"
    # tool install commands [...]
    add-aliases yourtool
    add-history yourtool
    add-test-command "yourtool.py --help"
    add-to-list "yourtool,https://link.to/the/tool,description"
}

Install standards

When installing a tool, depending on how it gets installed, here are the rules.

• Most tools have their virtual environment, in order to avoid dependencies conflicts. Python virtual environments must have access to the system site-packages, to avoid redunduncy on already install common dependencies.

• Most tools are installed either in their own directory in /opt/tools/ or have the binary (or a symlink) in /opt/tools/bin/.

• Disk space being limited, we’re not pull every code source around. When possible, add the --depth 1 option to your usual git clone command.

Python sources (pipx)Python sources (venv)APT installGoRubyCompile sourcesDownload compiled binary

The easiest way to install a Python tool is to use pipx.

# from github.com example
python3 -m pipx install git+https://github.com/AUTHOR/REPO

# from local sources
git -C /opt/tools/ clone --depth 1 https://github.com/AUTHOR/REPO
python3 -m pipx install --system-site-packages /opt/tools/yourtool/

But some tools cannot be installed this way, either because they’re missing the setup.py or for any other obscure reason. In that case, opt for the “Python (venv)” solution.

Other standards

If your tool opens ports, or if there are credentials at play, please take a look at the corresponding documentations

• Credentials

• Ports & services

Multi-architecture builds

Know that Exegol images are built by, and for, AMD64 and ARM64 systems. Most systems are AMD64 (x86_64), but some other people use ARM64 (M1/M2 Apple Sillicon chips, 64bits Raspberry-Pies, …). Whenever possible, try to make sure your tool install function works for both architectures. Rest assured, if you don’t have both architectures at your disposal it’s perfectly fine, we’ll take care of this part for you. If you do, and if your tool installation function includes some commands that differ wether they run on an ARM64 or AMD64 host, you can use the following structure.

if [[ $(uname -m) = 'x86_64' ]]
then
    # command for AMD64
elif [[ $(uname -m) = 'aarch64' ]]
then
    # command for ARM64
else
    criticalecho-noexit "This installation function doesn't support architecture $(uname -m)" && return
fi

Calling the install function

Once the install function is over with, it needs to be called in the function that holds the same name as the package. For instance, if you’re adding your tool install function in the package_web.sh package, you’ll need to call that function in the package_ad() function (usually at the bottom of that file).

It will look something like this.

function package_web() {
    [...]
    install_yourtool
    [...]
}

Submitting the pull request

Hint

Once all your changes are over, and before submitting a pull request, it is advised to test your installation process locally. The Exegol wrapper can be used to build local images. Run exegol install --help to see some examples. You can also run the unit tests yourself by creating

# build the local image
exegol install "testimage" "full" --build-log "/tmp/testimage.log"

# create and start a container for the tests
exegol start "testcontainer" "testimage"

# run the tests (from the container)
cat /.exegol/build_pipeline_tests/all_commands.txt | grep -vE "^\s*$" | sort -u > /.exegol/build_pipeline_tests/all_commands.sorted.txt
python3 /.exegol/build_pipeline_tests/run_tests.py
cat /.exegol/build_pipeline_tests/failed_commands.log

Warning

Your pull request needs to be made against the dev branch.

Once you submit your pull request, and once the various changes that may be requested are made, a CI/CD pipeline will run to make sure your code is compliant and that the tool is installed and works as intended. The pipeline may raise some issues, but if they’re not related to your tool (e.g. network issues are common) don’t worry about it. If the errors are due to your tool install, then you’ll need to make the necessary changes to make your install work.

Once everything works, the pull request will be merged, the pipeline will run again in order to test, build and publish a new nightly image. Congrats, you’re now an Exegol contributor!

Temporary fixing a tool

Tools sometimes have their own issues along their development. A temporary fix can be added as follows, in order to let builds pass successfully, while the respective tool is not fixed. The fix depends on the way the tool is supposed to be installed.

Git (checkout)Git (merge PRs)

Applying the temporary fix for a tool installed through git goes as follows when checking out a previous commit

1. Find the commit id that made the tool install fail. This can be found in a try & repeat manner by installing the tool in an exegol container, checking out on a commit ID, try installing again, and repeat until it works.

2. Comment out the inital git clone command.

3. Add the temporary fix (git clone and git checkout) in a if statement that makes sure the fix won’t stay there forever. The error message will be raised and noticed in the pipeline.

4. (bonus) create an issue on the repo (if it doesn’t exist already) with the appropriate logs to help the tool’s maintainers notice the installation error and fix it.

function install_TOOL() {
    [...]
    # git -C /opt/tools/ clone --depth 1 https://github.com/REPO/TOOL.git
    local temp_fix_limit="YYYY-MM-DD"
    if [ "$(date +%Y%m%d)" -gt "$(date -d $temp_fix_limit +%Y%m%d)" ]; then
      criticalecho "Temp fix expired. Exiting."
    else
      git -C /opt/tools/ clone https://github.com/REPO/TOOL.git
      git -C /opt/tools/TOOL checkout 774f1c33efaaccf633ede6e704800345eb313878
    fi
    [...]
}

Adding to my-resources

Hint

This documentation is not written yet… Please contact us if you would like to contribute to this part and don’t know how.

Wrapper

Hint

This documentation is not written yet… Please contact us if you would like to contribute to this part and don’t know how.

Signing commits

To make the project as secure as possible, signed commits are now required to contribute to the project. Using signatures for commits on GitHub serves several important purposes :

• Authentication: it verifies the authenticity of the commit, ensuring that it was indeed made by the person claiming to have made it.

• Integrity: it ensures that the commit hasn’t been tampered with since it was signed. Any changes to the commit after it has been signed will invalidate the signature.

• Trust: this ensures that all contributions come from trusted sources.

• Visibility: on GitHub, signed commits are marked with a “verified” label, giving users and collaborators confidence in the commit’s origin and integrity.

GitHub offers an official documentation on the matter that can be followed to setup and sign commits properly. Exegol’s documentation will sum it up briefly and link to it whenever it’s needed.

While SSH (+ FIDO2) is preferred since it offers better multi-factor signing capabilities (knowledge + hardware possession factors), people that don’t have the required hardware can proceed with GPG or SSH.

GPGSSHSSH (+ FIDO2)

Generating a GPG key can be done by following GitHub’s official documentation on the matter (generating a new GPG key). TL;DR, the commands look something like this:

# for the email, indicate your public email (ID+Name@users.noreply.github.com) from https://github.com/settings/emails
gpg --quick-generate-key "YOUR_NAME <ID+Name@users.noreply.github.com>" ed25519 sign 0
gpg --list-secret-keys --keyid-format=long
gpg --armor --export $KEYID

Once the GPG key is generated, it can be added to the contributor’s GitHub profile. Again, GitHub’s documentation explains how to achieve that (adding a GPG key to your GitHub account).

Once the GPG key is generated and associated to the GitHub account, it can be used to sign commits. In order to achieve that, the contributor must configure git properly on his machine (telling git about your GPG key).

TL;DR: the commands look something like this to set it up for git CLI:

gpg --list-secret-keys --keyid-format=long
git config --global user.signingkey $KEYID

# (option 1) configure locally on a specific repo
cd /path/to/repository && git config commit.gpgsign true

# (option 2) configure for all git operations
git config --global commit.gpgsign true

To set it up on IDEs, proper official documentations can be followed (e.g. GitKraken, PyCharm).

Hint

The contributor’s GitHub account can be configured to mark unsigned commits as unverified or partially verified. While it’s not mandatory regarding contributions to Exegol since the requirement is managed on Exegol repositories directly, it’s a nice thing to do. See GitHub’s documentation on Vigilante mode.

Maintainers

This part of the documentation is meant for Exegol maintainers. It adds up to the contributors documentation.

Wrapper release

Hint

The wrapper documentation must be aligned with the wrapper features. . The docs PR can be merged once the wrapper is released.

Preparation

1. Git updates

The first step is to update the project and sub-modules, meaning pointing the exegol-images and exegol-resources sub-modules to the latest master version. Even if the wrapper is able to auto-update itself, it is always better to keep the base reference at least up to date.

With gitWith Exegol

• Update current wrapper repo:

git pull

• Update git submodules and checkout to main branch for release:

git -C exegol-docker-build checkout main
git -C exegol-docker-build pull
git -C exegol-resources checkout main
git -C exegol-resources pull

Important

Don’t forget to reload and commit any submodule update at this step !

2. Config reviews

• Review exegol.utils.ConstantConfig variables

  • Change version number ! (remove the alpha or beta tag at the end of the version number)

• Review documentation

• Review README.md

Tests & build

First, test the code with mypy:

mypy exegol.py --ignore-missing-imports --check-untyped-defs

You can execute this one-liner to check the project and build it.

Warning

Require build package installed!

Hint

Exegol can only be published through a source build distribution because of the source code files for building local images.

python3 setup.py clean test && \
   (rm -rf Exegol.egg-info && python3 -m build --sdist) || \
   echo "Some tests failed, check your code and requirements before publishing!"

Post build

• Upgrade tests.test_exegol.py version number to the next version build to avoid future mistake

• Commit updates

• Publish PR

• Wait for review and merge

Manual Upload

Important

PyPi packaging and upload is now handle by GitHub action. It will be triggered with the creation of the new tag in the next-step with the release creation.

This step is no longer needed.

After validation of the PR, we can upload the new version package to pypi.

Warning

Require twine package installed and token configured on ~/.pypirc!

• Check package upload on the test repository (optional)

python3 -m twine upload --repository testpypi dist/* --verbose

• Upload to the production repository

python3 -m twine upload dist/*

Post-Deploy

• Create new github release with new version tag

• Fast-forward dev branch to the latest master commit

• Change the wrapper version on the dev branch to x.y.zb1

Images release

Hint

The images documentation must be aligned with the images features. Make sure to add code to the appropriate Exegol docs branch and have a pull request ready. The docs PR can be merged once the images are released.

Prepare changes

The first step consists in preparing the dev branch for merge.

1. create a pull request dev -> main named Release X.Y.Z (Release X.Y.ZbI is also accepted, X, Y, Z and I being numbers. Creating this pull request will trigger the pre-release workflows. The PR comment must indicate all major changes.

2. edit the dev branch until the pull requests checks (pipeline) all pass, effectively publishing all images to the preproduction Dockerhub registry

3. once all checks are good, the PR needs to be approved by a maintainer.

Merge changes

Once the PR is approved and ready for merge, it can be merged

1. merge the PR with Create a merge commit

2. Synchronize the dev branch with the latest main update with a fast-forward merge

git checkout main
git pull --all
git checkout dev
git pull --all
git merge --ff-only main
git push

New tag

The X.Y.Z (or X.Y.ZbI) tag then needs to be placed on the same commit the dev and main branches point to.

Optionally, the “Annotated Tag Message” can be set to the PR initial comment with the --file message.txt argument in the git tag command below.

git tag "X.Y.Z"
git push origin --tags

Puhing this tag will trigger the release workflow. Simply put, the workflow will migrate the images from preprod registry to production registry.

Maintainers needs to make sure workflow goes as planned and images end up in the prod Dockerhub registry. If the release fails for some reason, the tag can be deleted, changes pushed, and then the tag can be created again to trigger the release again (git tag -d "X.Y.Z" && git push --delete origin "X.Y.Z").

Publish release

The final step is to create a “release” in github (https://github.com/ThePorgs/Exegol-images/releases/new).

1. The release must point to the tag created before.

2. The release must be named Exegol images X.Y.Z.

3. The release notes can be created with the Generate releases notes button.

4. Set it as latest release.

5. Publish

CI/CD Pipeline

The Exegol project relies on a continuous integration and continuous deployment (CI/CD) pipeline for multiple scenarios. At the time of writing, Tue 31 Jan 2023, the pipeline is structured as follows:

wrapperimagesresourcesdocs

The GitHub Actions platform is used on the Exegol module. Its workflows are used for internal and external pull requests, new releases and testing on every commit. The workflows build, and push Python packages on the official PyPI registry, and run tests to make sure everything works as it should.

GitHub Actions

The GitHub Actions pipeline(s) need runners to operate the various jobs configured for each workflow. The Exegol project relies on self-hosted runners instead of the GitHub-hosted runners mainly for costing reasons.

At the time of writing, Tue 31 Jan 2023, the Exegol-images pipeline(s) require ARM64 and AMD64 runners in order to build, and run corresponding architectured images.

1. Setting up secrets

There are some operations that the runner will operate that will require authentication, including: - pushing Python packages on PyPI - pushing Docker images on Dockerhub

In order to allow this, GitHub Actions can be set up with secrets that the runner will be able to use later on. This part of the documentation shows what secrets must be set up and how.

PyPIDockerhub

API Tokens can be created in the maintainer account’s PyPI account settings, in the API Tokens part. The scope must be set to Project: Exegol. The tokens are linked to the personal PyPI account.

Once the token is created, it can be added as follows:

• For Exegol-images, go to the Exegol-images repo settings > secrets > actions. At the time of writing, 11 Feb. 2023, Dockerhub secrets are named DOCKER_USERNAME and DOCKER_PASSWORD in the workflows.

• For the Python wrapper, go to the Exegol repo settings > secrets > actions. At the time of writing, 11 Feb. 2023, the PyPI token is named PYPI_API_TOKEN in the workflows.

2. Deploying a runner

The runner can either run on macOS, Linux, or Windows, as those three operating systems are supporting by the GHA (GitHub Action) platform. x64 and ARM64 are supported for macOS and Windows, and for Linux, ARM is supported as well.

Below are the hardware requirements for each runner:

• enough RAM (to be defined)

• enough CPU (to be defined)

• enough free disk space (at least ~100GB, bare minimum)

Before deploying a GHA agent on a runner, software requirements must be met:

• Docker (or Docker Desktop for Windows and macOS)

• jq (lightweight and flexible command-line JSON processor)

LinuxmacOS

For Linux systems, Docker is required in order to have the GitHub Actions agent running.

Tip

Docker can be installed quickly and easily with the following command-line:

curl -fsSL "https://get.docker.com/" -o get-docker.sh
sh get-docker.sh

Warning

To run exegol from the user environment without sudo, the user must have privileged rights equivalent to root. To grant yourself these rights, you can use the following command

# add the sudo group to the user
sudo usermod -aG docker $(id -u -n)

# "reload" the user groups
newgrp

The jq utility is also required and can be installed with the following command line:

apt install jq

Once the requirements are met, the agent can be deployed as follows (with sufficient permissions in the GitHub repository):

• go to https://github.com/ThePorgs/Exegol-images/settings/actions/runners

• click on “New self-hosted runner”

• select Linux as operating system, as well as the right architecture and follow the instructions

• when running the config.sh script, the following settings must be set

  • name of the runner group: Default

  • name of the runner: up to you

  • additional labels: builder,tester (adapt this if the runner is to be used for only one of those actions). If the runner is an X64/AMD64, the AMD64 tag needs to be set as well. If the runner is ARM64, the right tag will be set automatically.

  • name of work folder: up to you

• start the runner with the run.sh script

• (option) configure the agent as a service if it is to be run unattended/headless with sudo ./svc.sh install <user>, more info at https://docs.github.com/en/actions/hosting-your-own-runners/configuring-the-self-hosted-runner-application-as-a-service

Note

When configuring the agent as a service, it will be enabled, meaning it will start at boot. The systemctl is-enabled command should return enabled.

sudo systemctl is-enabled actions.runner.ThePorgs-Exegol-images.<runner-name>.service

In order to start the service, either reboot the runner, or use systemctl.

sudo systemctl start actions.runner.ThePorgs-Exegol-images.<runner-name>.service

Note

Screenshots annotated with https://annotely.com/

3. Checking runners status

Go to https://github.com/ThePorgs/Exegol-images/settings/actions/runners

4. Understanding the pipelines

TODO explain the pipelines, include diagrams.

4. Common errors

1. docker login

When configuring a macOS agent as a service with ./svc.sh install, the following error was met during workflow run.

Run docker/login-action@v2
with:
    username: ***
    password: ***
    ecr: auto
    logout: true
Logging into Docker Hub...
Error: Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `User interaction is not allowed.``

In order to avoid that error, the runner was started interactively with ./run.sh.

2. Disk space

When there’s not enough disk space, the following error is usually raised by the pipelines.

You are running out of disk space. The runner will stop working when the machine runs out of disk space. Free space left: 62 MB

Pull Requests

When handling pull requests, maintainers may need to synchronize a contributor’s fork with latests changes. In command-line, this can be achieved as follows.

git clone "git@github.com:USER/FORK" "dest_dir"
cd dest_dir
git remote add upstream "git@github.com:ThePorgs/REPO"
git fetch upstream
git checkout "TARGET_FORK_BRANCH"
git merge --no-edit upstream/"ORIGIN_BRANCH"
# solve conflicts if any
git push

Sponsors

Dramelac and I work at Capgemini and we thank them for believing in the project since day 1, and for allowing us to have this personal initiative keep going.

We thank HackTheBox for continuously supporting the community and for helping us financially to acquire the necessary hardware for supporting multiple architectures (AMD64, ARM64). Show some love at https://www.hackthebox.com/ !

We thank JetBrains for supporting this community project through its OpenSource support program. More information at https://jb.gg/OpenSourceSupport !