Подключение источника

Эта страница объясняет общую модель коннекторов и то, как подключить реальный источник к движку. Если вам нужно лишь подключить кодового агента, начните с Подключение Claude Code — это один конкретный источник на кооперативном пути, а данная страница описывает модель под ним.

Модель коннекторов

Источник выполняет одну задачу: он наблюдает за внешней системой и эмитит нормализованные наблюдения. Он никогда не находится в пути данных, никогда не проксирует трафик и никогда не читает полезные нагрузки. Карта доступа R/RW строится из того, о чём сообщает источник, а не из перехвата того, что течёт по сети.

Конкретно, источник реализует небольшой интерфейс — Open (настроить один раз), Gather (выполнять, эмитя), Close (освободить) — и во время Gather он передаёт движку по одному наблюдению за раз через sink. Планированием владеет движок: потоковый источник (хвост лога, приёмник) блокируется в Gather и эмитит, пока его не отменят; пакетный источник делает свою работу и возвращает управление, а движок решает, когда запустить его снова. Коннектор никогда не владеет собственным таймером.

Существует ровно три вида наблюдений, которые может эмитить источник:

Наблюдение	Что оно несёт	Используется
`edge`	Инициатор (агент / идентичность / сессия) обратился к ресурсу, с режимом чтения/записи	Карта доступа R/RW
`cost`	Затраты на использование модели/провайдера	FinOps
`finding`	Findings от guardrails / red-team / форензики	Безопасность

Этот набор закрыт по замыслу — третья сторона не может ввести новый вид наблюдения. Движок поднимает каждое эмитированное наблюдение на внутрипроцессную шину событий, где модули потребляют его без связывания с источником, который его произвёл. Конкретно для карты доступа движок разрешает строковые ссылки коннектора в сущности и объединяет наблюдение в персистентное ребро доступа.

Коннекторы под Apache-2.0 и никогда не импортируют ядро

Коннектор импортирует SDK коннекторов и ничего больше из продукта. Он никогда не импортирует /core (AGPL-движок). Эта граница обеспечивается в CI, и именно она позволяет коннекторам поставляться под Apache-2.0 и позволяет третьим сторонам строить свои собственные без трений copyleft. Один и тот же бинарник коннектора работает внутри процесса или вне процесса через gRPC одинаково. См. Открытое ядро и лицензирование о полной границе.

Происхождение и достоверность: почему источник важен

Каждое ребро записывает, какой источник его произвёл, и уровень достоверности, и продукт показывает оба, а не сворачивает их в одно. READ из pg_audit и подсказка mcp_annotation — это не одно и то же свидетельство, и они никогда не трактуются как одно.

Два уровня достоверности честные, не косметические:

attributed — доступ прочно привязан к своему инициатору (например, идентичность отдельного агента, присутствующая в журнале аудита).
approximate — атрибуция выведена или потеряна с потерями (общая сервисная учётная запись или хранилище, чей аудит не может чисто разделить вызывающих).

Режим доступа — один из unknown, read, write, readwrite. unknown явный и никогда не угадывается — продукт скорее покажет «мы не смогли это классифицировать», чем сфабрикует метку чтения/записи.

Категории первичных источников, по сигналу

Первичные источники различаются по сигналу, который они несут. Выбирайте источник по тому, что система, за которой вы наблюдаете, может честно вам сообщить.

`pg_audit` — READ/WRITE PostgreSQL

Источник pgAudit читает хвост собственного структурированного журнала аудита PostgreSQL и эмитит одно ребро на каждый проаудированный доступ к данным. Режим чтения/записи берётся дословно из поля CLASS pgAudit (READ, WRITE, DDL) — никогда не выводится из текста SQL. Инициатором служит роль или application_name, которым лог приписывает доступ. Коннектор работает только на чтение по файлу лога; он никогда не подключается к базе данных и не пишет в неё. Это чистый уровень: объектное/реляционное хранилище, классифицирующее доступ в своём собственном журнале.

`cloudtrail` — readOnly для AWS S3

Источник CloudTrail читает файлы журналов CloudTrail и эмитит одно ребро на каждое событие S3. Режим чтения/записи берётся дословно из поля readOnly CloudTrail, никогда не выводится. Инициатором служит IAM-принципал, которому CloudTrail приписывает вызов. Принятая роль (assumed role), разделяемая многими вызывающими, помечается approximate намеренно, потому что журнал не может разделить реальных вызывающих за ней.

`otel` — кооперативные агенты

Это кооперативный путь: агент, эмитящий телеметрию инструментов OpenTelemetry, сообщает о том, что он сделал, а движок принимает это. Claude Code — канонический первичный источник здесь, сочетающий телеметрию OTLP с интроспекцией MCP — см. Подключение Claude Code. Кооперативная телеметрия — сигнал наивысшей точности, когда она присутствует, но она зависит от кооперативности агента, поэтому и существует резервный механизм на уровне ядра.

`ebpf` — резервный механизм ядра Tetragon (некооперативный путь)

Источник eBPF — это антиуклончивая половина карты: там, где кооперативный путь видит то, что агент сообщает, этот видит то, что ядро на самом деле сделало — чтения/записи файлов и сетевые соединения — даже когда агент отключает свою собственную телеметрию. Он работает вне контроля агента.

Его определяют два честных ограничения:

Он не загружает eBPF-программы сам. Захват на уровне ядра выполняет Tetragon, развёрнутый как отдельный укреплённый сервис; этот источник — потребитель потока событий Tetragon только на чтение, и ему не нужны собственные возможности ядра.
Он слеп к телу TLS. Он наблюдает отношения доступа, никогда не полезные нагрузки.

Его рёбра всегда approximate, по конкретной причине: ядро приписывает доступ процессу или контейнеру — runtime-идентичности, а не разрешённому агенту. Сам доступ — это истина по факту (системный вызов произошёл); достоверность квалифицирует атрибуцию, которую модуль карты доступа повышает, как только привязывает идентичность к агенту.

Кооперативный путь (нативный аудит хранилища, OTEL) — это проверенный случай высокой точности. Резервный механизм ядра обоснован в дизайне, но его сквозная атрибуция — это та часть, которая ещё прорабатывается. Относитесь к нему как к резервному механизму, поднимающему планку, а не как к завершённому первичному источнику. См. Честность и ограничения.

`mcp_annotation` — недоверенный

Источник интроспекции MCP перечисляет инструменты, ресурсы и промпты сервера и выводит подсказку чтения/записи из readOnlyHint / destructiveHint каждого инструмента. Согласно спецификации MCP клиент ОБЯЗАН считать эти аннотации недоверенными, если сам сервер не является доверенным, и значения по умолчанию асимметричны. Поэтому этот сигнал — заявленная подсказка о возможностях, никогда не наблюдённый доступ: каждое такое ребро — approximate и помечается ни как наблюдённое, ни как разрешённое. Оно поставляет поверхность возможностей для сравнения — а не свидетельство того, что что-то действительно было сделано. Оно должно подтверждаться наблюдённым источником, никогда не быть доверенным в одиночку.

Жёсткая зависимость: идентичность отдельного агента

Атрибуция хороша ровно настолько, насколько хороша идентичность, которую записывает нижележащая система. Нативный аудит приписывает доступ учётным данным или роли, а не агенту. Если множество агентов разделяют одну сервисную учётную запись или один пул соединений, каждый наблюдённый доступ сворачивается на эту единственную идентичность и атрибуция становится approximate — продукт так и скажет, а не сделает вид, что может различить агентов.

Чтобы получить attributed рёбра, дайте каждому агенту собственную идентичность. Это мост к управлению: выдача или обеспечение идентичности отдельного агента — это то, что делает карту доступа чёткой.

Многоуровневое покрытие — будьте реалистичны

Покрытие распределено по уровням в зависимости от того, что аудит-поверхность системы может честно поддержать:

Чистый — SQL-базы данных, объектные хранилища и хранилища данных, классифицирующие доступ нативно (Postgres, S3 и аналоги). Чтение/запись берётся дословно.
С потерями — хранилища, чей аудит не может чисто разделить чтение от записи или вызывающего от вызывающего (документные и векторные хранилища). Рёбра появляются, но часто approximate.
Невозможный пассивно — системы без пригодной пассивной аудит-поверхности (in-memory кеши, встроенные однофайловые базы данных). Здесь нет честного сигнала read-first для захвата; продукт не делает вид, что есть.

Выбирайте уровень осознанно. Хранилище чистого уровня с идентичностью отдельного агента — это место, где карта наиболее чёткая.

Подключение реального источника

Реальные (не демонстрационные) источники подключаются из единого операторского конфигурационного файла, заданного переменной окружения OLIVARES_SOURCES_CONFIG, читаемого до старта движка. Конфиг — это JSON-документ; секреты живут в этом файле (на которые ссылаются по значению) и никогда не персистятся движком.

Документ объявляет список источников. Каждая запись источника выбирает коннектор по виду, называет тенанта, которому принадлежат его наблюдения, и несёт собственные настройки коннектора. Общая форма такова:

{
  "sources": [
    {
      "name": "prod-postgres",
      "kind": "pgaudit",
      "tenant": "acme",
      "config": {
        "...": "connector-specific settings"
      }
    }
  ]
}

Поля над блоком config для конкретного коннектора — имя источника, kind коннектора, владеющий tenant и опциональный интервал опроса для пакетных источников — являются стабильным контрактом обвязки.

Точные ключи внутри блока config каждого коннектора (пути логов, эндпоинты, ссылки на учётные данные) принадлежат каждому коннектору и здесь не воспроизводятся, потому что публикация непроверенного ключа была бы хуже его опущения. Читайте собственную документацию коннектора по его настройкам или описывайте его обобщённо, пока не подтвердите ключи по коннектору, который вы развёртываете. Не копируйте схему, которую вы не проверили. См. Честность и ограничения.

Ненастроенный источник честно предупреждает

Движок отказывает безопасно, а не громко, когда ничего не подключено:

Если OLIVARES_SOURCES_CONFIG не задана, движок стартует без источников.
Если файл отсутствует, нечитаем или не является валидным JSON, движок предупреждает и продолжает без источников — он не падает при загрузке.
Если список источников пуст, движок предупреждает, что ни один коннектор не будет принимать данные и что estate работает без живого трафика.

В любом случае лог загрузки прямо сообщает вам, что ничего реального не подключено, вместо того чтобы молча выглядеть здоровым с пустой картой. Честное предупреждение — это замысел: пустая карта доступа никогда не должна выглядеть как чистая.

Где это работает

Data plane — коллекторы, которые запускают эти источники — всегда работает на инфраструктуре заказчика, будь то control plane как единый self-hosted бинарник, распределённое развёртывание или air-gapped. Источник наблюдает локально, а движок принимает. Обязательной телеметрии нет, а исходящий трафик управляющей плоскости по умолчанию отсутствует. За ваш периметр выходит только то, что вы настроили для передачи наружу: обращения к API ваших моделей, подключённые вами выходы SIEM/webhook и внешний поставщик эмбеддингов, если вы его настроили. См. Самостоятельный хостинг и Установка в air-gap о топологиях развёртывания.

Связанное

Подключение Claude Code — кооперативный путь otel, от начала до конца.
Обзор модулей — модули, потребляющие эти наблюдения (инвентаризация, карта доступа R/RW, FinOps, безопасность).
Обзор архитектуры — где SDK коннекторов, шина событий и карта доступа находятся в дизайне.