- Python 90%
- HTML 9.2%
- Mako 0.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| src | ||
| .gitignore | ||
| COPYING | ||
| COPYING.LESSER | ||
| MANIFEST.in | ||
| pyproject.toml | ||
| README.md | ||
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.verbin 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 issystem. - outcome is
success(the default),failureordenied. - 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
- Select
audit, an optional feature ofplataformain openhubs_spl, whereaudit => auth: its screen is for administrators, and the account events it keeps are auth's. - Pin it and run the migrations (
audit0001_events). - Schedule the purge.
Develop
splent feature:test audit --neutral
splent feature:contract audit --write