Aller au contenu

Guides

Connecter PostgreSQL (pgaudit)

Guide approfondi par connecteur pour l'observation de l'accès aux bases de données PostgreSQL via pgAudit — configuration du format de log.

Dernière mise à jour:

Le connecteur pgAudit suit le journal d’audit structuré de PostgreSQL et émet une arête de carte d’accès par accès aux données audité. Le mode lecture/écriture est pris tel quel depuis la classe pgAudit (READ, WRITE, DDL) — jamais déduit du texte SQL. Le connecteur est en lecture seule sur le fichier de log et n’ouvre jamais de connexion à la base de données.

Pour le modèle de source général et la structure de configuration, commencez par Connecter une source. Cette page couvre les prérequis côté PostgreSQL, la surface de configuration complète, les mécaniques d’attribution, et les considérations opérationnelles pour les environnements de production.

Prérequis PostgreSQL

Le connecteur lit la sortie pgAudit, PostgreSQL doit donc être configuré pour la produire. Installez l’extension (apt install postgresql-<version>-pgaudit sur Debian/Ubuntu), chargez-la via shared_preload_libraries, redémarrez, puis CREATE EXTENSION pgaudit dans chaque base de données que vous voulez observer.

Les paramètres minimum postgresql.conf pour une sortie utile :

shared_preload_libraries = 'pgaudit'
pgaudit.log = 'read, write'       # READ et WRITE couvrent l'accès aux données
log_destination = 'jsonlog'        # recommandé pour le streaming ; csvlog fonctionne aussi
logging_collector = on
log_directory = '/var/log/postgresql'
log_filename = 'postgresql.json'

Redémarrez après shared_preload_libraries ; rechargez (SELECT pg_reload_conf()) après le reste. Vérifiez en exécutant une requête et en confirmant qu’une entrée pgAudit apparaît dans le log — le champ message de l’entrée contient la ligne structurée pgAudit (class, command, object name). Si seuls des messages PostgreSQL standard apparaissent, l’extension n’est pas chargée ou pas configurée.

Configuration

Le connecteur est sélectionné par kind: "pgaudit" dans le fichier JSON OLIVARES_SOURCES_CONFIG. Un exemple complet :

{
  "sources": [
    {
      "name": "prod-postgres",
      "kind": "pgaudit",
      "tenant": "acme",
      "config": {
        "log_path": "/var/log/postgresql/postgresql.json",
        "format": "jsonlog",
        "follow": "true",
        "shared_accounts": "app_pool,reporting"
      }
    }
  ]
}

Toutes les valeurs de config sont des chaînes. Les clés sont détenues par le connecteur pgAudit :

  • log_path (requis) — chemin absolu vers le fichier de log PostgreSQL. Le connecteur lit ce fichier ; il ne découvre pas les fichiers de log par convention.
  • format — csvlog ou jsonlog. Par défaut csvlog. Contrôle le parseur que le connecteur utilise ; il doit correspondre au log_destination que PostgreSQL écrit effectivement.
  • follow — quand "true", suit le fichier en continu (mode streaming). Cela s’applique uniquement à jsonlog. Un fichier csvlog est lu en batch car les enregistrements CSV peuvent s’étendre sur plusieurs lignes, rendant un suivi en streaming peu fiable. Voir Batch vs streaming ci-dessous.
  • shared_accounts — liste séparée par des virgules de rôles PostgreSQL ou valeurs application_name qui sont mutualisés ou partagés entre plusieurs appelants. L’accès attribué à l’un d’eux est marqué approximate délibérément. Voir Attribution et comptes partagés.

N’inventez pas de clés de configuration au-delà de ces quatre. La surface de configuration du connecteur est intentionnellement étroite — il lit un fichier de log, il ne gère pas PostgreSQL.

Attribution et comptes partagés

La carte d’accès doit répondre à « quel agent a fait cela ». Les entrées de log pgAudit portent le rôle PostgreSQL (utilisateur) et, quand défini, le application_name de la session. Le connecteur utilise les deux pour construire l’origine de l’arête.

L’identité par agent obtient une arête ferme. Quand chaque agent définit un application_name distinct sur sa connexion (ou utilise un rôle dédié), le connecteur attribue chaque accès sans ambiguïté et l’arête est firm.

Les rôles partagés se réduisent à approximate. Quand plusieurs agents partagent un pool de connexions, un compte de service commun, ou un application_name générique, le connecteur ne peut pas séparer les appelants. Chaque accès via cette identité est marqué approximate, et le produit le dit ouvertement plutôt que de prétendre pouvoir distinguer des agents qu’il ne peut pas. C’est pourquoi shared_accounts existe : déclarer les identités mutualisées en amont dit au connecteur de les marquer approximate immédiatement.

L’implication pour la gouvernance est directe : une arête approximate ne peut pas supporter une découverte de moindre privilège ferme. Si vous avez besoin d’une gouvernance par agent sur l’accès aux bases de données, émettez des identifiants par agent ou des valeurs application_name. Voir Fidélité pour le modèle d’attribution complet.

Niveau de couverture

pgAudit est une couverture clean. Les classes READ, WRITE et DDL font autorité — le sous-système d’audit de PostgreSQL classifie la déclaration, et le connecteur prend cette classification telle quelle. Il n’y a pas d’inférence, pas de parsing SQL, et pas d’heuristique.

Le mode d’une arête est R (lecture), RW (lecture-écriture, pour les classes WRITE et DDL), ou laissé tel que la classe le dicte. Le connecteur n’élève ni ne dégrade jamais ce que pgAudit a rapporté. Voir Fidélité — couverture pour comment clean se compare aux sources lossy et opaque.

Batch vs streaming

  • csvlog — batch. Les enregistrements CSV peuvent s’étendre sur plusieurs lignes (une requête avec des retours à la ligne embarqués produit une ligne multi-lignes), donc un suivi en streaming ne peut pas découper les enregistrements de manière fiable. Le connecteur lit le fichier comme un batch complet ; définissez poll_seconds sur l’entrée source pour le relancer sur un intervalle.
  • jsonlog avec follow: "true" — streaming. Chaque entrée JSON est une seule ligne, donc un suivi est sûr. Le connecteur garde le fichier ouvert et émet des arêtes au fur et à mesure que PostgreSQL les écrit.

Pour des arêtes en quasi-temps réel, jsonlog avec follow est la configuration recommandée. Pour des audits périodiques ou des bases de données à plus faible volume, le batch csvlog est suffisant.

À quoi ressemblent les arêtes

Chaque entrée de log pgAudit que le connecteur parse produit une arête de carte d’accès avec ces champs :

  • Origine — le rôle PostgreSQL, qualifié par application_name quand présent. Exemple : reporting_agent ou app_pool/invoice-service.
  • Ressource — l’objet pleinement qualifié : database.schema.table. Exemple : prod.public.orders.
  • Mode — R (depuis la classe pgAudit READ) ou RW (depuis la classe pgAudit WRITE ou DDL).
  • Attribution — firm si l’origine se résout à une seule identité d’agent, approximate si elle correspond à une entrée shared_accounts ou ne peut pas être désambiguïsée.
  • Source — identifie cette instance de connecteur par nom.

L’arête ne porte pas de texte SQL, pas de données de ligne, et pas de paramètres de requête. Elle enregistre uniquement le fait structurel qu’une identité a accédé à un objet dans un mode donné.

Notes opérationnelles

Rotation des logs. Quand PostgreSQL fait la rotation de son fichier de log (via log_rotation_age ou log_rotation_size), le connecteur doit être pointé vers le fichier actuel. Si votre rotation renomme le fichier actif, le suivi follow continuera de lire l’ancien descripteur de fichier jusqu’à épuisement puis s’arrêtera. Pointez log_path vers un lien symbolique stable ou utilisez une convention de nommage que le connecteur peut suivre. Le connecteur ne gère pas la rotation lui-même.

Environnements à fort volume. pgAudit peut produire un volume de log substantiel sur des bases de données occupées, surtout avec pgaudit.log = 'all'. Scopez pgaudit.log aux classes dont vous avez besoin (typiquement read, write) et envisagez un filtrage par base de données ou par rôle via pgaudit.log_relation pour réduire le bruit sans perdre de couverture.

Instances PostgreSQL multiples. Chaque instance a besoin de sa propre entrée source dans OLIVARES_SOURCES_CONFIG avec un name distinct et son propre log_path. Il n’y a pas de découverte multi-instances — chaque source surveille exactement un fichier de log.

Permissions. Le processus collecteur a besoin d’un accès en lecture au fichier de log PostgreSQL. Il n’a pas besoin de connexion à la base de données, de rôle PostgreSQL, ou d’accès réseau au serveur de base de données. La permission de lecture sur le système de fichiers est la seule exigence.

Voir aussi

Rechercher la documentation