TopicsWhat it sends
What it sends
Events and their schema
Every event is one JSON document that follows the schema version chosen under Event schema, and names
that version in schema. Version 1 is described by
schema/pxmlogexporter-1.schema.json, and
schema/samples/1/ holds one sample per event, one more for each kind of event past
the cap of its network, and one for a bulk event that leaves out targets. Within a version changes are
additive, so receivers should ignore fields and events they do not know.
A minor release can add a schema version. A configured tenant follows the oldest version the module supports until someone chooses another under Event schema. Choose a version once the SIEM reads it; events queued before the change keep the version they were captured in. A version is removed only in a major release, and the documentation marks it deprecated in an earlier release.
Event groups
The event groups are security (logins, users, roles and rights, credentials, rejected input), configuration
changes, application errors, asset downloads, Active Script jobs, REST logins, and deletions of the record
classes you list. Application errors are fatal PHP errors, exhausted memory and time limits among them, and
requests answered with a 5xx status, REST calls included; a request whose input the core rejected gives
security.input_rejected instead, whatever its status. An exception the core catches and shows as an error
page leaves the status as it is, so such a request counts only when that status is a 5xx. Events about the
exporter itself are sent whichever groups are selected. REST logins gives one event for each web service
call that signs in with basic authentication or a token, whichever path of the web service it calls
(/admin/rest/, /admin/app/ or another the platform routes to it), so an integration that calls often can
send more of them than all the other groups together.
Configuration changes
exporter.config.changed lists the options that changed and who changed them, with the old and the new value
of each option that holds no secret, however the change was made. Deleting the row of one of the exporter’s
options leaves that option at its default and is listed the same way; only a holder of Administrate the PXM
Log Exporter can delete one.
The options import and the options REST API can store an option under a spelling of the module’s or the option’s name that the database treats as the same, for example with a different case, trailing spaces or accents. The exporter reads its options under their exact names only, so such a row leaves the option at its default. Such a row is reported:
- in
exporter.config.changed, with the reasonother-spellingand the stored spelling instored_as: a row of the exporter renamed to such a spelling, and a new row under the exporter’s module name in any letter case, with or without trailing spaces, that the exporter does not read as stored.optionsnames the option when the stored option name differs from it only in case or trailing spaces, and the row is reported once per option and request; for any other option name, an accented or full-width spelling for example,optionsis empty, and such rows are reported once per request; - as
config.option_changed, while the exporter is on: a new row under any other spelling of the module’s name, one with an accent for example.
A save of the options page that changes the option’s value stores it under its own name again; a save of the same value leaves the row as it is, since the platform skips a store that changes nothing.
People and addresses
Events name people by user name. actor.ip is the caller’s public address: the address the platform resolved,
else Cloudflare’s, else the first X-Forwarded-For entry, whichever is public first. When none is public, as
for a call the platform’s API gateway forwards, actor.ip is null. The address the connection came from, the
forwarded addresses as received and the user agent are next to it. Hash user identifiers replaces user
names with a salted hash: the SHA-256, in hexadecimal, of the salt followed by the user name, trimmed and
lower-cased. Addresses and user agents are sent as they are. The salt is random, one per tenant, and kept in
the credential store as hash-salt. When the salt is gone or the tenant cannot read it, for example after
someone deleted or renamed it or after a restore onto another platform key, the exporter creates a new salt,
keeps hashing and sends exporter.config.changed naming HashUserIdentifiers with the reason salt-renewed;
from then on, every user has a new hash. The salt is for hashing only; if you select it for a sink, that sink
stops with a message to select another credential.
The platform’s support accounts are recognised by their name: CS Support and the platform’s support
addresses, so a tenant user with such an address counts as support as well. Their events carry the actor type
support. Include platform support logins is off by default, which leaves out their logins, REST logins
and logouts; everything else they do is always sent. Failed logins are always sent and never carry the type
support, since anyone can enter a support account’s name: a failed login carries user, api for a web
service’s mechanism, or anonymous when no name was given.
What is never sent
Passwords, tokens, cookies, request bodies and query strings are never sent, nor are the values of rejected
input. A failed login carries what was typed as the user name in presented_user_name, hashed while
Hash user identifiers is on, so a password typed into that field leaves the tenant with it. The value of
another module’s option goes with its change when the change comes through the options page, the options
import or the options REST API, where the core declares the option’s editor type, unless that type is password
or credential or the option’s name suggests a secret or a license. Otherwise the change names the option only.
A URL in an option value keeps only its scheme, host and port.
Bulk changes and size
One request that does the same to several records, as a bulk edit of users does, gives one event per kind of
change: targets lists up to 100 of the records and target is null; more records give more events. When one
event of the platform names more than 25 records, as a bulk delete does, the records after the 25th carry
their id without a label.
An event whose JSON would exceed 8,192 bytes is cut to fit and carries "truncated": true. A merged event
first loses length in targets: labels are cut to 64 characters, then records are left out from the end,
counted in targets_omitted. Then strings in data are cut to 64 characters and lists to 10 entries, and if
the event is still too long, data is left empty, so a rule that matches a field of data can miss a
truncated event. seq is added on delivery, so an event sent over HTTPS or as newline-delimited JSON can end
a few bytes over 8,192; a syslog message stays within the limit.
Merged events
Failed logins from one address with the same presented user name, mechanism and reason within a minute arrive
as one auth.login.failure, whose data.count says how many there were. Every event with an actor.ip
carries its network in actor.ip_network, in CIDR notation: an IPv4 address as its /32, an IPv6 address as
its /64, since one client can use any address in its /64. Once 20 of these auth.login.failure events have
come from one network within a minute, its further failed logins of that minute arrive as one event per
mechanism and reason, with presented_user_name null, data.name_cap 20, the count, and in actor.ip the
address of the first of them. A client that holds more than one /64, such as a /56 or a /48, gets 20 names in
each. The login rule under Detection rules also counts these events against a login from
the same network, so it misses a login from another /64 of such a client.
These events also merge within a minute, and data.count says how many there were; the merged event carries
the request of the first:
api.access_denied, a web service call refused without a failed login: one event per network, user and HTTP status (data.http_status).security.input_rejected, input the core rejects: one event per network, user, page and kinds of error, with the variables of the first.app.error, an application error: one event per network, user, type, file, line and HTTP status (data.http_status), with the message of the first.
Once one network has given 20 events of one of these kinds within a minute, its further ones of that kind merge
without the user: api.access_denied per HTTP status, app.error per type and HTTP status without file, line
and message, and security.input_rejected into one event without page and variables. Such an event carries
data.network_cap 20, the count in data.count, and in actor.ip the address of the first of them.
Heartbeat
While the exporter is on, it sends exporter.heartbeat every five minutes with the queue, the delivery totals,
the selected event groups, and the state of each sink, of the capture plugins and of the plugin that guards the
exporter’s options. A heartbeat is up to twelve minutes old when it reaches the receiver, plus the receiver’s
own ingestion delay. Heartbeats come to about 250 KB per tenant and day. Alert when none arrived for 30
minutes, looking back over at least an hour, and on changes that can silence the exporter (see Detection
rules). When the alert fires, Status in the exporter’s settings shows the cause; saving
the options there, with or without changes, puts a stopped job back on its schedule and lets a failing sink
retry at once.
Centric PXM™ is a trademark of Centric Software, Inc.