API Log di Audit

Auris registra automaticamente ogni azione amministrativa, evento di autenticazione e operazione rilevante per la sicurezza in una traccia di audit immutabile. L’API Log di Audit fornisce accesso in lettura a questi log e la gestione delle configurazioni di log streaming che inoltrano gli eventi verso piattaforme di osservabilità esterne.

I log di audit vengono conservati in base alla policy di conservazione del tuo piano. Tutte le voci di log sono immutabili — non possono essere modificate o eliminate tramite API.

Tutti gli endpoint richiedono l’header x-tenant e un Bearer token valido.

Interrogazione dei Log

GET/api/audit-logsRequires: view:audit_logs

Elenca le voci del log di audit con filtraggio e paginazione. I risultati vengono restituiti in ordine cronologico inverso (più recenti prima). Supporta il filtraggio per azione, utente, tipo di risorsa, livello di gravità, intervallo di date e ricerca full-text.

Parametri di query

Parametro	Tipo	Descrizione
`page`	integer	Numero di pagina (default: 1)
`limit`	integer	Elementi per pagina (default: 20, max: 100)
`action`	string	Filtra per nome azione (es. `user.login`, `role.update`, `sso.connection.create`)
`userId`	string	Filtra per l’ID utente che ha eseguito l’azione
`resourceType`	string	Filtra per tipo di risorsa (es. `user`, `role`, `application`, `organization`, `sso_connection`)
`level`	`info` \| `warn` \| `error`	Filtra per livello di gravità
`dateFrom`	ISO 8601	Inizio dell’intervallo di date (incluso)
`dateTo`	ISO 8601	Fine dell’intervallo di date (incluso)
`search`	string	Ricerca full-text per azione, tipo di risorsa e dettagli

Risposta di successo


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "log_abc123",
        "action": "user.login",
        "userId": "usr_def456",
        "resourceType": "session",
        "resourceId": "sess_ghi789",
        "details": {
          "method": "password",
          "success": false,
          "reason": "invalid_credentials"
        },
        "level": "error",
        "ipAddress": "203.0.113.42",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "createdAt": "2025-02-18T14:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1284,
      "totalPages": 26
    }
  }
}

Struttura della Voce di Log

Ogni voce del log di audit ha la seguente struttura:

Campo	Tipo	Descrizione
`id`	string	Identificatore univoco della voce di log
`action`	string	L’azione eseguita (notazione puntata, es. `user.create`, `role.permission.update`)
`userId`	string \| null	L’utente che ha eseguito l’azione. Null per eventi generati dal sistema (cron job, webhook).
`resourceType`	string	Il tipo di risorsa interessata (es. `user`, `role`, `application`, `organization`, `session`, `sso_connection`, `log_stream`)
`resourceId`	string \| null	L’ID della risorsa specifica interessata
`details`	object	Dati specifici dell’azione. Per le mutazioni, include tipicamente snapshot `before` e `after`.
`level`	`info` \| `warn` \| `error`	Livello di gravità dell’evento
`ipAddress`	string \| null	Indirizzo IP del client che ha scatenato l’azione
`userAgent`	string \| null	Header User-Agent della richiesta
`createdAt`	ISO 8601	Timestamp di quando si è verificato l’evento

Tipi di Azione Comuni

Azione	Livello	Descrizione
`user.login`	info/error	Tentativo di login utente (successo o fallimento)
`user.login.2fa`	info	Autenticazione a due fattori completata
`user.signup`	info	Nuova registrazione utente
`user.create`	info	Admin ha creato un utente
`user.update`	info	Profilo utente aggiornato
`user.delete`	warn	Account utente eliminato
`user.disable`	warn	Account utente disabilitato
`user.password.change`	info	Password cambiata
`user.password.reset`	info	Reset password avviato
`role.create`	info	Ruolo creato
`role.update`	info	Metadati del ruolo aggiornati
`role.delete`	warn	Ruolo eliminato
`role.permission.update`	info	Permessi del ruolo modificati
`role.assign`	info	Ruolo assegnato a un utente
`role.unassign`	info	Ruolo rimosso da un utente
`application.create`	info	Applicazione creata
`application.update`	info	Impostazioni applicazione aggiornate
`application.secret.rotate`	warn	Client secret dell’applicazione ruotato
`organization.create`	info	Organizzazione creata
`organization.member.add`	info	Membro aggiunto all’organizzazione
`organization.member.remove`	warn	Membro rimosso dall’organizzazione
`sso.connection.create`	info	Connessione SSO configurata
`sso.connection.activate`	info	Connessione SSO attivata
`sso.connection.deactivate`	warn	Connessione SSO disattivata
`session.revoke`	warn	Admin ha revocato una sessione utente
`token.exchange`	warn	Scambio token (impersonazione o delega)
`log_stream.create`	info	Log stream configurato
`security.brute_force.lockout`	error	Account bloccato per brute force
`security.suspicious_login`	warn	Login sospetto rilevato

Il campo details per gli eventi di mutazione (create, update, delete) include tipicamente snapshot before e after dove applicabile. Per i campi sensibili come password e secret, viene registrato solo il fatto che il campo è cambiato — non i valori effettivi.

Log Streaming

Il log streaming inoltra gli eventi di audit in tempo reale verso piattaforme di osservabilità e SIEM esterne. Quando un log stream è configurato e attivo, ogni evento di audit viene inviato alla destinazione configurata in aggiunta alla memorizzazione nel database Auris.

GET/api/log-streamsRequires: manage:log_streams

Elenca tutti i log stream configurati per il tenant. Restituisce i metadati dello stream, il tipo, lo stato e l’ora dell’ultima consegna.

Risposta di successo


{
  "ok": true,
  "data": [
    {
      "id": "ls_abc123",
      "name": "Datadog Produzione",
      "type": "DATADOG",
      "status": "active",
      "config": {
        "region": "us1",
        "apiKey": "dd_api_***...***"
      },
      "lastDeliveryAt": "2025-02-18T14:29:55Z",
      "createdAt": "2025-01-10T09:00:00Z"
    }
  ]
}

POST/api/log-streamsRequires: manage:log_streams

Crea un nuovo log stream. Ogni tipo di stream richiede una forma di configurazione diversa. Auris valida la configurazione ed esegue opzionalmente una consegna di test prima del salvataggio.

Tipo di Stream: WEBHOOK

Invia ogni evento di audit come HTTP POST all’URL specificato. Supporta header personalizzati per l’autenticazione.

Corpo della richiesta


{
  "name": "Webhook SIEM",
  "type": "WEBHOOK",
  "config": {
    "url": "https://siem.internal.acme.it/auris-logs",
    "headers": {
      "Authorization": "Bearer tuo-siem-token",
      "X-Source": "auris"
    }
  }
}

Tipo di Stream: S3

Raggruppa gli eventi di audit e li carica come file JSON in un bucket S3-compatibile.

Corpo della richiesta


{
  "name": "Archivio S3",
  "type": "S3",
  "config": {
    "bucket": "auris-audit-logs",
    "region": "eu-west-1",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "prefix": "auris/nome-tenant/"
  }
}

I file vengono caricati con chiavi nel formato: {prefix}YYYY/MM/DD/HH-mm-ss-{uuid}.json.

Tipo di Stream: DATADOG

Invia gli eventi di audit all’API di Log Management di Datadog.

Corpo della richiesta


{
  "name": "Log Datadog",
  "type": "DATADOG",
  "config": {
    "apiKey": "dd_api_key_qui",
    "region": "eu1",
    "service": "auris-iam",
    "source": "auris"
  }
}

Tipo di Stream: SPLUNK

Invia gli eventi di audit a Splunk tramite HTTP Event Collector (HEC).

Corpo della richiesta


{
  "name": "Splunk HEC",
  "type": "SPLUNK",
  "config": {
    "hecUrl": "https://splunk.internal.acme.it:8088/services/collector/event",
    "hecToken": "tuo-hec-token",
    "index": "auris_audit",
    "source": "auris-iam",
    "sourcetype": "_json"
  }
}

Risposta di successo (tutti i tipi)


{
  "ok": true,
  "data": {
    "id": "ls_ghi789",
    "name": "Log Datadog",
    "type": "DATADOG",
    "status": "active",
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

I campi sensibili nella configurazione (chiavi API, secret, token) vengono mascherati nelle risposte GET. I valori completi vengono utilizzati solo internamente per la consegna e non vengono mai esposti tramite API dopo la creazione.

PATCH/api/log-streams/[id]Requires: manage:log_streams

Aggiorna il nome, la configurazione o lo stato di un log stream. Usalo per ruotare le chiavi API, cambiare endpoint o mettere in pausa/riprendere lo streaming.

Corpo della richiesta — metti in pausa lo streaming


{
  "status": "paused"
}

Stati degli stream:

Stato	Descrizione
`active`	Trasmette eventi alla destinazione
`paused`	Stream in pausa — gli eventi non vengono consegnati ma sono ancora registrati in Auris
`error`	La consegna ha fallito ripetutamente — stream auto-messo in pausa fino a correzione della configurazione

DELETE/api/log-streams/[id]Requires: manage:log_streams

Elimina un log stream. La consegna si ferma immediatamente. I log di audit storici non vengono influenzati — rimangono nel database Auris indipendentemente dalla configurazione dello streaming.

Riferimento Permessi

Permesso	Descrizione
`view:audit_logs`	Interroga e legge le voci del log di audit
`manage:log_streams`	Crea, aggiorna, elimina e configura le destinazioni di log streaming

I log di audit sono append-only e immutabili. Non esiste un endpoint API per eliminare o modificare le voci di log. Questo garantisce l’integrità della traccia di audit per scopi di conformità (SOC 2, ISO 27001, GDPR Articolo 30).

Pagine Correlate

Log Streaming — Trasmetti i log di audit a servizi esterni come Datadog e Splunk
Log e Conformità — Visualizza e filtra i log dalla Console