From ba6eb2af91aae8673400c69f33b739483ce1c298 Mon Sep 17 00:00:00 2001 From: pat-s Date: Mon, 23 Feb 2026 18:57:48 +0100 Subject: [PATCH 1/3] docs: add audit logging documentation --- .../v0-2/admin/technical/audit-logging.mdx | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 src/content/docs/v0-2/admin/technical/audit-logging.mdx diff --git a/src/content/docs/v0-2/admin/technical/audit-logging.mdx b/src/content/docs/v0-2/admin/technical/audit-logging.mdx new file mode 100644 index 0000000..b03dbdf --- /dev/null +++ b/src/content/docs/v0-2/admin/technical/audit-logging.mdx @@ -0,0 +1,60 @@ +--- +title: "Audit Logging" +--- + +Ricochet writes an audit log for security-related and administrative operations. +Each entry is appended as a single JSON line to `RICOCHET_HOME/logs/audit/audit.log`. + +## Audited operations + +| Action | Event | Details | +|---|---|---| +| User role change | `user.role_change` | Old role, new role, actor, target user | +| First admin bootstrap | `user.first_admin` | User promoted to admin as first registered user | +| Execution environment created | `exec_env.create` | Environment name, actor | +| Execution environment updated | `exec_env.update` | Environment name, changes, actor | +| Execution environment deleted | `exec_env.delete` | Environment name, actor | +| Content access granted | `access.grant` | Content ID, target user, role | +| Content access revoked | `access.revoke` | Content ID, target user, role | + +## Log format + +Each line is a JSON object with the following fields: + +```json +{ + "timestamp": "2026-02-23T14:30:00+01:00", + "action": "user.role_change", + "actor": "", + "target": "", + "details": { "old_role": "consumer", "new_role": "developer" }, + "success": true +} +``` + +| Field | Description | +|---|---| +| `timestamp` | ISO 8601 timestamp with timezone | +| `action` | The operation that was performed | +| `actor` | The user or system component that initiated the action | +| `target` | The resource or user the action was performed on (optional) | +| `details` | Additional context as a JSON object (optional) | +| `success` | Whether the operation succeeded | +| `error` | Error message when `success` is `false` (optional) | + +## Log rotation + +Audit logs are rotated daily. +When rotation occurs, the previous day's log is compressed with gzip and renamed to `audit-YYYY-MM-DD.log.gz`. +Archived logs are never automatically deleted. + +## File location + +``` +RICOCHET_HOME/ +└── logs/ + └── audit/ + ├── audit.log # current day + ├── audit-2026-02-22.log.gz + └── audit-2026-02-21.log.gz +``` From 1c5228c89b446063c40857b56dd5cb3aa7bfd9cf Mon Sep 17 00:00:00 2001 From: pat-s Date: Mon, 23 Feb 2026 18:58:55 +0100 Subject: [PATCH 2/3] docs: move audit logging page to dev section only --- src/content/docs/{v0-2 => dev}/admin/technical/audit-logging.mdx | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/content/docs/{v0-2 => dev}/admin/technical/audit-logging.mdx (100%) diff --git a/src/content/docs/v0-2/admin/technical/audit-logging.mdx b/src/content/docs/dev/admin/technical/audit-logging.mdx similarity index 100% rename from src/content/docs/v0-2/admin/technical/audit-logging.mdx rename to src/content/docs/dev/admin/technical/audit-logging.mdx From b3a2289c675b17b6f868232481a892073eddf61f Mon Sep 17 00:00:00 2001 From: pat-s Date: Mon, 23 Feb 2026 19:14:22 +0100 Subject: [PATCH 3/3] format --- .../dev/admin/technical/audit-logging.mdx | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/content/docs/dev/admin/technical/audit-logging.mdx b/src/content/docs/dev/admin/technical/audit-logging.mdx index b03dbdf..7c7345c 100644 --- a/src/content/docs/dev/admin/technical/audit-logging.mdx +++ b/src/content/docs/dev/admin/technical/audit-logging.mdx @@ -7,15 +7,15 @@ Each entry is appended as a single JSON line to `RICOCHET_HOME/logs/audit/audit. ## Audited operations -| Action | Event | Details | -|---|---|---| -| User role change | `user.role_change` | Old role, new role, actor, target user | -| First admin bootstrap | `user.first_admin` | User promoted to admin as first registered user | -| Execution environment created | `exec_env.create` | Environment name, actor | -| Execution environment updated | `exec_env.update` | Environment name, changes, actor | -| Execution environment deleted | `exec_env.delete` | Environment name, actor | -| Content access granted | `access.grant` | Content ID, target user, role | -| Content access revoked | `access.revoke` | Content ID, target user, role | +| Action | Event | Details | +| ----------------------------- | ------------------ | ----------------------------------------------- | +| User role change | `user.role_change` | Old role, new role, actor, target user | +| First admin bootstrap | `user.first_admin` | User promoted to admin as first registered user | +| Execution environment created | `exec_env.create` | Environment name, actor | +| Execution environment updated | `exec_env.update` | Environment name, changes, actor | +| Execution environment deleted | `exec_env.delete` | Environment name, actor | +| Content access granted | `access.grant` | Content ID, target user, role | +| Content access revoked | `access.revoke` | Content ID, target user, role | ## Log format @@ -32,15 +32,15 @@ Each line is a JSON object with the following fields: } ``` -| Field | Description | -|---|---| -| `timestamp` | ISO 8601 timestamp with timezone | -| `action` | The operation that was performed | -| `actor` | The user or system component that initiated the action | -| `target` | The resource or user the action was performed on (optional) | -| `details` | Additional context as a JSON object (optional) | -| `success` | Whether the operation succeeded | -| `error` | Error message when `success` is `false` (optional) | +| Field | Description | +| ----------- | ----------------------------------------------------------- | +| `timestamp` | ISO 8601 timestamp with timezone | +| `action` | The operation that was performed | +| `actor` | The user or system component that initiated the action | +| `target` | The resource or user the action was performed on (optional) | +| `details` | Additional context as a JSON object (optional) | +| `success` | Whether the operation succeeded | +| `error` | Error message when `success` is `false` (optional) | ## Log rotation