From 4d8bc8846aa7cf3ffa2795347354c4e10c7ae50c Mon Sep 17 00:00:00 2001 From: Lee Hannigan <29015211+LeeroyHannigan@users.noreply.github.com> Date: Thu, 5 Nov 2026 01:30:09 +0000 Subject: [PATCH] docs: list what the audit log records, and name EXTENDDB_PASSWORD for manage getting-started.md said that every management and settings operation goes to the audit log. Its list included changes to accounts, users, groups, roles, policies and access keys. Section 7 said that the server logs every credential import. The server writes audit entries only for DeleteAdmin, user and role tag changes, AssumeRole (granted, and refused by the role's trust policy) and settings changes made through the management API. extenddb settings set changes the catalog without the server and prints its entry on its own standard output, so the server writes no audit entry for it. Section 9 now says this and names the changes that are not audit-logged. It also says that the server writes no entry while the log level is error or the log filter turns the audit targets off, and gives the macOS and Docker Compose commands. The admin guide and the security model say the same, and no longer say that all logging goes to syslog: a server started with --foreground logs to stderr. getting-started.md and the security model told extenddb manage users to put the password in EXTENDDB_ADMIN_PASSWORD. extenddb init reads that variable for the first admin's password. extenddb manage reads EXTENDDB_PASSWORD when --password is not given. The notes now set it with read -rs, which keeps it out of shell history. They also say that the other password flags and --secret-access-key have no environment variable. Signed-off-by: Lee Hannigan <29015211+LeeroyHannigan@users.noreply.github.com> --- docs/getting-started.md | 25 +++++++++++++++++++------ docs/manuals/05-admin-guide.md | 8 ++++---- docs/manuals/10-security-model.md | 7 ++++--- 3 files changed, 27 insertions(+), 13 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 712f34cfe..b18b79277 100755 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -796,7 +796,7 @@ The management API is available at `/management/*` on the running extenddb serve Admin commands require admin credentials (the username and password printed during `extenddb init`). IAM user self-service commands accept `account_id/user_name` as the `--user` value. -**Note:** The `--password` flag is visible in process listings (`ps aux`). For sensitive environments, use the `EXTENDDB_ADMIN_PASSWORD` environment variable instead. +**Note:** The `--password` flag is visible in process listings (`ps aux`) and shell history. For sensitive environments, leave out `--password` and set the `EXTENDDB_PASSWORD` environment variable instead, with `read -rs EXTENDDB_PASSWORD && export EXTENDDB_PASSWORD`, which keeps the password out of shell history. `extenddb manage` reads the password from `EXTENDDB_PASSWORD`. `--admin-password`, `--new-password`, `--user-password` and `--secret-access-key` have no environment variable. ### List admin users @@ -928,7 +928,7 @@ Both `--secret-access-key` and `--yes` are required: --yes ``` -> **Security note:** `--secret-access-key` and `--password` are visible in `ps` output and shell history. For sensitive environments, use the `EXTENDDB_ADMIN_PASSWORD` environment variable for the password. +> **Security note:** `--secret-access-key` and `--password` are visible in `ps` output and shell history. For sensitive environments, set the password with `read -rs EXTENDDB_PASSWORD && export EXTENDDB_PASSWORD` and leave out `--password`. `--secret-access-key` has no environment variable. Credential import is gated by the `allow_credential_import` runtime setting (default: `true`). To disable: @@ -937,7 +937,7 @@ Credential import is gated by the `allow_credential_import` runtime setting (def allow_credential_import false ``` -Every import is logged to syslog (access key ID, account, user — never the secret). +Credential import is not audit-logged. See [9. Audit logging](#9-audit-logging). ### Change IAM user password @@ -1284,17 +1284,30 @@ Sessions expire after 8 hours of inactivity. Click "Logout" to end a session imm ## 9. Audit logging -All management and settings operations are logged to syslog at WARN level with structured targets for filtering: +The server writes audit entries at WARN level to its log: syslog when it runs as a daemon, and stderr with `--foreground`. Two targets cover some management operations and the settings changes made through the management API: -- **Management operations:** `extenddb::audit::manage` — covers admin CRUD, account CRUD, IAM user/group/role/policy CRUD, access key lifecycle, permissions boundaries, assume-role, and credential import. -- **Settings operations:** `extenddb::audit::settings` — covers `extenddb settings set` changes. +- `extenddb::audit::manage`: DeleteAdmin, user and role tag changes, and AssumeRole, both granted and refused by the role's trust policy. +- `extenddb::audit::settings`: each settings change made through the management API (`PUT /management/settings/{key}`). + +`extenddb settings set` changes the catalog without the server and prints its `extenddb::audit::settings` entry on its own standard output, so the server writes no audit entry for that change. A running server logs, under no audit target, when it applies a new `log_level`, `sqlx_log_level` or `throttling_enabled` value. + +Other management changes are not audit-logged. These include creating admin users, group membership and permissions boundary changes, password changes and credential import. Creating and deleting accounts, IAM users, groups, roles, access keys and policies are not audit-logged either. + +Audit entries are WARN events, so the server writes none of them while the log level (`logging.level`, or the `log_level` setting, which overrides it) is `error`, or while `logging.level` is `off` or a filter that turns the `extenddb::audit` targets off. Secrets (passwords, secret keys) are never included in audit log entries. View audit entries: ```bash +# Linux journalctl -t extenddb | grep 'extenddb::audit' + +# macOS +log show --predicate 'processImagePath ENDSWITH "extenddb"' --last 1d | grep 'extenddb::audit' + +# Docker Compose (--foreground) +docker compose logs extenddb | grep 'extenddb::audit' ``` ## 10. External test suites diff --git a/docs/manuals/05-admin-guide.md b/docs/manuals/05-admin-guide.md index e51da206c..7f790d9c7 100755 --- a/docs/manuals/05-admin-guide.md +++ b/docs/manuals/05-admin-guide.md @@ -164,7 +164,7 @@ All defaults match real DynamoDB limits. Override only for testing edge cases. | `level` | `info` | Initial log level (overridden by runtime setting) | | `format` | `pretty` | Log format: `pretty` or `json` | -Logging always goes to syslog (facility: daemon, ident: extenddb). +The server logs to syslog (facility: daemon, ident: extenddb) when it runs as a daemon, and to stderr with `--foreground`. ### Environment Variable Overrides @@ -819,7 +819,7 @@ Sessions expire after 8 hours. Click "Logout" to end immediately. ### Syslog -All server logging goes to syslog (facility: daemon, ident: extenddb). +The server logs to syslog (facility: daemon, ident: extenddb) when it runs as a daemon, and to stderr with `--foreground`. **Linux:** @@ -852,14 +852,14 @@ log show --predicate 'processImagePath ENDSWITH "extenddb" AND messageType >= 16 ### Audit Logging -Management and settings operations are logged at WARN level: +The server logs some management operations, and the settings changes made through the management API, at WARN level. [Security Model: Logging](10-security-model.md#logging) lists them. ```bash # View audit entries journalctl -t extenddb | grep 'extenddb::audit' ``` -Targets: `extenddb::audit::manage` (management ops), `extenddb::audit::settings` (settings changes). +Targets: `extenddb::audit::manage` (some management operations), `extenddb::audit::settings` (settings changes made through the management API). ### Metrics diff --git a/docs/manuals/10-security-model.md b/docs/manuals/10-security-model.md index 89da45d36..f0eb61aa9 100755 --- a/docs/manuals/10-security-model.md +++ b/docs/manuals/10-security-model.md @@ -309,13 +309,14 @@ Import/export file paths are validated: ### Credential Handling - `extenddb init` prints admin credentials once; they are not stored in plaintext -- The `--password` flag accepts passwords via environment variable (`EXTENDDB_ADMIN_PASSWORD`) to avoid process listing exposure +- `extenddb manage` reads the password from the `EXTENDDB_PASSWORD` environment variable when `--password` is not given, so the password does not appear in process listings - Access key secrets are shown once on creation and cannot be retrieved afterward ### Logging -- All logging goes to syslog (no log files with sensitive data on disk) -- Some management operations are audit-logged at WARN, with target `extenddb::audit::manage` or `extenddb::audit::settings`: DeleteAdmin, user and role tag changes, AssumeRole (granted and denied), and settings changes. Other management changes, such as creating or deleting users, roles, access keys and policies, are not audit-logged +- The server logs to syslog when it runs as a daemon and to stderr with `--foreground`, and writes no log files of its own +- Some management operations are audit-logged at WARN, with target `extenddb::audit::manage` or `extenddb::audit::settings`: DeleteAdmin, user and role tag changes, AssumeRole (granted, and refused by the role's trust policy), and settings changes made through the management API. `extenddb settings set` changes the catalog without the server and prints its entry on its own standard output, so the server writes no audit entry for that change. Other management changes, such as creating or deleting IAM users, roles, access keys and policies, are not audit-logged +- Audit entries are WARN events, so none are written while the log level (`logging.level`, or the `log_level` setting, which overrides it) is `error`, or while `logging.level` is `off` or a filter that turns the `extenddb::audit` targets off - Cache flushes (`cache invalidate`) are logged at INFO with the admin name, the scope and its selectors, so they are not recorded when the log level (`logging.level`, or the `log_level` setting, which overrides it) is `warn` or `error` - Log messages do not contain secret keys, passwords, or item data. Access key IDs can appear, for example in cache flush records