delinea-mcp Server

resmi

Delinea Secret Server ve Platform API'leri için resmi Delinea MCP sunucusu

GitHub
46

Dokümantasyon

DelineaMCP

Delinea Secret Server ve Platform API'leri için MCP sunucusu

License

Özellikler

  • Secret Server'a karşı otomatik kimlik doğrulama
  • Klasörleri, gizli bilgileri, kullanıcıları, grupları ve rolleri yönetmek için kapsamlı Secret Server araç seti. Gelen kutusu ve erişim isteği yardımcıları ile kodlama aracısı yardımcı programlarını içerir.
  • Kontrollü AI etkileşimleri için ChatGPT uyumluluk araçları (search ve fetch).
  • İsteğe bağlı Delinea Platform kullanıcı yönetim araçları
  • Sunucu Tarafından Gönderilen Olaylar veya STDIO aktarım modlarını destekler
  • MCP spesifikasyonuna uygun dinamik istemci kaydı ile OAuth 2.0
  • Güvenli bağlantılar için TLS desteği
  • Çalıştırmaya hazır Docker imajı ve geliştirme sunucusu giriş noktası
  • ChatGPT, Claude Desktop, uzak Claude bağlayıcısı, VSCode Copilot ve openwebui ile test edilmiştir

Kurulum

[!NOTE]

Bu proje uv (https://github.com/astral-sh/uv) kullanır, ancak komutları bu olmadan çalıştırmayı tercih ederseniz, istenirse pip ve venv komutlarını her zamanki gibi kullanabilirsiniz.

  • Uv'yi Kurun
  • Projeyi başlatın: uv pip sync requirements.txt
  • uv run server.py --config config.json kullanın

Yapılandırma

Parolalar gibi gizli bilgiler ortam değişkenlerinden gelmeye devam eder. Kabuk ortamınızda DELINEA_PASSWORD sağlayın. İsteğe bağlı özellikler AZURE_OPENAI_KEY veya PLATFORM_SERVICE_PASSWORD gibi ek değişkenlere dayanır.

Gizli olmayan parametreler config.json dosyasına aittir:

{
  "delinea_username": "<username>",
  "delinea_base_url": "https://your-secret-server/SecretServer",
  "platform_hostname": "<tenant>.secureplatform.io",
  "platform_service_account": "<service_account>",
  "platform_tenant_id": "<tenant_id>",
  "azure_openai_endpoint": "https://example.openai.azure.com/",
  "azure_openai_deployment": "<deployment_name>",
  "auth_mode": "none",
  "transport_mode": "stdio",
  "chatgpt_disable_scope_checks": false,
  "port": 8000,
  "debug": false,
  "external_hostname": null,
  "ssl_keyfile": null,
  "ssl_certfile": null,
  "registration_psk": null,
  "jwt_key_path": ".cache/jwt.json",
  "oauth_db_path": ".cache/oauth.db",
  "enabled_tools": []
}

Secret Server Cloud için /SecretServer olmadan bulut URL'sini kullanmanız yeterlidir. HTTPS'i etkinleştirmek için ssl_keyfile ve ssl_certfile belirtin. Let's Encrypt için privkey.pem ve fullchain.pem dosyalarını kullanın.

Yapılandırma dosyası aşağıdaki anahtarları destekler:

  • delinea_username - Secret Server kullanıcı adı. Yapmak istediğiniz görevleri gerçekleştirme iznine sahip programatik bir kullanıcı olmalıdır.
  • delinea_base_url - Secret Server örneğinizin temel URL'si.
  • platform_hostname - Platform kiracı ana bilgisayar adı (Platform araçlarını etkinleştirir).
  • platform_service_account - Platform API'si ile kullanılan hizmet hesabı.
  • platform_tenant_id - Platform API istekleri için kiracı kimliği.
  • azure_openai_endpoint - Azure OpenAI uç noktası. Yalnızca otomatik rapor oluşturmayı istiyorsanız (çoğu aracı kendi rapor SQL'ini oluşturabilir, bu nedenle ihtiyacınız yoksa etkinleştirmeyin).
  • azure_openai_deployment - Azure OpenAI için dağıtım adı.
  • auth_mode - Kimlik doğrulama modu (none veya oauth). OAuth, stdio aktarımı ile çalışmaz.
  • transport_mode - Komut satırı için stdio veya HTTP/SSE için sse.
  • chatgpt_disable_scope_checks - ChatGPT isteklerinde kapsam doğrulamasını atla. Yalnızca ChatGPT'ye bağlanırken sorun yaşarsanız etkinleştirin.
  • port - sse modunda HTTP sunucusu için bağlantı noktası.
  • debug - Ayrıntılı günlük kaydını etkinleştir.
  • external_hostname - OAuth belirteci hedef kitleleri oluşturulurken kullanılan ana bilgisayar adı. HTTP(S) öneki veya bağlantı noktası eklemeyin.
  • ssl_keyfile - HTTPS için SSL anahtarının yolu. (örn. privkey.pem)
  • ssl_certfile - HTTPS için SSL sertifikasının yolu. (örn. fullchain.pem)
  • registration_psk - OAuth istemcilerini kaydetmek için gereken ön paylaşımlı anahtar. OAuth bağlantılarını onaylamak için bu sırrı tarayıcınıza yazmanız gerekecektir.
  • jwt_key_path - OAuth belirteçleri için kullanılan RSA anahtar çiftinin konumu. Varsayılan .cache/jwt.json'dir. Mevcut değilse otomatik oluşturulur.
  • oauth_db_path - OAuth veritabanı dosyasının yolu. Varsayılan .cache/oauth.db'dir. Mevcut değilse otomatik oluşturulur.
  • enabled_tools - Kaydedilecek araç adlarının listesi. Boş bir liste tüm araçları etkinleştirir. Araçları kullanım durumuna veya göreve göre seçici olarak etkinleştirmeniz şiddetle önerilir. Bazı örnekler için docs/ klasörüne bakın.
  • search_objects - search aracı için izin verilen nesne türleri. Varsayılan ["secret"]'dır ancak user, folder, group ve role içerebilir.
  • fetch_objects - fetch aracı için izin verilen nesne türleri. Varsayılan ["secret"]'dir ancak search_objects ile aynı değerleri içerebilir.

Sunucuyu Çalıştırma

Sunucuyu geliştirme modunda yerel olarak başlatın:

python server.py

Başlangıçta sunucu bir taşıyıcı belirteç ister ve sonraki API istekleri için saklar. Bu proje, Secret Server API'si ile daha fazla entegre olacak şekilde genişletilecektir.

MCP Araçları

Sunucu, Secret Server ile etkileşim için çeşitli MCP araçları sunar:

  • run_report(sql_query, report_name=None) - geçici bir rapor oluştur ve çalıştır.
  • ai_generate_and_run_report(description) - Azure OpenAI kullanarak SQL oluştur ve çalıştır. Azure OpenAI değişkenlerini gerektirir.
  • list_example_reports() - örnek sorguları ve tablo bilgilerini listele.
  • get_secret(id, summary=False) - bir gizli bilgiyi veya özet ayrıntılarını al.
  • get_folder(id) - klasör meta verilerini ve alt öğelerini getir.
  • search_users(query) - aktif kullanıcıları ara.
  • search_secrets(query, lookup=False) - gizli bilgileri ara veya sorgula.
  • search_folders(query, lookup=False) - klasörleri ara veya sorgula.
  • get_secret_environment_variable(secret_id, environment) - belirtilen kabukta gizli bilgi kimlik bilgilerini almak için bir betik çıktısı ver.
  • check_secret_template(template_id) - gizli bilgi şablonu ayrıntılarını getir.
  • check_secret_template_field(template_id, field_id) - bir şablonun bir alan içerip içermediğini kontrol et.
  • get_secret_template_field(field_id) - belirli bir gizli bilgi şablonu alanı hakkında kimliğe göre ayrıntıları al.
  • handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - bir erişim isteğini onayla veya reddet.
  • get_pending_access_requests() - bekleyen erişim isteklerini listele.
  • get_inbox_messages(read_status_filter=None, take=20, skip=0) - gelen kutusu mesajlarını al.
  • mark_inbox_messages_read(message_ids, read=True) - mesajları okundu veya okunmadı olarak işaretle.
  • user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - birleşik kullanıcı işlemleri. action get, create, update, delete, list_sessions, reset_2fa, reset_password veya lock_out kabul eder. Gerektiğinde user_id sağlayın ve oluşturma, güncelleme ve parola sıfırlama eylemleri için istek gövdesini data aracılığıyla iletin. Örnek: user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
  • role_management(action, role_id=None, data=None, params=None) - rolleri yönet. action list, get, create veya update olabilir. Rolleri listelerken isteğe bağlı sorgu parametrelerini params ile iletin. Örnek: role_management("update", role_id=3, data={"name": "New Role"}).
  • user_role_management(action, user_id, role_ids=None) - bir kullanıcıya rol ata veya kaldır. action get, add veya remove ve role_ids ekleme/kaldırma işlemleri için bir rol tanımlayıcıları listesidir.
  • group_management(action, group_id=None, data=None, params=None) - grupları yönet. action get, list, create veya delete olabilir. Getirme/silme için group_id ve bir grup oluştururken data sağlayın.
  • folder_management(action, folder_id=None, data=None, params=None) - klasörleri yönet. action get, list, create, update veya delete olabilir. Getirme, güncelleme veya silme için folder_id sağlayın ve bir klasör oluştururken veya güncellerken data iletin.
  • user_group_management(action, user_id, group_ids=None) - bir kullanıcı için grup üyeliğini yönet. action get, add veya remove'dir. Üyelik eklerken veya kaldırırken bir group_ids listesi sağlayın.
  • group_role_management(action, group_id, role_ids=None) - bir gruptaki rolleri kontrol et. list, add veya remove eylemlerini kullanın. Eklerken veya kaldırırken role_ids sağlayın.
  • health_check() - Secret Server sağlık kontrolü uç noktasını sorgulayın ve mevcut hizmet durumunu döndürün.

Kimlik doğrulaması için yukarıda açıklanan sunucu yapılandırma değişkenlerini kullanın. Azure OpenAI değişkenleri eksikse AI aracı otomatik olarak devre dışı bırakılır. Yalnızca config.json içinde listelenen araç adları kaydedilecektir. Boş bir liste tüm araçları etkinleştirir.

Kullanım Durumları

Dokümantasyon, araçları sunucuya bağlamak için çeşitli iş akışlarını kapsar:

Docker Hızlı Başlangıç

MCP sunucusunu yerel olarak Python bağımlılıklarını kurmadan çalıştırmak için bir Dockerfile sağlanmıştır.

  1. İmajı oluşturun:
docker build -t dev.local/delinea-mcp:latest .
  1. Sunucuyu çalıştırın (kimlik bilgilerinizi ortam değişkenleri aracılığıyla iletin):
docker run --rm -p 8000:8000 \
  -e DELINEA_PASSWORD=<password> \
  -e PLATFORM_SERVICE_PASSWORD=<password> \
  -e DELINEA_DEBUG=1 \
  -e AZURE_OPENAI_KEY=<your-key-or-appropriate-token> \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v mcp-data:/app/data \
  dev.local/delinea-mcp:latest

config.json'i yukarıda gösterildiği gibi kullanıcı adlarınız ve URL'lerinizle doldurun.

Konteyner oauth.db ve jwt.json'i /app/data içinde saklar. Bu dosyaların ve HTTPS sertifikalarının çalıştırmalar arasında kalıcı olması için bir birim bağlayın (yukarıda mcp-data olarak gösterilmiştir).

Bağlantı hatalarını önlemek için <https://your-secret-server/SecretServer>'i Secret Server örneğinizin temel URL'si ile değiştirin.

Sunucu varsayılan olarak python server.py kullanarak 8000 bağlantı noktasında başlayacaktır. Varsayılanı geçersiz kılmak için config.json içindeki port seçeneğini ayarlayın. Tüm gelen HTTP isteklerini günlüğe kaydetmek için debug: true'i etkinleştirin.

Örnek Betikler

manual_secret_request.py betiği, belirli bir gizli bilgi kimliği için OAuth belirtecinin nasıl alınacağını gösterir:

python scripts/manual_secret_request.py <Secret_ID>

Betiği çalıştırmadan önce gizli bilgi için SECRET_USERNAME_<id> ve SECRET_PASSWORD_<id> ortam değişkenlerini ayarlayın. Varsayılan https://localhost/SecretServer'i geçersiz kılmak için isteğe bağlı olarak DELINEA_BASE_URL ayarlayın.

Testleri Çalıştırma

%100 kod kapsamı sağlamak için birim testlerini kapsam ile çalıştırın:

pip install -r requirements.txt
coverage run -m pytest -q
coverage report --omit "tests/*"

Canlı Test

Bazı entegrasyon testleri geçerli kimlik bilgileri gerektirir. Paketi çalıştırmadan önce aşağıdaki ortam değişkenlerini ve isteğe bağlı LIVE_SECRET_ID'i ayarlayın:

export DELINEA_PASSWORD=<password>
# Optional secret used by tests/test_live.py
export LIVE_SECRET_ID=<id>
export SECRET_USERNAME_<id>=<secret_username>
export SECRET_PASSWORD_<id>=<secret_password>

Bu değişkenler mevcut olduğunda canlı testler gerçek API istekleri gerçekleştirecektir.

Üretim Dağıtımı

Bağımlılıklar requirements.txt içinde sabitlenmiştir ve sürümler Semantik Sürümleme kullanılarak etiketlenmiştir. Etiketlenmiş bir commit'ten Docker imajını oluşturun ve gerekli ortam değişkenlerini (DELINEA_USERNAME, DELINEA_PASSWORD, isteğe bağlı olarak DELINEA_BASE_URL) ileterek üretim ortamınıza dağıtın. İsteğe bağlı özellikler ek değişkenlere dayanır:

  • PLATFORM_SERVICE_PASSWORD, PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT ve PLATFORM_TENANT_ID ile birlikte kullanıcı yönetim araçlarını etkinleştirir.
  • AZURE_OPENAI_KEY, AZURE_OPENAI_ENDPOINT ve AZURE_OPENAI_DEPLOYMENT ile birlikte AI rapor oluşturma yardımcısını etkinleştirir.

OAuth veya SSE aktarımı ile çalışırken registration_psk sağlamanız ve bir external_hostname veya HTTPS sertifika dosyaları yapılandırmanız gerekebilir.

Depo Düzeni

  • delinea_mcp/ - MCP araçlarını içeren paket.
  • server.py - her şeyi MCP sunucusuna kaydeden ince giriş noktası.
  • docs/ - proje dokümantasyonu ve oluşturulan delinea-secret-server-openapi-spec.json.
  • scripts/ - manual_secret_request.py dahil yardımcı örnekler.

Güvenlik Hususları

Dahil edilen OAuth uç noktaları geliştirme ve test amaçlıdır. /oauth/authorize rotası herhangi bir redirect_uri kabul eder ve kullanıcıyı doğrulama olmadan yönlendirir. Dağıtımlar bu değeri onaylanmış geri çağırma URL'leriyle sınırlandırmalıdır; aksi takdirde saldırganlar kötü amaçlı bir URL sağlayabilir ve yetkilendirme kodlarını ele geçirebilir. Arka plan için Açık Yönlendirme konusuna bakın.

Sürüm Notları

En son özelliklerin ve yol haritası öğelerinin bir özeti için docs/release_notes.md dosyasına bakın.

Yol Haritası

  1. Geçişli kimlik doğrulama
  2. Akışlı HTTP aktarım desteği
  3. Delinea Platform'da araç kapsamını genişletme ve diğer Delinea ürünlerini ekleme

Katkıda Bulunma

Katkılar memnuniyetle karşılanır! Herhangi bir iyileştirme için lütfen sorunlar veya çekme istekleri açın. Tüm yeni kodlar birim testleri içermeli ve mevcut test paketini geçmelidir.

Lisans

Bu proje MIT Lisansı altında lisanslanmıştır.