leonarski_fandClaude Opus 5.5
2981aedd3e
With a DECTRIS detector the broker starts the writers - and so learned the collection's start message - only when the detector's own start message arrived, after /start had returned. A reader started right after /start found no collection (404) and had to wait for, and race with, the detector. - /start registers the collection in LiveCollection (Expect) as it is accepted, so GET /live/events is accepted from then on. The image pusher fills in the start message when it starts the writers (Begin) - at once on the FPGA path, when the detector's start message arrives on the DECTRIS path. - The event stream's first event is now `start`, carrying that start message (CBOR, base64) with run number, file prefix, image count and images per file; it replaces `collection`. Until it is known the stream only keeps alive. file and end follow as before. - However the measurement thread ends, it ends a collection the pusher did not end (EndIfOpen), so a cancel or a failure before the detector streamed reaches the reader as `end` with an error. The wait is event-driven: it ends with the start message or with the measurement. - GET /live/start.cbor is removed: the stream carries the start message, one route less. - rugnux takes the start message from the stream (BrokerFeed::WaitForStart), so it can be started right after /start; files reported before it attached the reader are replayed to it. Tests: LiveCollection_ExpectedAtStart; BrokerFeed_StartFromEventStream (an event stream whose start message comes late, then a file and the end). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SVmAWnzCmRKAXVUCdc4iNi
9.2 KiB
Security
Jungfraujoch is a data-acquisition and analysis system for X-ray detectors, designed to run inside a controlled facility network. This document describes what the software does and does not protect against, the current known limitations, and the authentication work in progress.
Threat model and scope
The security model targets a semi-trusted internal facility network. The concern is a peer on that network reaching a Jungfraujoch service with little or no effort — a mistyped host/port, a curious colleague, a mis-pointed script, a stray browser tab — not a determined attacker and not passive wire capture (which is the responsibility of the network layer: 802.1x, VLANs, facility infrastructure).
The asset that matters most is the confidentiality of live analysis data: the diffraction images and derived metadata (unit cell, resolution, spot counts, sample name) that reveal which sample is being measured. This matters for industrial and proprietary experiments. By contrast, acquisition control (start / stop / configure) is treated as low risk — scientists operate their own experiments and there is little to gain from restricting it.
Security is best-effort: measures that materially impede normal operation get turned off, so the design favours a few high-value, low-friction controls over comprehensive lockdown.
Out of scope. Jungfraujoch is not designed to be exposed to an untrusted network or the public internet. Do not do this.
1. Good practice — what is and is not protected
What you can secure (and should)
These controls work and a deployment should apply them (see also DEPLOYMENT.md):
- Network isolation. Keep the broker and its data streams on a controlled segment. The broker ↔ writer ↔ receiver traffic should run on a dedicated back-end network, with the data-socket addresses pinned to that interface and the ports firewalled.
- Reverse proxy for TLS. The broker speaks plain HTTP. To get HTTPS, put a reverse proxy
(Apache / nginx) in front that terminates TLS and pin the broker to
localhostbehind it. The desktop viewer supportshttps://endpoints — choose the scheme in the Open HTTP Connection dialog. - Filesystem confinement of written data. The writer creates NXmx HDF5 files on shared storage. Confidentiality of that data at rest is enforced by the filesystem: run the writer under a dedicated identity and use directory ownership / ACLs (and setgid) so that only the owning experiment can read its files.
- Firewall the ZeroMQ ports. The image / preview / metadata / republish streams have no access control of their own (see below), so restrict who can reach those ports at the network layer.
What the software does NOT provide
The gaps are listed explicitly so a deployment does not assume protection that is not there:
- No authentication or authorization in the broker. The HTTP/REST API currently has no login, token, or access control. Anyone who can reach the broker's host and port has full read access (live images, unit cell, resolution, sample metadata) and full write access (start, cancel, reconfigure). Confidentiality currently depends entirely on network/firewall isolation. This is being addressed — see §3.
- No transport encryption in the broker. The broker serves plain HTTP; there is no built-in TLS. Encryption must be provided by a reverse proxy.
- No access control or encryption on the ZeroMQ streams. The preview, metadata, image, and
republish streams are unauthenticated sockets. Any peer that can connect can subscribe to live
data. For the image
PUSHstream specifically, an accidental extra consumer does not merely eavesdrop — aPULLpeer is load-balanced into the stream and will divert images away from the real writer. - No per-user isolation. The broker has no concept of users; it cannot separate one operator's access from another's.
- No application-level audit trail of who accessed or changed what.
Recommended deployment checklist
- Broker and back-end streams on an isolated network; never exposed to a general/untrusted network.
- ZeroMQ data-socket addresses pinned to the back-end interface; ports firewalled to known peers.
- TLS terminated by a reverse proxy; broker bound to
localhostbehind it. - Writer run under a dedicated identity; data directories owned / ACL'd per experiment (setgid) so users read only their own data.
- ZeroMQ compatibility streams (preview / metadata / republish) enabled only if actually consumed, and only on the trusted back-end.
2. Known issues
| # | Issue | Impact | Mitigation today |
|---|---|---|---|
| 1 | Broker HTTP API has no authentication for control, and read access is protected only per dataset | Anyone who can reach it can start / stop / configure; a dataset started without tokens is readable by anyone |
Per-dataset bearer tokens (§3) for the read endpoints; network / firewall isolation for the rest |
| 2 | Broker binds all interfaces, plain HTTP | Reachable from anywhere routable; no encryption | Expose only on the trusted segment; TLS via reverse proxy |
| 3 | ZeroMQ preview / metadata / image / republish streams are unauthenticated and unencrypted | Live-data exfiltration; a rogue PULL on the image stream diverts/steals images |
Firewall the ports; run only on the back-end network |
| 4 | Web frontend has no login | The bundled UI takes a dataset token (key button) but nothing identifies its user | Serve and reach it only on the trusted network |
Input robustness. Services parse framed data from peers on the (trusted) data path. Hardening of untrusted-frame handling (size caps, overflow guards) is ongoing; these paths are not intended to face an untrusted network.
3. Authenticated read access — per-dataset bearer tokens
The confidential read endpoints are protected with a best-effort, low-friction scheme; acquisition control stays open.
How it works. /start accepts an optional list of tokens - plain strings, any number, all
equivalent. A typical pair is one constant beamline secret and one secret minted for the
experiment, so both the beamline staff and the experiment's own users can open the data. While the
current dataset has tokens, the endpoints below answer 401 unless the request carries
Authorization: Bearer <one of them>; the 401 says nothing about the dataset. Every accepted
/start replaces the previous tokens, so a run started without them is open, and the next run's
users cannot read this one. No endpoint returns the tokens; the broker only compares strings
(constant-time) and keeps them in memory. Whoever runs /start hands the token to the viewers.
An accepted /start also clears what the previous run left readable - its statistics, plots and
buffered images - in the same step that installs the new tokens, so the previous run is never
served under the new tokens, and the new run's name never under the old ones. A refused /start
(wrong state, invalid settings) changes nothing.
| Endpoint | With tokens set |
|---|---|
/statistics/data_collection (dataset name, unit cell, ...) |
401 without a token |
/result/scan (dataset name, cell of a grid scan / rotation) |
401 without a token |
/image_buffer/start.cbor, /image_buffer/image.cbor, /image_buffer/image.jpeg, /image_buffer/image.tiff (the images and the start message) |
401 without a token |
/preview/plot, /preview/plot.bin (per-image plots, unit cell) |
401 without a token |
/live/events (the start message and the data files of the collection being written) |
401 without a token |
/statistics (the aggregate the web UI polls) |
200, but the measurement block is omitted |
everything else (/status, /config/*, /start, /cancel, masks, pedestal, ...) |
open |
Clients.
- jfjoch_viewer - the token field of File ▸ Open HTTP (password echo), the
JUNGFRAUJOCH_HTTP_TOKENenvironment variable, or D-Bus (LoadFile(url, image, sum, token)/SetHttpToken(token)); the dialog overrides both. A 401 clears the display and puts a note on the status bar - no dialog, since a changed dataset is the normal reason. - Web frontend - the key button in the top bar; the token lives in the tab's
sessionStorageand is sent with the protected calls only. The start form has a field for the tokens of a new run. - Python client -
Configuration(host=..., access_token="<token>"). - rugnux following a collection from the broker - the
JUNGFRAUJOCH_HTTP_TOKENenvironment variable, sent only in theAuthorizationheader and never written to its logs or reports. - Anything else -
curl -H "Authorization: Bearer <token>" ....
What it does not do. The broker still speaks plain HTTP, so the token crosses the network in
clear unless a TLS reverse proxy fronts the broker (§1); on a facility network this raises the bar
from "type the IP" to "capture packets", which is the aim. It does not authenticate users or
control, does not touch the ZeroMQ streams (issue #3), and /status's free-text message may
still quote a path. Datasets of different users within one session are separated by their tokens
alone; there is no long-lived login.