Перейти к содержимому

Машинный перевод. Авторитетным источником является английская версия; проверка носителем языка ещё не выполнена.

Руководства

Подключение PostgreSQL (pgaudit)

Подробное руководство по коннектору для наблюдения за доступом к базе данных PostgreSQL через pgAudit — настройка формата логов, потоковый приём.

Обновлено:

Коннектор pgAudit следит за структурированным аудиторским логом PostgreSQL и генерирует одно ребро карты доступа на каждый аудированный доступ к данным. Режим чтения/записи берётся дословно из класса pgAudit (READ, WRITE, DDL) — никогда не выводится из текста SQL. Коннектор работает только на чтение файла лога и никогда не открывает соединение к базе данных.

Для общей модели источников и структуры конфигурации начните с Подключение источника. Эта страница описывает предварительные требования на стороне PostgreSQL, полную поверхность конфигурации, механику атрибуции и операционные соображения для продакшен-окружений.

Предварительные требования PostgreSQL

Коннектор читает вывод pgAudit, поэтому PostgreSQL должен быть настроен для его генерации. Установите расширение (apt install postgresql-<version>-pgaudit на Debian/Ubuntu), загрузите его через shared_preload_libraries, перезапустите, затем выполните CREATE EXTENSION pgaudit в каждой базе данных, которую хотите наблюдать.

Минимальные настройки postgresql.conf для полезного вывода:

shared_preload_libraries = 'pgaudit'
pgaudit.log = 'read, write'       # READ и WRITE покрывают доступ к данным
log_destination = 'jsonlog'        # рекомендуется для потокового режима; csvlog тоже работает
logging_collector = on
log_directory = '/var/log/postgresql'
log_filename = 'postgresql.json'

Перезапустите после shared_preload_libraries; перезагрузите (SELECT pg_reload_conf()) после остального. Проверьте, выполнив запрос и убедившись, что запись pgAudit появляется в логе — поле message записи содержит структурированную строку pgAudit (класс, команда, имя объекта). Если появляются только стандартные сообщения PostgreSQL, расширение не загружено или не настроено.

Конфигурация

Коннектор выбирается с помощью kind: "pgaudit" в JSON-файле OLIVARES_SOURCES_CONFIG. Полный пример:

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

Все значения config — строки. Ключи принадлежат коннектору pgAudit:

  • log_path (обязательный) — абсолютный путь к файлу лога PostgreSQL. Коннектор читает этот файл; он не обнаруживает файлы логов по соглашению.
  • format — csvlog или jsonlog. По умолчанию csvlog. Управляет парсером, который использует коннектор; он должен соответствовать log_destination, который фактически пишет PostgreSQL.
  • follow — при "true" непрерывно следит за файлом (потоковый режим). Применяется только к jsonlog. Файл csvlog всегда читается пакетно, потому что записи CSV могут занимать несколько строк, что делает потоковое отслеживание ненадёжным. См. Пакетный vs потоковый режим ниже.
  • shared_accounts — через запятую список ролей PostgreSQL или значений application_name, которые являются пулированными или общими для нескольких вызывающих. Доступ, атрибутированный любому из них, намеренно помечается approximate. См. Атрибуция и общие аккаунты.

Не выдумывайте ключи конфигурации помимо этих четырёх. Поверхность конфигурации коннектора намеренно узкая — он читает файл лога, а не управляет PostgreSQL.

Атрибуция и общие аккаунты

Карта доступа должна ответить на вопрос «какой агент это сделал». Записи лога pgAudit несут роль PostgreSQL (пользователь) и, когда задано, application_name сессии. Коннектор использует оба для построения источника ребра.

Идентичность по агенту даёт надёжное ребро. Когда каждый агент устанавливает отдельное application_name для соединения (или использует выделенную роль), коннектор атрибутирует каждый доступ однозначно, и ребро является firm.

Общие роли сводятся к approximate. Когда несколько агентов разделяют пул соединений, общий сервисный аккаунт или общий application_name, коннектор не может разделить вызывающих. Каждый доступ через эту идентичность помечается approximate, и продукт говорит об этом открыто, а не притворяется, что может различить агентов, которых различить не может. Вот почему существует shared_accounts: объявление пулированных идентичностей заранее говорит коннектору сразу помечать их approximate.

Следствие для управления прямое: ребро approximate не может поддержать надёжную находку наименьших привилегий. Если вам нужно управление по агенту для доступа к базе данных, выдайте учётные данные или значения application_name по агенту. См. Точность для полной модели атрибуции.

Уровень покрытия

pgAudit — это покрытие clean. Классы READ, WRITE и DDL авторитетны — подсистема аудита PostgreSQL классифицирует оператор, и коннектор берёт эту классификацию дословно. Нет инференса, нет парсинга SQL и нет эвристики.

mode ребра — R (чтение), RW (чтение-запись, для классов WRITE и DDL), или остаётся как диктует класс. Коннектор никогда не повышает и не понижает то, что сообщил pgAudit. См. Точность — покрытие для сравнения clean с lossy и opaque источниками.

Пакетный vs потоковый режим

  • csvlog — пакетный. Записи CSV могут занимать несколько строк (запрос со встроенными переводами строк создаёт многострочную запись), поэтому потоковое отслеживание не может надёжно разделить записи. Коннектор читает файл как полный пакет; установите poll_seconds на записи источника для перезапуска через интервал.
  • jsonlog с follow: "true" — потоковый. Каждая запись JSON — одна строка, поэтому отслеживание безопасно. Коннектор держит файл открытым и генерирует рёбра по мере записи PostgreSQL.

Для рёбер близко к реальному времени, jsonlog с follow — рекомендуемая конфигурация. Для периодических аудитов или малонагруженных баз данных пакетного csvlog достаточно.

Как выглядят рёбра

Каждая запись лога pgAudit, которую коннектор разбирает, создаёт одно ребро карты доступа с этими полями:

  • Origin — роль PostgreSQL, квалифицированная application_name, когда присутствует. Пример: reporting_agent или app_pool/invoice-service.
  • Resource — полностью квалифицированный объект: database.schema.table. Пример: prod.public.orders.
  • Mode — R (из класса pgAudit READ) или RW (из класса pgAudit WRITE или DDL).
  • Attribution — firm, если источник разрешается до единственной идентичности агента, approximate, если совпадает с записью shared_accounts или не может быть однозначно определён.
  • Source — идентифицирует этот экземпляр коннектора по имени.

Ребро не содержит текста SQL, данных строк и параметров запроса. Оно записывает только структурный факт, что идентичность обратилась к объекту в заданном режиме.

Операционные заметки

Ротация логов. Когда PostgreSQL ротирует файл лога (через log_rotation_age или log_rotation_size), коннектор должен указывать на текущий файл. Если ваша ротация переименовывает активный файл, follow будет продолжать читать старый файловый дескриптор, пока он не исчерпается, а затем остановится. Укажите log_path на стабильный симлинк или используйте соглашение об именовании, за которым коннектор может следить. Коннектор не управляет ротацией сам.

Высоконагруженные окружения. pgAudit может создавать значительный объём логов на занятых базах данных, особенно с pgaudit.log = 'all'. Ограничьте pgaudit.log классами, которые вам нужны (обычно read, write), и рассмотрите фильтрацию по базе данных или по роли через pgaudit.log_relation для снижения шума без потери покрытия.

Несколько экземпляров PostgreSQL. Каждому экземпляру нужна своя запись источника в OLIVARES_SOURCES_CONFIG с отдельным name и собственным log_path. Нет автоматического обнаружения нескольких экземпляров — каждый источник наблюдает ровно один файл лога.

Права доступа. Процессу сборщика нужен доступ на чтение файла лога PostgreSQL. Ему не нужно подключение к базе данных, роль PostgreSQL или сетевой доступ к серверу базы данных. Право доступа на чтение файловой системы — единственное требование.

Связанные материалы

Поиск в документации