An audit trail of who did what on a hub, stored and queryable
  • Python 90%
  • HTML 9.2%
  • Mako 0.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-01 12:09:26 +01:00
src The trail is internal: not in the admin panel's generic screens 2026-10-31 20:28:22 +01:00
.gitignore feat: scaffold splent_feature_audit with splent feature:create 2026-10-25 00:35:19 +02:00
COPYING feat: scaffold splent_feature_audit with splent feature:create 2026-10-25 00:35:19 +02:00
COPYING.LESSER feat: scaffold splent_feature_audit with splent feature:create 2026-10-25 00:35:19 +02:00
MANIFEST.in feat: scaffold splent_feature_audit with splent feature:create 2026-10-25 00:35:19 +02:00
pyproject.toml chore: release splent_io/splent_feature_audit to v0.2.0 2026-11-01 12:09:26 +01:00
README.md docs: the parameters' types and ranges, and audit in the line 2026-10-25 16:24:55 +01:00

splent_feature_audit

The audit trail of a SPLENT product: who did what, to what, from where and when. Any feature writes to it through the framework's record_event, without importing this feature, and the call does nothing in a product without it (decision D10: the API in the framework, the storage in a feature). Administrators read it on /admin/audit; a daily purge deletes what is past retention (D19: 90 days).

Writing an event

from splent_framework.audit import record_event

record_event(
    "token.revoked",
    target_type="api_token",
    target_id=token.id,
    data={"scopes": token.scopes},
)
  • action is area.verb in small letters (account.deleted, dataset.withdrawn). Anything else is refused with a ValueError, with or without this feature, so the mistake shows in the tests of any product.
  • actor is the account signed in to the request unless the call names one (an account, its id or "system"); outside a request it is system.
  • outcome is success (the default), failure or denied.
  • data holds the details as JSON values. A key that names a credential (password, token, api_key, secret...) is kept with its value removed. Keep personal data out of it: an account is its id.
  • session: pass the session of a write that is not committed yet (a receiver of auth's user-deleting), and the event is written in the same flush and rolled back with it. Without it the event is written at once, on a connection of its own, whatever the caller's session does next.

The framework adds where the request came from: the client's address (as the app sees it behind SPLENT_TRUSTED_PROXIES), its user agent, the request id (nginx's X-Request-ID, or one made for the request), the method and the endpoint. Never the URL, which may carry a token; the endpoint says the same without it.

What it records already

The flows that announce themselves with a signal are recorded by this feature, with no change to the feature that sends it:

Signal Event
auth's user-registered account.created (the actor is the account itself when its visitor opened it)
auth's user-deleting account.deleted, with the deletion
auth's user-password-changed account.password_changed, with the change
auth's user-disabled, user-enabled account.disabled, account.enabled, with the change
Flask-Login's user_logged_in, user_logged_out account.signed_in, account.signed_out (off with AUDIT_SIGN_INS = false)
identities' identity-linked, identity-disconnected account.identity_linked, account.identity_unlinked, with the provider
dataset's dataset-published dataset.published, with its identifier, provider and owner
dataset's dataset-withdrawn dataset.withdrawn, with the reason's code and the owner
dataset's dataset-deleted dataset.deleted, with the owner

auth sends its account signals from the database session, before it flushes the change, so a deletion the database refuses leaves no account.deleted behind. The purge records itself as audit.purged.

What the other flows need to be recorded (a failed sign-in, an API token minted or revoked, a role changed on the accounts screen) is a call to record_event in the feature that does it, or a signal it sends.

The table

audit_event, one row per event, with indexes on the time, the action, the actor and the target. No column points at another table: an account that is deleted leaves its events behind, with an id that no longer names anybody, and the trail of a dataset outlives it.

The rows are append-only. The ORM refuses to change or delete one, and to write one by hand, so the admin panel's generic CRUD, a seeder or a script can neither rewrite history nor forge it; only the purge touches them, with statements of its own.

Until the migration has made the table nothing is written, and the log says so, rather than failing the write the event describes.

The screen

/admin/audit, for administrators (the admin role), in the Administration section of the menu: every event, newest first, 50 a page, narrowed by action (one, or an area ending in a dot: account.), outcome, account id, target and dates. Read only.

Retention

splent feature:audit purge

deletes the events older than AUDIT_RETENTION_DAYS and, when AUDIT_PSEUDONYMIZE_AFTER_DAYS is set, blurs the address of the events older than that (to its /24 or /48 network) and drops their user agent. Run it once a day in the web container:

15 3 * * * docker exec -u splent <product>_web_deploy splent feature:audit purge

It deletes in batches of a thousand, by primary key, so a large backlog does not hold one long transaction.

Settings

Each is a typed parameter in [tool.splent.config_schema], decided when the product is derived, and product:validate checks a product's value against it.

Variable Type Default
AUDIT_RETENTION_DAYS int, 1 to 3650 90 Days an event is kept (D19)
AUDIT_PSEUDONYMIZE_AFTER_DAYS int, 0 to 3650 0 Days after which an event's address is blurred and its user agent dropped. 0 keeps them until the event is deleted
AUDIT_SIGN_INS bool true Whether every sign-in and sign-out is an event. They are most of a busy site's trail

Enable it in a product

  1. Select audit, an optional feature of plataforma in openhubs_spl, where audit => auth: its screen is for administrators, and the account events it keeps are auth's.
  2. Pin it and run the migrations (audit0001_events).
  3. Schedule the purge.

Develop

splent feature:test audit --neutral
splent feature:contract audit --write