Security events

This screen connects your security team’s SIEM to this organisation’s audit trail. Everything the trail records goes to the SIEM: who signed in, who was refused, which accounts were locked, and who changed what. There are two ways to connect, and both read the same events in the same order:

Way	Who starts the conversation	Use it when
Your SIEM fetches it	Your SIEM asks for what is new, as often as it likes	Your SIEM can poll an HTTP endpoint, and you would rather nothing reached in from outside
We send it to you	Every few seconds, new events are posted to your OpenTelemetry collector	You run a collector, or your SIEM accepts OpenTelemetry logs directly

You can start with one and move to the other later without a gap. Open it from Administration → Integrations → Security events. The header shows how many collector keys can currently follow the trail.

The Security events screen, with the collector keys and the OpenTelemetry collector form

What your SIEM receives

The audit trail records two kinds of event. Security events, about getting in:

Event	When it is recorded
`SIGNED_IN`	Someone signs in with a password, a second factor or single sign-on. Renewing a session that is already open is not a new sign-in
`SIGNED_IN_WITH_API_KEY`	An integration exchanges an API key for a session
`SIGN_IN_FAILED`	A wrong password
`ACCOUNT_LOCKED`	The failed attempt that locks the credential. It says how many attempts there were and when the lock lifts
`SIGN_IN_REFUSED_WHILE_LOCKED`	Any attempt on a credential that is already locked, including one with the right password
`MFA_FAILED`	A wrong second-factor code, when signing in or while setting the factor up
`SSO_SIGN_IN_REFUSED`	A sign-in through single sign-on, Google or Microsoft that was refused, with the reason
`BREAK_GLASS_SIGN_IN`	Somebody in the break-glass role signed in with a password while passwords are otherwise switched off
`MFA_ENROLLED`	Somebody set up a second factor
`MFA_REMOVED`	Somebody removed their own second factor
`MFA_RESET_BY_ADMIN`	An administrator removed somebody’s second factor
`MFA_RECOVERY_CODE_USED`	Somebody signed in with a recovery code instead of their second factor
`MFA_RECOVERY_CODES_REISSUED`	Somebody issued themselves a new set of recovery codes

Changes to data, for every record anybody creates, changes, archives or deletes: RECORD_CREATED, RECORD_MODIFIED, RECORD_ARCHIVED and RECORD_DELETED. A person can hold accounts in several organisations with one password. A wrong password is therefore an attempt on every organisation that password opens. It is recorded in each of them, and each record names that organisation’s own account. An attempt on an address that nobody holds is not recorded anywhere, because no organisation owns it. Each event carries:

Field	Notes
When	To the microsecond
What happened	The event type, and a one-line sentence, such as “Sign-in refused: wrong password (attempt 2 of 5)“
Who	The person’s name and email address, or the name of the service account if a machine did it. Blank for something the system did by itself, such as a scheduled job
From where	The address the request came from, and the kind of client (the web app, the field app, the API, an import)
What it touched	The kind of record, its ID and the names of the fields that changed
Why	The reason, where the action asked for one

Field names leave. Values do not. An event says a work order’s priority changed, but not from what to what. The values before and after stay in the product, where reading them is checked against the person asking. Your SIEM needs to know what happened, and the audit trail keeps the detail for whoever investigates it.

The What your SIEM receives section shows up to twenty events from the last day, read exactly the way your SIEM will read them and in the same order. Check it before you connect anything, so you know what you are getting.

Column	What it shows
When	When it happened
What happened	The one-line sentence, with the event type and the kind of record underneath
Who	The person and their email address, the service account’s name, or the system
From	The kind of client, such as `WEB`

A link beside the section heading, Every attribute, as your SIEM sees it, opens what each event carries.

Your SIEM fetches it

Your SIEM signs in with a collector key and asks for everything since the last event it received. Nothing is missed and nothing is sent twice, even if the SIEM was switched off for a week.

Issuing a collector key

Click Issue a collector key. This creates three things:

a service account called SIEM collector
a role of the same name, which can follow the audit trail and do nothing else
a key for that service account

The service account and the role appear on Access under those names, so a key made last year can still be recognised.

The key is shown once. Copy it into your SIEM before you close the dialog. A lost key is replaced, not recovered.

Keys that can follow the trail lists every key that can read the feed, with the service account it signs in as, when it last signed in and when it stops working. Keys expire like any other. You rotate and revoke them on API keys.

The requests your SIEM makes

The Connect your SIEM section shows the two requests a collector makes, with this organisation’s address filled in, ready to copy into your SIEM’s HTTP input:

Trade the collector key for a session token. The token is good for fifteen minutes; reuse it for all of them.
Ask for the events after the last one you stored, sending the token. The answer is a page of events, oldest first.

The exact paths and parameters are part of the API. Copy them from the Connect your SIEM section rather than from here. Every event has a cursor. Store the cursor of the last event on each page, and send it with the next request.

To	Send
Start from the beginning of the trail	No cursor
Start from a date instead	A start timestamp, and no cursor
Carry on	The last cursor you stored

A page holds up to 1,000 events. When a page comes back empty, you are up to date. Ask again whenever you like. A change that is still being saved when your SIEM asks is held back until it is finished, not skipped. So the feed can run a few seconds behind the screen, but it never has a gap.

We send it to you

The Send it to your OpenTelemetry collector section sends new events every few seconds to an OpenTelemetry collector, as OTLP logs over HTTPS. The collector then forwards them to your SIEM. Connecting your SIEM has a collector configuration for Splunk, Microsoft Sentinel, Elastic and QRadar.

Field	Notes
Your collector’s address	Required. The collector’s OTLP/HTTP logs address. It must start with `https://`, usually ends `/v1/logs`, and must be reachable from the internet
Header	The header your collector checks for a credential. `Authorization` by default
Credential	The header’s value, such as `Bearer …`. Nobody can read it back once it is saved. Once one is stored, the field shows its last few characters. Leave it empty to keep the stored credential
Send events to this collector	Nothing is sent until this is ticked. Untick it to pause
Start from the beginning of the trail rather than from now	Offered only when you first set this up. Leave it unticked to send only what happens from now on. Tick it to send the whole trail first

People without the permission to configure integrations see only Sending to and the address. Click Save, then Send a test event (offered once the stream is saved). The test posts a single event to your collector, marked as a test. The result appears under the form: either The last test was accepted, or The last test was refused with the reason your collector gave. Nothing moves on for a test, so you can send as many as you need. Remove the credential deletes the stored credential, for a collector that does not need one. Changing the address does not restart the stream. A replacement collector picks up where the old one stopped.

Is it keeping up?

The section header shows Sending, Failing or Off. Below the form:

Figure	Meaning
Last delivered	When your collector last accepted a page
Up to events from	The time of the newest event your collector has
Waiting to be sent	Events recorded since then. It shows 10,000 or more beyond that
Sent so far	Every event delivered. If your collector turned down individual events, it also shows how many it refused

If your collector is down or refuses a delivery, The last attempt failed, and we will try again shows the reason. Nothing is lost while it is down. Events wait, the gap between attempts grows up to an hour, and delivery carries on from the first event your collector does not have. If your collector accepts a page but turns down particular events in it, those events are counted and not sent again. A collector that turns an event down because of its content would turn it down again.

Who can use this

To	You need (as shown on Access)	Default roles
Open this screen and see the feed	Export the audit trail	System Administrator, Auditor
Issue a collector key	Export the audit trail, Create roles and Issue and rotate api keys	System Administrator
See which keys can follow the trail	See api keys, their scopes and what they have been used for	System Administrator, Auditor, Executive
Set up sending to a collector	Configure integrations	System Administrator

Connecting a SIEM hands it the whole audit trail. So this screen is only for people who may export that trail themselves. See roles.

Connecting your SIEM

A collector configuration for Splunk, Microsoft Sentinel, Elastic and QRadar.

Setting up

Configuration

What your SIEM receives

Your SIEM fetches it

Issuing a collector key

The requests your SIEM makes

We send it to you

Is it keeping up?

Who can use this

Connecting your SIEM