KSM MCP Server — безопасный доступ ИИ к секретам Keeper

KSM MCP — это сервер протокола контекста модели (MCP), который выступает в качестве безопасного посредника между языковыми моделями ИИ (например, Claude) и Keeper Secrets Manager (KSM). Он позволяет агентам ИИ управлять вашими секретами KSM, такими как просмотр, создание, получение и удаление записей и папок, обеспечивая при этом защиту учетных данных вашего приложения KSM. Чувствительные операции требуют подтверждения пользователя, что гарантирует сохранение контроля над вашими данными.

Краткое руководство пользователя

Вариант 1: Использование Docker (рекомендуется)

1. Получите конфигурацию KSM в формате Base64:

   • Войдите в Keeper Secrets Vault.

   • Перейдите в Secrets Manager, затем в раздел Application и на вкладку "Devices".

   • Нажмите "Add Device" и скопируйте предоставленную строку конфигурации в формате base64 (обычно она начинается с ewog...).

   Важно: Конфигурация base64 содержит учетные данные вашего приложения KSM. Храните ее в безопасности и никогда не добавляйте в системы контроля версий.

2. Настройте Claude Desktop:

   • Откройте файл конфигурации Claude Desktop:

     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

     • Windows: %APPDATA%\Claude\claude_desktop_config.json

     • Linux: ~/.config/Claude/claude_desktop_config.json

   • Добавьте или обновите запись сервера ksm, заменив YOUR_BASE64_CONFIG_STRING_HERE на вашу фактическую конфигурацию base64:

   {
     "mcpServers": {
       "ksm": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "-e", "KSM_CONFIG_BASE64=YOUR_BASE64_CONFIG_STRING_HERE",
           "keeper/keeper-mcp-server:latest"
         ]
       }
       // You might have other servers like "memory" here, leave them as is.
     }
   }

3. Перезапустите Claude Desktop:

   • Сервер KSM теперь должен быть доступен для Claude. При первом подключении он будет использовать конфигурацию base64 для запуска.

Вариант 2: Использование предварительно скомпилированного бинарного файла

1. Скачайте бинарный файл:

   • Перейдите на страницу релизов KSM MCP и скачайте подходящий бинарный файл для вашей операционной системы (например, ksm-mcp-darwin-amd64 для Intel Mac, ksm-mcp-windows-amd64.exe для Windows).

   • Сделайте файл исполняемым (например, chmod +x ./ksm-mcp-darwin-amd64) и поместите его в директорию, включенную в системный PATH, или запомните полный путь к нему.

2. Получите конфигурацию KSM в формате Base64: (см. шаг 1 в руководстве по Docker выше)

   Важно: Конфигурация base64 содержит учетные данные вашего приложения KSM. Храните ее в безопасности и никогда не добавляйте в системы контроля версий.

3. Инициализируйте профиль KSM MCP:

   • Откройте терминал и выполните команду инициализации, заменив YOUR_BASE64_CONFIG_STRING и выбрав имя профиля (например, default):

     /path/to/ksm-mcp init --profile default --config "YOUR_BASE64_CONFIG_STRING"

   • Вам будет предложено установить пароль защиты для вашего локального хранилища профилей. Запомните этот пароль, так как он понадобится, если вы перезапустите сервер вручную или если он настроен на обязательный запрос пароля. Для автоматизированного использования с Claude сервер часто запускается в пакетном режиме, где этот запрос не происходит в интерактивном виде.

4. Настройте Claude Desktop:

   • Откройте файл claude_desktop_config.json (пути см. в руководстве по Docker).

   • Добавьте или обновите запись сервера ksm, заменив /path/to/ksm-mcp на фактический путь к скачанному бинарному файлу: GXP3

5. Перезапустите Claude Desktop.

Related MCP server: keyshade-mcp

Возможности (доступные инструменты)

Сервер KSM MCP предоставляет следующие инструменты для взаимодействия с Keeper Secrets Manager:

Операции с секретами

• list_secrets: список всех доступных секретов (только метаданные).

• get_secret: получение конкретного секрета (чувствительные поля по умолчанию скрыты; для раскрытия требуется подтверждение).

• search_secrets: поиск секретов по названию, заметкам или содержимому других полей.

• create_secret: создание нового секрета (требуется подтверждение).

• update_secret: обновление существующего секрета (требуется подтверждение).

• delete_secret: удаление секрета (требуется подтверждение).

Операции с папками

• list_folders: список всех доступных папок.

• create_folder: создание новой папки (требуется подтверждение; необходимо указать родительскую общую папку).

• delete_folder: удаление папки (требуется подтверждение; есть опция принудительного удаления непустых папок).

Управление файлами (внутри секретов)

• upload_file: загрузка вложения в секрет (требуется подтверждение).

• download_file: скачивание вложения из секрета.

Утилиты

• generate_password: генерация безопасного пароля. Можно опционально сохранить его напрямую в новый секрет, не раскрывая ИИ.

• get_totp_code: получение текущего кода TOTP для секрета, у которого настроен TOTP.

• get_server_version: получение текущей версии сервера KSM MCP.

• health_check: проверка рабочего состояния сервера MCP и его подключения к KSM.

Примеры использования

Вот несколько примеров того, как можно дать указание агенту ИИ (например, Claude) использовать сервер KSM MCP:

• Создание нового секрета в новой папке: "Пожалуйста, создай новую папку с названием 'Project Phoenix Shared' внутри нашей основной общей папки 'KSM-MCP-TEST-RECORDS'. Затем внутри 'Project Phoenix Shared' создай новый секрет для входа с названием 'Phoenix Dev DB', именем пользователя 'phoenix_user', паролем 'ComplexP@$$wOrd123!' и URL 'db.phoenix.dev.internal'."

• Список секретов и получение одного из них: "Выведи список всех секретов в папке 'API Keys'. Затем получи детали секрета с названием 'Third-Party Analytics API Key', но сам API-ключ оставь скрытым."

• Удаление секрета, а затем папки (если она пуста): "Удали секрет с названием 'Old Staging Server Credentials'. После этого, если папка 'Staging Environment', в которой он находился, теперь пуста, пожалуйста, удали и эту папку."

• Загрузка файла конфигурации в существующую запись: "У меня есть новый файл конфигурации Kubernetes для нашего кластера в '~/Downloads/kubeconfig-prod.yaml'. Пожалуйста, загрузи этот файл в запись KSM с названием 'Production K8s Cluster Access' и назови вложение 'kubeconfig-prod-cluster.yaml'."

• Генерация безопасного пароля и сохранение его в новую запись: "Сгенерируй очень надежный 32-символьный пароль, используя заглавные и строчные буквы, цифры и специальные символы. Сохрани его напрямую в новую запись для входа с названием 'Internal Audit Service Account' в папке 'Service Accounts'. Не показывай мне пароль."

• Проверка согласованности конфигурации в разных средах: "У меня есть записи конфигурации сервисов, организованные в папки по средам (dev, qa) с подпапками для каждого региона AWS. Пожалуйста, проанализируй эти записи и выяви любые несоответствия между похожими сервисами в разных средах. Обрати особое внимание на значения конфигурации, которые обычно должны быть одинаковыми во всех средах, такие как уровни логирования, настройки тайм-аутов или флаги функций."

Справочник по конфигурации сервера

Сервер KSM MCP может быть запущен несколькими способами с различными параметрами конфигурации. В этом разделе описаны все доступные методы, флаги и переменные окружения.

Методы конфигурации

Метод 1: Docker с переменными окружения (рекомендуется)

{
  "mcpServers": {
    "ksm": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "KSM_CONFIG_BASE64=YOUR_BASE64_CONFIG_STRING",
        "keeper-mcp-server:latest"
      ]
    }
  }
}

Метод 2: Предварительно скомпилированный бинарный файл с профилем

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": ["serve", "--profile", "default"]
    }
  }
}

Метод 3: Предварительно скомпилированный бинарный файл с конфигурацией Base64 (флаг CLI)

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": [
        "serve",
        "--config-base64", "YOUR_BASE64_CONFIG_STRING"
      ]
    }
  }
}

Метод 4: Предварительно скомпилированный бинарный файл с переменными окружения

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": ["serve"],
      "env": {
        "KSM_CONFIG_BASE64": "YOUR_BASE64_CONFIG_STRING"
      }
    }
  }
}

Метод 5: Тихий режим (без локальных логов)

Для сред, где вы хотите предотвратить создание любых локальных файлов (включая журналы аудита):

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": [
        "serve",
        "--no-logs",
        "--config-base64", "YOUR_BASE64_CONFIG_STRING"
      ]
    }
  }
}

Флаг --no-logs полностью отключает ведение журналов аудита, гарантируя, что локальные файлы не будут созданы. Это полезно для:

• Сред, соответствующих требованиям безопасности, где необходимо избегать создания локальных файлов

• Контейнеризированных развертываний, где не требуется сохранение данных

• Временных или тестовых сценариев

• Систем с файловыми системами, доступными только для чтения

Флаги командной строки

Детали флагов

--batch (Неинтерактивный режим)

• Цель: Предотвращает запросы сервера на ввод паролей или данных пользователем

• Когда использовать:

  • Автоматизированные среды (CI/CD, контейнеры Docker)

  • При запуске в качестве службы, где взаимодействие с человеком невозможно

  • Интеграция с Claude Desktop (рекомендуется)

• Что делает:

  • Пропускает запросы пароля при загрузке зашифрованных профилей

  • Использует переменные окружения или флаги CLI для всей конфигурации

  • Корректно завершает работу, если требуемые данные отсутствуют, вместо зависания

--no-logs (Тихий режим)

• Цель: Полностью отключает ведение журналов аудита для предотвращения создания локальных файлов

• Когда использовать:

  • Среды, где необходимо избегать создания локальных артефактов

  • Контейнеризированные или эфемерные развертывания

  • Среды с файловой системой только для чтения

  • Тестовые сценарии, где важна очистка данных

• Что делает:

  • Предотвращает создание директории ~/.keeper/ksm-mcp/logs/

  • Отключает все журналы аудита (логи доступа, ошибки, системные логи)

  • Сохраняет полную функциональность MCP без нагрузки от логирования

  • Безопасная работа с обертками проверки на nil для всех вызовов логирования

• Безопасность: Высокая — никакие чувствительные данные не записываются в локальные файлы

--auto-approve (Опасно)

• Цель: Обходит запросы подтверждения пользователем для деструктивных операций

• ⚠️ Предупреждение безопасности: Это опасно и должно использоваться только в контролируемых средах

• Какие операции обычно требуют подтверждения:

  • create_secret — создание новых секретов

  • update_secret — изменение существующих секретов

  • delete_secret — удаление секретов

  • create_folder — создание новых папок

  • delete_folder — удаление папок

  • upload_file — загрузка файлов в секреты

  • Раскрытие чувствительных данных (пароли, API-ключи и т.д.)

• Когда это может понадобиться:

  • Среды автоматизированного тестирования

  • Доверенные агенты ИИ в контролируемых сценариях

  • Массовые операции, где ручное подтверждение непрактично

• Рекомендуемая альтернатива: Используйте инструмент ksm_execute_confirmed_action для выборочного одобрения

Переменные окружения

Приоритет конфигурации

Сервер использует следующий порядок приоритета для конфигурации:

1. Флаг CLI --config-base64 (наивысший приоритет)

2. Переменная окружения KSM_CONFIG_BASE64

3. Флаг CLI --profile с локальным хранилищем профилей

4. Переменная окружения KSM_MCP_PROFILE с локальным хранилищем профилей

Команды управления профилями

Зачем использовать профили?

Профили предоставляют безопасный способ хранения и управления конфигурациями KSM локально без раскрытия чувствительных учетных данных:

• Безопасность: Ваша конфигурация base64 содержит чувствительные учетные данные приложения KSM. Профили шифруют и хранят их локально с защитой паролем

• Удобство: После инициализации вам нужно только ссылаться на имя профиля вместо передачи полной конфигурации base64 каждый раз

• Несколько сред: Управляйте разными приложениями KSM (dev, staging, prod) с помощью отдельных профилей

• Защита учетных данных: Хранит чувствительные данные вне командных строк, переменных окружения и файлов конфигурации

• Постоянное хранилище: Сохраняется после перезагрузки системы и не требует повторного ввода учетных данных

Когда использовать профили, а когда прямую конфигурацию:

• Используйте профили для: локальной разработки, постоянных настроек, нескольких сред

• Используйте прямую конфигурацию для: CI/CD, контейнеров Docker, временного использования, сред, где нежелательно локальное хранилище

Инициализация нового профиля

ksm-mcp init --profile PROFILE_NAME --config "BASE64_CONFIG_STRING"

Эта команда:

1. Берет вашу конфигурацию KSM в формате base64

2. Шифрует ее предоставленным вами паролем

3. Сохраняет ее локально в ~/.keeper/ksm-mcp/profiles/

4. Позволяет использовать ее