Skip to content

Security model

JANUS is built around explicit trust boundaries, least privilege where it matters, and fail-closed behaviour. This page states the model an operator needs in order to reason about their own deployment.

Principles

Principle What it means in practice
Deny by default Only explicitly enabled policy grants access. A principal with no binding sees nothing — including whether an object exists.
Authentication is never authorization Being authenticated grants no authority by itself; every action is separately authorized.
Administrative identity never lives in Git Desired state cannot grant administrative authority.
Secrets never enter Git Private keys, password hashes and tokens live outside the configuration of record.
Management plane and data plane are separate A management-plane failure — including total loss of administrative access — never weakens what the Gateways enforce.
Minimum exposure Services bind to specific addresses, not 0.0.0.0, and the public surface is as small as the product allows.
Fail closed Anything that cannot be verified is refused rather than permitted.

Management plane versus data plane

The two planes have different threats and are deliberately decoupled:

  • administrative access is not published to the public network;
  • an operator who cannot authenticate cannot change the data plane — but the data plane keeps enforcing the policy it already has;
  • no recovery operation writes to the data plane directly. Break-glass and bootstrap are management-plane concerns: a change made through them goes through the same API, the same validation, the same authorization decision and the same audit chain as any other change, with the single difference that the actor is marked.

Administrative identity

Authentication uses JANUS's built-in local identity provider:

Element Implementation
Local accounts password hashes stored as self-describing Argon2id (parameters can be raised and a hash re-computed at next sign-in)
Sessions server-side session records; the session cookie is __Host--prefixed, Secure, HttpOnly, SameSite=Lax, carries an absolute and an idle expiry, and is revoked server-side
Session id rotated at sign-in and on any privilege or identity change; never placed in a URL or a log
API tokens 256-bit random, hashed at rest, scope- and time-limited, revocable immediately; a token's authority is additionally bounded by its declared scopes, so it can never exceed the principal's own permissions, and it can never manage interactive factors
Second factor authenticator app (TOTP) and passkey (WebAuthn), both administered by the user from their own account-security page; the TOTP shared secret is stored encrypted at rest, recovery codes as SHA-256 digests, and only public credential material is stored for a passkey
Authentication assurance an ordered state on the session (single or mfa) plus an amr list, never a boolean; a recent-authentication window governs step-up, and security-sensitive operations require it
Service principals an explicit non-human identity kind with no interactive credential, so no sign-in can resolve it; its only credential is a revocable API token
MFA policy opt-in and per scope (platform, tenant, deployment); a principal subject to it cannot use its normal surfaces until it satisfies the requirement, while the account-security routes stay reachable so the requirement can always be satisfied
CSRF a session-bound token on every state-changing request, plus SameSite=Lax and Origin/Sec-Fetch-Site verification
Enumeration failure to authenticate is indistinguishable from an unknown or disabled principal — same status, body and timing
Brute force rate limits and progressive delay applied before key derivation; no account lockout that becomes a denial-of-service primitive
Source restriction the management API and UI support source-IP address restrictions
Browser hardening server-rendered templates with compile-time escaping, no inline script, no third-party script or CDN, frame-ancestors 'none', X-Content-Type-Options: nosniff, Cache-Control: no-store on authenticated responses

An external identity provider is not part of this release's documented surface. If one is introduced, one consequence is worth stating up front: once group membership at that provider maps to JANUS roles, the provider — and its administrators — become part of JANUS's authorization trust boundary, and must be reviewed and monitored as such.

Authorization

Authorization is evaluated per request, at the application boundary:

  • permissions are a closed enumeration (config:read, config:write, gateway:admin, siteedge:read, siteedge:admin, and so on), grouped into built-in roles that are code constants — a database row references a role but cannot redefine it;
  • evaluation is deployment-scoped: a deployment administrator of one Deployment can do nothing in another;
  • a new protected route that is reachable unauthenticated fails the test suite, because authorization lives at the boundary rather than in individual handlers.

Bootstrap: no default credential, ever

On a fresh installation the API fails closed: authoring and administrative routes return 503 until a first administrator exists. The deployment is not "insecure until configured" — it is unusable until configured, which is the correct failure direction.

The first administrator is created host-locally:

controller admin bootstrap --username <username> --password-file /path/to/secret
Property Mechanism
no command-line exposure the password comes from a file or stdin — never --password <value>, which would be visible in the process list
one permission model the password file must satisfy the same strict file invariants used for Git credentials: a regular file, not a symlink, no group or other access, not executable, with non-replaceable ancestors
not silently repeatable refuses when an administrator already exists unless explicitly forced; a replacement emits a distinct audit event
visible afterwards the principal carries a locally bootstrapped marker, shown in the API and in audit, so it can be found and replaced
idempotent safe to re-run while no administrator exists

For unattended deployments the same operation can be driven from installation configuration — which names a password file, never the password.

Break-glass recovery

Break-glass exists for exactly one purpose: regaining administrative control when authentication or authorization configuration is broken. It is designed to be inconvenient in the ways that stop it being a backdoor.

Property Mechanism
disabled by default the principal exists in a disabled state and authenticates nowhere until enabled
enabled only from the host controller admin enable-break-glass --duration <duration> on the Controller host — never a network request, never an API route
time-bounded an explicit duration is required; the principal disables itself on expiry
rotatable controller admin rotate-break-glass on the host, with an audit event
loud enabling, every authentication, every use and every automatic expiry emit high-severity audit events
observable the API exposes break-glass state so monitoring can alert on enabled and on used
marked actions taken through break-glass are flagged in audit and are distinguishable from a normal administrator's

Explicitly rejected by design: a permanent master credential; a recovery path that silently bypasses authorization; and any break-glass path reachable over the network while normal authentication is disabled.

Gateway and gateway-agent security

Property Implementation
Transport mutual TLS. Only the agent's mTLS-protected port is exposed, and the server requires and verifies a client certificate
Identity the client certificate's identity is checked, not merely its issuing CA
Payload strictly typed envelopes; strict JSON decoding with unknown fields refused; request size limits; header, read, write and idle timeouts
Replay per-delivery identity with conflict detection; an immutably-named candidate cannot be silently replaced
Wrong-Gateway delivery the Gateway name is verified at envelope and payload level
Defence in depth the Gateway validates independently; it does not trust the Controller's validation
No execution surface there is no arbitrary-execution endpoint of any kind
Key material private keys are 0600; a rotation procedure exists
Local state applied artifacts are written atomically with fsync, carry a content hash, and are re-verified on startup
Endpoint pinning the Controller endpoint is administrator configuration, never Git desired state

Client identity

WireGuard keys are client-owned. A client generates its own keypair and registers only its public key. JANUS never generates, receives or stores a client's private key. A device's granted reachability is derived from the compiled authorization, never from an address the client claims.

Site Edge identity and privilege

A Site Edge has its own durable Ed25519 identity, generated locally and never exported, and is admitted only by pre-registration plus proof of possession — there is no transferable bearer secret. Its unprivileged service holds no kernel capability; privileged changes go through a separate local service over a Unix socket, authorized by peer credentials, exposing three typed operations and no command execution. See Site Edge.

Secret handling

  • Secrets never enter Git desired state, and no secret appears in a log, an audit event, an operation record, an API response or a compiled artifact.
  • Secret files follow one strict permission model (regular file, no symlink, no group or other access, not executable).
  • Passwords are never accepted as command-line arguments.
  • Kernel rule comments carry a policy name and a content hash — never user-controlled text and never a secret.

Audit and provenance

  • The acting principal is taken from the authenticated session or token, never from a request body or a client-supplied header.
  • The principal id and request id are recorded in the operation row, the audit event and the Git commit trailer, so an action can be followed end to end.
  • Browser-side diagnostics are never authoritative audit evidence. Rendered state, browser logs and client timestamps are not the record; the server-side chain is.

Data-plane blast radius

JANUS owns exactly one nftables table and enforces policy only for JANUS-managed traffic. If that table exists without JANUS's ownership marker, JANUS performs no mutation at all rather than resolving the conflict. It does not take over the host's firewall. See Data plane.

Not part of this release

  • No external identity provider, SSO or federation integration.
  • No SMS or other out-of-band second factor: the supported factors are an authenticator application and a passkey, and no notification infrastructure is invented to carry a code.
  • No NAT66; IPv6 is routed, never translated.
  • No dynamic routing protocols (for example BGP/FRR).