chore: Simulator Docker instructions
What changed, and why it matters
This commit is purely a developer convenience change. It adds a Dockerfile and README instructions for building the Coldcard simulator inside Docker, plus a small tweak so the simulator writes an xterm log file to /tmp with normal permissions. There is no change to how real Coldcard hardware handles private keys, transactions, or security checks, and no vulnerability is introduced.
No security action required. Treat as routine developer tooling/documentation change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch adds Docker-based build/run instructions for the Coldcard simulator, adds ‘firmware’ to .gitignore, and modifies unix/simulator.py to create/truncate /tmp/cc_simulator.log and pass it to xterm via -l -lf. The simulator is an off-device development/testing tool; the change does not touch firmware cryptography, wallet logic, or hardware security boundaries.
Changed components
Dockerfile (new)README.md (documentation).gitignoreunix/simulator.py (simulator launcher logging)Inspect captured patch +65 / −1
diff --git a/.gitignore b/.gitignore
index ed8510c..0623e03 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,3 +26,4 @@ __pycache__/
pp
.idea/
+firmware
\ No newline at end of file
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..35ffc5a
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,32 @@
+FROM gcc:11.5.0-bullseye
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y \
+ git \
+ make \
+ python3 python3-venv python3-pip \
+ swig \
+ libpcsclite-dev pcscd \
+ pkg-config \
+ libffi-dev \
+ xterm \
+ autoconf automake libtool m4
+
+WORKDIR /build
+
+RUN git clone --depth 1 --recursive \
+ https://github.com/Coldcard/firmware.git
+
+WORKDIR /build/firmware/unix
+
+# Build mpy-cross
+RUN make -C ../external/micropython/mpy-cross
+
+# Build simulator & tools
+RUN make setup
+RUN make ngu-setup
+RUN make
+
+# remove unnecessary git files
+RUN find /build/firmware -name ".git" -type d -prune -exec rm -rf '{}' +
\ No newline at end of file
diff --git a/README.md b/README.md
index e0cbbb7..1e5a9e0 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,25 @@ so at the top level, do this command:
pip install -r requirements.txt
```
+### Using Docker to build simulator
+Install [Docker Desktop or Docker Engine](https://docs.docker.com/desktop/) (don't forget to add your user to the docker group `sudo usermod -aG docker $USER` than logout and login again)
+
+```
+# Build simulator
+docker build -t coldcard-simulator .
+docker create --name cc coldcard-simulator
+docker cp cc:/build/firmware ./firmware
+docker rm cc
+
+# Install specific libffi7 (as new Ubuntu versions ship with libffi8 only)
+wget http://archive.ubuntu.com/ubuntu/pool/main/libf/libffi/libffi7_3.3-4_amd64.deb
+sudo dpkg -i libffi7_3.3-4_amd64.deb
+
+# Run simulator (remember to follow the OS specific instructions detailed below to install python and its dependencies)
+cd firmware/unix
+./simulator.py
+```
+
### macOS
[Python 3.5 or higher](https://www.python.org) and [Homebrew](https://brew.sh) is required.
@@ -179,7 +198,13 @@ All steps you need to install and run the Coldcard simulator on Ubuntu 20.04:
apt install build-essential git python3 python3-pip libudev-dev gcc-arm-none-eabi libffi-dev xterm swig libpcsclite-dev python-is-python3 autoconf libtool python3-venv
# Get sources, this takes a long time (because of external libraries), then open
+
+# Recommended (fast, minimal download; sufficient for building and running the simulator):
+git clone --depth 1 --recursive https://github.com/Coldcard/firmware.git
+
+# Full clone (developers only; required for history, bisecting, or contributing):
git clone --recursive https://github.com/Coldcard/firmware.git
+
cd firmware
# Apply address patch
diff --git a/unix/simulator.py b/unix/simulator.py
index af7e94f..9840eb1 100755
--- a/unix/simulator.py
+++ b/unix/simulator.py
@@ -903,8 +903,14 @@ Q1 specials:
child.kill()
return
+ logfile = '/tmp/cc_simulator.log'
+
+ # truncate logfile and set correct permissions before starting xterm
+ open(logfile, 'w').close()
+ os.chmod(logfile, 0o644)
+
xterm = subprocess.Popen(['xterm', '-title', 'Coldcard Simulator REPL',
- '-geom', '132x40+650+40', '-e'] + cc_cmd,
+ '-geom', '132x40+650+40', '-l', '-lf', logfile, '-e'] + cc_cmd,
env=env,
stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
pass_fds=pass_fds, shell=False)
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.