From a4f7234c77db3bacba07d05dd58ccd65a64f76e5 Mon Sep 17 00:00:00 2001 From: Dramelac Date: Thu, 21 Dec 2023 17:50:40 +0100 Subject: [PATCH 1/7] Add new feature, configs and parameters --- source/exegol-wrapper/advanced-uses.rst | 8 +++++ source/exegol-wrapper/install.rst | 1 + source/exegol-wrapper/start.rst | 31 ++++++++++++++++++-- source/the-exegol-project/python-wrapper.rst | 18 ++++++++++++ 4 files changed, 55 insertions(+), 3 deletions(-) diff --git a/source/exegol-wrapper/advanced-uses.rst b/source/exegol-wrapper/advanced-uses.rst index 970ec12..a9e3239 100644 --- a/source/exegol-wrapper/advanced-uses.rst +++ b/source/exegol-wrapper/advanced-uses.rst @@ -58,6 +58,14 @@ Within the ``~/.exegol/config.yml`` file, several settings can be configured to * ``logging_method``: Choice of the method used to record the sessions, ``script`` or ``asciinema``. (Default: ``asciinema``) * ``enable_log_compression``: Enable automatic compression of log files (with gzip). (Default: ``True``) + .. tab:: Desktop + + Change the configuration of the virtual Desktop feature. + + * ``enabled_by_default``: Enables or not the desktop mode by default. If this attribute is set to True, then using the CLI ``--desktop`` option will be inverted and will **DISABLE** the feature (Default: ``False``) + * ``default_protocol``: Default desktop protocol,can be ``http``, or ``vnc`` depending on your wrapper / image version. (Default: ``http``) + * ``localhost_by_default``: Desktop service is exposed on localhost by default. If set to true, services will be exposed on ``localhost`` (127.0.0.1) otherwise it will be exposed on ``0.0.0.0``. This setting can be overwritten with :doc:`--desktop-config `. (Default: ``True``) + My-resources diff --git a/source/exegol-wrapper/install.rst b/source/exegol-wrapper/install.rst index c1a54ff..3f6f5bf 100644 --- a/source/exegol-wrapper/install.rst +++ b/source/exegol-wrapper/install.rst @@ -25,6 +25,7 @@ Options ``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. =================== ============= diff --git a/source/exegol-wrapper/start.rst b/source/exegol-wrapper/start.rst index 2c162cc..b5d7ca7 100644 --- a/source/exegol-wrapper/start.rst +++ b/source/exegol-wrapper/start.rst @@ -37,6 +37,9 @@ Many options exist to customize the creation of exegol container. .. tip:: The default options of some commands can be changed in the :ref:`exegol configuration file`. +Global options +~~~~~~~~~~~~~~ + =========================================================== =============================== Option Description =========================================================== =============================== @@ -44,20 +47,36 @@ Many options exist to customize the creation of 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/). +``-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 [:][:][:]. This configuration will disable the shared network with the host. ``--hostname HOSTNAME`` Set a custom hostname to the exegol container (default: exegol-) ``--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 display sharing to run GUI-based applications. (default: Enabled) +``--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) =========================================================== =============================== -An additional feature of Exegol is the addition of a VPN tunnel option (OpenVPN). +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:) +========================= =============================== + +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. ========================= =============================== @@ -72,6 +91,9 @@ Just provide an ovpn configuration to exegol and the container will take care of 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). @@ -86,6 +108,9 @@ This feature allows the user to record **everything** that happens in the exegol .. 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 =============================== =============================== diff --git a/source/the-exegol-project/python-wrapper.rst b/source/the-exegol-project/python-wrapper.rst index d76a19c..45e341c 100644 --- a/source/the-exegol-project/python-wrapper.rst +++ b/source/the-exegol-project/python-wrapper.rst @@ -25,6 +25,7 @@ Below is a, non-exhaustive, list of what the wrapper supports: Feature Description =================================================== ============= :ref:`Display sharing` Sharing of the graphic environment between the container and the host +:ref:`Desktop` Hosts a complete graphics environment available via a web page or VNC :ref:`Workspace` Persistent and shared workspace with the host :ref:`Update-fs` Permission sharing between the container and the host :ref:`OpenVPN connection` Opening an isolated VPN tunnel dedicated to the exegol container @@ -72,6 +73,23 @@ For example, if bloodhound is launched in an exegol container, the graphical win This feature can be disabled manually with the option ``--disable-X11`` of the :ref:`start action `. +.. _feature_desktop: + +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 :ref:`start action `. + +.. tip:: + + The default behavior and configuration of the desktop mode can be changed in the :ref:`configuration of Exegol`. + .. _feature_workspace: Workspace From 11d1164e7732fc1c2d0bdb7b1f24ca419e2b280e Mon Sep 17 00:00:00 2001 From: Dramelac Date: Thu, 21 Dec 2023 17:51:07 +0100 Subject: [PATCH 2/7] Update wrapper install docs --- source/getting-started/install.rst | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/source/getting-started/install.rst b/source/getting-started/install.rst index e2e30fe..8f96acf 100644 --- a/source/getting-started/install.rst +++ b/source/getting-started/install.rst @@ -135,7 +135,9 @@ The installation of Exegol on Linux, macOS and Windows are very similar. It can .. warning:: - You may want to disable Windows Defender during the installation, as Exegol will download pre-built remote shells. You should also add the folder ``C:\Users\\.exegol\exegol-resources`` to the exclution list. + You may want to disable Windows Defender during the installation, as Exegol will download pre-built remote shells (or temporarily exclude ``C:\Users\\AppData\Local\Temp``). + + You should also add the folder ``C:\Users\\.exegol\exegol-resources`` to the exclution list. .. group-tab:: Installing from sources @@ -145,6 +147,14 @@ The installation of Exegol on Linux, macOS and Windows are very similar. It can git clone "https://github.com/ThePorgs/Exegol" + .. tip:: + + If you want a **light** clone of Exegol (and **never** use the **dev** branch), you can use the following command: + + .. code-block:: bash + + git clone --shallow-since="2023/05/08" "https://github.com/ThePorgs/Exegol" + If you have access to docker directly as a user, you can install the requirements only for your current user otherwise the requirements must be installed as root to run Exegol with sudo. @@ -330,11 +340,13 @@ Exegol (wrapper) supports auto-completion in many shell environments but there i .. code-block:: powershell - python $HOME\AppData\Roaming\Python\Python311\Scripts\register-python-argcomplete --no-defaults --shell powershell exegol > $HOME\Documents\WindowsPowerShell\exegol_completion.psm1 + register-python-argcomplete --no-defaults --shell powershell exegol > $HOME\Documents\WindowsPowerShell\exegol_completion.psm1 - .. important:: + .. warning:: - `Python311` can be modified and depends on the version of Python you have installed + If the command ``register-python-argcomplete`` is not found, that means that python pip script are not in your PATH. + You can ty to fix your pip installation: `Linux `__ | `MacOS `__ | `Windows `__ + Or find the direct Python script path, it might be something like: ``$HOME\AppData\Roaming\Python\Python311\Scripts\register-python-argcomplete`` (``Python311`` PATH depends on the version of Python you have installed, it must be updated to match your local setup). Then import this completion file in `$PROFILE`: From e7cee61943fd3e040752ea60c8e6092c274c794e Mon Sep 17 00:00:00 2001 From: Dramelac Date: Fri, 22 Dec 2023 15:24:35 +0100 Subject: [PATCH 3/7] Handle merge conflict --- .github/workflows/automerger.yml | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/.github/workflows/automerger.yml b/.github/workflows/automerger.yml index 0f14759..24ad437 100644 --- a/.github/workflows/automerger.yml +++ b/.github/workflows/automerger.yml @@ -11,25 +11,27 @@ jobs: timeout-minutes: 5 runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Set Git config run: | git config --local user.email "actions@github.com" git config --local user.name "Github Actions" git fetch --unshallow - # TODO handling conflict / skip etc - name: Merge main back to dev + continue-on-error: true run: | git checkout dev git pull - git merge main --ff -m "Auto-update dev from main" && git push || echo "Unable to automatically merge dev" + git merge main --ff -m "Auto-update dev from main" && git push || (echo "Unable to automatically merge dev" && git merge --abort && exit 1) - name: Merge main back to dev-wrapper + continue-on-error: true run: | git checkout dev-wrapper git pull - git merge main --ff -m "Auto-update dev-wrapper from main" && git push || echo "Unable to automatically merge dev-wrapper" + git merge main --ff -m "Auto-update dev-wrapper from main" && git push || (echo "Unable to automatically merge dev-wrapper" && git merge --abort && exit 1) - name: Merge main back to dev-images + continue-on-error: true run: | git checkout dev-images git pull - git merge main --ff -m "Auto-update dev-images from main" && git push || echo "Unable to automatically merge dev-images" + git merge main --ff -m "Auto-update dev-images from main" && git push || (echo "Unable to automatically merge dev-images" && git merge --abort && exit 1) From a942ce6386137a23d70a73002286d8125a44fd9a Mon Sep 17 00:00:00 2001 From: Dramelac Date: Fri, 22 Dec 2023 15:28:59 +0100 Subject: [PATCH 4/7] Reorder tool list release --- source/assets/installed_tools/releases.csv | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/assets/installed_tools/releases.csv b/source/assets/installed_tools/releases.csv index 5189ff9..3ca9c9d 100644 --- a/source/assets/installed_tools/releases.csv +++ b/source/assets/installed_tools/releases.csv @@ -1,31 +1,31 @@ Image tag,Version,Arch,Build date,Tools list full,3.1.2,arm64,2023-12-22T12:20:18Z,:download:`full_3.1.2_arm64.csv ` -web,3.1.2,arm64,2023-12-22T12:08:45Z,:download:`web_3.1.2_arm64.csv ` full,3.1.2,amd64,2023-12-22T12:04:26Z,:download:`full_3.1.2_amd64.csv ` ad,3.1.2,arm64,2023-12-22T12:03:46Z,:download:`ad_3.1.2_arm64.csv ` -web,3.1.2,amd64,2023-12-22T11:46:29Z,:download:`web_3.1.2_amd64.csv ` ad,3.1.2,amd64,2023-12-22T11:41:22Z,:download:`ad_3.1.2_amd64.csv ` +web,3.1.2,arm64,2023-12-22T12:08:45Z,:download:`web_3.1.2_arm64.csv ` +web,3.1.2,amd64,2023-12-22T11:46:29Z,:download:`web_3.1.2_amd64.csv ` light,3.1.2,arm64,2023-12-22T00:48:17Z,:download:`light_3.1.2_arm64.csv ` -osint,3.1.2,arm64,2023-12-22T00:43:53Z,:download:`osint_3.1.2_arm64.csv ` light,3.1.2,amd64,2023-12-22T00:08:53Z,:download:`light_3.1.2_amd64.csv ` +osint,3.1.2,arm64,2023-12-22T00:43:53Z,:download:`osint_3.1.2_arm64.csv ` osint,3.1.2,amd64,2023-12-22T00:02:50Z,:download:`osint_3.1.2_amd64.csv ` -ad,3.1.1,amd64,2023-08-18T02:59:03Z,:download:`ad_3.1.1_amd64.csv ` -ad,3.1.1,arm64,2023-08-18T02:58:49Z,:download:`ad_3.1.1_arm64.csv ` full,3.1.1,amd64,2023-08-18T01:36:37Z,:download:`full_3.1.1_amd64.csv ` full,3.1.1,arm64,2023-08-18T01:36:23Z,:download:`full_3.1.1_arm64.csv ` +ad,3.1.1,amd64,2023-08-18T02:59:03Z,:download:`ad_3.1.1_amd64.csv ` +ad,3.1.1,arm64,2023-08-18T02:58:49Z,:download:`ad_3.1.1_arm64.csv ` +web,3.1.1,arm64,2023-08-18T01:08:44Z,:download:`web_3.1.1_arm64.csv ` web,3.1.1,amd64,2023-08-18T01:35:14Z,:download:`web_3.1.1_amd64.csv ` -light,3.1.1,amd64,2023-08-18T01:35:00Z,:download:`light_3.1.1_amd64.csv ` +osint,3.1.1,arm64,2023-08-18T01:04:50Z,:download:`osint_3.1.1_arm64.csv ` osint,3.1.1,amd64,2023-08-18T01:34:47Z,:download:`osint_3.1.1_amd64.csv ` -web,3.1.1,arm64,2023-08-18T01:08:44Z,:download:`web_3.1.1_arm64.csv ` light,3.1.1,arm64,2023-08-18T01:05:12Z,:download:`light_3.1.1_arm64.csv ` -osint,3.1.1,arm64,2023-08-18T01:04:50Z,:download:`osint_3.1.1_arm64.csv ` +light,3.1.1,amd64,2023-08-18T01:35:00Z,:download:`light_3.1.1_amd64.csv ` +full,3.1.0,arm64,2023-08-09T09:12:21Z,:download:`full_3.1.0_arm64.csv ` +full,3.1.0,amd64,2023-08-09T22:27:20Z,:download:`full_3.1.0_amd64.csv ` ad,3.1.0,amd64,2023-08-10T00:33:47Z,:download:`ad_3.1.0_amd64.csv ` ad,3.1.0,arm64,2023-08-10T00:11:36Z,:download:`ad_3.1.0_arm64.csv ` web,3.1.0,amd64,2023-08-09T11:12:12Z,:download:`web_3.1.0_amd64.csv ` web,3.1.0,arm64,2023-08-09T11:11:33Z,:download:`web_3.1.0_arm64.csv ` osint,3.1.0,amd64,2023-08-09T10:50:11Z,:download:`osint_3.1.0_amd64.csv ` osint,3.1.0,arm64,2023-08-09T10:48:56Z,:download:`osint_3.1.0_arm64.csv ` -full,3.1.0,arm64,2023-08-09T09:12:21Z,:download:`full_3.1.0_arm64.csv ` -full,3.1.0,amd64,2023-08-09T22:27:20Z,:download:`full_3.1.0_amd64.csv ` light,3.1.0,amd64,2023-08-09T02:53:53Z,:download:`light_3.1.0_amd64.csv ` light,3.1.0,arm64,2023-08-09T01:50:40Z,:download:`light_3.1.0_arm64.csv ` From 0385f6790655f91738eb474809fef193a47fd6c8 Mon Sep 17 00:00:00 2001 From: Dramelac Date: Fri, 22 Dec 2023 15:35:21 +0100 Subject: [PATCH 5/7] Fix my-resource CA path --- source/exegol-image/my-resources.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/exegol-image/my-resources.rst b/source/exegol-image/my-resources.rst index 41662ec..dd9adbf 100644 --- a/source/exegol-image/my-resources.rst +++ b/source/exegol-image/my-resources.rst @@ -90,7 +90,7 @@ To automatically: The output will be saved into the single file ``~/.config/bloodhound/customqueries.json``. -:code:`firefox` (addons, certs) +:code:`firefox` (addons, CA) ~~~~~~~~~~~~~~~~~~~~~~~~ .. seealso:: Available from version ``3.0.2`` of any exegol image. @@ -104,7 +104,7 @@ The ``.xpi`` files in ``/opt/my-resources/setup/firefox/addons/`` folder will be .. seealso:: Below, available from version ``3.2.0`` of any exegol image. -The ``.der`` files in ``/opt/my-resources/setup/firefox/certs/`` folder will be trusted . +The ``.der`` files in ``/opt/my-resources/setup/firefox/CA/`` folder will be trusted . :code:`python3` (pip3) From 06565cac6ccd25359b0aa8253c9730335ae2787f Mon Sep 17 00:00:00 2001 From: Dramelac Date: Fri, 22 Dec 2023 15:35:39 +0100 Subject: [PATCH 6/7] Add desktop feature ref --- source/getting-started/install.rst | 2 +- source/the-exegol-project/python-wrapper.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/getting-started/install.rst b/source/getting-started/install.rst index 263000f..4e28400 100644 --- a/source/getting-started/install.rst +++ b/source/getting-started/install.rst @@ -68,7 +68,7 @@ Additional dependencies may be required depending on the host OS. .. hint:: - The XQuartz requirement below is now optional if using the (beta) Graphical Remote Desktop feature instead of X11 sharing (join our Discord to know more about this beta feature). + The XQuartz requirement below is now optional if using the (beta) :ref:`Graphical Remote Desktop feature ` instead of X11 sharing (join our Discord to know more about this beta feature). * `XQuartz `__ must be installed * The XQuartz config ``Allow connections from network clients`` must be set to true diff --git a/source/the-exegol-project/python-wrapper.rst b/source/the-exegol-project/python-wrapper.rst index 40cc5c1..b06061c 100644 --- a/source/the-exegol-project/python-wrapper.rst +++ b/source/the-exegol-project/python-wrapper.rst @@ -67,7 +67,7 @@ The Exegol wrapper has many features to automatically and transparently manage d 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 to X11 sharing. +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. From 2e278459fbe0be97e9d92d89658505b4f0fe1a5f Mon Sep 17 00:00:00 2001 From: Dramelac Date: Fri, 22 Dec 2023 15:37:59 +0100 Subject: [PATCH 7/7] Improve automerge safe exit pipeline --- .github/workflows/automerger.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/automerger.yml b/.github/workflows/automerger.yml index 24ad437..9684049 100644 --- a/.github/workflows/automerger.yml +++ b/.github/workflows/automerger.yml @@ -22,16 +22,16 @@ jobs: run: | git checkout dev git pull - git merge main --ff -m "Auto-update dev from main" && git push || (echo "Unable to automatically merge dev" && git merge --abort && exit 1) + git merge main --ff -m "Auto-update dev from main" && git push || (echo "Unable to automatically merge dev" && git merge --abort; exit 1) - name: Merge main back to dev-wrapper continue-on-error: true run: | git checkout dev-wrapper git pull - git merge main --ff -m "Auto-update dev-wrapper from main" && git push || (echo "Unable to automatically merge dev-wrapper" && git merge --abort && exit 1) + git merge main --ff -m "Auto-update dev-wrapper from main" && git push || (echo "Unable to automatically merge dev-wrapper" && git merge --abort; exit 1) - name: Merge main back to dev-images continue-on-error: true run: | git checkout dev-images git pull - git merge main --ff -m "Auto-update dev-images from main" && git push || (echo "Unable to automatically merge dev-images" && git merge --abort && exit 1) + git merge main --ff -m "Auto-update dev-images from main" && git push || (echo "Unable to automatically merge dev-images" && git merge --abort; exit 1)