A highly secure, very lightweight, query system that lets outside applications run pre-approved SPARQL queries against a protected internal triplestore -- without ever exposing the triplestore, the query text, or an open SPARQL endpoint to the outside world. Users are Outside, Queries stay Inside.
The name comes from the popular TV series Severance where there is no communication between someone's "public facing self" and their "work self." The transition happens while riding the elevator to their office (the project logo). The outside world is completely excluded from the internal, very sensitive business.
Version: 2.0.0 (see VERSION; the running services also report it themselves --
External's GET /severance includes it in its plain-text response, and Internal logs it once at
startup). Maintaining/releasing this project? See RELEASING.md.
Already running Severance 1.1.0? Read Upgrading from 1.1.0 before you touch anything! Both components must be upgraded together.
Both must be running for the system to actually answer anything! Deploy only External and it will queue requests forever without ever returning a result -- it never talks to the triplestore itself, only Internal does.
A caller that needs Severance's query results in some other Interface (REDCap, GA4GH Beacon v2, a Shallot/GRLC-shaped service, or anything else) doesn't talk to External directly -- it goes through a
facade: a thin translation layer that speaks the external API on one side and only ever calls
External's own public API (available_queries, queries, jobs/:uuid) on the other. Facades live in
their own repo, FAIR-Data-Systems/Severance-Facades
-- see that repo's README for the two existing examples (shallot-facade, beacon-facade) and a
"How to implement a new facade" guide if you're building another one. Note that EURO-NMD have implemented their own "facade" for REDCap, and can provide advice on how to do that.
Building or installing a facade does NOT give you access to any data! A facade only provides an interface to queries the data provider has already approved and registered in Severance Internal. If the query you need doesn't exist there yet, you must negotiate with the data provider to get it added -- no facade, however cleverly built, can get you data through a query that was never registered.
Query Flow Diagram
Interoperability and Security Features:
- Requires an authorization token -- External will not even start without one! It must be at least 32 characters; example values like
YesItsMeare refused. Tokens are checked in constant time and case-sensitively, and repeated wrong guesses from one address are throttled. - Queries are named and pre-approved, not arbitrary -- you cannot run arbitrary SPARQL through Severance, ever, no matter what token or facade you have.
- The query itself is never passed -- it exists only in the internal component, referred to by name.
- Follows web standards for queued processes.
- External and Internal components are fully independent (containers); Internal can be switched off and External will continue to queue (no lost requests).
- No external connection to the secure area -- Inside to Outside only.
- Flooding External with requests cannot overload Internal or your triplestore -- Internal takes queries from the queue one at a time. (A flood CAN fill the queue and delay genuine requests; External caps the queue length -- see
MAX_PENDING_JOBSin the External guide.) - Data in the "intermediate store" is immediately encrypted upon arrival from the Triplestore.
- Data is decrypted and deleted as soon as it is called by the user -- no second chances, but also lower risk.
- Severance never writes query results to disk unencrypted; on both Internal and External, unencrypted results are only ever held in memory. (Your operating system can still swap memory to disk -- if that matters to you, turn swap off or encrypt it on both servers.)
- Variables holding unencrypted results, and the web server's response buffer, are overwritten with zeros and released as soon as they are no longer needed, to keep unencrypted data in memory for as short a time as possible. This is best effort: Ruby can make internal copies of data that no program can reach to erase.
- The Internal component runs with a RAM-based tempfile system, so attempts to write to
/tmpdo not go to disk. - Code content of the Docker containers is minimal -- a very low profile for security risks.
- Containers both run as unprivileged users.
- Incoming query bindings are cleansed before being placed into a query, not merely quoted:
iri-typed bindings are validated against the SPARQL 1.1IRIREFgrammar's disallowed characters and rejected outright (not sanitized and passed through) if invalid, and other typed bindings are quote-escaped. All bindings are then substituted in a single pass, so text one binding inserts is never re-read as a placeholder for another. This closes off using a pre-approved query's own parameters as an injection vector to reach data outside that query's intended scope -- seeCHANGELOG.mdfor the vulnerabilities this fixed. - Internal proves who it is to External with its own secret (
INNIE_TOKEN), separate from the callers'AUTH_TOKEN. Being on an allowed IP address is NOT enough on its own! An IP address is not an identity. - Each encrypted answer is bound to its own job: an answer moved into another job's slot fails to decrypt instead of being handed to the wrong caller.
- Request sizes, answer sizes and the length of the queue are all capped, so a flood of requests cannot fill External's disk.
- Binding values and the final, filled-in query text are never written to the logs.
- Nothing is queryable until the data provider puts it there. Internal starts with an empty query folder -- example queries are copied in only when explicitly asked for, for testing.
- Severance only ever reads: a query that would change data (SPARQL Update) is refused before it is offered or run -- on top of the read-only triplestore account you must use anyway.
- If a query lists the values a variable may take (
#+ enumerate:), no other value is accepted.
Before you deploy or update, look at what our scanner found in the exact images you're about
to run! Every image we publish is scanned for CRITICAL and HIGH vulnerabilities, and every
finding is published, each with our individual judgment on whether it can actually be reached in
Severance and why. Start with Security/VULNERABILITY_TRIAGE.md
-- its first section is written for you, and tells you how to read the rest. A long list of
findings is NOT the same as a long list of risks! Read the Decision column, not the count.
A scanner cannot find flaws in Severance's own design! For those, read Security/PEER_ADVISORIES.md: every security problem published by similar projects, whether Severance has the same kind of flaw, and which ones are still OPEN.
A note on how this and the list below are produced: several of the items above and the attack scenarios below (including the injection fix referenced in #15) were identified through simulated/predicted attack analysis performed with Claude AI, not from a professional penetration test or formal security audit. This is a useful additional lens, but it is not a substitute for one, and there is no guarantee it has found every vulnerability. Treat this list as "known issues considered and addressed so far," not as "a certified list of everything that could go wrong."
Possible Attacks?
- Modify queries -- high-impact attack. Likelihood? An attacker needs to either a) secretly change the query in GitHub so that a corrupted query is pulled by the Inside; b) count on the Inside forgetting to vet the queries they author or pull from GitHub (since this is voluntary and manual!); or c) already be inside the protected space with file-level access to modify the query -- in which case there are bigger problems! The most likely attacker profile for all of these is a rogue employee.
- Modification of the Docker image -- high-impact attack, similar risk profile to above.
- All other attacks we can imagine already require the attacker to be inside the Secure Zone, which is already the highest level of impact regardless of this software's security.
AUTH_TOKENcapture/replay -- real, and worth understanding rather than assuming away.AUTH_TOKENis a static, unsigned bearer value: whoever configures a client (a browser app, RedCap, a custom facade, etc.) to send it must keep it secret, but nothing in the protocol itself binds it to a specific request, a specific time window, or a specific caller. Anyone who ever sees the value -- a leaked config file, a compromised client host, a value visible in a client's own browser devtools/Network tab if it's ever handled client-side -- can replay it indefinitely from anywhere. This is bounded, not eliminated, by the named-query design: a stolen token only ever grants "submit one of the pre-approvedquery_ids with attacker-chosen binding values" -- never arbitrary SPARQL, never discovery of the query text itself (which never leaves Internal). Don't rely onAUTH_TOKENas strong evidence of who is calling, only as a basic filter against casual/accidental access; if a specific integration needs real per-caller distinction, that has to be built into the query design (bindings, tighter per-query allow-lists) rather than assumed from the token. Requiring a long random token and throttling wrong guesses makes guessing it hopeless -- it does nothing against a token that has already leaked! Every caller shares the same token, so rotating it means updating every caller at once.- Impersonating Internal -- whoever can pull from External's queue sees every caller's request, and whoever can push answers decides what callers receive. This is why Internal's routes need BOTH an allowed IP address AND
INNIE_TOKEN. GuardINNIE_TOKENmore carefully thanAUTH_TOKEN, and NEVER give it to a caller or a facade! Our penetration testing confirmed that a leakedINNIE_TOKENis on its own enough to do all of this ifALLOWED_INTERNAL_IPSis a wide range -- so pin that list to Internal's exact address, as a second barrier that still blocks a stolen token (details in the External install guide). There is also no built-in TLS between Internal and External: if they talk across a network you don't trust, put HTTPS in front of External, or anyone on that network can read the token. - Stealing a caller's answer with its job URL -- a finished answer is collected by its job URL (an unguessable random ID) plus the
AUTH_TOKEN, and only once. Severance does not separately check which caller collects it, so anyone holding both the URL and the token can take the answer -- and collecting it removes it from the real caller. The ID can't be guessed or enumerated, so this only bites if a job URL leaks (logs, browser history, a non-TLS hop). Run External behind HTTPS and treat the job URL as a secret; see "Treat the job URL as a secret" in the External install guide. (Confirmed in our penetration testing. Not an issue for a single caller; tying results to a specific caller would need per-caller tokens.) - Locking out your callers (availability, not disclosure) -- External throttles repeated failed logins per source address, which stops online token-guessing. But if your callers all reach External looking like the same address (a reverse proxy that hides the real client address, or some Docker published-port setups), anyone who can reach the port can trip that shared limit with wrong tokens and briefly lock out your real caller(s) -- without knowing the token. It is self-healing (it clears after a short window) and exposes no data, but if availability matters, read the "failed-login throttle" section in the External install guide and either restrict who can reach the port, make sure the real client address reaches External, or turn the throttle down. A confirmed finding from our own penetration testing.

