prosody-modules
a1f8cc591b66
mod_audit/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_audit/README.md @ 5563:a1f8cc591b66

Back out 22784f001b7f: Documentation change did not match code (thanks bronko)
author Kim Alvefur <zash@zash.se>
date Thu, 22 Jun 2023 22:00:51 +0200
parent 5326:dc058fcc3fe3
child 5769:561503e0c0f1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4932
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: 4932
diff changeset
28
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
diff changeset
29 ## Viewing the log
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
diff changeset
30
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
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: 4932
diff changeset
32 running.
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
diff changeset
33
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
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: 4932
diff changeset
35
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
diff changeset
36 ```shell
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
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: 4932
diff changeset
38 ```
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
diff changeset
39
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
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: 4932
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: 4932
diff changeset
42
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
diff changeset
43 ```shell
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
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: 4932
diff changeset
45 ```
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
diff changeset
46
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
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: 4932
diff changeset
48
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
diff changeset
49 ```shell
dc058fcc3fe3 mod_audit: Improve filtering options and add documentation to README
Matthew Wild <mwild1@gmail.com>
parents: 4932
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: 4932
diff changeset
51 ```