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 Settings → Integrations → Security events.

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

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 the last day of events, 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.

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 screen shows these with this organisation’s own address filled in:

curl -X POST "$CMMS_URL/api/rpc/exchange_api_key" \
  -H 'content-type: application/json' \
  -H 'accept: application/vnd.pgrst.object+json' \
  -d '{"p_key": "cmk_…"}'
# → { "token": "...", "expires_at": "..." }   good for fifteen minutes

curl -X POST "$CMMS_URL/api/rpc/audit_feed" \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"p_after": "<cursor of the last event you stored>", "p_limit": 1000}'
# → [ { "cursor": "...", "occurred_at": "...", "event_type": "...", ... } ]

Every event has a cursor. Store the cursor of the last event on each page, and send it as p_after with the next request.

To	Send
Start from the beginning of the trail	Leave out `p_after`
Start from a date instead	`p_from` with a timestamp, and no `p_after`
Carry on	`p_after` with 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	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

Click Save, then Send a test event. 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
Open this screen and see the feed	Permission to export the audit trail
Issue a collector key	Permission to export the audit trail, and to create roles and API keys
See which keys can follow the trail	Permission to view API keys
Set up sending to a collector	Permission to configure integrations

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

​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

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