enterprise_ai.audit
Source : sdks/python/src/enterprise_ai/audit/__init__.py. Retour à l'index de la référence du SDK Python.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Classe AuditClient
/v1/audit.
Resource
AuditClient.correlations
correlations(trace_id: str | None = None, run_id: str | None = None) -> Any
Corréler les événements par trace, exécution ou session. Avec trace_id, run_id ou session_id (le premier donné l'emporte), renvoie tout ce qui partage cette clé : audit_events, usage_events des LLM, runs, spans de télémétrie, multimodal_jobs (jusqu'à 1000 de chaque, 200 pour les exécutions et les tâches), les trace_ids rencontrés et counts.
Route : /v1/audit/correlations (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
trace_id | str | None | None | non | Identifiant de trace W3C (32 caractères hexadécimaux) à corréler. |
run_id | str | None | None | non | Identifiant d'exécution d'agent à corréler. |
Retour : Any. Réponse JSON décodée de l'opération « Corréler les événements par trace, exécution ou session ».
Erreurs levées : les erreurs typées du transport (Erreurs).
AuditClient.events
events(actor: str | None = None, action: str | None = None, resource: str | None = None, since: str | None = None, until: str | None = None, **page: Any) -> Any
Rechercher les événements d'audit. Recherche les événements d'audit du tenant, les plus récents d'abord (séquence la plus haute d'abord), paginés. Tous les filtres se combinent. Exige auditor, security_officer ou tenant_admin. La recherche elle-même est inscrite dans le journal d'accès aux preuves (qui, quelle requête, combien de résultats).
Route : /v1/audit/events (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
actor | str | None | None | non | Uniquement les événements de cet identifiant d'acteur, par exemple un sujet d'utilisateur ou apikey:<id>. |
action | str | None | None | non | Uniquement cette action, par exemple api_key.create. Un * final cherche un préfixe : approval.*. |
resource | str | None | None | non | Uniquement cette ressource : <type> ou <type>:<id>, par exemple project:42. |
since | str | None | None | non | Seulement les événements à partir de cette date, au format ISO 8601 (envoyé comme from). |
until | str | None | None | non | Fin de la période (ISO 8601), envoyée comme filtre to. |
**page | Any | non | Options de pagination transmises à la liste : limit (nombre maximal d'éléments par page) et cursor (le next_cursor de la page précédente). Itérer sur la page renvoyée suit tous les curseurs. |
Retour : Any. Réponse JSON décodée de l'opération « Rechercher les événements d'audit ».
Erreurs levées : les erreurs typées du transport (Erreurs).
AuditClient.export
export(since: str | None = None, until: str | None = None, retention_days: int | None = None) -> Any
Exporter le journal d'audit. Écrit les événements de la période (bornes incluses) dans un stockage à écriture unique, en NDJSON ou en CSV, avec un manifeste. Exige auditor, security_officer ou tenant_admin.
Route : /v1/audit/export (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
since | str | None | None | non | Début de la période exportée, au format ISO 8601 (envoyé comme from). |
until | str | None | None | non | Fin de la période exportée (ISO 8601), envoyée comme to. |
retention_days | int | None | None | non | Durée de conservation de l'export WORM, en jours. |
Retour : Any. Réponse JSON décodée de l'opération « Exporter le journal d'audit ».
Erreurs levées : les erreurs typées du transport (Erreurs).
AuditClient.get
get(event_id: str) -> Any
Lire un événement d'audit. Renvoie un événement d'audit avec sa séquence, ses empreintes, son acteur, sa ressource, sa décision et ses preuves. Exige auditor, security_officer ou tenant_admin. La lecture est inscrite dans le journal d'accès aux preuves. Répond 404 not_found.
Route : /v1/audit/events/{event_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
event_id | str | oui | Identifiant (UUID) de l'événement d'audit. |
Retour : Any. Réponse JSON décodée de l'opération « Lire un événement d'audit ».
Erreurs levées : les erreurs typées du transport (Erreurs).
AuditClient.query
query(**filters: Any) -> Any
Rechercher les événements d'audit. Recherche les événements d'audit du tenant, les plus récents d'abord (séquence la plus haute d'abord), paginés. Tous les filtres se combinent. Exige auditor, security_officer ou tenant_admin. La recherche elle-même est inscrite dans le journal d'accès aux preuves (qui, quelle requête, combien de résultats).
Route : /v1/audit/events (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
**filters | Any | non | Filtres et options de pagination de events : actor, action, resource, since, until, limit, cursor. |
Retour : Any. Réponse JSON décodée de l'opération « Rechercher les événements d'audit ».
Erreurs levées : les erreurs typées du transport (Erreurs).
AuditClient.record
record(action: str, resource_type: str, resource_id: str, outcome: str | None = None, details: dict[str, Any] | None = None, resource_name: str | None = None, classification: str | None = None, trace_id: str | None = None, event_time: str | None = None) -> Any
Enregistrer un événement d'audit applicatif. Ajoute un événement applicatif à la chaîne de hachage du tenant. L'acteur vient de l'authentification ; la séquence, les empreintes et occurred_at viennent du serveur ; les details du client sont conservés sous evidence.details.attributes, à côté de stream: sdk. L'événement est scellé et exporté vers la boîte d'envoi et le SIEM comme les événements de la plateforme.
Route : /v1/audit/events (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
action | str | oui | Nom de l'action dans l'espace de noms app., en minuscules, 128 caractères au plus, par exemple app.invoice.approved. | |
resource_type | str | oui | Type de la ressource concernée par l'événement (resource.type), par exemple invoice. | |
resource_id | str | oui | Identifiant de la ressource concernée par l'événement (resource.id). | |
outcome | str | None | None | non | success (par défaut), failure ou error. |
details | dict[str, Any] | None | None | non | Attributs libres de l'événement, 16384 octets au plus une fois sérialisés. |
resource_name | str | None | None | non | Nom lisible de la ressource (resource.name), facultatif. |
classification | str | None | None | non | Classification des données de l'événement : public, internal, confidential, restricted ou secret. |
trace_id | str | None | None | non | Identifiant de trace W3C, 32 caractères hexadécimaux en minuscules, pour relier l'événement à une trace. |
event_time | str | None | None | non | Moment de l'action selon l'horloge du client (ISO 8601), au plus le décalage d'horloge autorisé en avance sur le serveur. Par défaut : l'heure du serveur. |
Retour : Any. Réponse JSON décodée de l'opération « Enregistrer un événement d'audit applicatif ».
Erreurs levées : les erreurs typées du transport (Erreurs).
AuditClient.verify
verify(**params: Any) -> Any
Vérifier la chaîne d'audit. Recalcule la chaîne de hachage du tenant depuis le premier événement et renvoie tenant_id, valid, count, last_hash, broken_at, reason et verified_at. Quand la chaîne est rompue, broken_at est la séquence du premier événement fautif et reason en donne la cause : sequence gap, prev_hash mismatch ou hash mismatch. Exige auditor, security_officer ou tenant_admin. La vérification est inscrite dans le journal d'accès aux preuves.
Route : /v1/audit/verify (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
**params | Any | non | Champs supplémentaires fusionnés dans la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Vérifier la chaîne d'audit ».
Erreurs levées : les erreurs typées du transport (Erreurs).
AuditClient.verify_evidence
verify_evidence() -> Any
Vérifier la chaîne et tous les sceaux. Vérifie toute la chaîne du tenant et tous ses sceaux et renvoie tenant_id, valid, chain (résultat de la chaîne de hachage), seals (nombre et échecs), clock (échecs d'horodatage) et events (nombre vérifié). Exige auditor, security_officer ou tenant_admin. La vérification est inscrite dans le journal d'accès.
Route : /v1/evidence/verify (GET).
Cet élément ne prend aucun paramètre.
Retour : Any. Réponse JSON décodée de l'opération « Vérifier la chaîne et tous les sceaux ».
Erreurs levées : les erreurs typées du transport (Erreurs).
Fonctions
confirm_recorded
confirm_recorded(answer: Any) -> Any
Renvoie un événement d'audit applicatif uniquement si le serveur indique son event_id et le hash de chaîne.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
answer | Any | oui | Réponse de POST /v1/audit/events à contrôler. |
Retour : Any. La même réponse, inchangée ; sinon audit_unconfirmed est levée.
Erreurs levées : EaiError.
canonical
canonical(event: dict[str, Any]) -> str
JSON canonique d'un événement sans son champ hash.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
event | dict[str, Any] | oui | Événement d'audit sous forme de dict ; sa clé hash est ignorée. |
Retour : str. Texte JSON aux clés triées et sans espaces, entrée du hachage de la chaîne.
chain_hash
chain_hash(prev_hash: str, event: dict[str, Any]) -> str
Empreinte d'un événement dans la chaîne d'audit : sha256(prev_hash + canonical(event)) en hexadécimal.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
prev_hash | str | oui | Empreinte de l'événement précédent de la chaîne (chaîne vide pour le premier). | |
event | dict[str, Any] | oui | Événement d'audit à hacher ; sa clé hash est ignorée. |
Retour : str. Condensat SHA-256 en hexadécimal.
verify_chain
verify_chain(events: list[dict[str, Any]], prev_key: str = 'prev_hash') -> dict[str, Any]
Renvoie {valid, checked, broken_at} pour une chaîne exportée localement.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
events | list[dict[str, Any]] | oui | Événements d'audit exportés, dans l'ordre de la chaîne. | |
prev_key | str | 'prev_hash' | non | Clé de chaque événement qui contient l'empreinte précédente (prev_hash par défaut). |
Retour : dict[str, Any]. valid (booléen), checked (nombre d'événements contrôlés avant la rupture) et broken_at (event_id ou index du premier événement rompu, None si la chaîne est valide).