Skip to content
gunkslab

Security

How it's secured

Bots move, and desks get used where children are, so the question is always who can make a bot move. The answer here is the station, asked by a driver who has logged in. Everything else either can’t, or can only say things the station checks.

Who talks to whom: every client connects to the broker over TLS with a certificate from the CA, each held to its own
topics, and only the station sends bots commands

Three brokers, one set of rules

Broker Who can reach it Logins
Development (scripts/broker up) This machine only: 127.0.0.1 None. Anything on this machine is trusted as much as the machine is
Bench mode (scripts/broker up --lan) This machine, as above; and the local network, on 8883 None from this machine. From the network, TLS and a certificate from this machine’s own CA
A broker of your own, on Vault’s CA Whatever its network lets in, on 8883 TLS and a certificate from Vault’s CA, for everyone

Wherever a broker takes logins, it takes them the same way. Bench mode runs broker/acl, and a broker on Vault’s CA takes the same file, so the rules below hold for both.

Bench mode: open on this machine, TLS and certificates from the network

A login is a certificate

There are no passwords on the broker. A client shows a certificate, and the name on it is its login: driver-1, station, bot-a1b2c3. The broker checks it against its CA, and against its revocation list.

  • People get certificates from Vault through a Vault login of their own. A driver’s lasts 12 hours, and a Vault login may get only the names its policy allows: a driver its own, an admin the services’ too.
  • The station, the recorder and the position service each have a login of their own, a week at a time.
  • Bots make their own key on the chip. The key never leaves the bot, and its certificate, two years long, is signed from a request it prints over USB.

Logins and certificates makes and changes them all.

Who may do what

Each login is held to its own topics (broker/acl):

Login May publish May read
station its own station/status, station/fleet, station/notice; every bot’s cmd everything under gunkslab/v0/
driver-1, … (a driver: scripts/drive, the acceptance run) <fleet>/station/drive/<its name>, its own e-stop <fleet>/estop/<its name>; an admin, anyone’s e-stop everything under gunkslab/v0/
recorder (scripts/record) nothing everything under gunkslab/v0/
position (the overhead camera’s service: scripts/position) each bot’s pose nothing
bot-xxxxxx (each bot, by its own name) its own hello, status, telemetry, event, sync its own cmd and sync, everyone’s e-stop <fleet>/estop/+

So:

  • A bot publishes only its own topics, and reads only its own commands and the e-stop. It can’t speak as another bot.
  • A driver asks the station to drive, on station/drive/<its name>, and the broker lets it publish under no other name, so one driver can’t take another’s held bot. It never commands a bot directly.
  • Only the station sends a bot commands. The position service may only say where bots are; the recorder may only listen.
  • Everyone has an e-stop of their own, and the fleet stops while anyone’s is on. A driver may set and clear only their own; an admin may clear anyone’s. Setting one never goes through the station.
  • A client’s ID is its login, whatever it asks for, so one login can’t knock another’s client off by taking its ID.

Checking the broker

Every client checks the broker’s certificate, so nothing on the network can pose as the broker and send bots commands of its own. The station and the scripts check it by its address. Bots check it by name, broker.gunkslab.internal, whatever address they connect to.

Taking a login away

A certificate can be revoked: a lost bot, a driver who no longer drives. scripts/certs revoke revokes every certificate the name holds, and restarts the broker with the new list, so nothing using one stays connected: tried, the client dropped about nine seconds in.

What every message goes through

Every program checks every message against the protocol’s schemas before it acts on it, and drops one that doesn’t fit. That includes the station, the bots, the driving tool and the page. A bot obeys only well-formed commands, stops by itself half a second after the last one, and obeys the e-stop directly (Safety).

Checked on every change

  • The usual checks: secrets, known vulnerabilities in every pinned package, risky code, the containers, and the vendored code (the checks).
  • The broker’s configuration: bench mode’s, run with certificates from a throwaway CA (tests/broker). That checks who gets in, what each login may publish, client IDs, revocation, and a renewed certificate loaded without dropping anyone.

Tried for real, and not yet

Tried on a broker on Vault’s CA and in bench mode (2026-10-25):

  • the broker’s certificate verified by its address and its name;
  • a driver’s real certificate logging in;
  • drive requests under another driver’s name refused;
  • a client with no certificate refused;
  • a revoked certificate refused once the broker loaded the new list;
  • bench mode reachable on the network only by TLS.

Not yet on a real bot: the TLS handshake on an ESP32, and the key made on the chip. The code was run off the bot, on the same mbedTLS. Checking it on a real bot has the checks to run.