nprasad2077/docs
1
1
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-09-20 04:58:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Correct audit logging actors, warning and coverage

Browse Source 
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) <[email protected]>
This commit is contained in:
silverwind
2026-09-18 03:14:54 +02:00
co-authored by Claude
parent 240a2840a4
commit 1dd914792d
1 changed files with 31 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/administration/audit-logging.md
+31 -20
View File
@@ -36,8 +36,9 @@ before Gitea writes them into `app.ini`.
## View events ## View events
The Audit Log page is always available. When recording is disabled, it shows a The Audit Log pages are always available and still list any events that were
warning and still lists any events that were stored earlier. stored earlier. When recording is disabled, the site administration page also
shows a warning.
| Audience | Location | Events shown | | Audience | Location | Events shown |
| --- | --- | --- | | --- | --- | --- |
@@ -47,8 +48,9 @@ warning and still lists any events that were stored earlier.
| Repository administrators | Repository settings → Audit Log (`/<owner>/<repo>/settings/audit_logs`) | Events scoped to that repository | | Repository administrators | Repository settings → Audit Log (`/<owner>/<repo>/settings/audit_logs`) | Events scoped to that repository |
Each listing can be filtered by actor (username), action and origin, and sorted 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 by timestamp. The actor filter does not match the
`user:impersonation` or `repository:webhook`. [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 Site administrators can download the current filtered result as JSONL
(newline-delimited JSON) from **Export JSONL**. The file name is (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. - **Message**: a human-readable sentence rendered from a per-action template.
- **Metadata**: extra fields that fill the message template (token name, new - **Metadata**: extra fields that fill the message template (token name, new
visibility, and so on). Secrets and token values are not stored. 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. - **Timestamp**: when the event was recorded.
An exported JSONL line looks like: 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. 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 - `(gitea-cli)` for `gitea admin` commands and the `system:startup` and
- `AuthenticationSource` for authentication-source syncs and related background `system:shutdown` events
work - `(gitea-auth-source)` for authentication-source syncs and for users an
- `Unknown` if the actor cannot be resolved; the event is still recorded 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 Events of the `(gitea-cli)` actor use origin `cli`. Cron tasks, git hooks and
non-interactive paths are attributed the same way. other background work use origin `system`.
## What is recorded ## What is recorded
Events cover security-relevant changes, grouped by action family: Events cover security-relevant changes, grouped by action family:
- **User**: create and delete, name, password, visibility, emails, 2FA, - **User**: create and delete, admin, restricted and active status, name,
WebAuthn, OpenID, external logins, access tokens, OAuth2 applications and password and password reset requests, visibility, emails, authentication
grants, SSH/GPG/principal keys, secrets, webhooks, impersonation, failed source, 2FA, WebAuthn, OpenID, external logins, access tokens, OAuth2
two-factor authentication applications and grants, SSH/GPG/principal keys, secrets, webhooks,
impersonation, failed two-factor authentication
- **Organization**: create and delete, name, visibility, members, teams, - **Organization**: create and delete, name, visibility, members, teams,
OAuth2 applications, secrets, webhooks OAuth2 applications, secrets, webhooks
- **Repository**: create, fork, archive, delete, rename, visibility, transfer, - **Repository**: create, fork, archive, delete, rename, visibility, transfer,
mirrors, signing verification, collaborators and teams, default branch, mirrors, signing verification, collaborators and teams, default branch,
branch and tag protection, deploy keys, webhooks, secrets branch and tag protection, deploy keys, webhooks, secrets
- **Issues, pull requests, projects and wiki**: create, update, delete, comments - **Issues and pull requests**: create, delete, comments and merges
and merges - **Projects and wiki pages**: create, update and delete
- **Actions**: enable, disable and dispatch a workflow - **Actions**: enable, disable and dispatch a workflow
- **System**: startup and shutdown, instance-wide webhooks, authentication - **System**: startup and shutdown, instance-wide webhooks, authentication
sources, instance-wide OAuth2 applications sources, instance-wide OAuth2 applications
@@ -123,8 +132,10 @@ and the original operation continues.
## What is not recorded ## What is not recorded
- Read-only access such as browsing, clone, fetch or API GET requests - Read-only access such as browsing, clone, fetch or API GET requests
- Successful password or SSH logins (use the [access log](logging-config.md) - Logins, successful or failed, other than failed two-factor authentication
and [Fail2ban Setup](fail2ban-setup.md) for authentication traffic) (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 - Token or secret values
- Which SSH key a real user pushed with (deploy keys are named; ordinary SSH - Which SSH key a real user pushed with (deploy keys are named; ordinary SSH
user pushes are not) user pushes are not)