Audit trailing
Exponential 6 records security-relevant events in a tamper-evident audit trail: sign-ins and refused sign-ins, content moves, removals and hides, role and policy changes, section and state assignments, settings writes, cache clears, package installs, orders and VAT changes. The trail is on by default in every installation, needs no setup, and can be read in the administration interface and on the command line.
The audit trail of 6.0.15 replaces the per-event text files of the 4.x releases (login.log, content_move.log and the others). Code that calls eZAudit::writeAudit() with one of the old names keeps working: the old name is mapped to an event of the new trail.
What is recorded
Every record says when it happened, who did it (user ID and login), where the request came from, what was done and to what, and whether it succeeded, was refused or failed. Records are written to one file per channel and day, and each record carries the hash of the record before it, so an edited or cut file is detected.
| Channel | Examples |
|---|---|
| content | publish, move, copy, remove, hide and reveal, sections, states, trash, versions, URL aliases, classes, content jobs |
| access | sign-in, failed sign-in, refused view, account lock, role assignment, password reset, form token refusal |
| system | settings writes, cache clears, cronjob runs, commands, package installs, maintenance, deploys |
| commerce | orders, payments (never card data), VAT, currencies, discounts, exports and imports |
| read | sampled node views, searches and downloads, only when reads are switched on |
Privacy is built in: addresses are shortened, sessions hashed, user agents shortened and query values removed. Passwords, tokens and secrets are never recorded.
The old event names
The 4.x audit functions are recorded under these names (settings/audit.ini [AuditCompatSettings] Map[]):
| 4.x name | Recorded as |
|---|---|
| user-login | access.session.login |
| user-failed-login | access.session.login.failed |
| content-move | content.node.move |
| content-delete | content.node.remove.trash |
| content-hide | content.node.hide |
| role-change | access.role.change |
| role-assign | access.role.assign |
| section-assign | content.node.section |
| state-assign | content.object.state |
| order-delete | commerce.order.delete |
An old name without a mapping is recorded as system.legacy.<name> (UnmappedAsLegacy=enabled). To also write the old text files, outside the hash chain, set LegacyFiles=enabled in the same group.
Settings
The settings are in settings/audit.ini; override them in settings/override/audit.ini.append.php. The most used ones:
[AuditSettings] # enabled | disabled Audit=enabled # below the var directory of the siteaccess LogDir=log/audit # continue: a request goes on when the trail cannot be written # refuse: security-relevant changes are refused while it cannot be written OnWriteFailure=continue [AuditChannel_content] LiveDays=90 ArchiveDays=730
Each channel has its own group ([AuditChannel_access], _system, _commerce, _read) with LiveDays, ArchiveDays, MaxFileSize and ArchiveFormat. Which events are written is set in [AuditEventSettings] Enabled[] and Disabled[]. The override file also holds the signing and pseudonym keys of the trail: keep it in your backups.
In the administration interface
The Audit tab (/audit/dashboard) shows the health of the hash chains, the events of today and the last seven days, failed sign-ins, role grants and alerts. The Console searches and filters the records, Event shows one record, and Export, Charts, Alerts, Archives and Settings do what their names say.
The audit dashboard (Audit tab, /audit/dashboard). Logins and object names are blanked out in this screenshot.
Two policies control access: audit/read (dashboard, console, events, charts, alerts and export, optionally limited by channel) and audit/manage (archives, settings and Verify now). Only the Administrator role has them in a new installation.
From the command line
./console exp:audit status ./console exp:audit tail --channel=access --name='access.session.*' --lines=20 ./console exp:audit verify # exit code 1 when a chain is broken ./console exp:audit import # what importing the 4.x text logs would do; --apply imports
The manage actions (rotate, archive, restore, purge, reindex, import, checkpoint and others) only say what they would do until --apply is given. Run ./console exp:audit --help for every action and filter.
Cronjob
The cronjob script audit.php is part of the frequent cronjob part: it delivers the spools of the sinks (syslog, webhook, mail), evaluates the alert rules and, once a day, rotates, verifies and archives the files. Run php runcronjobs.php frequent every few minutes (see Cronjobs), or the part on its own with php runcronjobs.php audit.
Limits
- Node views, searches and downloads are only recorded when the read channel is switched on.
- The searchable index is three database tables. On an installation upgraded from an older release, create them with the script createaudittables.php in update/common/scripts/6.0/, run with php from the installation root.
- With OnWriteFailure=continue (the default) a full disk does not stop the site; the failure is logged as AUDIT-UNWRITTEN in error.log and shown on the dashboard.
More
- The audit trail: the short reference of 6.0.15.
- The audit guide: event catalogue, record format and every setting.
- exp:audit and the policies of the audit module.
- Security and audit.
Contributors
- Julia Shymova
- Geir Arne Waaler
- Manuele Arenghi Commenter
- Graham Brookins Updated Maintainer
Comments (1 historical)
Written by readers of the earlier documentation sites, kept as they were.
new audit function
Manuele Arenghi ·
New audit function - You say:
<<
In the PHP code which defines the operation that should be logged, you can do something like this:
[..............]
>>
I would like to have audit's logs concerning the view operations done by users .
Which is the php page I should modify and where is it?
Can you write an example audit function to reach this pourpose ?
Thanks