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 reason other-spelling and the stored spelling in stored_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. options names 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, options is 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.