Skip to content

Security

Regis edited this page Oct 31, 2026 · 19 revisions

Security

ZenithBoard runs as root on a machine in your home, listens on your network, and installs software written by other people. This page says what that means, what is checked, what is trusted, and what was found and fixed along the way.

Found a hole? Use GitHub's private vulnerability reporting on the repository (Security → Report a vulnerability), or a normal issue if it is not sensitive. See SECURITY.md. It is a spare-time project with no security team and no deadline to promise — but a real report will be read, answered and credited.

In one table

Layer What protects it Since
Your network The wall has no login by design. It answers home networks only (ALLOW_FROM=private): a forwarded port meets a 403 from the internet until you open it on purpose 0.15.0
The wall server Runs as a nologin system user inside a full systemd sandbox; can write nowhere 0.12.0
Its HTTP answers Every header value comes from a fixed table inside the program 0.12.2
Photos The address must be https inside planespotters.net or plnspttrs.net before it is handed to the tablet; the credit's link too (0.54.11), and neither sends a referrer 0.11.1, 0.12.4, 0.24.5, 0.54.11
Files it serves Real-path check: nothing outside its own folders, symlinks included always
Updates of ZenithBoard The commit is signature-checked before install.sh runs as root. One GitHub release per version, pointing at that signed commit 0.12.0, fixed in 0.12.3; releases 0.15.0
Downloads run as root Private mktemp folder (mode 700), https only, no downgrade on redirect 0.12.0, fixed in 0.12.1
Third-party installers Trusted, not checked — written down below always
Package signatures Never turned off. The Flightradar24 and AirNav Radar keys are installed only if their primary key's fingerprint matches the pinned one, and only that key goes into apt's keyring, whatever else the downloaded file carries (0.99.12) always
Secrets The dynamic-DNS token, the Bluesky app password and the Telegram bot's token never go on a command line, into config.env or into a log; they live in root-owned files (the social and Telegram ones readable by their service's group, checked by zenithboard security) always; social 0.18.0; Telegram 0.99.6
The operating system Debian's security fixes can install themselves daily, from the security channel only; the feeders are left alone 0.15.0
Checking all of it zenithboard security reads the running Pi and says what is open and how to close it 0.15.0
The repository CodeQL, shellcheck, pinned actions, Dependabot, a monthly check of the download addresses 0.11.1
The main branch A GitHub ruleset: pull request only, squash only, signed commits, the three checks must pass, no force push, no deletion. It refused a merge when the tests failed October 2026
Tailscale Off by default (0.45.0). Installed from Tailscale's own repository, the package checked by apt against its key (no fingerprint is published to pin; the key is fetched over HTTPS, as Tailscale's own script does); the repository list is refused unless every line is Tailscale's, signed by that key. The account is the owner's; ZenithBoard never sees a password. The wall answers Tailscale's range only while it is on; the console only with tailscale console on. remove signs out and takes away what was installed 0.45.0
Backups A backup holds Flightradar24's sharing key and the stations' identities, so it is written for its owner only (mode 600) and backup show names them without their values; the Bluesky app password and the console password never go in. A restore unpacks only the names a backup holds, refuses links, devices and paths outside, asks for the typed word RESTORE, and keeps what it replaces. The console's backup leaves the identities out and is never restored from the console 0.42.0
Secrets in the repository GitHub secret scanning and push protection are on October 2026
Statistics Off by default. Its sample runs as the zenithboard user in the same kind of sandbox, and the /stats page answers the same networks as the wall 0.16.0
Telegram messages Off by default (0.99.6). Text only, to the owner's own chat; the emergency squawks go there and never to Bluesky; no distance or bearing from the antenna (a squawk names the town nearest the aircraft); the token typed in the terminal only, never in the console, a backup or a log, and taken out of any network error before it is written; the service runs as the zenithboard user in the same sandbox as the Bluesky one, reaching api.telegram.org only 0.99.6
Social sharing Off by default. Posts carry no distance, no bearing and no photo; a map, when chosen, is centred on the track with nothing marking the receiver, and its tiles come from a fixed address (EOX) over HTTPS, checked to be images and capped in size; the service runs as the zenithboard user in the wall's sandbox; the account's secret is root:zenithboard 0640, checked by the audit; the picture is drawn in memory and deleted after the post. Bluesky only since 0.19.0: an update removes a Mastodon token left on the Pi 0.18.0, map 0.19.0

What is exposed on your network

Surface Reachable from Notes
The wall, port 8080 Home networks (ALLOW_FROM=private) No login: it is meant to be opened by a tablet with no keyboard. Anyone outside the private ranges gets a 403, forwarded port or not. Since 0.54.0 the data answers only to the Pi's own names too (DNS rebinding, see the table below)
/api/planes, /api/config Same Aircraft in range, and display settings. The antenna's exact position is never sent. A radius_km that is not a number, or not a finite one (nan, inf), is the configured radius, held between 0.1 and 500 km; an answer is always strict JSON, never NaN (0.99.14)
tar1090, port 80 Same Installed by readsb, not by ZenithBoard
Plane Finder, port 30053 Same Its own setup page
graphs1090, port 8542 and /graphs1090 on port 80 Anyone who reaches the port: lighttpd has no address check Only when graphs on (0.32.0). The decoder's counters, CPU and temperature; the range graph gives distances, never the antenna's position. Served by lighttpd, not by ZenithBoard. zenithboard security names it
SkyAware, port 8504 (or 8978) Same Served by FlightAware's lighttpd, not by ZenithBoard. zenithboard security names it
/stats, /api/stats Same as the wall Only when STATS=1. Counts and ranges per hour and per day; the antenna's position is not part of it. Since 0.22.0 also the farthest aircraft of the day and of the month, each with the large city nearest it and its distance from the antenna: two such lines narrow down where the antenna is, one more reason this page answers the home network only
/api/farthest Same as the wall Only when STATS=1. What the statistics sample asks on the loopback: the farthest aircraft of today and yesterday, named, never with a position
/social/preview Same as the wall The picture zenithboard social test drew, if any
/console (0.39.0) Home networks only, whatever ALLOW_FROM says, and only by an address or a local name Only when console on. Behind a password (a scrypt hash in console.env) or a phone paired by a one-time QR code; it hands one action from a fixed list to a root helper. Plain HTTP: a cookie on your Wi-Fi is readable by someone who can read your Wi-Fi. See Web console

Do not forward any of these from the internet. Nothing here expects a hostile visitor: there is no login on the wall, no rate limit, and no audit trail. To see your wall from outside, use a VPN into your home network. The dynamic-DNS feature exists so you can find your Pi, not so the world can.

Since 0.15.0 the wall enforces that itself: it answers only the private ranges (10/8, 172.16/12, 192.168/16, the Pi, link-local, and their IPv6 equivalents) and gives everyone else a 403. A port forwarded by mistake therefore shows nothing. If you do want it public, or reachable through a VPN whose addresses are not private (Tailscale uses 100.64/10), say so: sudo zenithboard config-set ALLOW_FROM any, or the networks allowed, sudo zenithboard config-set ALLOW_FROM 100.64.0.0/10. The dynamic-DNS menu repeats this at the moment a name is set up. BIND_ADDRESS (default 0.0.0.0) is the other knob: 127.0.0.1 keeps the wall to the Pi itself, for a reverse proxy in front of it. Behind such a proxy every visitor comes from 127.0.0.1, the Pi itself: ALLOW_FROM, the console's home-network check and its slowing of failed sign-ins by address then see one address for everyone, and let it through. The proxy must do the filtering itself, and the console is best left off or reached another way (SSH, Tailscale).

The services can only do their own job

The wall server and the social sharing service run as the zenithboard system user, which cannot log in, inside a full systemd sandbox: no devices, no kernel tuning, modules or logs, no namespaces, no new privileges, an empty capability set, a restricted list of network families and a system-call filter. The wall server can write nowhere — it only reads — except, since 0.39.0, /var/lib/zenithboard/console/state (the web console's sessions and job spool; nothing there runs unless the root helper finds it on its fixed list).

What that buys: a hole in the wall server stays a hole in a read-only program that can see aircraft.json, its own files and the internet. It cannot become a foothold on the Pi.

Root never trusts a path the service user owns (0.99.11)

The services and root share /var/lib/zenithboard. Until 0.99.10 the folder belonged to the zenithboard user, so a hole in one of its services could have renamed root's update keyring (trust/) away and put its own in its place, or left a link where root was about to write. Since 0.99.11 (the review of 0.99.8, batch B3), on every install and update:

Path Owner, mode Who writes in it
/var/lib/zenithboard root:zenithboard 3771 (drwxrws--t) root, and the service's group for its own entries; the sticky bit keeps it from removing or renaming anything of root's
trust/, trust/gnupg/, restore-pending/ root, closed to everyone else root only. The update stops, and a restore's waiting identities are not used, when they are anything else
data/ root, 755 root (the monthly aircraft-type list)
console/, console/out/ root:zenithboard 750 root (the helper's results); the wall reads them
console/state/, its spool/, stats/, social/, telegram/, gain-log.csv zenithboard the services

Root makes those folders without following a link found in their place (a link is removed, owners are set on the name with chown -h), writes its files in a folder the service may write in to a new name renamed into place, and the console's root helper opens the spool once without following a link and reads and removes every job through that one descriptor.

Measure it yourself:

systemd-analyze security zenithboard-flightinfo

On the author's Pi 3B it scores 1.3 (OK), on a scale where 0 is fully locked down and 10 is unprotected. What remains open is what the job needs: the internet (for photos and routes) and Python's memory model.

Every ZenithBoard service is sandboxed since 0.15.0, each keeping only what its job needs. Measured offline on the unit files, and enforced by tests/test_units.sh so a directive cannot quietly disappear:

Unit Score What it keeps, and why
zenithboard-flightinfo 1.3 Nothing: it reads, and talks to the internet for photos and routes
zenithboard-gain-log 1.0 Runs as the zenithboard user, not root, since 0.15.0: it reads stats.json and appends one CSV line
zenithboard-social 1.3 Reads aircraft.json, asks the wall on the loopback, writes its own state folder (and the map tiles' cache in it), posts over the internet. Node or Pillow runs inside the same box to draw the picture
zenithboard-logs-clean 1.4 May write the journal folder, nothing else
zenithboard-ddns 1.7 curl, no capability at all; its status line lives in /run/zenithboard
zenithboard-data-refresh 4.2 Writes the aircraft-type list
zenithboard-netwatch 4.2 Keeps raw sockets for ping, netlink and D-Bus for nmcli and systemctl, and no system-call filter: a filter that killed ping would leave the Pi unwatched without a sound
zenithboard-wifi 3.9 Keeps CAP_NET_ADMIN for iw reg set and /dev/rfkill

The code is checked before it is run

zenithboard update pulls from GitHub and then runs install.sh as root. So before anything is merged or run, the new commit's signature is checked against keys you approved.

The first time, ZenithBoard fetches GitHub's signing-key file. GitHub rotated its key in 2024 and still publishes the expired one; expired or revoked keys are never trusted and, since 0.54.18, not even listed. The valid key is recorded in /var/lib/zenithboard/trust/signer.fpr.

Since 0.54.18 the current key is shipped with ZenithBoard (GITHUB_SIGNING_KEY_FPRS in lib/versions.sh: 968479A1AFF927E37D1A566BB5690EEEBB952194, key ID B5690EEEBB952194, checked on 25 October 2026: the key ID of the signature on main's latest commit, and GitHub's key file as the owner's fresh card read it). When GitHub's file holds exactly that key, it is trusted without a question. Until then every new card asked you to compare it with the Verified badge on GitHub, with the expired key listed first, and it read as an error (the owner's fresh card, 25 October 2026). That question came right after install.sh had run as root from the same clone, so the clone was already trusted; the question added a ceremony, not a check. A key GitHub adds later (a new rotation) is not in the shipped list: it is shown and asked about as before: click the Verified badge beside a commit on GitHub, and the key ID it shows must be the last 16 characters of the listed fingerprint.

After that the check is silent, and speaks only when something changes:

What it finds What it does
Good signature by a recorded key Installs, says nothing
Bad signature Refuses outright. It does not offer to continue
A signature by an expired key Treated as unknown, not as good
Not signed, or signed by another key Explains the possible honest reasons and asks. With nobody there to answer, nothing is installed

What the shipped fingerprint proves, and what it does not: it is in the files you cloned, so it proves no more than the clone itself. It changes nothing for an attacker who could already change those files before your first run; it stops one who changes the code GitHub sends later, exactly as the recorded fingerprint did.

While an update waits for your answer, you can see exactly which commit it is about to install, from a second terminal, and compare it with the top commit on GitHub:

git -C ~/ZenithBoard rev-parse --short origin/main

Housekeeping:

To Do
See the trusted keys sudo cat /var/lib/zenithboard/trust/signer.fpr
Start the trust over sudo rm /var/lib/zenithboard/trust/signer.fpr — the next update shows the keys and asks
Run a fork or your own branch sudo zenithboard config-set UPDATE_VERIFY 0

What is checked in the code

  • Files served by the wall. Both file handlers resolve the real path and refuse anything outside their folder, so ../../etc/shadow and its symlink cousins get a 404.
  • The photo address. Photos are found at Planespotters and, since 0.24.5, loaded by the tablet from the address the API gives (their terms forbid a proxy). The address must be https and inside planespotters.net or plnspttrs.net, checked when the answer arrives. Without it, a tampered answer could send the tablet to any address. The Pi no longer fetches any picture, so it no longer serves one either.
  • Every response header. The content type is chosen by file extension from a short list written in the program, the cache rule from two allowed values, and anything else gets a safe default. Nothing that arrives with a request or with somebody else's answer can reach a header — which closes header injection (a line break that splits one reply into two) for good.
  • Downloads that are about to be run as root land in a private folder made for the run (mktemp -d, mode 700), never on a fixed name in /tmp that somebody else could have created first.
  • Every download is https, TLS 1.2 or later, and a redirection cannot drop it to plain http on the way.
  • The dynamic-DNS token lives in a root-only file read by curl. It is never on a command line, never in zenithboard config, never in a log — which is why zenithboard config is safe to paste into an issue.
  • The Flightradar24 and AirNav Radar signing keys are installed only when the fingerprint of a primary key in the downloaded file matches the one recorded in lib/versions.sh, and only that key is written to apt's keyring: the file is read in a scratch GnuPG folder and the pinned key exported from it alone. Until 0.99.12 a file that carried the pinned key and another one was installed whole, and apt would have trusted both; a file where the pinned fingerprint is only a subkey of another key is refused. Package signature checking is never turned off, for any reason.

What is trusted, and cannot be checked

The installer runs other people's installers, as root, straight from the network:

Fetched and run as root From
readsb-install.sh wiedehopf/adsb-scripts on GitHub
feed.sh, feed-update.sh adsbexchange.com
stats.sh, only with adsbx-stats on (0.52.0, off by default) adsbexchange.com, then their GitHub
install_fr24_rpi.sh repo-feed.flightradar24.com
.deb packages FlightAware, Plane Finder
rbfeeder, from AirNav's apt repository (0.99.6, only when AirNav Radar is ticked) apt.rb24.com, its key installed only with the fingerprint pinned in lib/versions.sh; nothing of theirs is run as a script

This is a real trust decision, and it is not hidden. Installing ZenithBoard means trusting those projects as much as you trust this one. Pinning a checksum for each would break on every one of their releases, so what is pinned instead is the address, in lib/versions.sh, where you can read it before running anything. A monthly check (below) says when one of those addresses stops answering, and When a provider changes something says what happens then.

readsb cannot be uninstalled by ZenithBoard. Its installer builds it from source and ships no way back, so removing readsb prints the commands to run by hand instead of guessing which system files to delete. Everything ZenithBoard itself installed is removed normally.

If that trust is more than you want: install readsb yourself, by hand, and use only the wall. The wall needs nothing but aircraft.json.

The supply chain

Deliberately very little. Python standard library only, no pip install; plain browser JavaScript, no build step, no npm; bash. There is no lockfile because there is nothing to lock — the main reason a dependency scanner finds nothing to report here: the dependencies were never taken on.

What is left is the GitHub Actions used by CI. They are pinned to a commit, not a tag, since a tag can be moved to other code and these run with a token, and each job gets only the permissions it needs. Dependabot opens a pull request when a pinned action has a new release.

What runs on every change

Check When Does
shellcheck (-S warning, following source) every push Quoting, unset variables, the usual shell traps
CodeQL, Python and JavaScript every pull request, and Mondays Injection, unsafe data flows, dead code
The test suite every push Including the address, header, trust and temp-folder checks above, and that the command reference lists every command
The download-address check the 1st of each month, or by hand Opens one issue when a pinned address stops answering (tools/check-links.sh)
Dependabot monthly Pull requests for the pinned actions

How CodeQL findings are handled: a real finding is fixed and gets a test. A finding that describes something deliberate is dismissed in the Security tab as Won't fix, with the reason written in the dismissal — the rule is never switched off, because it should still catch the next mistake. Two are dismissed this way today, and a third, an Empty except note raised on the statistics reader the same day, was fixed rather than dismissed. The notes open on 21 October 2026 (eight Empty except, one mixed returns) were fixed in 0.40.1, with two more of the same kind: each empty except now says in a comment why nothing is to be done there. Third-party code is not analysed: flightinfo/static/vendor/ (the QR code generator, kept unchanged and checked by its checksum, see its README) is listed in paths-ignore in .github/workflows/codeql.yml, with the reason; its one note, a missing semicolon in its own style, is not ours to change:

Alert Why it stays
types.json is mode 0644 A public list of aircraft model names, written by root and read by the wall server as another user; not world-writable

Tools that are not used, and why, since the question comes up: Trivy reads lockfiles, and there are none. OWASP ZAP tests running web applications, and this one is five routes with no login, no forms and no database — it was read line by line instead, which is how the photo-address problem was found. Opengrep/Semgrep would duplicate what CodeQL and shellcheck already cover.

What was found, and when

Kept as a record, because a security page that only lists what is fine is not believable.

Version Found by What Fix
0.11.1 Reading the code The Pi followed a photo address from a third-party answer without checking it https + host check, tested
0.11.2 The monthly link check, first run Removing readsb fetched an uninstaller that no longer exists, so it silently did nothing Says so, prints the manual commands
0.12.0 Review Downloads run as root went to fixed names in /tmp Private folder
0.12.1 A real Pi's update output The private folder was made inside a sub-shell that deleted it again: updates of readsb and ADSB Exchange failed with curl: (23) Folder made once by the command; a test holds it
0.12.1 CodeQL, first run A photo's type went into a response header: a line break could have split the reply Known image types only
0.12.2 CodeQL The 0.12.1 line-break filter was not recognisable as a protection Every header from a fixed table
0.12.3 A real Pi asking at every update GitHub's key file has its expired key first; only that one was recorded All usable keys recorded, expired ones never
0.12.4 The wall itself The host check left out plnspttrs.net, where the pictures actually are, so every photo was refused in silence Both domains allowed; the test uses the real answer
0.54.0 The audit of 22-23 October 2026 The wall's data answered any name once the address was a home one: a page on another site pointing its own name at the Pi (DNS rebinding) could read /api/planes from a browser on the home network, aircraft positions and distances, from which the antenna's position follows /api/* and /social/preview* answer only to an address, a local name, the Pi's own name, DDNS_HOST or a name in CONSOLE_HOSTS (the console's rule); not asked when ALLOW_FROM=any. A router's own name (pi.fritz.box) is added with config-set CONSOLE_HOSTS
0.15.0 Reading the code again The wall answered anyone, forwarded port included; Grafana kept admin/admin; five timers ran as root with no sandbox; the Pi installed no security fixes by itself ALLOW_FROM=private; a generated Grafana password; every unit sandboxed; zenithboard patches; zenithboard security to check all of it
0.16.1 The first zenithboard security on a real Pi An older install still had the unsandboxed data-refresh unit (score 9.6): updates installed new unit files only for features that were switched on, never refreshing the ones already there. The same port was listed twice; feeder ports were unrecognised Every update now refreshes every ZenithBoard unit file the Pi has; ports listed once; decoder and feeder ports recognised
0.16.2+ CodeQL, on main An except OSError: pass in the statistics reader: the deliberate fallback (keep the running count when a day file is gone) was indistinguishable from a forgotten error The fallback is an explicit return value, same behaviour
0.16.2 The same audit, rerun Ports 8504 and 8978 were reported as unknown: they are SkyAware, served by FlightAware's lighttpd Recognised and named

What the author's own Pi says

zenithboard security was run on the Pi that is actually outside, on 15 October 2026 (version 0.16.2). Everything passes except two warnings, and both are decisions rather than oversights:

Warning Decision
Debian security patches are not switched on Left to the owner: sudo zenithboard patches on when wanted. It is off by default because a machine that changes itself at night should be a choice
SSH still accepts passwords Kept on purpose. The Pi is reached by SSH from the home network only, nothing forwards port 22, and the wall refuses everyone outside the private ranges. The warning stays visible in the audit so the decision stays a decision. Anyone who opens the Pi to the internet should turn passwords off first

All five services are sandboxed, and every listening port is recognised: none is unexpected.

Running it more tightly, if you want to

  • Put the Pi on a guest network or its own VLAN. It needs the internet and nothing else on your LAN.
  • Run zenithboard security and do what its WARN lines say.
  • sudo zenithboard update regularly: it is what brings security fixes to the decoder and the feeders.
  • sudo zenithboard patches on: Debian's security fixes, daily, from the security channel only. The feeders are left out on purpose — a feeder restarting itself at three in the morning can quietly break the single-MLAT rule — and the Pi is never rebooted by it. patches off removes exactly what on added.
  • SSH with a key rather than a password, once your key is in place: PasswordAuthentication no in /etc/ssh/sshd_config.d/zenithboard.conf, then sudo systemctl restart ssh. zenithboard security reads this setting.

Clone this wiki locally