Skip to main content
Version: 0.4 · current

Security model

ConceptReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Viewer, Operator, Editor, Entity admin, Super admin
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

Excubius has no passwords of its own for your team: people sign in with the Microsoft or Google account your organisation already manages. What they can see and do then depends on the role they hold on each branch of the entity tree, checked again on every request. Secrets that the collector needs are stored encrypted and can never be read back. This article explains each layer.

Sign-in​

Excubius uses OpenID Connect with Microsoft Entra ID (one tenant) and Google, through the authorization code flow with PKCE, state and nonce. No provider SDK and no paid identity service are involved.

  • The ID token is validated on every sign-in: its signature against the keys the provider publishes, the issuer (for Entra ID, your tenant), the audience, the expiry and the nonce of that sign-in.
  • The sign-in in progress is kept in a signed, HttpOnly cookie that lasts 10 minutes. The page to return to after sign-in must be a page of the same site, so a crafted link cannot send anyone elsewhere.
  • Accounts are keyed by provider and subject, the user's object ID in Entra ID or Google's subject, never by e-mail address alone.
  • Who may get an account is decided per entity: by invitation, or by an allowed e-mail domain. A Google account counts for a domain only when it is a Google Workspace account of that domain; personal Google accounts always need an invitation.
  • Provider secrets come from the server's configuration only. They, the authorization codes and the tokens are never stored in the database, returned by the API or written to logs.
ProviderPlans
GoogleFree, Core, Pro, Enterprise
Microsoft Entra IDCore, Pro, Enterprise
Microsoft Entra ID groups as role holdersEnterprise

Multi-factor authentication​

MFA is enforced by your identity provider: Entra ID Conditional Access or Google 2-Step Verification. Excubius does not inspect MFA claims yet, so require MFA at the provider for everyone who can sign in, and above all for entity administrators.

Sessions and tokens​

A successful sign-in sets two cookies, both HttpOnly, Secure over HTTPS and SameSite=Lax:

TokenLifetimePurpose
Access token15 minutesProves who you are on each request
Refresh token14 daysGets a new pair of tokens; every refresh issues a new pair

Permissions are not carried in the token. They are read from the database on every request, so deactivating a user, removing a role or changing a group assignment takes effect on that person's next request. Membership of directory groups is read again at each sign-in.

note

Refresh tokens cannot be revoked one by one yet. To end someone's access before their session expires, deactivate the user. Signing out of Excubius does not sign you out of Microsoft or Google.

There are no API keys yet: scripts and other tools cannot call the API on their own behalf in this release.

Roles on the entity tree​

A role is given to a person, or to a directory group, on an entity, and applies to that entity and everything below it. A person can be Entity admin for one client and Operator for another. On any entity, the effective role is the highest one found on the entity and its ancestors, counting the person's own roles and those of their groups.

RoleCan
ViewerRead dashboards, alerts, findings and resource detail; change their own settings
OperatorEverything a viewer can, plus acknowledge, silence, assign and resolve alerts, create Jira tickets and plan maintenance windows
EditorEverything an operator can, plus change the checks and thresholds of resources and accept security risks
Entity adminEverything an editor can, plus manage the branch's entities, entity defaults, resources, credentials, sources, people, roles, invitations, notification channels, Jira settings and status page
Super adminEverything, on every branch, plus the settings of the whole installation. Given only on the root, by another super admin

What this means in practice:

  • Every list is limited to your branches: entities, resources, alerts, the Overview, credentials, channels and people. If your roles start at Ciguapa Inc., the entity tree you see starts there too.
  • Anything outside your branches does not exist for you: opening its address answers Not found, or no longer visible to you. Something you can see but not change answers Your role does not allow this.
  • Giving roles stays inside your branch and level: an entity admin can invite people and give roles only on entities they administer, and never a role above their own.
  • A credential belongs to the entity that owns it and can be used by resources of that entity and below. Pointing the collector at a host with a credential requires the entity admin role on the credential's entity, so an administrator of one client cannot aim a login shared from above at a host of their choosing.

Entities, tags and inheritance explains the tree itself.

Secrets​

Monitoring credentials, source API keys, client secrets and the keys of uploaded certificates are write-only:

  • They are encrypted in the database with AES and an HMAC signature (Fernet), using a key that the installer generates and keeps in the server's configuration file, not in the database. A database dump alone reveals no secret.
  • Screens and the API only say whether a secret is set, for example stored — leave empty to keep it. Nobody can read a secret back, whatever their role.
  • A secret is decrypted on the server, or sent to the collector over the server's internal network when a check needs it. The collector holds it in memory and never logs it.
  • The collector container receives only its own token and settings: never the database password, the session signing secret or the encryption key. The collector's routes are refused at the edge of the server, so it can only be reached from inside.

The credentials themselves are provisioned without write or install rights on the monitored systems; see Architecture.

Audit​

Every change made through the API is written to the audit log with the acting user, the time and the request's IP address. For sign-in and access this includes:

EventRecorded as
A sign-inlogin
A refusal after the provider answered, with the reasonlogin.failed
An account created on first sign-inuser.create
An invitation created, accepted or deletedinvitation.create, invitation.accept, invitation.delete
A role given or removedrole.grant, role.revoke
A change of registration moderegistration.update, registration.reset
A change to a user or to their preferencesuser.update, user.preferences

Alert actions, threshold changes, source changes, maintenance windows and status page edits are audited the same way. The audit log is kept in the platform database.