Documentation · The Lagstyr handbook

Securing your installation

Lagstyr’s controls span the kernel, database, service accounts, ingress and customer authority. Maintain those layers together. A correctly rejected API request is useful evidence, but it does not establish that the host, identity lifecycle or backup custody is secure.

Separate identities and credentials

Use infra/workload-identity/inventory.tsv from the kit to derive the credential and database role for every selected workload. The embedder makes no kernel calls and needs its confined database identity rather than a machine API key. Do not issue a shared worker credential.

Machine tokens use X-Lagstyr-Key. The machine-credential CLI mints, rotates and revokes exact credentials under operator-controlled access; grant_machine_role is a separate governed act. An ungranted credential has no route permissions. Rotation retains the stable label’s grant, while revocation targets an exact key. Prepare grants before service enablement and retain expiry and rotation records.

Machine API admission uses a refreshed in-memory credential snapshot. Commit-triggered reload accelerates revocation, with a 30-second periodic catch-up plus query time; revocation is not atomic with that reader. Sensitive connector transactions re-read the exact credential. Verify the actual refusal and stop the affected workload or close its ingress/egress for urgent containment rather than assuming a secret-store change immediately blocks every request.

For generic Rust worker units, the instance/file name is the binary suffix with hyphens, such as xero-worker.env; inventory labels use underscores, such as xero_worker. Use the configured workload environment directory. A correctly named credential in an incorrectly named file is unavailable to the service.

The kernel’s 64-hex-character LAGSTYR_KERNEL_DML_KEY is separate from its DSN password and HTTP keys. Its verifier lives in the owner-only database schema. Rotate the database copy and kernel environment value together during a stopped deployment using the kit’s provisioning procedure. Possession of a kernel DSN alone does not authorise direct DML.

Customer-lane OAuth adds one workload and two keys. integration_token_broker has its own machine credential and login bundle integration_token_broker_db, the only role granted the sealed refresh credential; the kernel has no privilege on it. The broker alone loads integration-token-sealing-key, which seals refresh tokens at rest. The broker and the kernel share integration-token-delivery-key, under which the kernel seals the authorization code for the broker and the broker seals short-lived access tokens for the kernel to serve. The two keys must differ, or whoever opens an access token could open a refresh token too. A connection stores only a reference to its OAuth client secret, resolved inside the broker. A kernel compromise therefore reaches current access tokens, never a refresh token or client secret. No code, verifier, state or token is logged or returned by a read.

Do not accept role confinement from catalogue inspection alone. The provisioning wrapper signs in with each actual password and proves that the login cannot rewrite skill contracts or their history, disable triggers, acquire database objects, create code in the public schema, grant itself privilege or assume a protected owner role. Run and retain that proof after every schema or role change.

Keep secrets scoped and private

Store secrets in your approved secret manager and materialise only the required private files. Check owner, group, permissions and systemd consumers against the installation JSON. Root-only credential files and group-readable service environment files have different consumers; do not make either world-readable. Keep secrets out of JSON manifests, tickets, code, shell tracing, screenshots, raw support uploads and command history.

The release download token is read-scoped. Runtime object upload, mirror upload, retention deletion and lifecycle administration should use distinct scoped identities. Keep the age private backup identity off the host. A hosting administrator with root access can inspect on-host secrets; record any third-party root-access decision rather than treating encryption at rest as protection from that administrator.

Verify human access and deprovisioning

The console uses OIDC authorization-code with PKCE against your exact HTTPS issuer and client. Configure the public origin and redirect URI, complete group-to-role mapping, and accepted MFA amr/acr evidence. Test allowed, unmapped, non-MFA, expired and disabled identities against the real issuer before cutover. An issuer configuration is not universal certification of every IdP.

Commission the chosen identity lifecycle feed and test revocation, group removal and session termination. Just-in-time login alone does not prove a leaver is removed. Optional SCIM, SAML brokering and workload-identity adapters need their own configuration and acceptance evidence. External workload authentication still needs an exact local identity binding and compiled role; it grants no business authority by itself.

Keep ordinary ingress, console ingress and any workload JWT/X.509 surfaces distinct. Restrict administrative access and retain the proxy/firewall as-built configuration. Emergency console password access is explicitly armed through a host control and reviewed separately; follow Emergency access, passwords and sessions. A recorded second-reviewer name in an administrator review is not a second authenticated identity.

Admit egress and data deliberately

Declare the data-home inventory, encryption and retention choices in the customer contract. Provider approvals name the exact processor, purpose, endpoint, data class, region, retention, workloads and permitted destinations. Hosted model/embedding approvals are disabled in the reference configuration. A credential or reachable endpoint alone is insufficient admission.

Provider-export clients load an immutable installation-policy snapshot at construction. Changing an approval, endpoint, purpose, data class or enabled state requires restarting every affected workload and verifying startup. An already-running client retains the previous snapshot. For urgent containment, revoke its provider credential and apply network denial while stopping the workload.

Use the kit’s hardened units and per-service network policy, then verify the effective policy on the installed host. Keep databases, storage and operational listeners private; narrowly admit only required external destinations. Retain observed-egress evidence rather than inferring safety from a firewall file or an empty packet capture.

An OAuth consent callback is not a vendor reach-in. The provider redirects the operator’s own browser to /integration-oauth/callback on the installation’s console, using a client the installation registered itself; no vendor holds a key or sits on the path, and no provider opens a connection inbound. The console origin must be reachable from that browser, not from the internet. The only new egress is the token broker calling the token and revocation hosts a release declares, and only after a second operator approves the connection. Its unit is fenced like every workload, so admit those hosts deliberately.

Telemetry applies a deny-by-default attribute allowlist and message minimisation before sinks. Your team still chooses sink access and retention and verifies actual exported traffic. Integration metrics carry installed integration keys as labels, so a sink shared with another party sees those names, never record content. A record an integration’s signed extraction refuses stays inside the installation as a confidential drift capsule for 30 days and is then erased to a tombstone; operator reads show only its metadata. Local event-day roots provide integrity checks. Independently detecting privileged history rewriting requires the optional separately administered audit anchor, its approved storage, credentials, keys and retained evidence; local roots alone do not supply that independence.

Recheck identity, secret expiry, access reviews, provider approvals and network drift during routine operations, and use incident response when an identity may be compromised.