Skip to content

Commit

Permalink
Merge branch 'main' of github.com:PentHertz/RF-Swift
Browse files Browse the repository at this point in the history
  • Loading branch information
@FlUxIuS
FlUxIuS committed Jun 9, 2024
2 parents 02e2b36 + 385c045 commit 64218d6
Show file tree
Hide file tree
Showing 3 changed files with 153 additions and 101 deletions.
2 changes: 2 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@

rfswift
234 changes: 138 additions & 96 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,20 +26,24 @@ The tool requires only one direct dependency to install on you own:

You need to install 3 tools:

- Docker desktop following this link (making sure it is run in WSL 2): https://docs.docker.com/desktop/wsl/#enabling-docker-support-in-wsl-2-distros
- GoLang installed with MSI package: https://go.dev/dl/
- `usbipd` as described here: https://learn.microsoft.com/en-us/windows/wsl/connect-usb
1. Docker Desktop by following this link (make sure it is run in WSL 2): [Docker Desktop WSL 2](https://docs.docker.com/desktop/wsl/#enabling-docker-support-in-wsl-2-distros)
2. GoLang using the MSI package: [GoLang Downloads](https://go.dev/dl/)
3. `usbipd` as described here: [Connect USB in WSL](https://learn.microsoft.com/en-us/windows/wsl/connect-usb)

To attach USB device, you'll need first to detect the USB id you are connecting with this command line:
To attach a USB device, you'll need to first detect the USB ID with this command line:

usbipd wsl list
```
usbipd wsl list
```

Then bind & attach this device:
Then bind and attach the device:

usbipd bind --busid <bus id>
usbipd attach --wsl --busid <busid>
```
usbipd bind --busid <busid>
usbipd attach --wsl --busid <busid>
```

After that, the device should appear on the container without issues ;)
After that, the device should appear in the container without issues. 😊


## Quick overview
Expand All @@ -56,45 +60,46 @@ https://github.com/PentHertz/RF-Swift/assets/715195/25a4a857-aa5a-4daa-9a08-28fa

## On Mac-OS - Apple Silicon M1/M2/M3

Even if the Go program can build in any platform and Dockerfile are compilable also on Mac OS, the USB may be difficult to reach on this platform.
Even if the Go program can build on any platform and Dockerfiles are compilable on macOS, the USB may be difficult to reach on this platform.

For the moment, consider using the tool inside a VM that handles USB such as VM Fusion.
For the moment, consider using the tool inside a VM that handles USB, such as VMware Fusion.

You can directly pull a working container from our registry using the `penthertz/rfswift:sdr_full_aarch64` reference: https://hub.docker.com/layers/penthertz/rfswift/sdr_full_aarch64/images/sha256-3385e49c1369bad2465e85c75b74ae241a0e285f0666321620c73fc9ff260996?context=repo
You can directly pull a working container from our registry using the `penthertz/rfswift:sdr_full_aarch64` reference: [Docker Hub Link](https://hub.docker.com/layers/penthertz/rfswift/sdr_full_aarch64/images/sha256-3385e49c1369bad2465e85c75b74ae241a0e285f0666321620c73fc9ff260996?context=repo).

## Quick run

If you want to skip building the Go program you can pick one of the builded archive here: https://github.com/PentHertz/RF-Swift/releases/tag/v0.1-dev
If you want to skip building the Go program, you can pick one of the built archives here: [RF-Swift Releases](https://github.com/PentHertz/RF-Swift/releases/tag/v0.1-dev).

Then if you want to use directly one of our builded container, please find tags you can pull from our official registry: https://hub.docker.com/repository/docker/penthertz/rfswift/tags
If you want to use one of our built containers directly, please find the tags you can pull from our official registry: [RF-Swift Docker Tags](https://hub.docker.com/repository/docker/penthertz/rfswift/tags).

## Building

This section is about building your own images with our provided recipes, but also your own recipes as well.
If you want to use an already built docker container, you can skip this section and go the the "Pulling containers" one.
This section is about building your own images using our provided recipes, as well as your own recipes. If you want to use an already built Docker container, you can skip this section and go to the "Pulling Containers" one.

### On Linux

For the momemt the building script is rather simple and give you the choice of using a image tag name and a specific Docker file:
For the moment, the build script is rather simple and gives you the choice of using an image tag name and a specific Dockerfile:

./build.sh
[+] Installing Go
...
[+] Building RF Switch Go Project
Enter image tag value (default: myrfswift:latest):
Enter value for Dockerfile to use (default: Dockerfile):
```
./build.sh
[+] Installing Go
...
[+] Building RF Switch Go Project
Enter image tag value (default: myrfswift:latest):
Enter value for Dockerfile to use (default: Dockerfile):
```

Note: uncomment some lines in Docker files, particularly if you are using the GPU with OpenCL
Note: Uncomment some lines in the Dockerfile, particularly if you are using the GPU with OpenCL.

Note 2: the default tag that is used by the tool is `myrfswift:latest`. We will manage configuration file in the future to avoid precising it for each `run` and `exec` commands when using a non-default one.
Note 2: The default tag used by the tool is `myrfswift:latest`. We will manage configuration files in the future to avoid specifying it for each `run` and `exec` command when using a non-default one.

### On Windows

Use the `build-windows.bat` instead after installing all the requirements.

## Pulling a container

If you want to use an already built container and save more time, you can pull one docker container from our official repository: https://hub.docker.com/repository/docker/penthertz/rfswift/tags
If you want to use an already built container and save more time, you can pull one docker container from our official repository: [https://hub.docker.com/repository/docker/penthertz/rfswift/tags](https://hub.docker.com/r/penthertz/rfswift/tags)

As an example, we'd like to pull `rfswift:bluetooth` that includes all tools from the `bluetooth.docker` file, we can use the following command:

Expand All @@ -105,131 +110,168 @@ As an example, we'd like to pull `rfswift:bluetooth` that includes all tools fro
{"status":"Status: Image is up to date for penthertz/rfswift:bluetooth"}


## Creating and running a container
Existing images from our container registry:

To run a container, use the command `./rfswift run -h` to see needed arguments:
| Tag | Supported OS | architecture | Description |
|---------------------|-------------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| corebuild | - Linux - Windows | amd64 | Base image including prerequisites for compiling tools + common SDR devices without tweaks |
| latest | - Linux - Windows | amd64 | The full images including all tools for SDR, Wi-Fi, Bluetooth and RFID used in the Dockerfile file |
| sdr_light | - Linux - Windows | amd64 | Light image built for SDR uses with limited number of tools used in sdr_light.docker file |
| sdr_full | - Linux - Windows | amd64 | Full image including all SDR tools used in sdr_full.docker file |
| wifi | - Linux - Windows | amd64 | Wi-Fi image for security tests using tools included in wifi.docker |
| rfid | - Linux - Windows | amd64 | RFID image for security tests using tools included in rfid.docker |
| bluetooth | - Linux - Windows | amd64 | Bluetooth classic and LE image for security tests using tools in bluetooth.docker |
| rfid_aarch64 | - Linux - Windows | arm64/v8 | RFID image for security tests using tools included in rfid.docker |
| sdr_light_aarch64 | - Linux - Windows | arm64/v8 | Light image built for SDR uses with limited number of tools used in sdr_light.docker file |
| latest_aarch64_rpi5 | - Linux - Windows | arm64/v8 | The full images including all tools for SDR, Wi-Fi, Bluetooth and RFID used in the Dockerfile file but two tools are missing. Can be used in Apple M1-M3. |
| sdr_full_rpi5 | - Linux - Windows | arm64/v8 | Full image including all SDR tools used in sdr_full.docker file but with two missing tools. Also works in Apple M1-M3. |
| bluetooth_aarch64 | - Linux - Windows | arm64/v8 | Bluetooth classic and LE image for security tests using tools in bluetooth.docker |

[...]
Usage:
rfswift run [flags]
## Creating and running a container

Flags:
-b, --bind string extra bindings (separe them with commas)
-e, --command string command to exec (by default: '/bin/bash')
-d, --display string set X Display (by default: 'DISPLAY=:0')
-h, --help help for run
-i, --image string image (by default: 'myrfswift:latest')
To run a container, use the command `./rfswift run -h` to see the needed arguments:

```
[...]
Usage:
rfswift run [flags]
By default, you can the command without arguments if you want to start the `/bin/bash` interpreter and use the default image tag name, and with default envirnement display variable.
Flags:
-b, --bind string extra bindings (separate them with commas)
-e, --command string command to exec (default: '/bin/bash')
-d, --display string set X Display (default: 'DISPLAY=:0')
-h, --help help for run
-i, --image string image (default: 'myrfswift:latest')
```

### Not able to see some devices
By default, you can run the command without arguments if you want to start the `/bin/bash` interpreter and use the default image tag name, and the default environment display variable.

You can add extra bindings with the following command line that helps bringing the PlutoSDR:
### Not Able to See Some Devices

sudo ./rfswift run -b "/run/dbus/system_bus_socket:/run/dbus/system_bus_socket,/dev/snd:/dev/snd,/dev/dri:/dev/dri"
You can add extra bindings with the following command line to help bring up the PlutoSDR:

## Executing a command inside an existing container
```
sudo ./rfswift run -b "/run/dbus/system_bus_socket:/run/dbus/system_bus_socket,/dev/snd:/dev/snd,/dev/dri:/dev/dri"
```

Running a command inside a previous container is fairly easy, if you run a cointainer and exit it.
## Executing a Command Inside an Existing Container

All you need to do, is to execute the desire command as follows:
Running a command inside a previous container is fairly easy if you run a container and exit it.

sudo ./rfswift exec -e urh
All you need to do is execute the desired command as follows:

if you want to run it into another existing container, you can precise the container ID as follows:
```
sudo ./rfswift exec -e urh
```

sudo ./rfswift last # to get the list
[...]
[ 1716024976 ][ myrfswift:latest ] Container: c9e223a987a36441fb631f4a11def746aabb1a1bc862b5f2589d5b3ac8429cb1 , Command: /bin/bash
[ 1716024209 ][ sha256:ed26c47b0d1dba0473a4729885374e04e24b4189125a245c77280fd472bf934b ] Container: 2354c99f6699b4f3abc97d55cdb825fcfafba2af1b27e02a612fc2586061eb6e , Command: /bin/sh -c './entrypoint.sh eaphammer_soft_install'
[ 1716021780 ][ myrfswift:rfid ] Container: a3e91704571d92f9a48e355b1db0ca5a97769087aebf573a6295392fb3f4d394 , Command: /bin/bash
[ 1716021385 ][ sha256:95fd8938e078792fc3e09c1311c7bdbed3e8e112887b7f0f36bf5a57616cf414 ] Container: 0b922d0ee58c1235bdba13fe2793ee7544f16fc5a5a710df4ebc68b05b928cc8 , Command: /bin/sh -c './entrypoint.sh mfoc_soft_install'
[...]
sudo ./rfswift exec -e /bin/bash -c c9e223a987a36441fb631f4a11def746aabb1a1bc862b5f2589d5b3ac8429cb1 # we are executing on the 'c9e223a987a36441fb631f4a11def746aabb1a1bc862b5f2589d5b3ac8429cb1' container
If you want to run it in another existing container, you can specify the container ID as follows:

## Getting the latests containers
```
sudo ./rfswift last # to get the list
[...]
[ 1716024976 ][ myrfswift:latest ] Container: c9e223a987a36441fb631f4a11def746aabb1a1bc862b5f2589d5b3ac8429cb1 , Command: /bin/bash
[ 1716024209 ][ sha256:ed26c47b0d1dba0473a4729885374e04e24b4189125a245c77280fd472bf934b ] Container: 2354c99f6699b4f3abc97d55cdb825fcfafba2af1b27e02a612fc2586061eb6e , Command: /bin/sh -c './entrypoint.sh eaphammer_soft_install'
[ 1716021780 ][ myrfswift:rfid ] Container: a3e91704571d92f9a48e355b1db0ca5a97769087aebf573a6295392fb3f4d394 , Command: /bin/bash
[ 1716021385 ][ sha256:95fd8938e078792fc3e09c1311c7bdbed3e8e112887b7f0f36bf5a57616cf414 ] Container: 0b922d0ee58c1235bdba13fe2793ee7544f16fc5a5a710df4ebc68b05b928cc8 , Command: /bin/sh -c './entrypoint.sh mfoc_soft_install'
[...]
sudo ./rfswift exec -e /bin/bash -c c9e223a987a36441fb631f4a11def746aabb1a1bc862b5f2589d5b3ac8429cb1 # executing on the 'c9e223a987a36441fb631f4a11def746aabb1a1bc862b5f2589d5b3ac8429cb1' container
```

To get the 10 last containers you have create, you can use the following command:
## Getting the Latest Containers

sudo ./rfswift last -h
rfswift last [flags]
To get the last 10 containers you have created, you can use the following command:

Flags:
-f, --filter string filter by image name
[...]
sudo ./rfswift last -f myrfswift:latest # we are using a filter for images
[ 1716024976 ][ myrfswift:latest ] Container: c9e223a987a36441fb631f4a11def746aabb1a1bc862b5f2589d5b3ac8429cb1 , Command: /bin/bash
```
sudo ./rfswift last -h
rfswift last [flags]
Flags:
-f, --filter string filter by image name
[...]
sudo ./rfswift last -f myrfswift:latest # using a filter for images
[ 1716024976 ][ myrfswift:latest ] Container: c9e223a987a36441fb631f4a11def746aabb1a1bc862b5f2589d5b3ac8429cb1 , Command: /bin/bash
```

## Hotinstall
## Hot Install

If you forgot to enable an installation function, you can always install it :
If you forgot to enable an installation function, you can always install it:

sudo ./rfswift install -i <install function (called by entrypoint.sh)> -c <container id> [-c <container id>]
```
sudo ./rfswift install -i <install function (called by entrypoint.sh)> -c <container id> [-c <container id>]
```

## Commit changes
## Commit Changes

If you want to commit changes you've made of your container an start at this images later on a new one, you can use the `commit` command as follows:
If you want to commit changes you've made to your container and start a new one from this image later, you can use the `commit` command as follows:

sudo ./rfswift commit -c <container id> -i myrfswift:newtag
```
sudo ./rfswift commit -c <container id> -i myrfswift:newtag
```

## Renaming images
## Renaming Images

You can rename images using the `rename` command as follows:

sudo ./rfswift rename -i myrfswift:supertag -t myrfswift:newsupertag
```
sudo ./rfswift rename -i myrfswift:supertag -t myrfswift:newsupertag
```

## Removing container
## Removing Containers

You can remove a container using the `remove` command as follows:

sudo ./rfswift remove -c <container id>

```
sudo ./rfswift remove -c <container id>
```

## Options

### OpenCL

You can enable OpenCL with the driver associated to your graphic card:
You can enable OpenCL with the driver associated with your graphics card:

```
# Installing OpenCL
## NVIDIA drivers
#RUN apt-fast install -y nvidia-opencl-dev nvidia-modprobe
## Installing Intel's OpenCL
#RUN apt-fast install -y intel-opencl-icd ocl-icd-dev ocl-icd-opencl-dev
```

# Installing OpenCL
## NVidia drivers
#RUN apt-fast install -y nvidia-opencl-dev nvidia-modprobe
## Installing Intel's OpenCL
#RUN apt-fast install -y intel-opencl-icd ocl-icd-dev ocl-icd-opencl-dev

![OpenCL recipe in action](https://github.com/PentHertz/RF-Swift/assets/715195/a29eedd5-b1df-40fc-97c0-4dc5323f36a8)

### RTL-SDR
### RTL-SDR

The RTL-SDR v4 uses a different driver that replaces the others.
The RTL-SDR v4 uses a different driver that replaces the others.

Until we find a proper way to support both drivers, comment the basic function and uncomment the v4 one in the recipe as follow:
Until we find a proper way to support both drivers, comment the basic function and uncomment the v4 one in the recipe as follows:

#RUN ./entrypoint.sh rtlsdr_devices_install
RUN ./entrypoint.sh rtlsdrv4_devices_install # optionnal, remove rtlsdr_devices_install if you are using the v4 version
```
#RUN ./entrypoint.sh rtlsdr_devices_install
RUN ./entrypoint.sh rtlsdrv4_devices_install # optional, remove rtlsdr_devices_install if you are using the v4 version
# Installing gr-fosphor with OpenCL
#RUN ./entrypoint.sh grfosphor_grmod_install
# Installing gr-fosphor with OpenCL
#RUN ./entrypoint.sh grfosphor_grmod_install
```

## How to contribute
## How to Contribute

You are warmly welcomed to contribute to fill scripts we your desired tools.
You are warmly welcomed to contribute and fill scripts with your desired tools.

In the future, we will create a dedicated page for developpers.
In the future, we will create a dedicated page for developers.

## Troubleshooting

### Sound

The sound is sometimes not restarting when stoping to play with tools like SDR++.
The sound sometimes does not restart when stopping playback with tools like SDR++.

To solve it for the moment, you can restart the tool and try playing it.
To solve it for now, you can restart the tool and try playing it again.

Some tools like GQRX are not yet working with the sound, we will try to fix it when possible, but you can also capture the signal and demodulate it to `wav` and play it with Audacity as a quick fix.
Some tools, like GQRX, are not yet working with sound. We will try to fix it when possible, but you can also capture the signal and demodulate it to `wav` and play it with Audacity as a quick fix.

If some contributor have the time to solve this issue, that would be awesome <3
If any contributor has the time to solve this issue, that would be awesome. ❤️

### Wiki??!

We will find out some time to build one ;)
We will find some time to build one. 😉
18 changes: 13 additions & 5 deletions build.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,26 @@

# Quick and dirty building shell script which will evolve with more time make inside a Makefile


# stop the script if any command fails
set -euo pipefail

install_go() {
go version && { echo "golang is already installed. moving on" && return 0 ; }

[ -d thirdparty ] || mkdir thirdparty
cd thirdparty
arch=`uname -i`
prog="" # default Go binary tar.gz
version="1.22.4"

case "$arch" in
x86_64|amd64)
prog="go1.22.3.linux-amd64.tar.gz";;
prog="go${version}.linux-amd64.tar.gz";;
i?86)
prog="go1.22.3.linux-386.tar.gz";;
prog="go${version}.linux-386.tar.gz";;
arm64|aarch64|unknown) # Let assume from now unknown is RPi 5 => TODO: fix
prog="go1.22.3.linux-arm64.tar.gz";;
prog="go${version}.linux-arm64.tar.gz";;
*)
printf 'Unsupported architecture: "%s" -> Download or build Go instead\n' "$arch" >&2; exit 2;;
esac
Expand All @@ -32,7 +40,7 @@ building_rfswift() {
}

echo "[+] Installing Go"
install_go
install_go

echo "[+] Building RF Switch Go Project"
building_rfswift
Expand All @@ -50,4 +58,4 @@ imagename=${imagename:-$DEFAULT_IMAGE}
dockerfile=${dockerfile:-$DEFAULT_DOCKERFILE}

echo "[+] Building the Docker container"
sudo docker build . -t $imagename -f $dockerfile
sudo docker build . -t $imagename -f $dockerfile

0 comments on commit 64218d6

Please sign in to comment.