Security
What's protected, and every way in
What gunkslab protects, every way in, how each one stands today, and the checks that run on every change. Keep it true: a merge request that changes any row below changes this file too.
What’s at stake
- Bots that move. A bot driven by the wrong hands, or off the edge of a desk, can break, or hurt someone or something nearby: desks get used where children are.
- The home network the bots and this machine sit on.
- Credentials: its own Wi-Fi and update passwords on each bot, and its key and certificate for the cluster’s broker (the
key made on the bot, both kept in its flash); the certificates the station, drivers, the recorder and the position service log in to that broker
with, from Vault’s CA, on the machines that run them (a driver’s lasts 12 hours, a service’s a week); the Vault
logins that get them (admin work as an admin login,
vault-admin; no root token is kept, 2026-10-25); the overhead camera’s login, in Vault. - The room the overhead camera sees. It looks at the desk, and whatever else is in its picture.
- The site (gunkslab.com), once it’s public: its own repo covers its deployment.
Nothing here handles personal data. Telemetry carries power, signal strength, distances and events, never names.
Ways in
| Where | Who can reach it | What they could do | Today | Closed by |
|---|---|---|---|---|
The development broker (scripts/broker up) |
This machine only: 127.0.0.1 | Anything a client can | No logins: accepted for this machine. Its WebSocket takes only the viewer’s own page (http://127.0.0.1:8080, localhost:8080): a page from any other site in this machine’s browser is refused (2026-10-24) |
none |
Bench mode (scripts/broker up --lan) |
The local network, while it’s up | With a certificate from this machine’s CA: what that login may do, as on the cluster’s broker; without: nothing | TLS only on the network (8883), and a certificate from this machine’s own CA as each client’s login, held to its own topics and client ID, revoked at once (scripts/broker revoke); plain MQTT stays on 127.0.0.1 (2026-10-25). The CA’s key is in ~/.gunkslab/bench, readable by you only: whoever can read it can make any login, as anyone who has this machine could |
none |
The station’s station/drive/<client> |
Anyone who can publish to the broker | Drive any bot nobody’s holding | On the cluster’s broker, only the station and the drivers may publish to it, each driver under its own name only, which the station takes as the driver’s: a hold keeps other drivers off (2026-10-25). On the development broker, anyone may use any name | none |
The fleet’s e-stop, estop/<name> |
Anyone who can publish to the broker | Set one (stops everything: safe by design), or clear one | Everyone’s is their own, and the fleet stops while any is on. On the cluster’s broker a driver may set or clear only their own, an admin anyone’s, and no other login may touch them (2026-10-25); on the development broker, anyone | none |
A bot’s cmd |
Anyone who can publish to the broker | Drive that bot directly, around the station | On the cluster’s broker, only the station login may publish to cmd (2026-10-13); on the development broker, the bot obeys any well-formed command |
none |
| Updates over the air (firmware) | Anyone on the Wi-Fi | Flash their own code onto a bot | Needs the bot’s own password, made by scripts/bot-ota and kept in Vault (2026-11-09); without one, OTA is off, USB only (2026-10-03). The image must be signed with the fleet’s key, its public half typed into the bot over USB; one that isn’t is wiped before the bot restarts (2026-11-11, not yet on a real board). A power cut between the write and the wipe could start an unsigned image, and wrong passwords aren’t limited |
Secure boot (desk-issues#6) |
| A bot in hand (USB) | Whoever holds it | Read its Wi-Fi password, its update password and its broker key out of its flash; flash it | Unencrypted: accepted for the bench. Its broker key logs in as that bot only, and its certificate can be revoked (2026-10-25). Its update and Wi-Fi passwords are its own, so they open no other bot (2026-11-09); on the bots’ network, its Wi-Fi key can be removed alone | ESP32 flash encryption, before bots leave the house (desk-issues#4) |
| Bad messages (rule 8) | Anyone who can publish | Crash or confuse a bot or the station | Refused: every layout lists its fields; the firmware’s and the station’s checks are tested. The driving tool and the page check every message against the schemas too, and drop the rest (2026-10-25); scripts/record show and list print control codes as escapes (2026-10-25) |
none |
| Python packages, at image build | Whoever can tamper with a download | Put their own code in a container | Every container the stack runs installs from requirements.txt, each file checked against its published hash (2026-10-21); so do CI’s jobs, the firmware’s build container and the security checks’ own tools, from lock files of their own (2026-10-25). Accepted: the toolchains and libraries PlatformIO fetches are pinned by version only (PlatformIO can’t check hashes), and scripts/lock installs pip-tools by version to write the lock files |
none |
| Driving off the desk, into things | The station, a driver, a bug | Physical damage | The bot’s own reflex (rule 9), independent of the station; the station’s guard | none |
The page (scripts/viewer up) |
This machine only: 127.0.0.1 | none | Its one outside library is checked byte for byte against the published one | none |
| A broker on Vault’s CA (port 8883) | Whatever its network lets in | With a bot’s login, act as that bot; with a driver’s, drive through the station as that driver and set or clear the e-stop; with the station’s, send any bot commands (its login may publish nothing else, 2026-10-25) | TLS only, and no passwords: each client shows a certificate from the fleet’s CA (Vault’s pki-gunkslab), its name the login, each login held to its own topics. Clients check the broker’s certificate, so nothing on the LAN can pose as it. A client’s ID is its login, so no login can drop another’s client by taking its ID; a revoked certificate is refused once the broker has the new list, which scripts/certs revoke sees to (2026-10-25, desk-issues#5). Messages over 64 KiB, a client’s queue past 200 and the broker’s memory past 32 MiB are refused (2026-10-24). Bots log in with a certificate signed from a request they make, their key never leaving them (2026-10-25); not yet done on a real bot, and a bot doesn’t check certificates’ dates (the ESP32 core’s mbedTLS is built without them) |
none |
The position service’s login (position) |
Whoever holds its certificate | Publish any bot’s pose: the station steers its go-tos and detours by what it’s told, so wrong poses steer a bot wrong |
On the cluster’s broker it may publish poses and nothing else (2026-10-24); the bot’s own reflex still holds at an edge (rule 9). The station believes poses only for bots that have said hello, on the desk, and no faster than a bot can go (2026-10-24). Accepted: a pose that moves no faster than 1 m/s still gets through, so the login could still steer a bot slowly wrong; its certificate lasts a week, and its key stays on the machine that runs the service | none |
The overhead camera (a Wi-Fi camera, CAMERA_URL) |
Anyone on its Wi-Fi; its maker’s cloud and app, through the camera’s own account | Watch the room; with its stream’s login, show the position service another picture | None installed yet (2026-10-24): nothing exposed until one goes up. Once it is: the stream’s login is a camera account of its own, in Vault, never in git, and left out of the service’s log; the stream and its login cross the Wi-Fi unencrypted (RTSP) | The camera on a network of its own (desk-issues#3) |
| The site | none | none | LAN-only | none |
Checks on every change
scripts/security runs them on this machine; CI runs the same on every merge request, on main, and once a week on
main whether anything changed or not (a pipeline schedule, Mondays at 06:00 Pacific). A vulnerability published
after a merge fails the next weekly run, which shows in the project’s pipelines, marked as scheduled.
| Check | Tool | What fails it |
|---|---|---|
| Secrets | gitleaks | A credential anywhere in the code or its git history |
| Commit identity | git (security/identity.sh) |
A commit made under any name but gunkslab <noreply@gunkslab.com>, as author or committer |
| Dependencies | pip-audit | A known vulnerability in any pinned Python package (security/pins.py reads them from where they’re pinned) |
| Python | bandit | Risky code: a shell call, an assert doing a real check, and so on |
| Firmware | cppcheck | Uninitialised memory, overruns, undefined behaviour |
| Containers | trivy | A Containerfile running as root, or a HIGH or CRITICAL fixed vulnerability in an image the stack runs on (security/images.sh) |
| Vendored code | npm | The page’s copy of mqtt.js differs from the published file |
| The brokers’ rules | Mosquitto, a throwaway CA (tests/broker) |
Bench mode letting in a client it shouldn’t, letting a login publish outside its own topics, letting one login take another’s client ID, taking a revoked certificate, or dropping clients on a renewed one |
A merge request merges only once its pipeline has passed, every check above among it, and nobody pushes to main directly (2026-10-24). security/images.sh lists every image the stack runs, the broker’s among them.
Accepted findings
A finding is fixed, or accepted with a reason. Accepted ones live in security/bandit.yaml and
security/trivyignore.yaml, each with why. Vulnerabilities are accepted for a month at a time: once a date passes,
the check fails again, and someone looks again (a newer image fixes it, or a new date with a reason).
Before merging
For a change that touches the network, the protocol, the firmware or a container (the merge request template asks):
- Does it listen anywhere but 127.0.0.1? Then it’s a row in the table above.
- A new message, or a new field: is it in a schema, with nothing else allowed?
- A new dependency or image: pinned, and in the checks?
- A secret: only in a gitignored file, or Vault, never in git?
- Does a row above change? Change it.
The backlog
Every security problem found, by a check, a review or a report, is a confidential issue in the issue tracker,
gitlab.com/gunkslab/desk-issues, labelled security and one of
security-high, security-medium or security-low. Confidential, because the details of what’s still open are
something to keep from outsiders: the tracker is public, these issues aren’t. Known limits says
what each is, in short.
- High: someone could drive a bot, take over a machine on the network or read a credential, from where they are today.
- Medium: it takes a login, a bot in hand or a second problem first; or it weakens a check that something else relies on.
- Low: hardening: it narrows what a problem elsewhere could do.
Each is fixed, or accepted with a reason and a date in the table above, as a failing check is. The tracker’s issues,
filtered on security, are the backlog; a row above names the issue that closes it (desk-issues#4). Problems
fixed before 2026-11-14 were tracked in an earlier project, kept private; their rows give the date instead. The
pipeline schedule, the labels, and the merge settings (pipelines must succeed; no pushes to main) are made through
GitLab’s API, not code: the project’s GitLab settings aren’t in OpenTofu yet.
Reporting a problem
Report a problem as a confidential issue in the issue tracker, gitlab.com/gunkslab/desk-issues. Tick Turn on confidentiality before you create it: it’s then hidden from the public, and only gunkslab’s maintainers can read it. Opening one needs a GitLab account. Say what it is, where (a file, a topic, a message), how to reproduce it, and what it could let someone do. Don’t put credentials or a working exploit in the issue; describe them, and they’ll be asked for privately.
There’s no promise on how soon a report is answered. Please keep it private until it’s fixed, or for 90 days from your report, whichever comes first; after that it’s yours to publish.
A report is triaged like a failing check: fixed, or accepted with a reason and a date in the table above.