Release 4.3.0 (wrapper)

.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 "[email protected]"
           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)

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       </assets/installed_tools/lists/full_3.1.2_arm64.csv>`
-web,3.1.2,arm64,2023-12-22T12:08:45Z,:download:`web_3.1.2_arm64.csv       </assets/installed_tools/lists/web_3.1.2_arm64.csv>`
 full,3.1.2,amd64,2023-12-22T12:04:26Z,:download:`full_3.1.2_amd64.csv       </assets/installed_tools/lists/full_3.1.2_amd64.csv>`
 ad,3.1.2,arm64,2023-12-22T12:03:46Z,:download:`ad_3.1.2_arm64.csv       </assets/installed_tools/lists/ad_3.1.2_arm64.csv>`
-web,3.1.2,amd64,2023-12-22T11:46:29Z,:download:`web_3.1.2_amd64.csv       </assets/installed_tools/lists/web_3.1.2_amd64.csv>`
 ad,3.1.2,amd64,2023-12-22T11:41:22Z,:download:`ad_3.1.2_amd64.csv       </assets/installed_tools/lists/ad_3.1.2_amd64.csv>`
+web,3.1.2,arm64,2023-12-22T12:08:45Z,:download:`web_3.1.2_arm64.csv       </assets/installed_tools/lists/web_3.1.2_arm64.csv>`
+web,3.1.2,amd64,2023-12-22T11:46:29Z,:download:`web_3.1.2_amd64.csv       </assets/installed_tools/lists/web_3.1.2_amd64.csv>`
 light,3.1.2,arm64,2023-12-22T00:48:17Z,:download:`light_3.1.2_arm64.csv       </assets/installed_tools/lists/light_3.1.2_arm64.csv>`
-osint,3.1.2,arm64,2023-12-22T00:43:53Z,:download:`osint_3.1.2_arm64.csv       </assets/installed_tools/lists/osint_3.1.2_arm64.csv>`
 light,3.1.2,amd64,2023-12-22T00:08:53Z,:download:`light_3.1.2_amd64.csv       </assets/installed_tools/lists/light_3.1.2_amd64.csv>`
+osint,3.1.2,arm64,2023-12-22T00:43:53Z,:download:`osint_3.1.2_arm64.csv       </assets/installed_tools/lists/osint_3.1.2_arm64.csv>`
 osint,3.1.2,amd64,2023-12-22T00:02:50Z,:download:`osint_3.1.2_amd64.csv       </assets/installed_tools/lists/osint_3.1.2_amd64.csv>`
-ad,3.1.1,amd64,2023-08-18T02:59:03Z,:download:`ad_3.1.1_amd64.csv     </assets/installed_tools/lists/ad_3.1.1_amd64.csv>`
-ad,3.1.1,arm64,2023-08-18T02:58:49Z,:download:`ad_3.1.1_arm64.csv     </assets/installed_tools/lists/ad_3.1.1_arm64.csv>`
 full,3.1.1,amd64,2023-08-18T01:36:37Z,:download:`full_3.1.1_amd64.csv     </assets/installed_tools/lists/full_3.1.1_amd64.csv>`
 full,3.1.1,arm64,2023-08-18T01:36:23Z,:download:`full_3.1.1_arm64.csv     </assets/installed_tools/lists/full_3.1.1_arm64.csv>`
+ad,3.1.1,amd64,2023-08-18T02:59:03Z,:download:`ad_3.1.1_amd64.csv     </assets/installed_tools/lists/ad_3.1.1_amd64.csv>`
+ad,3.1.1,arm64,2023-08-18T02:58:49Z,:download:`ad_3.1.1_arm64.csv     </assets/installed_tools/lists/ad_3.1.1_arm64.csv>`
+web,3.1.1,arm64,2023-08-18T01:08:44Z,:download:`web_3.1.1_arm64.csv     </assets/installed_tools/lists/web_3.1.1_arm64.csv>`
 web,3.1.1,amd64,2023-08-18T01:35:14Z,:download:`web_3.1.1_amd64.csv     </assets/installed_tools/lists/web_3.1.1_amd64.csv>`
-light,3.1.1,amd64,2023-08-18T01:35:00Z,:download:`light_3.1.1_amd64.csv     </assets/installed_tools/lists/light_3.1.1_amd64.csv>`
+osint,3.1.1,arm64,2023-08-18T01:04:50Z,:download:`osint_3.1.1_arm64.csv     </assets/installed_tools/lists/osint_3.1.1_arm64.csv>`
 osint,3.1.1,amd64,2023-08-18T01:34:47Z,:download:`osint_3.1.1_amd64.csv     </assets/installed_tools/lists/osint_3.1.1_amd64.csv>`
-web,3.1.1,arm64,2023-08-18T01:08:44Z,:download:`web_3.1.1_arm64.csv     </assets/installed_tools/lists/web_3.1.1_arm64.csv>`
 light,3.1.1,arm64,2023-08-18T01:05:12Z,:download:`light_3.1.1_arm64.csv     </assets/installed_tools/lists/light_3.1.1_arm64.csv>`
-osint,3.1.1,arm64,2023-08-18T01:04:50Z,:download:`osint_3.1.1_arm64.csv     </assets/installed_tools/lists/osint_3.1.1_arm64.csv>`
+light,3.1.1,amd64,2023-08-18T01:35:00Z,:download:`light_3.1.1_amd64.csv     </assets/installed_tools/lists/light_3.1.1_amd64.csv>`
+full,3.1.0,arm64,2023-08-09T09:12:21Z,:download:`full_3.1.0_arm64.csv     </assets/installed_tools/lists/full_3.1.0_arm64.csv>`
+full,3.1.0,amd64,2023-08-09T22:27:20Z,:download:`full_3.1.0_amd64.csv     </assets/installed_tools/lists/full_3.1.0_amd64.csv>`
 ad,3.1.0,amd64,2023-08-10T00:33:47Z,:download:`ad_3.1.0_amd64.csv     </assets/installed_tools/lists/ad_3.1.0_amd64.csv>`
 ad,3.1.0,arm64,2023-08-10T00:11:36Z,:download:`ad_3.1.0_arm64.csv     </assets/installed_tools/lists/ad_3.1.0_arm64.csv>`
 web,3.1.0,amd64,2023-08-09T11:12:12Z,:download:`web_3.1.0_amd64.csv     </assets/installed_tools/lists/web_3.1.0_amd64.csv>`
 web,3.1.0,arm64,2023-08-09T11:11:33Z,:download:`web_3.1.0_arm64.csv     </assets/installed_tools/lists/web_3.1.0_arm64.csv>`
 osint,3.1.0,amd64,2023-08-09T10:50:11Z,:download:`osint_3.1.0_amd64.csv     </assets/installed_tools/lists/osint_3.1.0_amd64.csv>`
 osint,3.1.0,arm64,2023-08-09T10:48:56Z,:download:`osint_3.1.0_arm64.csv     </assets/installed_tools/lists/osint_3.1.0_arm64.csv>`
-full,3.1.0,arm64,2023-08-09T09:12:21Z,:download:`full_3.1.0_arm64.csv     </assets/installed_tools/lists/full_3.1.0_arm64.csv>`
-full,3.1.0,amd64,2023-08-09T22:27:20Z,:download:`full_3.1.0_amd64.csv     </assets/installed_tools/lists/full_3.1.0_amd64.csv>`
 light,3.1.0,amd64,2023-08-09T02:53:53Z,:download:`light_3.1.0_amd64.csv     </assets/installed_tools/lists/light_3.1.0_amd64.csv>`
 light,3.1.0,arm64,2023-08-09T01:50:40Z,:download:`light_3.1.0_arm64.csv     </assets/installed_tools/lists/light_3.1.0_arm64.csv>`

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)

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 </exegol-wrapper/start>`. (Default: ``True``)
+
 
 
 My-resources

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.
 =================== =============
 
 

source/exegol-wrapper/start.rst

@@ -37,27 +37,46 @@ 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<exegol_configuration>`.
 
+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/).
+``-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 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:<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.
 
 ========================= ===============================
@@ -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
 
 =============================== ===============================

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 <feature_desktop>` instead of X11 sharing (join our Discord to know more about this beta feature).
 
         * `XQuartz <https://www.xquartz.org/>`__ must be installed
         * The XQuartz config ``Allow connections from network clients`` must be set to true
@@ -139,7 +139,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\<user>\.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\<username>\AppData\Local\Temp``).
+
+            You should also add the folder ``C:\Users\<user>\.exegol\exegol-resources`` to the exclution list.
 
     ..  group-tab:: Installing from sources
 
@@ -149,6 +151,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.
 
@@ -334,11 +344,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 <https://stackoverflow.com/a/62823029>`__ | `MacOS <https://stackoverflow.com/a/43368894>`__ | `Windows <https://builtin.com/software-engineering-perspectives/pip-command-not-found>`__
+                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`: