KSM MCP 서버 - Keeper Secrets에 대한 안전한 AI 액세스

KSM MCP는 AI 언어 모델(예: Claude)과 Keeper Secrets Manager(KSM) 사이에서 안전한 중개자 역할을 하는 MCP(Model Context Protocol) 서버입니다. 이 서버를 통해 AI 에이전트는 사용자의 KSM 보안 정보를 관리(레코드 및 폴더 나열, 생성, 검색, 삭제 등)할 수 있으며, 동시에 사용자의 KSM 애플리케이션 자격 증명을 보호합니다. 민감한 작업은 사용자 확인을 거쳐야 하므로 데이터에 대한 통제권을 유지할 수 있습니다.

빠른 사용자 가이드

옵션 1: Docker 사용 (권장)

1. KSM Base64 구성 가져오기:

   • Keeper Secrets Vault에 로그인합니다.

   • Secrets Manager, 애플리케이션, "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 재시작:

   • 이제 Claude에서 KSM 서버를 사용할 수 있습니다. 처음 연결할 때 base64 구성을 사용하여 시작됩니다.

옵션 2: 사전 컴파일된 바이너리 사용

1. 바이너리 다운로드:

   • KSM MCP 릴리스 페이지로 이동하여 운영 체제에 맞는 바이너리를 다운로드합니다(예: Intel Mac용 ksm-mcp-darwin-amd64, Windows용 ksm-mcp-windows-amd64.exe).

   • 바이너리를 실행 가능하게 만들고(예: chmod +x ./ksm-mcp-darwin-amd64) 시스템 PATH에 포함된 디렉토리에 배치하거나 전체 경로를 기록해 둡니다.

2. KSM Base64 구성 가져오기: (위 Docker 가이드의 1단계 참조)

   중요: 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: 안전한 암호 생성. AI에 노출하지 않고 새 보안 정보에 직접 저장할 수 있습니다.

• get_totp_code: TOTP가 구성된 보안 정보에 대한 현재 TOTP 코드 가져오기.

• get_server_version: KSM MCP 서버의 현재 버전 가져오기.

• health_check: MCP 서버의 작동 상태 및 KSM 연결 확인.

사용 사례 예시

AI 에이전트(예: Claude)에게 KSM MCP 서버를 사용하도록 지시하는 몇 가지 예입니다:

• 새 폴더에 새 보안 정보 생성: "메인 'KSM-MCP-TEST-RECORDS' 공유 폴더 아래에 'Project Phoenix Shared'라는 새 폴더를 만드세요. 그런 다음 'Project Phoenix Shared' 안에 사용자 이름 'phoenix_user', 암호 'ComplexP@$$wOrd123!', URL 'db.phoenix.dev.internal'인 'Phoenix Dev DB'라는 제목의 새 로그인 보안 정보를 만드세요."

• 보안 정보 나열 및 하나 검색: "'API Keys' 폴더의 모든 보안 정보를 나열하세요. 그런 다음 'Third-Party Analytics API Key'라는 제목의 보안 정보에 대한 세부 정보를 가져오되, API 키 자체는 마스킹된 상태로 유지하세요."

• 보안 정보 삭제 후 폴더 삭제(비어 있는 경우): "'Old Staging Server Credentials'라는 이름의 보안 정보를 삭제하세요. 완료되면 해당 보안 정보가 있던 'Staging Environment' 폴더가 비어 있다면 해당 폴더도 삭제하세요."

• 기존 레코드에 구성 파일 업로드: "'~/Downloads/kubeconfig-prod.yaml'에 프로덕션 클러스터를 위한 새 Kubernetes 구성 파일이 있습니다. 이 파일을 'Production K8s Cluster Access'라는 제목의 KSM 레코드에 업로드하고 첨부 파일 이름을 'kubeconfig-prod-cluster.yaml'로 지정하세요."

• 안전한 암호 생성 및 새 레코드에 저장: "대문자, 소문자, 숫자, 특수 문자를 포함하여 32자 길이의 매우 강력한 암호를 생성하세요. 이를 'Service Accounts' 폴더의 'Internal Audit Service Account'라는 제목의 새 로그인 레코드에 직접 저장하세요. 암호는 저에게 보여주지 마세요."

• 환경 간 구성 일관성 확인: "환경별(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-check 래퍼로 안전한 작동

• 보안: 높음 - 로컬 파일에 민감한 데이터가 기록되지 않음

--auto-approve (위험함)

• 목적: 파괴적 작업에 대한 사용자 확인 프롬프트 우회

• ⚠️ 보안 경고: 이는 위험하며 통제된 환경에서만 사용해야 합니다

• 일반적으로 확인이 필요한 작업:

  • create_secret - 새 보안 정보 생성

  • update_secret - 기존 보안 정보 수정

  • delete_secret - 보안 정보 삭제

  • create_folder - 새 폴더 생성

  • delete_folder - 폴더 삭제

  • upload_file - 보안 정보에 파일 업로드

  • 민감한 데이터 마스킹 해제(암호, API 키 등)

• 사용할 수 있는 경우:

  • 자동화된 테스트 환경

  • 통제된 시나리오의 신뢰할 수 있는 AI 에이전트

  • 수동 확인이 실용적이지 않은 대량 작업

• 권장 대안: 선택적 승인을 위해 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. base64 KSM 구성을 가져옵니다.

2. 제공한 암호로 암호화합니다.

3. ~/.keeper/ksm-mcp/profiles/에 로컬로 저장합니다.

4. 향후 --profile PROFILE_NAME만으로 사용할 수 있게 합니다.

사용 가능한 프로필 나열

ksm-mcp profiles list

프로필 삭제

ksm-mcp profiles delete --profile PROFILE_NAME

보안 고려 사항