From 1dd914792d6a7ccf574e7b8728b91329aa1d9665 Mon Sep 17 00:00:00 2001 From: silverwind Date: Fri, 18 Sep 2026 03:14:54 +0200 Subject: [PATCH] Correct audit logging actors, warning and coverage The system actor names did not match what Gitea records, the disabled warning only shows on the admin page, and the recorded/not recorded lists overstated login and issue edit coverage while missing user status changes. Co-Authored-By: Claude (Opus 5) --- docs/administration/audit-logging.md | 51 +++++++++++++++++----------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/docs/administration/audit-logging.md b/docs/administration/audit-logging.md index 9c97e346..fc135eed 100644 --- a/docs/administration/audit-logging.md +++ b/docs/administration/audit-logging.md @@ -36,8 +36,9 @@ before Gitea writes them into `app.ini`. ## View events -The Audit Log page is always available. When recording is disabled, it shows a -warning and still lists any events that were stored earlier. +The Audit Log pages are always available and still list any events that were +stored earlier. When recording is disabled, the site administration page also +shows a warning. | Audience | Location | Events shown | | --- | --- | --- | @@ -47,8 +48,9 @@ warning and still lists any events that were stored earlier. | Repository administrators | Repository settings → Audit Log (`///settings/audit_logs`) | Events scoped to that repository | Each listing can be filtered by actor (username), action and origin, and sorted -by timestamp. Action filters accept an exact action or a family prefix such as -`user:impersonation` or `repository:webhook`. +by timestamp. The actor filter does not match the +[system actors](#actors-and-origins). Action filters accept an exact action or +a family prefix such as `user:impersonation` or `repository:webhook`. Site administrators can download the current filtered result as JSONL (newline-delimited JSON) from **Export JSONL**. The file name is @@ -72,7 +74,9 @@ A recorded event contains: - **Message**: a human-readable sentence rendered from a per-action template. - **Metadata**: extra fields that fill the message template (token name, new visibility, and so on). Secrets and token values are not stored. -- **IP address**: the client address of the request, when one exists. +- **IP address**: the client address of the request, when one exists. Events + triggered by a git push record the SSH client address for SSH pushes and + `127.0.0.1` for HTTP pushes. - **Timestamp**: when the event was recorded. An exported JSONL line looks like: @@ -88,31 +92,36 @@ can parse it: `System started [Gitea {version}]`. Most web and API requests pick up the signed-in user automatically. -Some entry points have no signed-in user. Those events use a dedicated actor: +Other entry points record a system actor: -- `CLI` for `gitea` command-line operations -- `AuthenticationSource` for authentication-source syncs and related background - work -- `Unknown` if the actor cannot be resolved; the event is still recorded +- `(gitea-cli)` for `gitea admin` commands and the `system:startup` and + `system:shutdown` events +- `(gitea-auth-source)` for authentication-source syncs and for users an + authentication source creates or updates at sign-in +- `gitea-actions` for Gitea Actions tasks +- `(deploy-key)` for pushes with a deploy key +- `(Cron)` for scheduled cron tasks +- `Unknown` when no actor can be resolved -Cron tasks and other background work use origin `system`. Git hooks and similar -non-interactive paths are attributed the same way. +Events of the `(gitea-cli)` actor use origin `cli`. Cron tasks, git hooks and +other background work use origin `system`. ## What is recorded Events cover security-relevant changes, grouped by action family: -- **User**: create and delete, name, password, visibility, emails, 2FA, - WebAuthn, OpenID, external logins, access tokens, OAuth2 applications and - grants, SSH/GPG/principal keys, secrets, webhooks, impersonation, failed - two-factor authentication +- **User**: create and delete, admin, restricted and active status, name, + password and password reset requests, visibility, emails, authentication + source, 2FA, WebAuthn, OpenID, external logins, access tokens, OAuth2 + applications and grants, SSH/GPG/principal keys, secrets, webhooks, + impersonation, failed two-factor authentication - **Organization**: create and delete, name, visibility, members, teams, OAuth2 applications, secrets, webhooks - **Repository**: create, fork, archive, delete, rename, visibility, transfer, mirrors, signing verification, collaborators and teams, default branch, branch and tag protection, deploy keys, webhooks, secrets -- **Issues, pull requests, projects and wiki**: create, update, delete, comments - and merges +- **Issues and pull requests**: create, delete, comments and merges +- **Projects and wiki pages**: create, update and delete - **Actions**: enable, disable and dispatch a workflow - **System**: startup and shutdown, instance-wide webhooks, authentication sources, instance-wide OAuth2 applications @@ -123,8 +132,10 @@ and the original operation continues. ## What is not recorded - Read-only access such as browsing, clone, fetch or API GET requests -- Successful password or SSH logins (use the [access log](logging-config.md) - and [Fail2ban Setup](fail2ban-setup.md) for authentication traffic) +- Logins, successful or failed, other than failed two-factor authentication + (use the [access log](logging-config.md) and + [Fail2ban Setup](fail2ban-setup.md) for authentication traffic) +- Edits to issues and pull requests - Token or secret values - Which SSH key a real user pushed with (deploy keys are named; ordinary SSH user pushes are not)