Security
Policies
Section titled “Policies”Settings → Security. Values from minibrain.yaml (policy:) or MINIBRAIN_POLICY_<NAME> are locked in the UI and
show “Set by config file” or “Set by environment”; the rest are editable, and every change is written to the audit
log with who, before and after.
| Policy | Values | Enforced at |
|---|---|---|
| Network | Open, Allowlist (hosts), Offline (MINIBRAIN_OFFLINE forces it) |
Downloads, retries, S3 imports, catalogue sync, Add from Hugging Face, the online check |
| Model sources | Approved publishers (default), any, imports only | Download, retry, Add from Hugging Face (shown only with any) |
| Licences | Only selected licences (default; a list of reviewed commercial licences) or any licence, including unreviewed ones | Download, retry, Add from Hugging Face |
| Safetensors only | Always on | Download file filter; pickle weights are never loaded |
| Request logs | Always on, metadata only; retention in days | Hourly purge on the leader (below) |
| Request inputs and answers | Default for new models (off), and Lock for every model | Gateway config, per model (below) |
| API keys | Expiry in days for new keys | Gateway rejects expired keys with 401, and models the key does not cover with 403 |
| Audit log retention | Days, 0 keeps every event (default) | Hourly prune on the leader, cut at a chain anchor (below) |
| SIEM export | Off (default), TLS, TCP or UDP; host, port (0 is 6514 for TLS, 514 otherwise), CA bundle path | Syslog forwarder on the leader (below) |
| OpenTelemetry export | Off (default) or OTLP over HTTP; collector endpoint, headers (encrypted, write-only), service name, CA bundle path; also OTEL_EXPORTER_OTLP_* |
Exporters in main and gateways, applied within 5 seconds (observability) |
| Encryption at rest | Local key file (default), HashiCorp Vault Transit, PKCS#11 HSM, AWS KMS or Off; each provider’s settings | Every file main stores (below) |
Request logs
Section titled “Request logs”- Every
/v1request is logged with its time, model, version, key, status, latency, tokens in and out, finish reason and response ID. These hold no content; Monitor, Overview, cost and the Requests tab depend on them, so there is no switch to turn them off. Log retention deletes them. - A request’s input (the last user message) and the model’s answer are kept only for models whose “Keep request inputs
and answers” switch is on, on the model’s deployment page. Off by default. Builders change it; each change is audited
as
model.request_bodieswith the value before and after. Kept inputs and answers let apps send feedback with the response ID alone, feed distillation, and show on the Requests tab to Builders and Admins. They are stored in the database next to the request log and deleted with it. - The Request inputs and answers policy is the default for new models, and the setting for base models served through
/v1. Lock for every model (request_bodies_locked) makes every model follow it: each model’s switch shows the value and cannot be changed, and Builders get a 409. Settingrequest_bodiesinminibrain.yamlorMINIBRAIN_POLICY_REQUEST_BODIESlocks it for every model too, unlessrequest_bodies_locked: falseis set beside it. POST /v1/feedbackwithoutinputfor a model that does not keep them returns 422 and names the model’s switch.- Gateways, standalone ones included, get each model’s value in their config snapshot, within a second of a change.
Accounts and sign-in
Section titled “Accounts and sign-in”People sign in to the UI and /api; apps call /v1 with API keys only, and workers and engines keep their tokens.
| Source | How | Notes |
|---|---|---|
| Local accounts | Email and password; an admin adds people with a one-time set-password link (24 hours), or minibrain admin create on the server |
PBKDF2-HMAC-SHA256, 600,000 iterations, 16-byte salt, through cryptography; 10 failures lock the account for 15 minutes |
| OIDC | Authorization code with PKCE (S256) through Authlib; the ID token is checked with joserfc (issuer, audience, expiry, nonce, signature from the provider’s JWKS; RSA, RSA-PSS or ECDSA only) | The issuer must match discovery; state, nonce and verifier sit in a signed, HttpOnly cookie for 10 minutes |
| Proxy headers | X-Forwarded-User, -Email, -Groups (names configurable) |
Honoured only from auth.proxy.addresses; the same headers from anywhere else are ignored |
- Accounts are always on: everyone who opens the UI or calls
/apisigns in, on loopback too. Audit events name the person; workers, engines and/v1keep their tokens and API keys. - Sessions: a random 256-bit token in an HttpOnly, SameSite=Lax cookie; the database keeps only its SHA-256. Idle
and absolute lifetimes are the
session_idle_minutes(480, a working day) andsession_hours(168, a week) policies. Signing out, a new password or turning an account off ends sessions at once. - Your account (Settings › Your account,
/api/me, any signed-in person, no role needed): people rename themselves, list their own sessions and end any other one, and local accounts change their password. A change needs the current password; wrong ones count toward the same per-address lockout as sign-in. The new password follows the same policy, and every other session of the account ends while this one stays. Session ids of other accounts answer 404. Audit actions:account.update,account.password_change,account.password_change_failed,account.session_end,account.sessions_end. Single sign-on and proxy accounts have no password in minibrain. - The cookie is Secure when the request is HTTPS, a configured proxy says it was (
X-Forwarded-Proto), or the browser’sOriginis HTTPS. Plain HTTP on loopback (localhost,127.0.0.1,::1) gets no Secure flag, since Safari drops Secure cookies onhttp://localhost. Plain HTTP on any other address gets it, so the browser keeps no session there, and the sign-in page says to use TLS or localhost. - CSRF: every state-changing
/apicall from a signed-in person carriesX-CSRF-Token, an HMAC-SHA256 of the session (or proxy identity) under a per-install key. - Forwarded client addresses (
X-Forwarded-For,X-Forwarded-Proto) count only fromauth.proxy.addresses; uvicorn’s own proxy-header handling is off. - Roles: Viewer, Builder and Admin, enforced by one guard per
/apiroute;tests/test_access.pylists every route with its role. Viewers get versions, jobs and model details without data rows. - The OIDC provider is called directly by main (discovery, JWKS, token); the network policy does not apply to it,
since an admin configured it.
auth.oidc.ca_bundletrusts an internal CA.
auth: default_role: none # none, viewer, builder or admin for people with no mapped group admins: [[email protected]] # emails or user names that are always admins; locked in Settings > Accounts roles: # identity provider group -> role; locked in Settings > Accounts minibrain-admins: admin ml-team: builder proxy: addresses: [10.0.0.10/32] # only these may send identity headers oidc: issuer: https://keycloak.corp/realms/corp client_id: minibrain client_secret_file: /run/secrets/oidc # or MINIBRAIN_OIDC_CLIENT_SECRET; omit for a public client label: Keycloak groups_claim: groupsFirst admin
Section titled “First admin”| Way | For | How |
|---|---|---|
| Setup link | The default, native and Docker | The first start with no accounts prints a one-time link that creates the admin |
| Environment | Automated deploys | MINIBRAIN_ADMIN_EMAIL and MINIBRAIN_ADMIN_PASSWORD_FILE create the admin on the first start |
| Single sign-on | OIDC or proxy headers | A group mapped to admin, or a person in auth.admins, in minibrain.yaml; no local admin and no setup link |
| Command line | Recovery | minibrain admin create adds an admin; minibrain admin reset-password sets a new password |
Setup link:
minibrain serveprints it once main listens, to standard output, so it lands in the terminal or the container log:http://127.0.0.1:8000/setup?token=…. On a desktop terminal it also opens it in the browser; not in Docker, CI, over SSH or without a TTY, and never with--no-browser.- The token is 256 random bits from
secrets. The database keeps only its SHA-256 (inapp_settings), so the link survives restarts until it is used. It works once, and creating the admin any other way voids it. Later starts print a reminder instead of the link, since minibrain cannot show it again. - Lost it:
minibrain admin setup-linkprints a new link and voids the old one;--url https://minibrain.corpnames the address people use. In Docker:docker logs minibrain | grep setup, ordocker exec minibrain minibrain admin setup-link. - The link names the address main listens on (
127.0.0.1:8000unless--hostor--portchange it). Opening minibrain at another address, keep the path and the token. The page asks for the token when the link lacks it.
Environment, for automated deploys:
MINIBRAIN_ADMIN_EMAILwithMINIBRAIN_ADMIN_PASSWORD_FILE, a file such as a Docker or Kubernetes secret that holds the password (a trailing newline is dropped). Read on the first start only, and ignored once any account exists, so changing them later changes nothing.- A plain
MINIBRAIN_ADMIN_PASSWORDworks too, but logs a warning recommending the file: environment variables show indocker inspectand process listings. minibrain never logs the password. - A missing or unreadable password file, a password under 12 characters or a malformed email stops the start with the reason.
Single sign-on only: with auth.oidc or auth.proxy set and auth.roles mapping a group to admin, auth.admins
listing people by email or user name (or auth.default_role: admin), no local admin is needed. minibrain issues no setup link; the first page is sign-in, and
whoever signs in from the admin group is an admin. minibrain admin create still adds a local admin, such as a
break-glass account. With single sign-on but no admin group, the setup link is issued as usual.
Recovery: minibrain admin reset-password --email [email protected] sets a new password for a local account, clears
a lockout and ends its sessions; minibrain admin create --email [email protected] adds another admin. Both ask for the
password, or read it with --password-stdin, and record command line as the actor in the audit log.
Password guesses are throttled by client address (the peer, or the address a trusted proxy forwards): one address gets 30 sign-in attempts in 5 minutes, then 429 until the oldest ages out, and 10 wrong passwords for one account from one address lock that account for 15 minutes from that address only, so guessing from one place cannot lock the admin out everywhere. A password reset clears the account’s lockouts.
Trust zones and ports
Section titled “Trust zones and ports”| Zone | Holds | Accepts connections from | Ports |
|---|---|---|---|
| Corporate network | Apps, browsers | ||
| Edge | Load balancers | The corporate network | 443 |
| Internal network | Gateways, mains, Postgres, S3 | The edge; GPU pools reach main only | gateway 8100, main 8000, Postgres 5432, S3 443 |
| GPU network | Workers, engines | Engines: gateways only. Workers: nothing | Outbound HTTPS to main 8000, and to the bucket endpoint when Storage is S3 |
- GPU boxes need no internet access: engines and workers pull adapters and dataset versions from
main, and base weights frommainor, when Storage is S3, from the bucket on linksmainsigns. They never hold bucket keys. - Workers and engines on other machines join a pool in one of two ways, never with database credentials and never
with neither; there is no switch that lets machines join unchecked.
- Pool token. Each pool has one join token (
MINIBRAIN_JOIN_TOKEN): 256 random bits aftermbj_, shown once when an admin makes it (Infrastructure › Add machine) or rotates it (the pool’s row under Machines). The database keeps its SHA-256 and its first 12 characters. Rotating revokes the old token at once: workers on it get 401 and stop with the reason, and the engine tokens minted from it end too. - Approval.
minibrain worker --main URLwith no token makes a 256-bit request key (mbr_…), sends it with the host name, a hardware summary and the pool asked for, and prints a 6-character code (no 0, O, 1 or I). Main keeps the key’s SHA-256; the request waits under Infrastructure › Machines › Waiting for approval for an hour, then expires. An admin checks the code and approves it into a pool, or denies it. On its next poll the worker gets a machine credential (mbm_…, stored as SHA-256, handed out once) bound to that pool and host, saves it in<home>/worker/approval.json(mode 0600) and uses it on later starts. Removing the machine revokes it (401); rotating the pool’s token does not. A request key reaches nothing but its own request’s state. - Join requests are limited to 5 waiting per address and 50 in all (429); a new request from the same host and address replaces its older one.
- Pool token. Each pool has one join token (
- Either credential reaches
/internal/worker/*and what engines need on/internal/gateway/*, for its pool only: registering, claiming, asking for engines or announcing an engine in another pool answers 403, as does an approved credential used from another host. Making, rotating, a machine first joining with a token, requests, approvals, denials, revocations and every refusal (wrong pool or host, revoked, too many requests; one event per target, pool and address in 10 minutes) are audit events (join_token.*,join_request.*). - The worker main starts on its own machine uses
<home>/secrets/worker_token, which joins thelocalpool only; thelocalpool takes no other machine. - Engines a worker starts in a pool get a narrower engine token for that pool (announce in that pool, base weights,
adapters of models served in that pool; serving), never the gateway token, whose
config carries routes and API key digests. An engine token is signed with
<home>/secrets/engine_tokenover the pool and the pool token or approval that admitted the worker, and main checks that credential on every use: rotating the token or removing the approved machine ends its engines’ tokens at once (401), in that pool only, and each refusal is ajoin_token.refusedevent on the credential, rate-limited like the others. Thelocalpool’s engines use the gateway token and are not affected. - A worker on a pool token or an approval downloads only what the jobs it holds need. Each download
(
/internal/worker/artifacts/<id>,/internal/worker/bases/<key>, its files and/stored) carries the job’s lease inX-Job-Lease, and main answers only for an artifact or base model named in the params of that running job, leased to a worker of the credential’s pool: its dataset version, adapter and base model. Anything else, including another pool’s dataset or the same job’s inputs after its lease ends, answers 403 and writes ajoin_token.refusedevent (one per credential, reason and address in 10 minutes; the first asked id is in the event). An engine token gets an adapter only when a version on a base model deployed, or running, in its pool uses it; other artifacts answer 403 the same way. The local worker token is unaffected: that worker shares main’s machine. - Identity headers from a reverse proxy are trusted only when the request comes from a configured proxy address.
- Deleting a model writes an audit event with who, what and its size.
- No outbound telemetry. With the Offline network policy nothing leaves the install, except audit events to the SIEM you configure, traces and metrics to the OpenTelemetry collector you configure, the Vault or AWS KMS that holds the master key, and artifact storage you point at a bucket. Settings → This install lists the SIEM, collector and bucket; Settings → Security shows the key service. The OTLP exporter ignores proxy variables and does not follow redirects.
/metricsis off untilmetrics.addressesor a scrape token is set, and then needs that address or token, not a session (observability).- Every response carries an
X-Request-ID, and JSON logs (MINIBRAIN_LOG_FORMAT=json) carry it on each line. - Content hashes and signatures use SHA-256 through OpenSSL or
cryptography; never MD5 or SHA-1. - DuckDB extensions are native code; the one that does its own TLS (delta) is kept off the network (below).
TLS in DuckDB extensions
Section titled “TLS in DuckDB extensions”S3, Iceberg and Delta Lake sources are read by DuckDB extensions, native code that the Python crypto checks cannot see. Checked on DuckDB v2.0.0 (osx_arm64 and linux_amd64 builds from extensions.duckdb.org):
| Extension | Sources | TLS and S3 request signing |
|---|---|---|
| httpfs | S3, Iceberg data and metadata | OpenSSL 3.6.0, linked into the extension |
| iceberg, avro | Iceberg | None of their own: they read through httpfs |
| delta | Delta Lake | The table log: delta-kernel-rs’s own client, object_store 0.13.2 over reqwest and rustls 0.23 with ring 0.17 (aws-lc-rs is linked too), SigV4 signed with ring’s HMAC. Data files: httpfs |
So minibrain reads Delta tables only from folders on the server, inside Settings → Security → Folder sources: local
disk, NFS or SMB, or a bucket mounted by a client whose TLS you control. s3://, https:// and every other URL is
refused when the source is added, and dataset SQL cannot call delta_* functions. On a local path the kernel opens no
connection and does no cryptography: the extension checks DuckDB’s allowed_directories (the table’s folder), the
kernel reads _delta_log itself, and DuckDB reads the data files through its own file system. A _delta_log that is
a symbolic link is refused.
Evidence:
- Build: DuckDB v2.0.0 pins duckdb-delta at
9dcfb65, whoseCMakeLists.txtbuilds delta-kernel-rs v0.28.0 with--features default-engine-rustls. Its scan code says the kernel “resolves the table location using its own file and HTTP I/O, outside of the file systems of DuckDB”. - Binary:
delta.duckdb_extensionhas no OpenSSL (noSSL_CTX_new, no OpenSSL version string; httpfs has both) and carries rustls 0.23.37, ring 0.17.14, aws-lc-rs 1.16.2, hyper-rustls and object_store 0.13.2;otool -Lshows only system libraries.object_store::util::hmac_sha256callsring::hmac::Key::newandring::hmac::sign. - Run: S3 (moto) over TLS with a private CA, behind a proxy that logs each ClientHello. With DuckDB’s
ca_cert_file(an OpenSSL setting) pointing at the CA,read_parquetover httpfs succeeds with OpenSSL’s ClientHello (30 cipher suites with CBC and DHE, X25519MLKEM768 offered).delta_scanon the same connection fails in the kernel (DeltaKernel ObjectStoreError, “error sending request” after 10 retries), each attempt a rustls ClientHello (9 AEAD suites and the renegotiation SCSV, no CBC, groups X25519, P-256 and P-384: ring’s set). Over plain HTTP, the log requests carryUser-Agent: object_store/0.13.2and the data file readsduckdb/v2.0.0.
Re-check after a DuckDB upgrade: strings -a delta.duckdb_extension | grep -E 'rustls-|ring-|^OpenSSL [0-9]'. Delta
on S3 can come back when the kernel reads its log through DuckDB’s file system or is built with
default-engine-native-tls against OpenSSL; a self-built extension would also need DuckDB’s unsigned extensions
setting, which minibrain keeps off.
Audit log integrity
Section titled “Audit log integrity”Every audit event is append-only and hash-chained. Writers insert events as before, with no chain fields; the leader
seals them about once a second. Sealing locks the one-row audit_chain head (an UPDATE of that row, which waits on
Postgres and takes SQLite’s write lock), takes the unsealed events in id order and gives each the next sequence number
(seq), the previous event’s hash (prev_hash) and its own hash, then moves the head. On Postgres an id can commit
after a higher one; it is simply sealed later, with a higher seq, so the chain follows commit order and nothing is
skipped. A unique index on seq backs the lock. Events recorded before the chain existed are chained on the first seal,
in id order.
hash is the lowercase hex SHA-256 of the event’s canonical form: this JSON object as ASCII bytes, with keys sorted
at every level, no whitespace (, and : as separators) and every non-ASCII character escaped as \uXXXX
(Python’s json.dumps(fields, sort_keys=True, separators=(",", ":"))):
| Key | Value |
|---|---|
seq |
Sequence number, from 1 |
prev_hash |
The previous event’s hash; 64 zeros for seq 1 |
at |
UTC time with six fractional digits and Z, as 2026-11-03T12:34:56.123456Z |
actor, ip, action, target |
As recorded; ip is null when not recorded |
actor_id |
The account id of the person who acted; null for the system, the command line, API keys and failed sign-ins |
detail |
The detail object with secret-named string values replaced by [redacted], exactly as the API and exports show it |
The row id is not hashed, so the chain survives a copy into another database. Hashing the redacted detail means every export and every SIEM message can be checked on its own, without the server.
Verification walks the events in seq order and reports the first break: an event whose fields no longer match its
hash, one that does not link to the event before it, a missing seq, events past the head that minibrain did not
seal, or a newest event that does not match the head. It runs from Settings → Security (Audit integrity, “Verify again”),
GET /api/audit/chain, and minibrain audit verify (exit code 1 on a break; --file <export.jsonl> checks an
unfiltered JSONL export instead of the database; --json prints the report).
Retention keeps the chain checkable. The hourly prune deletes sealed events up to the newest one whose seq and all
before it are older than the retention period (never an unsealed event, and with SIEM export on, never one the SIEM
has not received), then writes an audit.prune event with cut_seq and cut_hash: the last deleted event’s seq
and hash. That event is chained like any other. Verification starts at the oldest remaining event and needs either
seq 1 linking to 64 zeros, or a prune whose cut_seq is the event just before it and whose cut_hash is its
prev_hash.
What the chain shows: any edit, deletion or insertion inside the retained log, and deletions at either end. What it cannot show on its own: someone with write access to the database rewriting every hash from the point they changed onwards, since the chain uses no key. The SIEM’s copy is the witness for that: its hashes stop matching the database’s from the rewritten event on.
SIEM export
Section titled “SIEM export”Off by default. With a protocol and host set, the leader sends every sealed event, in seq order, to that one
address and nowhere else; the network policy does not apply to it, as it does not to artifact storage.
- RFC 5424 syslog: facility 13 (log audit), severity 5 (notice), so PRI is
<109>; the event time as the timestamp; this host’s name; app nameminibrain; the action as MSGID;[origin software="minibrain" swVersion="…"]as structured data; and the event as JSON, ASCII only, as the message: the canonical fields plusidandhash. - TLS (RFC 5425) and TCP use octet-counting framing (
<length> <message>, RFC 6587). TLS goes through Python’ssslmodule (OpenSSL), TLS 1.2 or later, and checks the certificate and host name against the CA bundle, or the system’s CAs when none is set. UDP (RFC 5426) sends one message per datagram and cannot tell whether it arrived. - The head row keeps a cursor: the last
seqsent. Each batch of up to 500 events goes over a fresh connection: minibrain writes it, closes its side (a TLS close_notify first) and waits up to 2 seconds for the SIEM to close too, which a receiver does once it has read everything, then moves the cursor. A restart or a new leader resumes at the next event. A connection that fails mid-batch sends the whole batch again, so the SIEM may see an event twice (sameseqandhash, so it can drop the copy). UDP has none of these checks. - While the SIEM is unreachable minibrain retries every 15 seconds, events queue in the database, and Settings → Security (Audit integrity) shows the error and how many events wait. Turning export on for the first time sends the whole retained log, oldest first.
Encryption at rest
Section titled “Encryption at rest”Every file minibrain stores is encrypted with its own random 256-bit data key, and that data key is wrapped by a
master key that lives somewhere else: a local key file (the default), HashiCorp Vault Transit, a PKCS#11 HSM, or AWS
KMS. Settings → Security → Encryption at rest picks the provider, tests it before saving, shows which key each file
uses, and starts checks, rotations and the encryption of older files. Everything there is admin-only, audited, and
locked when minibrain.yaml (policy:) or MINIBRAIN_POLICY_<NAME> sets it.
What is encrypted
Section titled “What is encrypted”| Kept by main | Encrypted | Notes |
|---|---|---|
| Uploads, dataset versions, adapters, job logs (the artifact store) | Yes, in the local folder and in an S3 bucket | The bucket only ever holds ciphertext (client-side encryption) |
Staging databases built from uploads (<home>/staging) |
Yes | Built in a private temporary folder, sealed, and the plaintext removed straight away |
| Connection secrets and sealed settings (OpenTelemetry headers) | Yes, same master key | One AES-256-GCM envelope per value, the row’s id as associated data |
| The database (SQLite or Postgres) | No | Request inputs and answers kept for the models you choose live there: put SQLite on an encrypted volume, or use Postgres with storage encryption |
| Base model weights in an S3 bucket | Yes | Each file is a sealed artifact under its SHA-256, like every other one |
Base model weights on main’s disk (<home>/models, Storage set to the folder) |
No | Public weights; imported private weights are not encrypted by minibrain either |
Main never writes decrypted copies of these files. DuckDB reads dataset versions, uploads and staging databases through a filesystem that decrypts on the fly, a chunk at a time, so queries, previews, diffs and the gateway’s prompt context work on the encrypted files directly (the sandbox still refuses every path it was not given). The trade-off is a little CPU per read (measured below) instead of a decrypted cache on disk.
Workers, engines and gateways are different: training, evaluation and serving read plain files, and those machines
hold no master key. Main decrypts an artifact when a worker or engine pulls it over HTTPS, and the worker’s or
engine’s own home (<home>/worker, <home>/engines, <home>/gateway) holds plain working copies of the dataset
versions and adapters it uses. Put those folders on an encrypted volume (or tmpfs) on GPU boxes; they are caches and can be
wiped at any time. A worker’s outputs are encrypted the moment main stores them.
Base weights on other machines
Section titled “Base weights on other machines”With Storage on S3, base model files stay sealed in the bucket and machines read them from there, not through main:
- A worker or engine asks main over its authenticated channel (
GET /internal/worker/bases/<key>with the worker’s token,/internal/gateway/bases/<key>with the gateway token, a pool’s engine token, a pool token or an approved machine’s credential). - Main answers, with
Cache-Control: no-store, each file’s path, size and SHA-256, a presigned GET link (SigV4, valid 15 minutes, for the configured endpoint and nothing else) and the file’s data key: main reads the object’s 4 KiB header with its own bucket credentials and unwraps the data key with the master key, through the same provider as every other unwrap (cryptography, Vault Transit, the HSM or KMS). - The machine downloads the object, decrypts the STREAM format chunk by chunk with AES-256-GCM through
cryptography, checks the plaintext’s size and SHA-256 against the saved list, and only then renames the file into its working copy. A changed byte, chunk or header fails authentication or the hash, and the file is refused.
The machine never holds the bucket’s keys or the master key. A data key opens one object only (each file has its
own), stays in memory and is never written to disk; a verify job takes its links and keys on standard input, not in
its job file. The node channel carried these files’ plaintext before, so it carries nothing it did not; run it over
HTTPS. Working copies are plaintext, as engines need, so treat <home>/models, <home>/engines and
<home>/worker/models like the other plain working copies above.
File format
Section titled “File format”A sealed file is a 4,096-byte header followed by the body in chunks.
| Bytes | Field |
|---|---|
| 0-7 | Magic 89 4D 42 45 0D 0A 1A 0A |
| 8 | Format version, 1 |
| 9 | Cipher suite, 1: AES-256-GCM in a STREAM construction |
| 10-11 | Reserved, zero |
| 12-15 | Chunk size in plaintext bytes, big-endian (1 MiB) |
| 16-22 | Random 7-byte nonce prefix |
| 23-63 | Reserved, zero |
| 64-2079 | Key slot A |
| 2080-4095 | Key slot B |
- Body: each plaintext chunk is encrypted with AES-256-GCM under the file’s data key, with the 96-bit nonce
prefix ‖ chunk index (4 bytes, big-endian) ‖ final flag (1 byte), the first 64 header bytes as associated data, and a 16-byte tag appended. Every chunk but the last is exactlychunk size + 16bytes. Reordering, dropping, duplicating or appending chunks, cutting the file at a chunk boundary or anywhere else, and changing a header byte all fail authentication. Each data key encrypts one file only, so a nonce never repeats under a key. - Key slot: a sequence number (4 bytes), the length of a JSON payload (2 bytes), the payload, zero padding, and the
slot’s SHA-256 in its last 32 bytes. The payload is
{"p": provider, "k": key reference, "w": wrapped data key}. Readers use the valid slot with the highest sequence number; the other one lets re-wrapping replace a header in place without a moment where a crash leaves the file unreadable. - The wrapped data key is bound to the file: the wrap’s associated data (local key, HSM), encryption context (KMS) or
wrapped plaintext (Vault, which carries the SHA-256 of the context next to the key) holds
minibrain.artifact.<id>for artifacts andminibrain.staging.<key>for staging databases, so a header copied onto another file does not open. - Files without the magic are read as plaintext, so files written before encryption at rest stay readable.
- Plaintext size is the file size minus the header and 16 bytes per chunk, so random access needs no index.
Content hashes stay over the plaintext: an artifact’s id is still the SHA-256 of its plain bytes. Identical uploads and dataset versions are still stored once, a re-saved version still matches its earlier copy, and model cards and AI-BOMs keep the hashes customers can check against their own files. The hash says only what any copy of the same content would hash to, which the content-addressed file name already revealed.
Key providers
Section titled “Key providers”| Provider | Master key | Wrapped by | Rotation |
|---|---|---|---|
| Local key file (default) | <home>/keys/master.key (folder 0700, file 0600), made on first start; or the file MINIBRAIN_MASTER_KEY_FILE names, such as a Kubernetes or Docker secret |
AES-256-GCM through cryptography, random 96-bit nonce, the file’s context as associated data |
minibrain keys rotate adds a key to the file. A mounted file is never written: add a line yourself |
| HashiCorp Vault Transit | An aes256-gcm96 Transit key |
Transit encrypt and decrypt over HTTPS (httpx, TLS 1.2+ through Python’s ssl), token or AppRole |
Transit’s key rotate, then re-wrap |
| PKCS#11 HSM | Non-extractable AES-256 key objects with one label, the version as CKA_ID |
C_Encrypt with CKM_AES_GCM inside the HSM, random 96-bit IV, the context’s SHA-256 as associated data (PyKCS11) |
A new key object, then re-wrap |
| AWS KMS | A symmetric KMS key | KMS Encrypt and Decrypt through botocore, the context’s SHA-256 as encryption context |
KMS rotates key material itself; point minibrain at a new key ARN to move every data key |
Local key file. The file holds one base64 256-bit key per line; the last line is the current key and the others stay
readable. The same key seals files and connection secrets, so there is one key for everything. Back the key up separately from the data: a
backup that holds both protects nothing, and data whose key is lost cannot be read. With more than one main, every
main needs the same key file: mount it from your secret store and set MINIBRAIN_MASTER_KEY_FILE. A main that finds
the install already encrypting under a local key it does not have refuses to make its own and says so.
openssl rand -base64 32 > /run/secrets/minibrain-master.key # then MINIBRAIN_MASTER_KEY_FILE=/run/secrets/minibrain-master.keyHashiCorp Vault Transit.
vault secrets enable transitvault write -f transit/keys/minibrain type=aes256-gcm96vault policy write minibrain - <<'HCL'path "transit/encrypt/minibrain" { capabilities = ["update"] }path "transit/decrypt/minibrain" { capabilities = ["update"] }path "transit/keys/minibrain" { capabilities = ["read"] }path "transit/keys/minibrain/rotate" { capabilities = ["update"] }HCLvault auth enable approlevault write auth/approle/role/minibrain token_policies=minibrain token_ttl=1hpolicy: encryption: vault vault_address: https://vault.internal:8200 vault_auth: approle # or token, read from MINIBRAIN_VAULT_TOKEN(_FILE) vault_role_id: 7f1c… # the secret ID comes from MINIBRAIN_VAULT_SECRET_ID(_FILE) vault_ca_bundle: /etc/minibrain/vault-ca.pem vault_namespace: "" # Vault Enterprise onlyDrop the rotate path from the policy if Vault admins rotate the key themselves; minibrain then re-wraps to whatever
version is newest. Tested against Vault 1.20.4 in dev mode with AppRole.
PKCS#11 HSM. Install the extra (pip install 'minibrain[hsm]', which adds PyKCS11) and the vendor’s PKCS#11 module.
minibrain loads that module into the server process, so its path is set only in minibrain.yaml or
MINIBRAIN_POLICY_HSM_LIBRARY: Settings shows it read-only, and the API refuses to change it (409), so an admin
account cannot point the server at a library of its choosing. The token and key labels stay editable in Settings.
policy: encryption: hsm hsm_library: /usr/lib/softhsm/libsofthsm2.so # the vendor module hsm_token: minibrain # token (partition) label hsm_key: minibrain-master # key label; the PIN comes from MINIBRAIN_HSM_PIN(_FILE)If the token has no key with that label the first time minibrain uses it, minibrain generates one (AES-256,
sensitive, not extractable, CKA_ID 1); create it yourself if your HSM policy reserves key generation for its
officers. Tested against SoftHSM 2.7.0.
AWS KMS. Credentials come from the server’s AWS environment (variables, profile, web identity on EKS, or the instance role); nothing calls AWS unless KMS is the provider.
policy: encryption: kms kms_key: arn:aws:kms:us-gov-west-1:111122223333:key/1234abcd-… kms_fips: true # kms-fips.<region>.amazonaws.com kms_endpoint: "" # an https:// VPC endpoint, if you use oneThe IAM policy needs kms:Encrypt, kms:Decrypt and kms:DescribeKey on the key. With S3 storage on AWS,
SSE-KMS on the bucket is a useful second layer: it protects the objects at the storage layer and logs every read in
CloudTrail, but it decrypts for anyone holding the bucket credentials, while minibrain’s client-side layer keeps the
bucket’s contents unreadable without the master key.
The network policy does not apply to Vault or KMS, as it does not to artifact storage: an admin chose them. Switching provider tests a wrap and an unwrap first and refuses the change if either fails; files wrapped under the old provider stay readable as long as its settings stay in place.
Rotation, checks and older files
Section titled “Rotation, checks and older files”| Action | Command | UI | What it does |
|---|---|---|---|
| Check | minibrain keys status |
Check now | Reads every header and counts files under the current key, under older keys, unencrypted and unreadable, per key |
| Rotate | minibrain keys rotate |
Rotate master key | Makes a new master key version, then re-wraps every data key under it |
| Encrypt older files | minibrain keys encrypt-existing |
Encrypt existing files | Encrypts files written before encryption at rest, in place |
- Re-wrapping rewrites only the header: unwrap with the old key, wrap with the new one, write the free slot, sync,
then clear the old slot. File bodies are never re-encrypted. A bucket object is rewritten in the bucket: a multipart
upload whose first part is the new header and the object’s first 5 MiB, and whose other parts the bucket copies from
the old object (
UploadPartCopy, pinned to its ETag), so only 5 MiB leave main however large the file; an object under 5 MiB is sent again whole. Secrets are resealed in the same pass. - Older local key versions stay readable until a pass finds nothing uses them and the new key is at least an hour
old; the leader runs that check on its own and then drops them from the key file (
--retire-nowskips the wait when no server is running). Vault, HSM and KMS keep their versions: retire them there. - Encrypting an older file writes an encrypted copy beside it, reads the copy back and checks its SHA-256 against the file’s id, then swaps the two atomically; a file whose content does not match its id is left alone and reported. The same pass deletes leftover plaintext staging files and main’s old decrypted cache.
- In the UI these run as one background pass on the leader, with progress; each is audited (
encryption.rotate,encryption.rewrap,encryption.encrypt_existing,encryption.check,encryption.retire,encryption.key). - Rotation answers “a key version should no longer be used”; it does not make copies of files taken before the rotation unreadable to someone who also has the old key.
Turning it on later
Section titled “Turning it on later”Encryption at rest is on by default: on first start main makes the local key and every file is encrypted. Set the
master key to Off (MINIBRAIN_POLICY_ENCRYPTION=off) only for a multi-main install whose mains do not share a key file
yet. Turned on again, every new file is encrypted and files stored while it was off stay readable as they are; run
minibrain keys encrypt-existing or press Encrypt existing files when convenient, without downtime.
Performance
Section titled “Performance”Measured on an Apple M1 Pro (macOS, cryptography 50.0.2 on OpenSSL 4.0.3) with a 1 GiB file of random bytes,
reading and writing the local SSD, best of two runs:
| Operation | Plaintext (before) | Encrypted |
|---|---|---|
| Store: read, SHA-256, write | 1,009 MB/s | 712 MB/s |
| Read: read, SHA-256 | 1,929 MB/s | 1,427 MB/s |
| AES-256-GCM alone, in memory, 1 MiB chunks | 4,349 MiB/s encrypt, 2,104 MiB/s decrypt |
Memory stays flat: 1 MiB chunks are encrypted and decrypted one at a time, and random reads keep at most 8 decrypted chunks per open file.
Bills of materials
Section titled “Bills of materials”Software (SBOM)
Section titled “Software (SBOM)”Every CI run uploads a minibrain-sbom artifact beside the wheel with two CycloneDX JSON files. mise run sbom
writes the same two into sbom/.
| File | Format | Made by | Covers |
|---|---|---|---|
minibrain-python.cdx.json |
CycloneDX 1.5 | uv export --format cyclonedx1.5 from uv.lock |
The wheel’s dependencies with every extra (postgres, mlx, llamacpp, qlora, hsm: --all-extras), no dev group: version, purl, the SHA-256 of every sdist and wheel, platform markers and the dependency graph |
minibrain-web.cdx.json |
CycloneDX 1.6 | syft from web/pnpm-lock.yaml |
Every package in the lockfile, by name, version and purl. syft does not tell dev dependencies apart in pnpm lockfiles, so the build tools (Vite, TypeScript, Biome) are listed too; the built UI ships only what dependencies pulls in |
- Both read only the lockfile: no install, no registry lookups.
uv export --frozennever resolves; uv marks the CycloneDX export experimental (--preview-features sbom-export), so the format can change with uv, which CI pins. - syft’s network features (remote licence lookups for npm, Python, Go and Maven) are off by default and stay off.
Its update check is on by default;
SYFT_CHECK_FOR_APP_UPDATE=falseturns it off, in CI and inmise run sbom. - CI downloads syft by release version and checks the archive’s SHA-256 (
SYFT_VERSIONandSYFT_SHA256in.github/workflows/ci.yml).
Dependency licences
Section titled “Dependency licences”minibrain is Apache-2.0. The Dependency licences CI job runs scripts/check_licences.py, which fails on any
dependency the product ships whose licence is outside this policy:
- Checked: the wheel’s Python dependencies with every extra, for every platform in
uv.lock(licences from PyPI’s metadata for the locked version), and the web UI’s production dependencies (pnpm licenses list --prod). Dev tools are not shipped and are not checked. - Allowed: permissive licences (MIT, BSD, Apache-2.0, ISC, PSF, Zlib, BSL-1.0, Unlicense, CC0, 0BSD and the like),
OFL-1.1 for fonts, CC-BY-4.0 for data, and weak copyleft used as an unmodified library (MPL-2.0, LGPL). An
ORexpression passes when one side does; anANDexpression needs every part. - Refused: GPL, AGPL, SSPL, non-commercial or proprietary licences, and packages with no licence metadata, unless the
script names them with a reason. Today: NVIDIA’s CUDA libraries, which torch pulls in on Linux (NVIDIA’s licence
lets an application redistribute them), and PyKCS11 (GPL-2.0-or-later), in the optional
hsmextra only: never a requirement of the wheel and not in the image; the operator installs it.
The check needs the network (PyPI) and runs in CI only; nothing in minibrain looks licences up at run time.
Docker image
Section titled “Docker image”Each release carries one SBOM per image, minibrain-image-{cpu,cuda}-{amd64,arm64}.cdx.json: the release workflow
loads the image it pushes into Docker and runs syft on it, with the settings below, and attests the SBOM on that
image in GHCR. CI does not build the image (the CUDA one is about 7 GB). Its Python packages are the
--no-dev --extra postgres --extra qlora subset of minibrain-python.cdx.json, except torch, which comes from the
PyTorch index as the CUDA or CPU build. For a local build, operating system packages included, run syft against the
built image:
SYFT_CHECK_FOR_APP_UPDATE=false SYFT_FILE_METADATA_DIGESTS=sha256 \ syft scan docker:minibrain:cuda --source-name minibrain --source-version "$(git rev-parse HEAD)" \docker:reads the image from the local Docker daemon; nothing is pulled. To scan elsewhere, save it (docker save minibrain:cuda -o minibrain-cuda.tar) and runsyft scan docker-archive:minibrain-cuda.tar.SYFT_FILE_METADATA_DIGESTS=sha256keeps file digests to SHA-256; syft adds SHA-1 by default.- Measured on the CPU image (syft 1.54.1): about 4,100 components (88 Debian packages, 97 Python packages, the Rust
crates compiled into Python wheels, and the files those packages own with their SHA-256), 3 MB, under a minute.
Two Debian packages carry licence IDs newer than CycloneDX 1.6’s SPDX list (
SMAIL-GPL,Artistic-dist), so a strict schema check flags those two entries.
Signed releases
Section titled “Signed releases”Every release file and image is signed keyless through Sigstore by the release workflow at its tag, and the SBOMs and SLSA build provenance are attested on the images. No signing key exists to leak. Verifying, online or air-gapped with the bundles and Sigstore’s trusted root: Install → Verify a release; how it is made: Releasing → Signing and provenance.
AI bill of materials (AI-BOM)
Section titled “AI bill of materials (AI-BOM)”Every version has a CycloneDX 1.6 ML-BOM: GET /api/models/{slug}/versions/{n}/aibom.json, or Download
AI-BOM on the model card page ({slug}-v{n}-aibom.cdx.json, application/vnd.cyclonedx+json). It is built from
the same data as the model card, without the deployment history, so deploying or undeploying a version does not
change it.
| Part | CycloneDX | Holds |
|---|---|---|
| The version | metadata.component, machine-learning-model |
Name, number, kind, status, who created it; the recipe (minibrain:recipe:*), training and evaluation runs (minibrain:training:*, minibrain:evaluation:*) as properties; a model-card reference to card.json |
| Model card | metadata.component.modelCard |
Task, architecture (LoRA adapter on the base, or the base with the task prompt and few-shot examples), the dataset version as its dataset, the labels; held-out and test accuracy, macro F1, invalid-answer rate, per-label precision, recall, F1 and support, latency p50 and p95 (quantitativeAnalysis.performanceMetrics, sliced by split and label); intended use and every derived and written limit (considerations) |
| Base model | component, machine-learning-model |
Repository and revision, pkg:huggingface purl, the licence (SPDX ID where one exists, else its name and URL), the content hash as SHA-256, whether it was recorded when training started, who accepted the licence |
| Adapter | component, file (LoRA versions only) |
The adapter archive’s artifact ID, which is the SHA-256 of the tar, its size |
| Training dataset version | component, data |
The dataset version hash as SHA-256, rows per split, when it was taken, the SQL, every data check and its result, personal data findings as sensitiveData |
| Sources | component, data, one per table |
Table, source kind and fingerprint; uploads also carry the file’s SHA-256 as a hash. Folder and remote fingerprints are SHA-256 over a listing or the source’s state, so they stay a property |
| Dependencies | dependencies |
The version on the base, the adapter and the dataset version; the adapter on the base; the dataset version on its sources |
The output is deterministic: the same version gives the same bytes. metadata.timestamp is the newest of the
version’s creation, its training and evaluation finish times, the base model’s licence acceptance and the last card
edit. metadata.properties carries minibrain:aibom:sha256, the SHA-256 of the canonical BOM: the BOM without
serialNumber and metadata.properties, as JSON with keys sorted, no whitespace and non-ASCII characters kept (the
model card’s canonical form). serialNumber is a version 8 UUID made from the first 16 bytes of that digest, so it
changes whenever the content does. Check a download with:
python3 -c 'import hashlib,json,sys; b=json.load(open(sys.argv[1])); b.pop("serialNumber"); p=b["metadata"].pop("properties"); s=json.dumps(b,sort_keys=True,separators=(",",":"),ensure_ascii=False); print(hashlib.sha256(s.encode()).hexdigest(), p[0]["value"])' support-triage-v1-aibom.cdx.jsonBoth printed values match for an unchanged file. tests/test_aibom.py validates prompt-only and trained versions
against the CycloneDX 1.6 JSON schema, vendored in tests/cyclonedx/ (Apache 2.0) so the test needs no network.