# 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](https://jsonlines.org/) 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, `/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: ```json {"v":1,"seq":42,"ts":"2026-06-01T07:45:12.531Z","action":"profile_deploy","outcome":"success","actor":"admin","actor_local":true,"src":"10.0.0.5","target":"orders-service","reason":"deployed profile 'orders'","prev":"9f2c…","hash":"4ab1…"} ``` #### 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. {% hint style="warning" %} 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. {% endhint %} #### 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). ```json {"v":1,"seq":0,"ts":"2026-06-01T03:00:00.000Z","action":"audit_init","outcome":"success","actor":null,"actor_local":null,"src":null,"target":null,"reason":"audit log initialized","prev":"0000000000000000000000000000000000000000000000000000000000000000","hash":"a1b2c3d4e5f6…0091"} {"v":1,"seq":1,"ts":"2026-06-01T07:45:09.812Z","action":"login","outcome":"success","actor":"admin","actor_local":true,"src":"10.0.0.5","target":"admin","reason":"user signed in","prev":"a1b2c3d4e5f6…0091","hash":"7f4e9a01bc23…d5a8"} {"v":1,"seq":2,"ts":"2026-06-01T07:45:12.531Z","action":"profile_deploy","outcome":"success","actor":"admin","actor_local":true,"src":"10.0.0.5","target":"orders-service","reason":"deployed profile 'orders'","prev":"7f4e9a01bc23…d5a8","hash":"3c8d61f0aa47…1e7b"} ``` 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**. ```toml [audit] enabled = true ``` * 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. {% hint style="info" %} 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. {% endhint %} ### 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: ```shellscript $ tail -f /logs/audit.log ``` * **Filtering** — pipe the stream through a JSON processor to focus on specific actions or actors. For example, to list failed sign-ins: ```shellscript $ grep '"action":"login"' /logs/audit.log | grep '"outcome":"failure"' ``` * **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. {% hint style="info" %} 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. {% endhint %} {% hint style="warning" %} 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. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.flopsar.com/7/security/logging-monitoring-and-audit-trail.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.