Skip to content

[pull] master from kevoreilly:master #520

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pull merged 1 commit into from
Aug 15, 2026
Merged

[pull] master from kevoreilly:master #520

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 22 additions & 27 deletions docs/book/src/installation/guest/linux.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,41 +31,36 @@ avoid having to start as root, e.g.::
with your user. You also have a script in utils/linux_mktaps.sh**


Preparing x32/x64 Linux guests
===========================================
Preparing Linux guests (32-bit & 64-bit)
========================================

.. warning::
Historically, Windows-focused sandbox tools required 32-bit Python runtimes. However, for Linux guests in CAPEv2, **using 32-bit Python on a 64-bit system is not required and is highly discouraged.**

For Linux guests on an Azure hypervisor, installing Python3 32-bit breaks the way that the Azure agent starts: https://docs.microsoft.com/en-us/azure/virtual-machines/extensions/agent-linux#installation.
So the use of the monitor is limited to what can be run with the 64-bit version of Python3. You will have to comment out the architecture check in the CAPE `agent.py` for the CAPE agent to start. To
reiterate, this warning is only relevant if you are using an Azure hypervisor.
Attempting to force-install 32-bit Python (via ``dpkg --add-architecture i386`` and ``apt install python3:i386``) on a 64-bit Linux guest (e.g., Ubuntu x86_64) will swap out the native 64-bit system Python. This conflicts with core system packages and breaks the operating system, making it impossible to boot the graphical desktop/UI interface (e.g., GNOME/GDM) or use standard system utilities.

x32 guests
----------
Install support file dependencies::
For all modern 64-bit (x86_64) Linux guests, you should use the native, standard 64-bit Python 3.

.. note::
Starting with Python 3.12 (default on Ubuntu 24.04 LTS and later), ``distutils`` has been completely removed from the standard library. The package ``python3-distutils`` is no longer available in package repositories and is not required by CAPEv2's guest agent or Linux analyzer. If any of your custom scripts require it, you can install ``python3-setuptools`` instead.

.. note::
On newer Linux distributions (Debian 12+, Ubuntu 23.04+), PIP blocks system-wide package installations by default under PEP 668 to avoid corrupting OS packages. Since the guest VM is a disposable sandbox environment, you can safely bypass this warning using the ``--break-system-packages`` flag.

32-bit (i386) guests
--------------------
Install support file dependencies using native 32-bit packages::

$ sudo apt update
$ sudo apt install python3-pip systemtap-runtime
$ sudo pip3 install pyinotify
$ sudo pip3 install Pillow # optional
$ sudo pip3 install pyscreenshot # optional
$ sudo pip3 install pyautogui # optional
$ sudo apt install python3-pip systemtap-runtime -y
$ sudo pip3 install pyinotify Pillow pyscreenshot pyautogui --break-system-packages

x64 guests
----------
Install support file dependencies (we need Python3 32-bit)::
64-bit (x86_64 / amd64) guests
------------------------------
Install support file dependencies using standard native 64-bit packages::

$ sudo dpkg --add-architecture i386
$ sudo apt update
$ sudo apt install python3:i386 -y
$ sudo apt install python3-distutils -y
$ sudo apt install systemtap-runtime -y
$ curl -sSL https://bootstrap.pypa.io/get-pip.py -o get-pip.py
$ sudo python3 get-pip.py
$ sudo python3 -m pip install pyinotify
$ sudo python3 -m pip install Pillow # optional
$ sudo python3 -m pip install pyscreenshot # optional
$ sudo python3 -m pip install pyautogui # optional
$ sudo apt install python3 python3-pip systemtap-runtime -y
$ sudo pip3 install pyinotify Pillow pyscreenshot pyautogui --break-system-packages

Ensure the agent automatically starts. The easiest way is to add it to crontab::

Expand Down
28 changes: 28 additions & 0 deletions web/templates/submission/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -762,6 +762,10 @@ <h5 class="mb-0 text-white"><i class="fas fa-cogs me-2 text-primary"></i>Advance
<td class="text-end"><code>unhook-apis</code></td>
<td>Dynamically unhook functions (colon-separated)</td>
</tr>
<tr>
<td class="text-end"><code>unhook-on-terminate</code></td>
<td>Restore all hooked API original bytes to memory when the process terminates</td>
</tr>
<tr>
<td class="text-end"><code>coverage-modules</code></td>
<td>Colon-separated list of DLLs to include in monitoring (exclude from 'dll range' filtering)</td>
Expand Down Expand Up @@ -821,6 +825,18 @@ <h5 class="mb-0 text-white"><i class="fas fa-cogs me-2 text-primary"></i>Advance
<td class="text-end"><code>amsidump</code></td>
<td>Enable AMSI buffer dumping (Win10+)</td>
</tr>
<tr>
<td class="text-end"><code>yarascan</code></td>
<td>Enable in-memory YARA scanning of process memory and JIT-compiled native code</td>
</tr>
<tr>
<td class="text-end"><code>yara-timeout</code></td>
<td>Timeout limit in milliseconds for in-memory YARA scanning (default: 60000)</td>
</tr>
<tr>
<td class="text-end"><code>dumpsize</code></td>
<td>Maximum size in bytes allowed for a single raw memory dump</td>
</tr>
<tr>
<td class="text-end"><code>tlsdump</code></td>
<td>Enable dumping of TLS secrets</td>
Expand Down Expand Up @@ -896,6 +912,18 @@ <h5 class="mb-0 text-white"><i class="fas fa-cogs me-2 text-primary"></i>Advance
<td class="text-end"><code>break-on-return</code></td>
<td>Break on return from specific APIs</td>
</tr>
<tr>
<td class="text-end"><code>break-on-jit</code></td>
<td>Break on .NET JIT compiled native code</td>
</tr>
<tr>
<td class="text-end"><code>softbpmode</code></td>
<td>Execution mode behavior for software breakpoints</td>
</tr>
<tr>
<td class="text-end"><code>idbg</code></td>
<td>Enable interactive remote debugger interface / locks</td>
</tr>
<tr>
<td class="text-end"><code>base-on-api</code></td>
<td>Set base address for breakpoints based on API</td>
Expand Down
Loading