Skip to content

Installation

Jump to bottom
b0rdst31n edited this page Nov 14, 2024 · 19 revisions

There is a shell script provided that installs all dependencies, but it depends on apt (used by Debian-based Linux operating systems) and an available Python2.7 distribution (which isn't supported in Debian >= 12). So if you have a running Linux (sub-)system and it is Debian-based and < Debian 12, you can use the script without further installations. Otherwise you have to install another Linux distribution (e.g. kali-linux), get a VM or use the provided container image.

The container image can be run with tools like Podman or Docker. Please note that the sbleedy CLI tool relies on connected USB hardware, so you should be able to pass the devices through (e.g., with podman run -it --device /dev/ttyACM0 <image>), which requires some extra work when using Windows. Please refer to the section "Using the container image (without a VM)" for more instructions.

⚠️ Attention: When using Windows and your PC is routing all traffic through a Proxy/Firewall, trying to pass the USB devices to wsl (when running the tool directly or in a container in a Linux subsystem) can be an uphill battle, due to reasons like blocked TCP connections. In this case, it may be easier to use a VM and either run the container in there or run the install script in the VM. Whether on Linux or Windows, if your proxy requires a certificate, some additional work will be necessary.

Using the shell script in a (appropriate) Linux (sub-)system The shell script installs Python3.10 and Python2.7, creates virtual environments for both versions, and installs the required submodules and pip packages. After the installation, you should be able to activate the venv for Python3.10 and run the CLI tool. When Windows is your main system, you can install a Linux subsystem pretty easily using wsl, but please note that you have to share USB devices with a tool like [usbipd-win](https://github.com/dorssel/usbipd-win) to be able to use them in wsl.
  • git clone https://github.com/b0rdst31n/SbleedyGonzales.git --recurse submodules
  • cd SbleedyGonzales
  • helpers/sbleedy_installer.sh
  • Have some patience
  • If everything got installed correctly, there should now be a venv2 and venv3 folder in Sbleedy Gonzales. Then you can activate the venv3, where the sbleedy CLI tool is installed in with source venv3/bin/activate
  • Test the installation with sbleedy -h #should print usage info
Using the container image (without a VM)
  • Install a container tool of your choice (Docker, Podman, etc.)
  • ⚠️ When behind a Proxy: You may have to add the certificate to the container machine. Please refer to the documentation of the tool you chose (e.g., this for Podman).
  • Get the container image from the GitHub registry [WILL BE PROVIDED].
  • ⚠️ When using Windows: Follow these instructions to attach the connected USB devices to the container using usbipd and WSL.
  • Run the container with a bash as entrypoint and pass the connected hardware (e.g., podman run -it --device /dev/ttyACM0 <image>). When behind a proxy, you also have to add the proxy settings like this: podman run -it -e http_proxy=http://whatever.net:0000 -e https_proxy=http://whatever.net:0000 -e no_proxy=localhost,etc.int your-image-name
  • Activate the venv3 (source venv3/bin/activate).
  • Test the installation of the CLI tool by running sbleedy -h #should print usage info.
  • Test the connected hardware by running hciconfig and lsusb and confirm that your connected devices are found.
Using a VM
  1. Setup the VM:
    • Install a virtual machine of your choice (e.g., VirtualBox).
    • Download a pre-built VM for your machine (e.g., Kali Linux) and start it.
    • ⚠️ When behind a Proxy: Configure the VM to use the certificate by copying the certificate as root to /usr/local/share/ca-certificates, then update the settings with sudo update-ca-certificates --verbose.
    • ⚠️ Some virtual machines require an extension to be able to use the hardware that is connected through USB (e.g. VirtualBox Extension Pack)

Choose one of the following methods to proceed:

Option 1: Run the Container Option 2: Run the Shell Script
Install a container tool of your choice (Docker, Podman). Clone the repository: git clone https://github.com/b0rdst31n/SbleedyGonzales.git --recurse-submodules.
Get the container image from the GitHub registry [WILL BE PROVIDED]. Run the shell script to get both Python versions and their corresponding virtualenvs, create venv3 and venv2, and install the necessary dependencies and submodules: cd SbleedyGonzales && helpers/sbleedy_installer.sh. When behind a Proxy, pass arguments to the script like this helpers/sbleedy_installer.sh --http_proxy "http://whatever.net:0000/" --https_proxy "http://whatever.net:0000/" --no_proxy "localhost,etc.int" --pip_proxy "http://whatever.net:0000/" --pip_cert "$HOME/Desktop/my_cert.crt"
Run the container with a bash as entrypoint and pass the connected hardware (e.g., podman run -it --device /dev/ttyACM0 <image>). ⚠️ If using a Linux distribution that doesn't use apt (non-Debian systems) or lacks an available Python2.7 package, you will need to edit the script accordingly. Please avoid changing the name of venv2, or you'll have to adapt the variable VENV2_PATH in sbleedyCLI/constants.py.
  1. Test the installation:
    • Activate the venv3 (source venv3/bin/activate).
    • Test the installation of the CLI tool by running sbleedy -h #should print usage info. You may need to run pip install . again after activating the venv3.
    • Test the connected hardware by running hciconfig and lsusb and confirm that your connected devices are found.
Clone this wiki locally