Administrator alerts

Whoever holds the database credential can change the directory without signing in: issue an invitation, grant a group, activate a policy. That cannot be prevented, so Cardinal makes it visible, and visible to people other than whoever holds the credential. The server reads the audit journal and mails every administrator.

What alerts

What	When
Anything done with the database credential	Any change at all, migrations included
A recovery	Requested, approved, cancelled or expired. The person concerned is told as well
An invitation for an account that can already sign in	It hands a second way in to whoever receives the link
The administration groups	Someone joins or leaves directory-admins, user-admins, security-admins or a group nested in one. A group joining lists the people it brings in
A key or secret	An SSH or X.509 authority key, an application secret, the OpenID Connect signing key
Mail	Switched off. That alert is sent before the change takes effect
The digest	Switched off or its interval changed, in the console, through the API or in the database

Recipients are everyone who holds an administration right when the alert is sent, with an email address. Administrators without one are listed on the Notifications page as unreachable.

What an alert says

What happened, to which account, by whom, when, and the journal event's number and hash. Where from, when it is known:

• with the database credential, the host name the command reported, marked reported by the command, not verified: whoever runs the command chooses it. It is kept beside the journal rather than in it, because a host name can name a person, and deleted once the alert is delivered, or after alerts.reported_host_retention (7 days unless set) if it never is;
• signed in, the address of the session the person was using, looked up when the alert is sent. It never enters the journal.

A change made while the server was stopped is reported when it starts. Alerts begin at the end of the journal the first time the server runs with this; the history before that is not replayed.

When alerts are held

Alerts are held, never dropped, with no age limit, in two cases: while mail is off, and while no administrator has an email address, which is the state right after the first administrator is created. The server logs it at start, /api/health reports "alerts": "held: mail is off" or "held: no administrator has an email address", and every administrator sees a banner in the console saying which. When the cause is gone, held alerts go out, as one summary when there are more than five.

The recount

The alerts and the position the server has read up to are not journaled, so somebody who can write to the database could delete an alert or skip past a change. The Notifications page recounts from the journal itself: every change that matches a rule, against the alerts that exist. When they differ it says so in plain words, lists the changes, and administrators see it as a banner on every page.

The digest

Every administrator also receives a digest, daily unless set otherwise: the journal's current fingerprint, the digest's own running number, how many journal events and alerts there have been since the previous one, and the recount. It is sent even when nothing happened. Its arrival is the point: number 41 followed by 43, or no digest at all, is the signal. Keep them somewhere this server cannot reach; cardinal journal verify against one says whether history since was rewritten.

The interval, from 1 hour to 7 days, and the switch are on the Notifications page and at PUT /api/alerts/digest. Changing either alerts. Changed in the database instead, or its setting deleted, the server notices within seconds that the setting differs from what the journal last recorded, journals it as direct-database, and that alerts too. The stored value stands; nothing is put back.

What it cannot stop

Somebody with write access to the database and control of the host can still stop the server (nothing is sent until it restarts), or change the database with psql without writing to the journal, which neither the alerts nor the journal's hash chain can see. A digest setting changed and put back between two of the server's checks leaves no trace, and neither does moving the digest's own record of when it last went out: it arrives late or not at all. The alerts make the rest visible: switching mail off, deleting alerts, skipping changes, silencing the digest.

So the people outside the host have a part to play: notice when alerts or the digest stop arriving, read them when they do, and keep the fingerprints.