Skip to content
gunkslab

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.