Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Logging, Monitoring & Audit Trail

This page describes what the Flopsar Server records, where, and in what format, and how an operator uses those records to monitor for and investigate security events. Recording and, where relevant, monitoring security-relevant internal activity — including access to and modification of data — is an essential requirement of the Cyber Resilience Act (Annex I, Part I, point (l)). This page is the operator-facing description of how Flopsar meets it.

Two distinct streams

Flopsar produces two separate logging streams, and it is important not to confuse them:

  1. The operational log — diagnostic output about the running server (startup, errors, warnings, informational messages). It is meant for troubleshooting and health monitoring.

  2. The security audit trail — a structured, tamper-evident record of security-relevant actions (who did what, to what, with what outcome). It is the authoritative record for security review and forensics.

Treat the audit trail, not the operational log, as your source of truth for security events.

Operational logging

The operational log is configured in the [logger] section of settings.toml; see the Server Configuration Reference. Two backends are available:

  • Local (default) — writes to a rolling log file, flopsar.log, in the server's working location. Rotation is size-based: when the file reaches max_size it is rolled, and max_files rotated files are retained (flopsar-1.log, flopsar-2.log, …). This bounds disk usage.

  • Syslog — forwards log records to the local syslog facility (RFC 3164 format over the system's Unix socket). Use this backend when you want logs collected centrally by the platform's logging stack or forwarded to a SIEM.

The operational log is for diagnostics. It is not tamper-evident and should not be relied on as the security record; that role belongs to the audit trail below.

Security audit trail

The audit log is a tamper-evident, append-only record of security-relevant actions performed against the Flopsar server. It answers the questions auditors and security teams care about: who did what, to which object, from where, when, and with what outcome. Typical uses include incident investigation, compliance reporting, and detecting unauthorized changes to instrumentation, users, or licensing.

Unlike the server log, which is intended for operational diagnostics, the audit log is a structured, security-focused stream that is designed to be archived, shipped to a SIEM, and verified for integrity.

How It Works

When auditing is enabled, the server starts a dedicated writer that receives audit records from every part of the application and appends them to a single file. Each record is written as one line of JSON (the file is a JSON Lines stream), flushed to disk immediately, and chained to the previous record with a cryptographic hash.

  • Location — the log is stored in the environment's logs directory, as audit.log (for example, <server_home>/logs/audit.log).

  • Format — one self-contained JSON object per line, UTF-8 encoded.

  • Ordering — every record carries a strictly increasing sequence number (seq), starting at 0.

  • Append-only — records are only ever appended; the server never rewrites or reorders existing lines.

Record Fields

Each audit entry contains the following fields:

  • v — schema version of the record (currently 1).

  • seq — monotonic, gap-free sequence number of the record.

  • ts — timestamp in RFC 3339 / ISO 8601 form, in UTC, with millisecond precision (for example, 2026-06-01T07:45:12.531Z).

  • action — the audited action (see Audited Actions).

  • outcome — either success or failure.

  • actor — the user name that performed the action. When no authenticated user applies, the JSON value is null (shown as - in the interface).

  • actor_local — true for a local account, false for an account authenticated through LDAP, or null when not applicable.

  • src — the source of the request (for example, the client address). When unknown, the JSON value is null (shown as -).

  • target — the object the action applies to, such as a user name, application name, profile, or key.

  • reason — a short, human-readable description of the event.

  • prev — the hash of the previous record in the chain (hex).

  • hash — the hash of this record (hex).

A single line looks like this:

Tamper Evidence

Every record embeds the hash of the record before it. The hash of each entry is a cryptographic digest (BLAKE2b-256) computed over the entry's canonical contents, which include the prev value. This forms a hash chain:

  • The very first record of a fresh log is a genesis entry whose prev is a string of 64 zeros. It uses the audit_init action and marks the start of the chain.

  • Each subsequent record's hash depends on its own contents and on the previous record's hash. Because of this chaining, any attempt to modify, insert, remove, or reorder a record breaks the chain from that point onward: the recomputed hashes no longer match the stored hash/prev values. This makes after-the-fact tampering detectable rather than silent.

The hash chain makes tampering detectable, not impossible. To get the full benefit, ship audit records off the host (for example, to a SIEM or an append-only store) and restrict write access to the logs directory so that only the server's service account can write to it.

Example: A Chain Fragment

The following three lines show the start of a log. The genesis record (seq 0) opens the chain with a prev of 64 zeros. Each following record sets its prev to the hash of the line directly above it, so the records are cryptographically linked in order (hashes below are shortened for readability).

Reading the chain top to bottom:

  • The genesis record's hash (a1b2c3d4e5f6…0091) becomes the prev of record 1.

  • Record 1's hash (7f4e9a01bc23…d5a8) becomes the prev of record 2.

If anyone altered record 1 — for instance, changing its actor — its recomputed hash would no longer equal the prev stored in record 2, and the break would be obvious during verification.

Audited Actions

The audit log focuses on actions that change security posture, touch sensitive data, or affect what runs inside your monitored JVMs. Actions are grouped below by area; the value in parentheses is the action field as it appears in the log.

  • Authentication and session

    • Successful sign-in (login).

    • Sign-in refused because the account is locked (login_blocked).

    • A request with a missing, invalid, or expired token (token_rejected).

    • A request rejected for insufficient permissions (access_denied).

  • Users

    • Create (user_create), update (user_update), delete (user_delete).

    • Password change (user_password_change).

    • Role assignment change (user_role_assign).

    • Account lock (user_lock) and unlock (user_unlock).

    • Banned-applications change (user_banned_apps_change).

  • Roles and permissions

    • Create (role_create), update (role_update), delete (role_delete). Updating a role can escalate privileges, so these events are always recorded.

  • LDAP

    • Configuration change (ldap_config_update).

    • Connection, login, and directory test queries (ldap_query).

  • Agent tokens (pre-shared keys)

    • Create (psk_create), rotate (psk_rotate), delete (psk_delete).

    • Reveal a token in clear text (psk_view).

  • Agent connections

    • Connection accepted (agent_connect), authentication result (agent_auth), disconnect (agent_disconnect), and command execution (agent_execute).

  • Instrumentation (high risk — affects code running in your JVMs)

    • Profile create (profile_create), update (profile_update), status change (profile_status_change), deploy (profile_deploy), delete (profile_delete).

    • Plugin/extension upload (plugin_upload) and delete (plugin_delete).

    • Dynamic, ad-hoc instrumentation dry run (agent_dry_run).

  • Data protection — masking

    • Create (data_mask_create), update (data_mask_update), delete (data_mask_delete). Deleting a mask weakens data protection, so it is audited.

  • Data access and deletion

    • Viewing captured method arguments or exception data, which may contain sensitive information (sensitive_data_view).

    • Deleting collected calls (calls_delete) and deleting archives (archive_delete).

  • Licensing

    • License update (license_update) and license-to-application mapping change (license_mapping_update).

  • Filters

    • Filter changes (filter_change) and filter-group changes (filter_group_change).

  • Server configuration

    • Server settings change (config_change).

  • Audit subsystem itself

    • Chain initialization (audit_init), audit enable/disable (audit_config_change), export or read of the audit log (audit_export), and anchoring of the chain head (audit_anchor).

Configuration

Auditing is controlled by a single option in the server configuration file. It is enabled by default.

  • Set enabled = false to turn the audit writer off. When disabled, audit calls become no-ops and nothing is written to audit.log.

  • Changing this setting takes effect on server start. After editing the configuration, restart the server.

Disabling the audit log removes an important security control. If your environment is subject to compliance requirements, keep auditing enabled and forward audit.log to durable, access-controlled storage.

Working with the Audit Log

  • Reading — because the file is plain JSON Lines, you can inspect it with standard tools. For example, to follow new events:

  • Filtering — pipe the stream through a JSON processor to focus on specific actions or actors. For example, to list failed sign-ins:

  • Shipping — point your log shipper or SIEM agent at audit.log. Each line is an independent, self-describing JSON document, so no multi-line parsing is required.

  • Verifying integrity — verification walks the file in order and, for each record, recomputes its hash from its contents and confirms that every record's prev equals the previous record's hash. Any mismatch indicates the chain was altered at or before that point.

A built-in verification command that validates the entire chain in one step is coming in a future release. Until then, you can verify the chain with the procedure described above.

Treat the audit log as sensitive. Some events reference object names (users, applications, profiles, keys) and source addresses. Restrict read access to administrators and security personnel.

Last updated