delinea-mcp Server

oficial

Servidor MCP oficial da Delinea para as APIs do Delinea Secret Server e Platform

GitHub
46

Documentação

DelineaMCP

Servidor MCP para as APIs do Delinea Secret Server e Platform

License

Funcionalidades

  • Autenticação automática no Secret Server
  • Conjunto abrangente de ferramentas do Secret Server para gerenciar pastas, segredos, usuários, grupos e funções. Inclui auxiliares de caixa de entrada e solicitações de acesso, além de utilitários para agentes de codificação.
  • Ferramentas de compatibilidade com ChatGPT (search e fetch) para interações controladas com IA.
  • Ferramentas opcionais de gerenciamento de usuários da Delinea Platform
  • Suporta modos de transporte Server Sent Events ou STDIO
  • OAuth 2.0 com registro dinâmico de cliente conforme a especificação MCP
  • Suporte a TLS para conexões seguras
  • Imagem Docker pronta para execução e ponto de entrada para servidor de desenvolvimento
  • Testado com ChatGPT, Claude Desktop, conector remoto Claude, VSCode Copilot e openwebui

Instalação

[!NOTE]

Este projeto usa uv (https://github.com/astral-sh/uv), mas se preferir executar comandos sem isso, você pode usar os comandos pip e venv normalmente, se desejar.

  • Instalar Uv
  • Inicializar projeto: uv pip sync requirements.txt
  • Usar uv run server.py --config config.json

Configuração

Segredos como senhas continuam vindo de variáveis de ambiente. Forneça DELINEA_PASSWORD no seu ambiente shell. Funcionalidades opcionais dependem de variáveis adicionais como AZURE_OPENAI_KEY ou PLATFORM_SERVICE_PASSWORD.

Parâmetros não secretos pertencem ao config.json:

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

Para o Secret Server Cloud, basta usar a URL da nuvem sem /SecretServer. Especifique ssl_keyfile e ssl_certfile para habilitar HTTPS. Para Let's Encrypt, use os arquivos privkey.pem e fullchain.pem.

O arquivo de configuração suporta as seguintes chaves:

  • delinea_username - Nome de usuário do Secret Server. Deve ser um usuário programático com permissão para realizar as tarefas desejadas.
  • delinea_base_url - URL base da sua instância do Secret Server.
  • platform_hostname - Nome do host do tenant da Platform (habilita ferramentas da Platform).
  • platform_service_account - Conta de serviço usada com a API da Platform.
  • platform_tenant_id - ID do tenant para requisições da API da Platform.
  • azure_openai_endpoint - Endpoint do Azure OpenAI. Apenas se desejar a geração automática de relatórios (a maioria dos agentes pode gerar seu próprio SQL de relatório, então não habilite a menos que precise).
  • azure_openai_deployment - Nome da implantação para o Azure OpenAI.
  • auth_mode - Modo de autenticação (none ou oauth). OAuth obviamente não funciona com transporte stdio.
  • transport_mode - stdio para linha de comando ou sse para HTTP/SSE.
  • chatgpt_disable_scope_checks - Pular validação de escopo em requisições do ChatGPT. Habilite apenas se encontrar problemas ao conectar ao ChatGPT.
  • port - Porta para o servidor HTTP no modo sse.
  • debug - Habilitar registro de log detalhado.
  • external_hostname - Nome do host usado ao construir audiências de token OAuth. Não adicione prefixo HTTP(S) ou porta.
  • ssl_keyfile - Caminho para a chave SSL para HTTPS. (ex: privkey.pem)
  • ssl_certfile - Caminho para o certificado SSL para HTTPS. (ex: fullchain.pem)
  • registration_psk - Chave pré-compartilhada necessária para registrar clientes OAuth. Você precisará digitar este segredo no seu navegador para aprovar conexões OAuth.
  • jwt_key_path - Localização do par de chaves RSA usado para tokens OAuth. Padrão: .cache/jwt.json. Gerado automaticamente se não existir.
  • oauth_db_path - Caminho para o arquivo de banco de dados OAuth. Padrão: .cache/oauth.db. Gerado automaticamente se não existir.
  • enabled_tools - Lista de nomes de ferramentas a registrar. Uma lista vazia habilita todas as ferramentas. É altamente recomendável habilitar ferramentas seletivamente por caso de uso ou tarefa. Veja a pasta docs/ para alguns exemplos.
  • search_objects - Tipos de objeto permitidos para a ferramenta search. Padrão: ["secret"], mas pode incluir user, folder, group e role.
  • fetch_objects - Tipos de objeto permitidos para a ferramenta fetch. Padrão: ["secret"], mas pode incluir os mesmos valores que search_objects.

Executando o Servidor

Inicie o servidor localmente em modo de desenvolvimento:

python server.py

Na inicialização, o servidor solicita um token de portador e o armazena para requisições subsequentes à API. Este projeto será expandido para integrar-se ainda mais com a API do Secret Server.

Ferramentas MCP

O servidor expõe várias ferramentas MCP para interagir com o Secret Server:

  • run_report(sql_query, report_name=None) - criar e executar um relatório temporário.
  • ai_generate_and_run_report(description) - gerar SQL usando Azure OpenAI e executá-lo. Requer as variáveis do Azure OpenAI.
  • list_example_reports() - listar consultas de exemplo e informações de tabelas.
  • get_secret(id, summary=False) - recuperar um segredo ou detalhes resumidos.
  • get_folder(id) - buscar metadados de pastas e filhos.
  • search_users(query) - pesquisar usuários ativos.
  • search_secrets(query, lookup=False) - pesquisar ou consultar segredos.
  • search_folders(query, lookup=False) - pesquisar ou consultar pastas.
  • get_secret_environment_variable(secret_id, environment) - gerar um script para obter credenciais de segredo no shell especificado.
  • check_secret_template(template_id) - buscar detalhes do modelo de segredo.
  • check_secret_template_field(template_id, field_id) - verificar se um modelo contém um campo.
  • get_secret_template_field(field_id) - recuperar detalhes sobre um campo específico do modelo de segredo por ID.
  • handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - aprovar ou negar uma solicitação de acesso.
  • get_pending_access_requests() - listar solicitações de acesso pendentes.
  • get_inbox_messages(read_status_filter=None, take=20, skip=0) - recuperar mensagens da caixa de entrada.
  • mark_inbox_messages_read(message_ids, read=True) - marcar mensagens como lidas ou não lidas.
  • user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - operações unificadas de usuário. action aceita get, create, update, delete, list_sessions, reset_2fa, reset_password ou lock_out. Forneça user_id quando necessário e envie o corpo da requisição via data para ações de criar, atualizar e redefinir senha. Exemplo: user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
  • role_management(action, role_id=None, data=None, params=None) - gerenciar funções. action pode ser list, get, create ou update. Passe parâmetros de consulta opcionais com params ao listar funções. Exemplo: role_management("update", role_id=3, data={"name": "New Role"}).
  • user_role_management(action, user_id, role_ids=None) - atribuir ou remover funções de um usuário. action é get, add ou remove e role_ids é uma lista de identificadores de função para operações de adicionar/remover.
  • group_management(action, group_id=None, data=None, params=None) - lidar com grupos. action pode ser get, list, create ou delete. Forneça group_id para obter/excluir e data ao criar um grupo.
  • folder_management(action, folder_id=None, data=None, params=None) - gerenciar pastas. action pode ser get, list, create, update ou delete. Forneça folder_id para obter, atualizar ou excluir e envie data ao criar ou atualizar uma pasta.
  • user_group_management(action, user_id, group_ids=None) - gerenciar associação de grupo para um usuário. action é get, add ou remove. Forneça uma lista de group_ids ao adicionar ou remover associação.
  • group_role_management(action, group_id, role_ids=None) - controlar funções em um grupo. Use ações list, add ou remove. Forneça role_ids ao adicionar ou remover.
  • health_check() - consultar o endpoint de verificação de integridade do Secret Server e retornar o status atual do serviço.

Use as variáveis de configuração do servidor descritas acima para autenticar. A ferramenta de IA é automaticamente desabilitada se as variáveis do Azure OpenAI estiverem ausentes. Apenas os nomes de ferramentas listados em config.json serão registrados. Uma lista vazia habilita todas as ferramentas.

Casos de Uso

A documentação cobre vários fluxos de trabalho para conectar ferramentas ao servidor:

Início Rápido com Docker

Um Dockerfile é fornecido para executar o servidor MCP sem instalar dependências Python localmente.

  1. Construir a imagem:
docker build -t dev.local/delinea-mcp:latest .
  1. Executar o servidor (passe suas credenciais via variáveis de ambiente):
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

Preencha config.json com seus nomes de usuário e URLs conforme mostrado acima.

O contêiner armazena oauth.db e jwt.json em /app/data. Monte um volume (mostrado como mcp-data acima) para que esses arquivos e quaisquer certificados HTTPS persistam entre execuções.

Substitua <https://your-secret-server/SecretServer> pela URL base da sua instância do Secret Server para evitar erros de conexão.

O servidor iniciará na porta 8000 por padrão usando python server.py. Defina a opção port em config.json para substituir o padrão. Habilite debug: true para registrar todas as requisições HTTP recebidas.

Scripts de Exemplo

O script manual_secret_request.py mostra como recuperar um token OAuth para um ID de segredo específico:

python scripts/manual_secret_request.py <Secret_ID>

Defina as variáveis de ambiente SECRET_USERNAME_<id> e SECRET_PASSWORD_<id> para o segredo antes de executar o script. Opcionalmente, defina DELINEA_BASE_URL para substituir o padrão https://localhost/SecretServer.

Executando Testes

Execute os testes unitários com cobertura para garantir 100% de cobertura de código:

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

Testes ao Vivo

Alguns testes de integração exigem credenciais válidas. Defina as seguintes variáveis de ambiente e a opcional LIVE_SECRET_ID antes de executar a suíte:

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>

Quando essas variáveis estão presentes, os testes ao vivo realizarão requisições reais à API.

Implantação em Produção

As dependências estão fixadas em requirements.txt e os lançamentos são etiquetados usando Versionamento Semântico. Construa a imagem Docker a partir de um commit etiquetado e implante-a em seu ambiente de produção, passando as variáveis de ambiente necessárias (DELINEA_USERNAME, DELINEA_PASSWORD, opcionalmente DELINEA_BASE_URL). Funcionalidades opcionais dependem de variáveis adicionais:

  • PLATFORM_SERVICE_PASSWORD juntamente com PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT e PLATFORM_TENANT_ID habilita as ferramentas de gerenciamento de usuários.
  • AZURE_OPENAI_KEY junto com AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_DEPLOYMENT habilita o auxiliar de geração de relatórios com IA.

Ao executar com transporte OAuth ou SSE, pode ser necessário fornecer registration_psk e configurar um external_hostname ou arquivos de certificado HTTPS.

Estrutura do Repositório

  • delinea_mcp/ - pacote contendo ferramentas MCP.
  • server.py - ponto de entrada fino que registra tudo com o servidor MCP.
  • docs/ - documentação do projeto e o delinea-secret-server-openapi-spec.json gerado.
  • scripts/ - exemplos auxiliares incluindo manual_secret_request.py.

Considerações de Segurança

Os endpoints OAuth incluídos são destinados a desenvolvimento e teste. A rota /oauth/authorize aceita qualquer redirect_uri e redirecionará o usuário sem validação. Implantações devem restringir este valor a URLs de callback aprovadas; caso contrário, atacantes poderiam fornecer uma URL maliciosa e capturar códigos de autorização. Veja Redirecionamento Aberto para contexto.

Notas de Lançamento

Veja docs/release_notes.md para um resumo das últimas funcionalidades e itens do roteiro.

Roteiro

  1. Autenticação de passagem
  2. Suporte a transporte HTTP de streaming
  3. Expandir a cobertura de ferramentas na Delinea Platform e adicionar outros produtos Delinea

Contribuindo

Contribuições são bem-vindas! Por favor, abra issues ou pull requests para quaisquer melhorias. Todo código novo deve incluir testes unitários e passar na suíte de testes existente.

Licença

Este projeto está licenciado sob a Licença MIT.