proxmark3 quick start (with docker)

how to start using proxmark3

these a my notes on how to create a dev environment, complile the firmware and software for the proxmark3, flash it and run the client, all in a docker container. it is necessary to have a build environment because the firmware and client must be of the same version, so each time the software is updated, it must be recompiled and the firmware reflashed. recompiling and reflashing is also needed for installing a standalone script

hardware

• proxmark3 easy 512Kb, connected to the host/vm (assumed as /dev/ttyACM0)

host setup

Debian/Ubuntu Linux host/vm with docker installed. might work on other platforms with docker too. docker is installed like this (the example is for Debian 12. Ubuntu needs to replace debian with ubuntu in the repo link):

sudo apt update
sudo apt install ca-certificates curl

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/debian \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  tee /etc/apt/sources.list.d/docker.list > /dev/null
  
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

proxmark3 development environment setup

it is preferrable to use a virtual machine and not an actual host with Linux, since we need to disable ModemManager to prevent it from interfering with the proxmark3 device. on the host:

sudo systemctl stop ModemManager
sudo systemctl disable ModemManager

mkdir -p ~/iceman/docker
mkdir ~/iceman/proxmark-docker-data
cd ~/iceman/docker

tee Dockerfile <<-'EOF'

FROM ubuntu:22.04

RUN apt update

RUN DEBIAN_FRONTEND=noninteractive TZ=Asia/Shanghai apt-get -y install tzdata

RUN apt install ca-certificates -y

COPY <<EOF /etc/apt/sources.list
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
deb http://security.ubuntu.com/ubuntu/ jammy-security main restricted universe multiverse
EOF

RUN apt update && apt install -y --no-install-recommends nano git ca-certificates build-essential pkg-config libreadline-dev gcc-arm-none-eabi libnewlib-dev qtbase5-dev libbz2-dev liblz4-dev libbluetooth-dev libpython3-dev libssl-dev libgd-dev

WORKDIR /root
EOF

tee docker-compose.yml <<-'EOF'
name: proxmark3_custom

services:
  ubuntu:
    build: .
    image: ubuntu_custom:22.04
    container_name: proxmark3_custom
    # to keep the container running
    command: tail -f /dev/null
    volumes:
      - $HOME/iceman/proxmark-docker-data:/root
      - /tmp/.X11-unix:/tmp/.X11-unix
      - /dev:/dev
      - /run/udev:/run/udev:ro
    environment:
      - DISPLAY=$DISPLAY
    privileged: true
    network_mode: host
    restart: unless-stopped

EOF

this is a dev container, intended to be running indefinitely, and all operations are done inside it

docker compose up -d --build --force-recreate
docker exec -it proxmark3_custom bash

to allow displaying the GUI with the graph for the antenna tuning (hw tune) it is necessary to do xhost +local:docker on the host

compiling and flashing

run the follwing inside the container. all of this can be put into the Dockerfile as well. setting access rights are not really needed since the user inside the container is root, but will be necessary if a non-root user is used.

git clone https://github.com/RfidResearchGroup/proxmark3.git
cd proxmark3
make accessrights
[ -r /dev/ttyACM0 ] && [ -w /dev/ttyACM0 ] && echo ok

tee Makefile.platform <<-'EOF'
PLATFORM=PM3GENERIC
INSTALLSUDO=sudo
#STANDALONE=HF_YOUNG
EOF

make clean && make -j

it is possible to run standalone scripts by adding STANDALONE=xxx line to the Makefile with xxx being the particular script name. read the source code of the script, start the client and long press the button on the device to start the script, then watch the logs to learn how it works (single press, double press, long press of the button). installing a different script is similar to the update process, but there is no need to reflash the bootloader, so just recompiling make clean && make -j and flashing the image ./pm3-flash-fullimage is enough.

since the firmware must be the same version as the client, each time afer pulling a new version we must flash both the bootloader and the firmware (the proxmark will reset and reconnect itself during the process):

./pm3-flash-all

start the client:

/root/proxmark3/client/proxmark3 /dev/ttyACM0

then it can also be done from the host directly like this:

docker exec -it proxmark3_custom /root/proxmark3/client/proxmark3 /dev/ttyACM0

naturally, it can also be done remotely via ssh using local and remote docker daemons:

DOCKER_HOST="ssh://$USER@dockerhost" docker exec -it proxmark3_custom  /root/proxmark3/client/proxmark3 /dev/ttyACM0

later, updating will be like (inside the container):

cd proxmark3
git pull
make clean && make -j
./pm3-flash-all

references

• https://github.com/RfidResearchGroup/proxmark3/tree/master/doc
• https://github.com/RfidResearchGroup/proxmark3/blob/master/doc/md/Installation_Instructions/Linux-Installation-Instructions.md
• https://github.com/RfidResearchGroup/proxmark3/blob/master/doc/md/Use_of_Proxmark/0_Compilation-Instructions.md