Exegol Docs

Appearance

Contributing to Docker Images ​

The Docker images are the heart of the Exegol project. They contain a carefully curated selection of tools, configurations, aliases, history commands, and various customizations prepared in multiple images adapted for different uses: web hacking, Active Directory, OSINT (Open Source INTelligence), etc.

Getting started ​

  1. Fork the Exegol-images repository
  2. Follow the Installation Guide to set up your development environment
  3. Checkout the dev branch
  4. (optional) create a new branch in your fork, if you plan on working on different topics
  5. Create your content using this guide
  6. Make sure your changes work locally
  7. Stage, Commit, and Push your changes
  8. Submit a Pull Request (https://github.com/ThePorgs/Exegol-images/compare)

Making changes ​

When adding a new tool to an image (or modifying a tool install function), follow these steps:

  1. Identify which package your tool installation function should go into in the packages directory.

  2. Create an installation function following this structure:

bash
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"
}

Tools directories need to be installed in /opt/tools. Binaries can be installed in /opt/tools/bin directly.

Required components ​

Your installation function should include:

  • colorecho "Installing yourtool" - For progress logging
  • catch_and_retry <command> - For commands that might fail due to network issues. Note: Most standard Internet-involved commands (git, wget, curl, go, etc.) are already transparently wrapped with catch_and_retry. You probably won't need that.
  • add-aliases yourtool - If your tool needs aliases. You will need to create the aliases file in /sources/assets/shells/aliases.d/ named after your tool. Example:
    bash
    alias tool.py='python3 /opt/tools/yourtool/tool.py'
  • add-history yourtool - For command examples. Create a history file in /sources/assets/shells/history.d/ named after your tool. Example:
    bash
    yourtool.py --user "$USER" --password "$PASSWORD" --target "$TARGET"
yourtool.py --mode enum --user "$USER" --target "$TARGET"
yourtool.py --mode unauthenticated
  • add-test-command "testcommand" - For CI/CD unit tests. The command must return 0 if successful. If --help doesn't work, try using grep: yourtool.py --help|& grep 'Usage:'
  • add-to-list "yourtool,https://link.to/the/tool,description" - For tools list export. Format is CSV with 3 columns: name, link, description. No comma allowed in description.

Code Check Whitelisting ​

If your tool doesn't need aliases or history commands, add a whitelist comment at the beginning of the function:

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

Installation methods ​

bash
# From GitHub
pipx install --system-site-packages git+https://github.com/AUTHOR/REPO

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

# if a requirement needs to be added in the tool's venv
pipx inject yourtool therequirement

Temporary fixes (tempfix) ​

Sometimes tools have issues that need temporary fixes. Here are two approaches:

bash
function install_TOOL() {
    [...]
    git -C /opt/tools/ clone --depth 1 https://github.com/REPO/TOOL.git
    local temp_fix_limit="YYYY-MM-DD"
    if check_temp_fix_expiry "$temp_fix_limit"; then
      git -C /opt/tools/TOOL fetch --unshallow
      # checkout on the commit ID before the bug was introduced
      # link to the issue: https://github.com/REPO/TOOL/issues/1337
      git -C /opt/tools/TOOL checkout 774f1c33efaaccf633ede6e704800345eb313878
    fi
    [...]
}

Multi-architecture support ​

Exegol images are built for both AMD64 and ARM64 systems. When possible, ensure your tool installation works on both architectures:

bash
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

Testing your changes ​

Before submitting a pull request, test your installation locally with a locally built exegol image (see wrapper/cli/build):

bash
# Build the local image
exegol build "testimage" "full" --build-log "/tmp/exegol_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

# Test your additions manually
...
Recover disk space after failed custom image builds

When building a custom Exegol image, failed builds can leave intermediate layers and artifacts on the system. These leftovers are not automatically removed and can consume a significant amount of disk space.

To safely free up space, use the following command:

bash
docker image prune          # remove dangling images

Additional resources ​

Last updated: