Mercurial > prosody-modules

annotate mod_audit/README.md @ 5516:f25df3af02c1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_client_management: Include client software version number in listing Should you ever wish to revoke a client by version number, e.g. for security reasons affecting certain versions, then it would be good to at the very least see which version is used. Also includes the OAuth2 software ID, an optional unique identifier that should be the same for all installations of a particular software.
author Kim Alvefur <zash@zash.se>
date Sat, 03 Jun 2023 19:21:39 +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 ```