Mercurial > prosody-modules

annotate mod_audit/README.md @ 5473:e4382f6e3564

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: Tweak formatting of log message No need to `or ""` anymore since Prosody rev e88db5668cfb (0.11.0) and the %q format should produce either (nil) or "http://example"
author Kim Alvefur <zash@zash.se>
date Thu, 18 May 2023 13:27:27 +0200
parents dc058fcc3fe3
children 561503e0c0f1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4933
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
1 ---
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
2 summary: Audit Logging
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
3 rockspec: {}
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
4 ...
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
5
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
6 This module provides infrastructure for audit logging inside Prosody.
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
7
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
8 ## What is audit logging?
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
9
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
10 Audit logs will contain security sensitive events, both for server-wide
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
11 incidents as well as user-specific.
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
12
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
13 This module, however, only provides the infrastructure for audit logging. It
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
14 does not, by itself, generate such logs. For that, other modules, such as
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
15 `mod_audit_auth` or `mod_audit_register` need to be loaded.
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
16
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
17 ## A note on privacy
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
18
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
19 Audit logging is intended to ensure the security of a system. As such, its
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
20 contents are often at the same time highly sensitive (containing user names
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
21 and IP addresses, for instance) and allowed to be stored under common privacy
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
22 regulations.
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
23
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
24 Before using these modules, you may want to ensure that you are legally
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
25 allowed to store the data for the amount of time these modules will store it.
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
26 Note that it is currently not possible to store different event types with
530d116b7f68 mod_audit*: modules for audit logging in prosody
Jonas Schäfer <jonas@wielicki.name>
parents:
diff changeset
27 different expiration times.
5326
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
28
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
29 ## Viewing the log
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
30
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
31 You can view the log using prosodyctl. This works even when Prosody is not
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
32 running.
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
33
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
34 For example, to view the full audit log for example.com:
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
35
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
36 ```shell
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
37 prosodyctl mod_audit example.com
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
38 ```
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
39
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
40 To view only host-wide events (those not attached to a specific user account),
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
41 use the `--global` option (or use `--no-global` to hide such events):
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
42
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
43 ```shell
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
44 prosodyctl mod_audit --global example.com
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
45 ```
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
46
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
47 To narrow results to a specific user, specify their JID:
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
48
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
49 ```shell
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
50 prosodyctl mod_audit user@example.com
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4933
diff changeset
51 ```