Aller au contenu

Guides

Connecter une source

Câbler une source d'observation réelle dans Olivares AI, comprendre le modèle de connecteur lecture d'abord.

Dernière mise à jour:

Une source observe un système externe et émet des observations normalisées — elle ne se place jamais dans le chemin de données, ne proxifie pas le trafic, et ne lit pas les charges utiles. Cette page couvre le modèle de connecteur et comment câbler une source réelle via OLIVARES_SOURCES_CONFIG. Si vous voulez seulement connecter un agent de codage, commencez par Connecter Claude Code ; c’est une source sur le chemin coopératif, et ceci est le modèle sous-jacent.

Ce que fait une source

Une source observe un système et rapporte ce qu’elle a vu sous forme d’observations typées. La carte d’accès lecture/écriture est construite à partir de ce que la source rapporte, pas de l’interception de ce qui circule. Le moteur gère l’ordonnancement : une source en streaming (un tail de log) bloque jusqu’à annulation ; une source batch fait son travail et retourne, et le moteur décide quand la relancer.

Une observation ne porte que des identifiants et une classification lecture/écriture — jamais de corps SQL, de charges utiles de requête, de secrets, ou de données personnelles. C’est une propriété du vocabulaire filaire que le connecteur parle, pas un paramètre que vous pouvez basculer. Voir Permis vs observé pour comment ces observations atterrissent sur la carte.

Chaque arête enregistre quelle source l’a produite et un niveau de confiance, et le produit affiche les deux. L’attribution est firm quand l’accès est lié à une identité par agent et approximate quand il est déduit ou imprécis (un compte de service partagé, une connexion mutualisée). Le mode d’accès est l’un de unknown, read, write, ou readwrite — unknown est explicite et jamais deviné. Voir Fidélité.

Où elle fonctionne

Les collecteurs qui exécutent ces sources fonctionnent toujours sur votre infrastructure. Le plan de contrôle qui les ingère peut être un binaire unique auto-hébergé, un déploiement distribué, ou air-gappé — les données de l’environnement observé ne quittent jamais votre frontière. Voir Auto-hébergement et l’aperçu de l’architecture.

Le fichier de configuration

Les sources réelles (hors démonstration) sont câblées depuis un fichier de configuration opérateur unique nommé par la variable d’environnement OLIVARES_SOURCES_CONFIG, lu avant le démarrage du moteur. C’est un document JSON qui déclare une liste de sources. Chaque entrée sélectionne un connecteur par kind, nomme le tenant auquel ses observations appartiennent, donne un name à la source, et porte la config propre au connecteur. Un poll_seconds optionnel relance une source batch sur un intervalle ; une source en streaming l’ignore.

Les types de source sont des noms enregistrés dans le moteur. Les deux observateurs de fichiers de niveau clean sont pgaudit (PostgreSQL) et s3cloudtrail (AWS S3). Utilisez ces chaînes exactes — les documentations antérieures qui écrivaient pg_audit ou cloudtrail étaient erronées et ces chaînes ne se résolvent pas.

Une source pgaudit réelle

La source pgAudit suit le journal d’audit structuré de PostgreSQL et émet une arête 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. Elle est en lecture seule sur le fichier de log et ne se connecte jamais à la base de données.

{
  "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"
      }
    }
  ]
}

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

  • log_path (requis) — chemin vers le fichier de log PostgreSQL à lire.
  • format — csvlog ou jsonlog ; par défaut csvlog.
  • follow — suit en continu. Cela s’applique uniquement à jsonlog ; un fichier csvlog est lu en batch car ses enregistrements peuvent s’étendre sur plusieurs lignes.
  • shared_accounts — rôles ou application_name séparés par des virgules qui sont mutualisés ou partagés. L’accès attribué à l’un d’eux est marqué approximate, délibérément, car la piste ne peut pas séparer les vrais appelants derrière une identité partagée.

Un application_name distinctif est le pont par agent qui obtient une arête firm. Si de nombreux agents partagent un rôle ou un pool de connexions, chaque accès se réduit sur cette identité et l’attribution devient approximate — le produit le dit plutôt que de prétendre pouvoir distinguer les agents.

Une source s3cloudtrail réelle

La source CloudTrail lit les fichiers de log AWS CloudTrail et émet une arête par événement S3, prenant la classification lecture/écriture telle quelle depuis le champ readOnly de CloudTrail. L’origine est le principal IAM ; un rôle assumé partagé entre appelants est marqué approximate.

{
  "sources": [
    {
      "name": "prod-s3",
      "kind": "s3cloudtrail",
      "tenant": "acme",
      "config": {
        "path": "/var/log/cloudtrail/",
        "shared_accounts": "shared-pipeline-role"
      }
    }
  ]
}

La clé path (requise) est un fichier de log CloudTrail ou un répertoire de fichiers *.json / *.json.gz. shared_accounts se comporte comme pour pgAudit.

Quand rien n’est câblé, le moteur prévient

Le moteur échoue en sécurité, pas bruyamment :

  • Si OLIVARES_SOURCES_CONFIG n’est pas défini, le moteur démarre sans sources.
  • Si le fichier est manquant, illisible, ou pas du JSON valide, le moteur prévient et continue sans sources — il ne plante pas au démarrage.
  • Si la liste de sources est vide, il prévient qu’aucun connecteur n’ingérera et que l’environnement fonctionne sans trafic réel.

Dans chaque cas, le log de démarrage vous dit clairement que rien de réel n’est câblé. Une carte d’accès vide ne devrait jamais ressembler à une carte propre.

Tous les connecteurs en arborescence ne sont pas câblés dans le serve standard

Olivares AI livre plus de connecteurs en arborescence qu’un binaire serve standard n’en enregistre comme types de source sélectionnables. Les observateurs de fichiers pgaudit, s3cloudtrail, le backstop noyau ebpf, le lecteur hôte runtime, et l’introspection mcp sont câblés dans le serve standard, aux côtés d’un ensemble d’observateurs de plateforme de données, secrets, réseau et identité. D’autres connecteurs existent dans l’arborescence mais ne sont pas encore câblés dans le registre de sources du serve standard — c’est un suivi identifié, pas l’affirmation que tout est sélectionnable aujourd’hui. Si un kind que vous attendez ne se résout pas, traitez-le comme pas encore câblé plutôt que mal configuré, et confirmez contre le propre descripteur du connecteur avant de vous y fier.

Cette page ne décrit que les clés vérifiées contre les connecteurs ci-dessus. Les clés config exactes pour tout autre connecteur sont détenues par ce connecteur ; lisez son descripteur plutôt que de copier un schéma non vérifié.

Voir aussi

Rechercher la documentation