Mécanisme de Journal d’Audit

Qu’est-ce qu’un journal d’audit ?

Un journal d’audit (également appelé piste d’audit) est un enregistrement chronologique pertinent pour la sécurité, un ensemble d’enregistrements, et/ou la destination et la source des enregistrements qui fournissent une preuve documentaire de la séquence des activités ayant affecté à tout moment une opération, une procédure ou un événement spécifique.

Dans NuxSaaS, les journaux d’audit sont essentiels pour suivre les activités des utilisateurs, les événements système et les incidents de sécurité potentiels. Ils aident à maintenir la responsabilité, à faciliter le débogage et à garantir la conformité.

Schéma du journal d’audit

Les entrées du journal d’audit sont stockées dans la table audit_log avec la structure suivante (définie dans server/database/schema/auditLog.ts) :

• id : SERIAL - Un identifiant unique pour l’entrée du journal d’audit (clé primaire).
• userId : UUID - L’ID de l’utilisateur ayant effectué l’action. Cela fait référence à user.id. Peut être null si l’action a été effectuée par le système ou une entité non authentifiée.
• category : TEXT - La catégorie de l’événement. Exemples : auth, email, payment.
• action : TEXT - L’action spécifique effectuée. Exemples : login, register, verification, reset_password, trial_start, subscription_created.
• targetType : TEXT - Le type d’entité sur laquelle l’action a été effectuée. Exemples : user, email, stripeCustomerId.
• targetId : TEXT - L’identifiant de l’entité cible.
• ipAddress : TEXT - L’adresse IP d’où provient l’action.
• userAgent : TEXT - La chaîne user agent du client ayant initié l’action.
• status : TEXT - Le statut de l’action. Exemples : success, failure, pending. Par défaut : success.
• details : TEXT - Détails supplémentaires ou messages d’erreur liés à l’événement.
• createdAt : TIMESTAMP - L’horodatage indiquant quand l’événement s’est produit. Par défaut à l’heure actuelle.

Comment les événements d’audit sont enregistrés

Les événements d’audit sont enregistrés à l’aide de la fonction logAuditEvent située dans server/utils/auditLogger.ts. Cette fonction centralisée est appelée depuis différentes parties de l’application pour enregistrer les événements importants.

export async function logAuditEvent(data: {
  userId?: string;
  category: 'auth' | 'email' | 'payment';
  action: string;
  targetType?: string;
  targetId?: string;
  ipAddress?: string;
  userAgent?: string;
  status?: 'success' | 'failure' | 'pending';
  details?: string;
}) {
  // ... implémentation pour insérer dans la table audit_log ...
}

Cette fonction prend un objet avec les détails de l’événement et le sauvegarde dans la base de données.

Exemples d’événements enregistrés

NuxSaaS enregistre divers événements dans différents modules :

1. Événements d’authentification

Les activités liées à l’authentification sont enregistrées via des hooks dans le système better-auth, tel que configuré dans server/utils/auth.ts.

• Événements enregistrés :
  • Tentatives de connexion utilisateur (ex : /sign-in/email)
  • Inscription utilisateur (ex : /sign-up/email)
  • Demandes de réinitialisation de mot de passe (ex : /forget-password)
  • Finalisation de la réinitialisation de mot de passe (ex : /reset-password)
• Informations capturées :
  • userId (si disponible, par exemple après une connexion réussie ou pour des actions de session existante)
  • category : auth
  • action : Le chemin API de l’opération d’authentification (ex : /sign-in/email).
  • targetType : email (pour les actions email/mot de passe) ou user.
  • targetId : L’email ou l’ID utilisateur.
  • ipAddress : Capturée depuis les en-têtes de la requête.
  • userAgent : Capturée depuis les en-têtes de la requête.
  • status : success ou failure.
  • details : Messages d’erreur en cas d’échec (ex : depuis APIError).

2. Événements d’envoi d’e-mails

Les événements liés à l’envoi d’e-mails (ex : vérification, réinitialisation de mot de passe) sont enregistrés juste après la tentative d’envoi.

• Événements enregistrés (depuis server/utils/auth.ts) :
  • Envoi d’e-mails de réinitialisation de mot de passe (sendResetPassword).
  • Envoi d’e-mails de vérification (sendVerificationEmail).
• Informations capturées :
  • userId : L’ID de l’utilisateur destinataire.
  • category : email
  • action : reset_password ou verification.
  • targetType : email.
  • targetId : L’adresse e-mail de l’utilisateur.
  • status : success ou failure (selon la réponse du service d’envoi d’e-mails).
  • details : Messages d’erreur si l’envoi a échoué.

3. Événements de paiement (intégration Stripe)

Les événements liés aux paiements et au cycle de vie des abonnements sont enregistrés via les callbacks de l’intégration Stripe, définis dans server/utils/stripe.ts.

• Événements enregistrés :
  • Début d’essai gratuit (trial_start)
  • Fin d’essai gratuit (trial_end)
  • Expiration d’essai sans conversion (trial_expired)
  • Création d’abonnement (subscription_created)
  • Mise à jour d’abonnement (subscription_updated)
  • Annulation d’abonnement (subscription_canceled)
  • Suppression d’abonnement (subscription_deleted)
• Informations capturées (par la fonction utilitaire addPaymentLog) :
  • userId : L’ID de l’utilisateur associé à l’ID client Stripe.
  • category : payment
  • action : Une chaîne composite comme trial_start:pro-monthly, indiquant l’événement et le plan.
  • targetType : stripeCustomerId.
  • targetId : L’ID client Stripe.
  • status : Généralement success pour ces événements déclenchés par webhook.

Accès et utilisation des journaux d’audit

Les journaux d’audit peuvent être consultés en interrogeant la table audit_log dans la base de données. Les administrateurs peuvent utiliser ces données pour :

• Surveillance de la sécurité : Détecter des activités suspectes, des tentatives d’accès non autorisées ou des violations potentielles de sécurité.
• Dépannage : Diagnostiquer des problèmes en examinant la séquence des événements précédant un incident.
• Conformité : Fournir des preuves des activités du système pour des exigences réglementaires ou internes.
• Support utilisateur : Comprendre les actions des utilisateurs pour mieux les assister.

En général, une interface dédiée dans le panneau d’administration permet de visualiser, filtrer et rechercher dans les journaux d’audit, les rendant facilement accessibles à des fins administratives.