Add security event logging documentation (#1135)

* Add security event logging documentation

Signed-off-by: Marcelo Henrique Neppel <marcelo.neppel@canonical.com>

* Ignore terraform URLs in link checker

---------

Signed-off-by: Marcelo Henrique Neppel <marcelo.neppel@canonical.com>
Co-authored-by: Andreia <andreia.velasco@canonical.com>

Author: marceloneppel

docs/.custom_wordlist.txt

@@ -31,6 +31,7 @@ CSR
 CSRs
 databag
 databags
+DDL
 dev
 dvipng
 eks
@@ -81,6 +82,7 @@ otf
 Parca
 Patroni
 Patroni*
+pgAudit
 pgbackrest
 pgBackRest
 pgbouncer

docs/conf.py

@@ -208,7 +208,9 @@
 linkcheck_ignore = [
     "http://127.0.0.1:8000",
     "https://github.com/canonical/*",
-    "https://matrix.to/*"
+    "https://matrix.to/*",
+    "https://developer.hashicorp.com/*",
+    "https://www.terraform.io/*"
     ]
 
 # A regex list of URLs where anchors are ignored by 'make linkcheck'

docs/explanation/legacy-charm.md

@@ -2,8 +2,8 @@
 
 There are [two types of charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#by-generation) stored under the same charm name `postgresql-k8s`:
 
-1. [Reactive](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive)  charm in the channel `latest/stable` (called `legacy`)
-2. [Ops-based](https://documentation.ubuntu.com/juju/3.6/reference/charm/#ops) charm in the channel `14/stable` (called `modern`)
+1. [Reactive](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm)  charm in the channel `latest/stable` (called `legacy`)
+2. [Ops-based](https://documentation.ubuntu.com/juju/3.6/reference/charm/#ops-charm) charm in the channel `14/stable` (called `modern`)
 
 The legacy charm provided endpoints `db` and `db-admin` (for the interface `pgsql`). The modern charm provides old endpoints as well + new endpoint `database` (for the interface `postgresql_client`). Read more details about the available [endpoints/interfaces](/explanation/interfaces-and-endpoints).
 

docs/explanation/security/index.md

@@ -23,7 +23,7 @@ Charmed PostgreSQL K8s can be deployed on top of several Kubernetes distribution
 
 ### Juju
 
-Juju is the component responsible for orchestrating the entire lifecycle, from deployment to Day 2 operations. For more information on Juju security hardening, see the [Juju security page](https://canonical-juju.readthedocs-hosted.com/en/latest/user/explanation/juju-security/) and the [How to harden your deployment](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-deployment/#harden-your-deployment) guide.
+Juju is the component responsible for orchestrating the entire lifecycle, from deployment to Day 2 operations. For more information on Juju security hardening, see the [Juju security page](https://canonical-juju.readthedocs-hosted.com/en/latest/user/explanation/juju-security/) and the [How to harden your deployment](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-juju-deployment/harden-your-juju-deployment/#harden-your-deployment) guide.
 
 #### Cloud credentials
 
@@ -91,6 +91,21 @@ Charmed PostgreSQL K8s provides native integration with the [Canonical Observabi
 
 PostgreSQL logs are stored in `/var/log/postgresql` within the postgresql container of each unit. It’s recommended to integrate the charm with [COS](https://canonical.com/data/docs/postgresql/k8s/h-enable-monitoring), from where the logs can be easily persisted and queried using [Loki](https://charmhub.io/loki-k8s)/[Grafana](https://charmhub.io/grafana).
 
+### Security event logging
+
+Charmed PostgreSQL K8s provides [PostgreSQL Audit Extension (or pgAudit)](https://www.pgaudit.org/) enabled by default. These logs are stored in the `/var/log/postgresql/` directory of each unit along with the regular workload logs, and rotated minutely. If COS is enabled, audit logs are also persisted there.
+
+The following information is configured to be logged:
+
+* Statements related to roles and privileges, such as GRANT, REVOKE, CREATE, ALTER, and DROP ROLE.
+* Data Definition Language (DDL) statements.
+* Miscellaneous commands like DISCARD, FETCH, CHECKPOINT, VACUUM, SET.
+* Miscellaneous SET commands.
+
+Other events, like connections and disconnections, are logged depending on the value of the charm configuration options related to them. For more information, check the configuration options with the `logging` prefix in the [configuration reference](https://charmhub.io/postgresql-k8s/configurations#logging_log_connections).
+
+No secrets are logged.
+
 ## Additional Resources
 
 For details on the cryptography used by Charmed PostgreSQL K8s, see the [Cryptography](/explanation/security/cryptography) explanation page.