Security Compass / SD Elements - ZeroPath Documentation

Esta integração está em beta. As operações do dia a dia podem ser conduzidas pelo seu assistente de IA (usando os servidores MCP do ZeroPath), com um caminho correspondente no dashboard em Settings → Integrations sempre que houver um. A única exceção é conectar a integração em si: você fornece a chave de API do SD Elements no dashboard do ZeroPath, nunca por meio de um assistente de IA.

Visão geral

Esta integração conecta um scan do ZeroPath a um projeto existente do SD Elements. Suas contramedidas do SD Elements são traduzidas em regras de scan do ZeroPath, e o ZeroPath escaneia seu repositório com base nelas. Três coisas participam dessa relação:

Seu projeto SD Elements é a fonte da verdade para as contramedidas — os requisitos de segurança que sua aplicação deve atender.
Seu repositório Git é o que o ZeroPath escaneia.
O ZeroPath fica no meio. Ele mapeia o projeto para o repositório, classifica cada contramedida (coberta pela análise integrada, coberta por uma regra gerada automaticamente ou não suportada) e escaneia o código com base nas regras resultantes.

Ao final desta página, você terá um projeto SD Elements vinculado a um repositório no ZeroPath, com suas contramedidas sincronizadas no ZeroPath como regras de scan e scans sendo executados com base nelas.

Antes de começar

Contas necessárias

Um tenant ZeroPath com acesso de admin. Se você não tiver um, fale com seu contato na Security Compass ou envie um e-mail para a ZeroPath em support@zeropath.com. O provisionamento de um tenant normalmente leva cerca de 24 horas.
Uma implantação do SD Elements com acesso à API e pelo menos um projeto que você queira vincular.
Um repositório no GitHub, GitLab, Bitbucket, Azure Repos, Gerrit, Git genérico ou CVS que você possa conectar ao ZeroPath.

Software necessário

Um assistente de IA com suporte a MCP. A configuração abaixo cobre Claude Code, Cursor e GitHub Copilot.
Para o servidor MCP do ZeroPath que você instala localmente, o toolchain uv — ele é executado via uvx. O servidor MCP do SD Elements é hospedado pela sua instância do SD Elements, então não há nada para instalar nesse caso.

Credenciais necessárias

Você vai coletar seis valores. Guarde-os em um lugar seguro enquanto configura tudo.

URL base do ZeroPath

O host que você visita para fazer login. Para o SaaS do ZeroPath, é https://zeropath.com. Tenants enterprise ou dedicados podem usar um host diferente — use o que aparece no seu navegador quando você está logado, sem nenhum caminho ao final.

ID da organização no ZeroPath

O identificador da sua organização no ZeroPath (algo como org_0123ABC…). Encontre-o em Settings → General no dashboard, ou pergunte ao seu assistente de IA depois que o MCP do ZeroPath estiver conectado: “Qual é o ID da minha organização no ZeroPath?”

Token de API do ZeroPath (ID + segredo)

Vá em Settings → API keys, clique para criar uma chave, dê um nome, escolha uma expiração e copie tanto o ID do token quanto o segredo do token. O segredo é exibido apenas uma vez. Criar um token exige o papel de admin. Veja API Tokens para a referência completa.

URL base do SD Elements

O host que você visita para usar o SD Elements, por exemplo https://<your-sde-instance>.sdelements.com. Apenas o host, sem caminho ao final.

Chave de API do SD Elements

Crie um token de API dentro do SD Elements (no seu perfil de usuário / tokens de API) e copie-o. Siga o guia do usuário e a documentação da API do SD Elements para o fluxo de token deles, e não o do ZeroPath. Note que você não vai encontrar uma entrada do ZeroPath na página de integrações do SD Elements, e não precisa de uma — criar essa chave de API e fornecê-la ao ZeroPath é tudo o que o lado do SD Elements exige.Recomendamos criar um usuário dedicado no SD Elements chamado ZeroPath e gerar este token como esse usuário. O SD Elements atribui cada nota de verificação ao dono do token, então os resultados passam a mostrar “ZeroPath” como quem atualizou, em vez do nome de uma pessoa (veja as Perguntas frequentes).

ID do projeto no SD Elements

O ID numérico exibido na URL do projeto quando você o visualiza no SD Elements (por exemplo, …/projects/8/). Você fornecerá um ID de projeto por mapeamento.

Acesso de rede

Se o seu repositório ou a sua instância do SD Elements estiver atrás de uma VPN ou em uma rede privada, libere os endereços IP de saída do ZeroPath:

112.134.81
232.87.32
37.222.237

Provisione seu tenant ZeroPath

Se você ainda não tem um tenant, solicite um através do seu contato na Security Compass ou em support@zeropath.com. Use uma organização por prova de conceito; clientes distintos recebem tenants separados para isolamento.

Peça à ZeroPath para habilitar o Security Compass

A integração com o Security Compass é ativada por ambiente pela ZeroPath. Depois que seu tenant existir, peça ao seu contato na ZeroPath — ou envie um e-mail para support@zeropath.com — para habilitar a integração do Security Compass para a sua organização. Até que ela seja habilitada, a opção Security Compass não aparecerá em Settings → Integrations.

Adicione colegas de equipe

Depois de entrar, você pode adicionar colegas de equipe. Os papéis são Admin, Member e Viewer — veja Teams & Permissions para o que cada um pode fazer.

Peça ao seu assistente
Use o dashboard

“Convide alice@example.com como admin para a minha organização no ZeroPath.” O assistente adiciona o membro e confirma o papel atribuído.

Conecte um repositório

O ZeroPath escaneia um repositório Git, então conecte um antes de mapeá-lo. Escolha o provedor que você usa; o passo a passo completo de cada um está no Guia Rápido.

Peça ao seu assistente
Use o dashboard

“Mostre as instalações do GitHub disponíveis para a minha organização,” e depois “Conecte o repositório em https://github.com/acme/web ao ZeroPath.” O assistente lista o que consegue alcançar e adiciona o repositório que você indicar.

Notas específicas por provedor:

GitHub. Use o botão Install GitHub App na página Add Repositories. O GitHub App solicita acesso de leitura ao código, além de leitura/escrita em checks e pull requests, para que o ZeroPath possa publicar resultados e abrir PRs de correção.
GitLab. Use um token de acesso de grupo ou de projeto, ou um PAT de conta dedicada, com o escopo api. Maintainer é recomendado para webhooks de projeto automáticos. Conecte em Add Repositories → GitLab. Veja o guia de integração com GitLab para fluxos com papéis inferiores, restrições de repositórios e requisitos de pipeline de MRs.
Bitbucket. Conecte através de Add Repositories → Bitbucket, conforme descrito no Guia Rápido.
Azure Repos. Conecte a partir da mesma página Add Repositories.

Você também pode conectar um repositório por URL direta com um token de acesso, que é como os repositórios são configurados em muitos pilotos do SD Elements. Conexões por token escaneiam normalmente, mas não recebem o conjunto completo de recursos do GitHub App (checks automáticos em PRs, PRs de correção). Use o GitHub App quando quiser esses recursos.

Se o repositório estiver atrás de uma VPN, aplique a mesma liberação de rede indicada em Antes de começar.

Configure seu projeto SD Elements

Você deve terminar esta seção com um projeto SD Elements cujo questionário (survey) esteja completo e cujas contramedidas estejam populadas, pronto para mapear. O ZeroPath não muda a forma como você constrói um projeto no SD Elements — crie o projeto, complete o questionário e revise as contramedidas resultantes usando o guia do usuário do SD Elements. Um projeto típico (por exemplo, um perfil de aplicação web Django ou .NET) termina com algumas centenas de contramedidas distribuídas por fases como Requirements e Development.

Peça ao seu assistente
Use a interface do SD Elements

Com o MCP do SD Elements conectado, você pode explorar sem sair do chat: “Liste minhas unidades de negócio no SD Elements,” “Encontre o projeto chamado ‘Payment Service’ no SD Elements,” ou “Mostre as contramedidas do projeto Payment Service no SD Elements.” O assistente retorna as unidades de negócio correspondentes, o projeto (com seu ID numérico) e a lista de contramedidas com títulos, fases e status.

Instale os servidores MCP

Dois servidores MCP conduzem o lado do assistente nesta integração:

O MCP do ZeroPath — github.com/ZeroPathAI/zeropath-mcp-server, instalado localmente. Ele cobre as ferramentas gerais do ZeroPath (ler repositórios, executar scans, inspecionar issues e regras) e as ferramentas do Security Compass (mapear projetos para repositórios, sincronizar regras, ler a auditoria) em um único servidor. Os passos de instalação também estão espelhados em MCP Installation. Ele usa os quatro valores do ZeroPath que você coletou: URL base, ID da organização, ID do token de API e segredo do token de API.
O MCP do SD Elements — hospedado em https://<your-sde-instance>.sdelements.com/mcp, autenticando com sua chave de API do SD Elements no cabeçalho sde-api-key. Não há nada para instalar nesse caso.

As três subseções abaixo fornecem uma configuração pronta para copiar e colar dos dois servidores juntos, no formato de cada cliente.

Claude Code

O caminho recomendado no Claude Code é o comando claude mcp add (veja a documentação de MCP do Claude Code). Execute estes dois comandos, substituindo seus valores:

# ZeroPath MCP (local)
claude mcp add --scope user zeropath \
  --env ZEROPATH_BASE_URL=https://zeropath.com \
  --env ZEROPATH_TOKEN_ID=<your-token-id> \
  --env ZEROPATH_TOKEN_SECRET=<your-token-secret> \
  --env ZEROPATH_ORG_ID=<your-org-id> \
  -- uvx --from git+https://github.com/ZeroPathAI/zeropath-mcp-server zeropath-mcp-server

# SD Elements MCP (remote HTTP)
claude mcp add --scope user --transport http sde-mcp-server \
  https://<your-sde-instance>.sdelements.com/mcp \
  --header "sde-api-key: <your-sde-api-key>"

Todas as opções vêm antes do nome do servidor, e o -- separa o nome do comando que inicia o servidor. Se você preferir um arquivo, os mesmos dois servidores vão sob a chave mcpServers no .mcp.json.

Cursor

O Cursor lê servidores MCP de ~/.cursor/mcp.json (global) ou .cursor/mcp.json (por projeto), sob a chave mcpServers (veja a documentação de MCP do Cursor):

{
  "mcpServers": {
    "zeropath": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ZeroPathAI/zeropath-mcp-server", "zeropath-mcp-server"],
      "env": {
        "ZEROPATH_BASE_URL": "https://zeropath.com",
        "ZEROPATH_TOKEN_ID": "<your-token-id>",
        "ZEROPATH_TOKEN_SECRET": "<your-token-secret>",
        "ZEROPATH_ORG_ID": "<your-org-id>"
      }
    },
    "sde-mcp-server": {
      "url": "https://<your-sde-instance>.sdelements.com/mcp",
      "headers": {
        "sde-api-key": "<your-sde-api-key>"
      }
    }
  }
}

GitHub Copilot

O GitHub Copilot no VS Code lê servidores MCP de .vscode/mcp.json (por workspace) ou do seu settings.json de usuário, sob a chave servers (veja a documentação de MCP do GitHub). O bloco do SD Elements aqui corresponde à configuração que sua instância do SD Elements fornece:

{
  "servers": {
    "zeropath": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ZeroPathAI/zeropath-mcp-server", "zeropath-mcp-server"],
      "env": {
        "ZEROPATH_BASE_URL": "https://zeropath.com",
        "ZEROPATH_TOKEN_ID": "<your-token-id>",
        "ZEROPATH_TOKEN_SECRET": "<your-token-secret>",
        "ZEROPATH_ORG_ID": "<your-org-id>"
      }
    },
    "sde-mcp-server": {
      "url": "https://<your-sde-instance>.sdelements.com/mcp",
      "headers": {
        "sde-api-key": "<your-sde-api-key>"
      }
    }
  }
}

Verificação rápida. Depois que um cliente estiver configurado, pergunte ao seu assistente: “Mostre a integração do Security Compass atualmente configurada para a minha organização no ZeroPath.” Você verá a integração existente e seus mapeamentos, ou uma confirmação de que nenhuma foi configurada ainda.

Acesso pela API

Todas as operações de gerenciamento da integração do Security Compass estão disponíveis pela API do ZeroPath, além do dashboard e do servidor MCP. Autentique-se com seu token de API (veja API Tokens) e use as seguintes operações:

Operação	Endpoint HTTP	O que faz
`securityCompass.getIntegration`	`POST /api/v2/securityCompass/getIntegration`	Busca a integração e todos os mapeamentos de projeto de uma organização
`securityCompass.upsertIntegration`	— (apenas dashboard)	Cria ou atualiza a conexão com o SD Elements (URL base, token de API, estado habilitado, mapeamento de status de tarefa padrão)
`securityCompass.deleteIntegration`	— (apenas dashboard)	Remove a integração inteira e todos os seus mapeamentos de projeto
`securityCompass.testConnection`	`POST /api/v2/securityCompass/testConnection`	Valida as credenciais armazenadas contra um projeto específico do SD Elements
`securityCompass.listProjects`	— (apenas dashboard)	Lista os projetos do SD Elements acessíveis com as credenciais armazenadas
`securityCompass.listTaskStatuses`	`POST /api/v2/securityCompass/listTaskStatuses`	Lista os status de tarefa que existem na instância do SD Elements conectada (id, slug, nome, significado)
`securityCompass.addProjectMapping`	`POST /api/v2/securityCompass/addProjectMapping`	Vincula um projeto SD Elements a um repositório ZeroPath, inicia a sincronização de regras inicial e, quando a integração está habilitada, envia o último scan completo finalizado do repositório
`securityCompass.updateProjectMapping`	`POST /api/v2/securityCompass/updateProjectMapping`	Define o mapeamento de status de tarefa de um mapeamento, ou o limpa para que o mapeamento herde o padrão da integração
`securityCompass.removeProjectMapping`	`POST /api/v2/securityCompass/removeProjectMapping`	Desvincula um mapeamento de projeto (e limpa as regras geradas quando não restam outros mapeamentos para o repositório)
`securityCompass.syncRules`	`POST /api/v2/securityCompass/syncRules`	Dispara manualmente uma sincronização de contramedidas para regras em um mapeamento
`securityCompass.pushLatestScan`	`POST /api/v2/securityCompass/pushLatestScan`	Enfileira um envio de resultados do último scan completo finalizado do repositório para um mapeamento
`securityCompass.getMappingAudit`	`POST /api/v2/securityCompass/getMappingAudit`	Recupera o detalhamento de cobertura por contramedida de um mapeamento
`securityCompass.getCountermeasureDetail`	— (apenas dashboard)	Busca o detalhe completo de uma única contramedida (descrição, how-tos, CWEs, issues vinculadas)
`securityCompass.getLinkedIssues`	`POST /api/v2/securityCompass/getLinkedIssues`	Lista os achados abertos do ZeroPath vinculados a uma contramedida específica
`securityCompass.getSyncHistory`	`POST /api/v2/securityCompass/getSyncHistory`	Recupera o log de auditoria do Security Compass de uma organização

As operações com um endpoint HTTP listado estão disponíveis tanto pelo servidor MCP quanto como requisições HTTP POST diretas para /api/v2/securityCompass/{procedure}. Todas as requisições precisam incluir os cabeçalhos do seu token de API (veja API Tokens). As operações upsertIntegration e deleteIntegration (credenciais do SD Elements) estão disponíveis apenas pelo dashboard: chamadas com token de API não podem fornecer nem rotacionar credenciais do SD Elements. O endpoint testConnection usa as credenciais já salvas no dashboard; ele não aceita um token de API do SD Elements diretamente. Gerenciar a integração (criar, excluir, adicionar, atualizar e remover mapeamentos, sincronizar, enviar o último scan) exige o papel de admin. As operações de leitura (obter a integração, a auditoria, as issues vinculadas e o histórico de sincronização) estão disponíveis a todos os membros da organização. Listar projetos e status de tarefa do SD Elements (listProjects, listTaskStatuses) também exige o papel de admin, porque ambas chamam o SD Elements com o token armazenado em nome de quem faz a chamada.

Ao atualizar a URL base do SD Elements pela API, você precisa fornecer um sdeApiToken se a nova URL apontar para uma origem diferente da armazenada. Isso evita que o token armazenado seja encaminhado a outro host.

addProjectMapping e updateProjectMapping aceitam um objeto opcional taskStatusMapping com até três chaves: pass, partial e fail. Cada valor é o slug de um status de tarefa do SD Elements, como retornado por listTaskStatuses. Uma chave ausente significa “deixar o status da tarefa como está”, {} significa apenas a nota de verificação, e null em um mapeamento significa “herdar o padrão da integração”. Todo slug precisa existir na instância conectada e ter o significado DONE ou TODO; um slug cujo significado é NA é rejeitado. As respostas de mapeamento trazem tanto o taskStatusMapping do próprio mapeamento quanto o effectiveTaskStatusMapping que os envios de fato usam. Veja Mapeamento de status de tarefa para o que o mapeamento faz.

Cada mapeamento retornado por getIntegration traz o resultado do seu último envio em lastPushStats, com as chaves issuesMapped, countermeasuresUpdated, statusChangesRequested (notas que pediram ao SD Elements uma mudança de status), passCount, partialCount, failCount, notApplicableSkipped (contramedidas deixadas em Not Applicable), updateFailures, mappingFailures, unmapped e linksPersisted. getSyncHistory retorna os eventos de auditoria security_compass.mapping_update (um mapeamento de status de tarefa foi alterado) e security_compass.push_requested (um envio foi solicitado sob demanda), junto com os eventos de sincronização, envio, mapeamento, integração e teste de conexão.

Fluxo de trabalho de ponta a ponta

Este é o manual de operação. Cada etapa tem um prompt para o assistente e, quando existe, o caminho correspondente no dashboard. O lado do dashboard fica em Settings → Integrations: o card Security Compass mostra a conexão, seus mapeamentos e o status de sincronização de cada mapeamento; o ícone de engrenagem abre Manage Security Compass integration, onde ficam as ações de mapeamento.

Conecte sua instância do SD Elements

Uma vez por organização, e feito no dashboard do ZeroPath. Obtenha sua chave de API no dashboard do SD Elements (veja Credenciais necessárias), depois vá em Settings → Integrations → Add Integration → Security Compass. No diálogo, informe a SD Elements Base URL e o API Token, deixe Enable Integration ligado e clique em Create Integration.

Duas coisas para saber sobre esta etapa:

Forneça a chave de API somente através do dashboard do ZeroPath. Não a cole em um assistente de IA — mantenha credenciais fora do chat.
Não há nada para configurar do lado do SD Elements. Você não vai encontrar uma integração do ZeroPath na página de integrações do SD Elements, e não precisa de uma; fornecer a chave de API aqui é suficiente.

Teste a conexão

Confirme que as credenciais funcionam e que o ZeroPath consegue ver as contramedidas de um projeto.

Peça ao seu assistente
Use o dashboard

“Teste minha conexão do Security Compass contra o projeto <SDE project ID>.” O assistente relata o sucesso e quantas contramedidas vê nesse projeto.

Atualize as credenciais

Quando você rotacionar a chave de API do SD Elements (ou apontar para uma instância diferente), salve a conexão novamente. Isso sobrescreve as credenciais e a URL base armazenadas, mas mantém intactos os mapeamentos de projeto existentes. Se a nova URL base apontar para uma instância diferente do SD Elements, o ZeroPath também confere cada status de tarefa que seus mapeamentos nomeiam (o padrão da integração e o mapeamento próprio de cada projeto) com essa instância antes de salvar. Um status que não existe lá, ou que significa Not Applicable, bloqueia o salvamento com um erro que nomeia o mapeamento; atualize o mapeamento ou crie o status na nova instância e salve novamente. Se a lista de status da nova instância não puder ser lida (por exemplo, o novo token de API não tem permissão para listar status de tarefa), os mapeamentos que nomeiam apenas os slugs integrados DONE e TODO ainda são salvos, porque esses status existem em toda instância; um mapeamento que nomeia um status personalizado bloqueia o salvamento com um erro que nomeia esse status. Assim como a conexão inicial, isso é feito no dashboard — obtenha a nova chave no dashboard do SD Elements em vez de entregá-la a um assistente de IA. Em Manage Security Compass integration → Connection Settings, atualize a Base URL ou o API Token e clique em Save Settings. Deixar o token em branco mantém o atual.

Mapeie um projeto para um repositório

Um mapeamento vincula um projeto SD Elements a um repositório. Você pode mapear vários projetos para um repositório, e um projeto para vários repositórios.

Peça ao seu assistente
Use o dashboard

“Mapeie o projeto <ID> do SD Elements para o repositório <repo name> no ZeroPath.” O assistente cria o mapeamento e o confirma.

Sincronize regras a partir das contramedidas

A sincronização busca as contramedidas do projeto, classifica cada uma e cria regras no ZeroPath onde forem necessárias. O trabalho roda em segundo plano — pode levar alguns minutos para um projeto grande. O mapeamento mostra um status running enquanto busca as contramedidas, classifica a cobertura e cria as regras, e então muda para um resumo success quando termina. Uma contramedida que não pode ser classificada é pulada, em vez de fazer toda a execução falhar.

Peça ao seu assistente
Use o dashboard

“Sincronize as regras do mapeamento de <project> para <repo>.” O assistente inicia a sincronização (ela roda em segundo plano) e, quando termina, relata um resumo do tipo: 356 contramedidas — 274 cobertas pela análise integrada, um conjunto coberto por regras em linguagem natural recém-criadas e 51 não suportadas atualmente.

Apenas uma sincronização roda por mapeamento por vez. Se você solicitar outra enquanto uma está em andamento, o ZeroPath informa que uma sincronização já está em execução, em vez de iniciar uma segunda.

Revise a auditoria do mapeamento

A auditoria é o detalhamento por contramedida: para cada tarefa, se o ZeroPath a cobre com a análise integrada, a cobre com uma regra em linguagem natural gerada automaticamente ou ainda não a suporta. Este é o artefato que mais interessa aos revisores de segurança.

Peça ao seu assistente
Use o dashboard

“Mostre a auditoria do mapeamento do projeto <ID>.” O assistente lista cada contramedida com sua categoria de cobertura.

Dispare um scan

Peça ao seu assistente
Use o dashboard

“Execute um scan completo em <repo>.” O assistente inicia o scan e confirma que ele foi enfileirado.

Verifique o histórico de sincronizações e scans

Peça ao seu assistente
Use o dashboard

“Mostre os eventos recentes de sincronização do Security Compass” e “Mostre os scans recentes em <repo>.” O assistente retorna o log de sincronização (entradas de início, busca e conclusão, com contagens) e o histórico de scans.

Revise os achados e os resultados no SD Elements

Quando um scan completo termina, o ZeroPath enfileira automaticamente um envio (push) de resultados ao SD Elements para cada mapeamento de projeto vinculado ao repositório. O envio de cada mapeamento roda de forma independente em segundo plano: se um repositório está mapeado para vários projetos SD Elements, cada projeto recebe seu próprio envio, e uma falha em um não afeta os outros. O envio normalmente termina poucos minutos depois do fim do scan. O envio associa os achados do scan às contramedidas que eles violam (veja Como os achados são associados às contramedidas) e escreve uma nota de verificação em cada contramedida suportada no SD Elements. A nota traz um de três resultados:

Resultado	Quando o ZeroPath o reporta
Pass	Nenhum achado está associado à contramedida. Reportado com confiança alta.
Partial	O ZeroPath não conseguiu concluir a análise de um ou mais achados que podem pertencer à contramedida, ou os únicos achados vinculados a ela são correspondências secundárias cuja contramedida principal é outra. Reportado com confiança baixa.
Fail	Um ou mais achados têm esta contramedida como correspondência principal. Reportado com confiança alta.

A lista Findings da nota depende do resultado. Uma nota Pass tem a lista vazia. Uma nota Fail tem uma entrada por achado, escrita como <título> [severity N], até 50 entradas; além disso, uma última entrada traz a contagem dos achados restantes e remete ao Reference/Evidence. Uma nota Partial tem uma única entrada com a contagem de achados que o ZeroPath não conseguiu analisar por completo, ou a contagem de achados vinculados apenas como correspondências secundárias. O campo Reference/Evidence da nota traz o resumo legível: o ID do scan, o repositório e a data em que o scan terminou, depois a frase do resultado, um link por achado no ZeroPath e um link para todos os achados abertos do repositório. O texto fica abaixo de 8.000 caracteres; quando as linhas de achados não cabem, a lista termina com ”… and N more”. Cada envio substitui o resultado de verificação anterior na contramedida, então o SD Elements sempre mostra o scan mais recente. Por padrão o envio não muda mais nada: o status da tarefa da contramedida no SD Elements permanece como está. Um admin pode fazer com que um resultado também defina o status da tarefa; veja Mapeamento de status de tarefa abaixo. Você pode revisar os achados no ZeroPath e no SD Elements:

Peça ao seu assistente
Use o dashboard

“Resuma os achados do scan mais recente de <repo>.” ou “Mostre os eventos recentes de sincronização do Security Compass” para verificar o status do envio.

Mapeamento de status de tarefa

Um mapeamento de status de tarefa diz ao ZeroPath qual status de tarefa do SD Elements, se algum, cada resultado de verificação deve definir. Ele é opcional. Sem um, o ZeroPath escreve a nota de verificação e não toca no status da tarefa. Você o configura em dois níveis:

Padrão da integração. Em Manage Security Compass integration → Connection Settings, o bloco Default task status mapping tem um menu suspenso por resultado: When verification is Pass, Partial e Fail. Cada um oferece Leave task status unchanged mais todos os status de tarefa da sua instância do SD Elements, exibidos como nome (significado), por exemplo Complete (DONE). Os status cujo significado é Not Applicable aparecem na lista, mas não podem ser selecionados. Salve com Save Settings.
Por mapeamento de projeto. Na linha de um mapeamento, o ícone Task status mapping abre um editor inline com duas opções: Use integration default (com um resumo do que o padrão faz atualmente) ou Custom for this project, que mostra os mesmos três menus suspensos apenas para este mapeamento.

Um mapeamento no padrão da integração o acompanha: mude o padrão e todo mapeamento que o herda muda junto. Um mapeamento com configuração própria a mantém até você voltar ao padrão. Você pode escolher qualquer status que já exista na sua instância do SD Elements com o significado Complete (DONE) ou Incomplete (TODO). Isso inclui os status integrados Complete e Incomplete e qualquer status personalizado que o administrador do seu SD Elements tenha criado, por exemplo um status ZeroPath-Verified com significado Complete, para que uma aprovação fique visivelmente atribuída a um scan e não a uma pessoa. O ZeroPath não cria status no SD Elements; crie o status personalizado lá primeiro (veja o guia do SD Elements sobre status de tarefa personalizados). Not Applicable nunca é oferecido como destino. O ZeroPath nunca altera uma contramedida que uma pessoa marcou como Not Applicable. Quando alguém definiu uma contramedida com um status cujo significado é Not Applicable, o ZeroPath ainda escreve a nota de verificação, mas não envia nenhuma mudança de status para essa tarefa, independentemente do mapeamento. O mesmo acontece quando o status atual da contramedida não pode ser lido, por exemplo porque ela deixou de ser relevante para o risco no projeto: sem um status conhecido, o ZeroPath não consegue saber se uma pessoa a marcou como Not Applicable, então escreve a nota e deixa o status como está. Sempre que o mapeamento nomeia pelo menos um status, o ZeroPath o confere com a lista atual de status antes de cada envio. Se um status configurado não existe mais na instância (por exemplo, um status personalizado foi excluído ou renomeado), ou se o significado dele foi alterado para Not Applicable, o envio falha imediatamente com um erro no mapeamento que nomeia o status; um erro de configuração não é repetido. Escolha outro status, ou restaure-o no SD Elements, e envie novamente. Se a própria lista de status não puder ser lida (por exemplo, o token de API não tem permissão para listar status de tarefa), um mapeamento que nomeia apenas os slugs integrados DONE e TODO ainda prossegue, porque esses status existem em toda instância; um mapeamento que nomeia um status personalizado falha com um erro que nomeia o status. Um mapeamento sem nenhum status nomeado nunca lê a lista.

Peça ao seu assistente
Use o dashboard

“Quais status de tarefa do SD Elements o ZeroPath pode definir?” lista os status da sua instância. Depois: “Defina o mapeamento de status de tarefa do mapeamento de <project> para <repo>: pass para ZeroPath-Verified, fail para Incomplete, partial sem alteração.” O assistente aplica o mapeamento e o confirma. “Use o padrão da integração nesse mapeamento” volta ao padrão.

Criar um mapeamento em uma integração habilitada envia ao SD Elements o último scan completo finalizado do repositório assim que a primeira sincronização de regras do mapeamento é concluída, então você não precisa de um novo scan para ver resultados em um projeto que acabou de vincular. Depois disso, os envios acontecem automaticamente sempre que um scan completo termina. Para enviar novamente sem um novo scan, por exemplo depois de mudar o mapeamento de status de tarefa, use Push latest scan:

Peça ao seu assistente
Use o dashboard

“Envie o scan mais recente de <repo> ao SD Elements.” O assistente enfileira o envio e informa qual scan usou, ou avisa que o repositório ainda não tem um scan completo finalizado.

Um envio é recusado enquanto um envio desse mesmo scan ainda está em execução (aguarde terminar e tente de novo) e enquanto a integração está desabilitada (habilite-a primeiro). Um reenvio de um scan já enviado roda de novo com o mapeamento atual e os achados abertos como estão agora.

Integrações criadas antes de o mapeamento de status de tarefa existir receberam um padrão de Pass → Complete, Partial → Incomplete, Fail → Incomplete, para que seus projetos SD Elements continuem se comportando como antes nos scans completos. Duas coisas mudaram para elas: contramedidas que uma pessoa marcou como Not Applicable não são mais sobrescritas, e scans de PR não enviam mais (apenas scans completos e Push latest scan enviam). Edite o padrão da integração se quiser outra política.

Execute o pipeline inteiro de uma vez

Você não precisa fazer as etapas uma de cada vez. Com o MCP do ZeroPath e o MCP do SD Elements conectados, um único prompt pode conduzir o pipeline inteiro:

“Configure <repo> com o projeto <ID> do SD Elements: crie o mapeamento, sincronize as regras, execute a auditoria, dispare um scan completo e resuma o que voltou.”

O assistente cria o mapeamento, executa a sincronização (e relata o detalhamento SAST / regras em linguagem natural / não suportadas), apresenta a auditoria, inicia o scan, resume os achados quando o scan termina e informa quando o ZeroPath enviou os resultados de volta ao SD Elements.

Como o ZeroPath transforma contramedidas em regras

Análise do repositório inteiro

O ZeroPath analisa o repositório inteiro. Ele identifica as aplicações dentro dele, mapeia sources, sinks e as relações entre eles, e constrói um modelo de ameaças por aplicação. Falhas tradicionais são avaliadas de source a sink; controles de nível mais alto são avaliados de forma agêntica contra esse modelo de ameaças. Para uma visão mais profunda, veja o SAST Overview e as Custom Rules. Quando você sincroniza um mapeamento, cada contramedida cai em uma de três categorias:

Cobertura integrada — a análise padrão do ZeroPath já detecta essa classe de problema (por exemplo, “Validate all forms of input” ou “Set HttpOnly flag on session cookies”).
Regra em linguagem natural — a contramedida corresponde a uma política que o ZeroPath aplica através de uma regra personalizada gerada automaticamente e limitada ao repositório mapeado (por exemplo, um requisito de log de auditoria ou de política de senhas).
Não suportada — a contramedida não está relacionada ao desenvolvimento de código, ou não pode ser implementada ou verificada via análise estática (por exemplo, “Verify that penetration testing has been performed”). Essas são puladas durante a sincronização.

Onde os achados mapeados aparecem

Quando um scan completo termina, o ZeroPath envia automaticamente os resultados ao seu projeto SD Elements. Cada achado é associado à contramedida que viola, e cada contramedida suportada recebe uma nota de verificação (Pass, Partial ou Fail) cujo texto em Reference/Evidence leva de volta aos achados no ZeroPath. O status da tarefa no SD Elements só muda quando um admin configurou um mapeamento de status de tarefa para aquele resultado, e contramedidas que uma pessoa marcou como Not Applicable nunca são alteradas. Você também pode revisar os achados na visão padrão Issues do ZeroPath, filtrada pelo repositório, e usar a auditoria do mapeamento (etapa 6) para ver o detalhamento de cobertura por contramedida.

O que isso significa para a cobertura

De início, o ZeroPath cobre diretamente uma grande parte das contramedidas de um projeto, com boa parte do restante coberta por regras geradas automaticamente e uma cauda menor que um scan de código não consegue verificar. A auditoria (etapa 6) é o registro por contramedida de qual é qual no seu projeto.

Como os achados são associados às contramedidas

Depois de um scan, o ZeroPath associa cada achado à contramedida que ele viola mais diretamente. Duas estratégias de correspondência rodam juntas:

Correspondência por regra: achados produzidos por uma regra do ZeroPath que foi gerada a partir de uma contramedida são associados de forma determinística a essa contramedida, sem chamada de IA.
Correspondência assistida por IA: todos os outros achados são associados por um modelo de IA, com os candidatos pré-filtrados por sobreposição de CWE para melhorar a precisão. Cada achado recebe uma contramedida principal (a que conta para o resultado de verificação) e pode também ser marcado em contramedidas secundárias para rastreabilidade.

Uma contramedida sem achados associados recebe uma nota de verificação Pass. Uma contramedida com um ou mais achados principais recebe uma nota Fail com uma linha por achado (título e severidade) e, em Reference/Evidence, um link de volta para cada achado no ZeroPath. Uma contramedida cujos achados candidatos não puderam ser analisados por completo, ou que tem apenas correspondências secundárias, recebe uma nota Partial. Se a nota também muda o status da tarefa no SD Elements depende do mapeamento de status de tarefa.

Scan de PR vs. scan de branch completa

Scans completos

O modo padrão. Scans completos rodam de forma agendada (geralmente todas as noites) e constroem o cache do repositório que o ZeroPath reutiliza entre os tipos de scan. Configure o agendamento em Scanner Settings.

Scans de PR

Habilitados por repositório, os scans de PR verificam cada pull request usando o cache construído pelos scans completos. A maioria das equipes começa com scans completos na main, ganha confiança e então ativa os scans de PR. Veja PR Scanning. Scans de PR nunca enviam resultados ao SD Elements: suas descobertas cobrem apenas os arquivos alterados, então um envio a partir de um deles reportaria incorretamente todas as outras contramedidas. Apenas scans completos enviam.

Peça ao seu assistente
Use o dashboard

“Ative o scan de PR para <repo>.”

Segurança e confiança

O ZeroPath armazena credenciais de integração e registros de vulnerabilidades em um banco de dados criptografado e por tenant. O código-fonte é clonado apenas no momento do scan, dentro de um contêiner, e removido quando o scan termina. A ZeroPath executa testes de penetração externos e mantém um programa de divulgação de vulnerabilidades. O relatório SOC 2 está em andamento; uma carta de intenção está disponível mediante solicitação. Para o status de conformidade atual e para solicitar relatórios, veja os recursos abaixo.

ZeroPath Trust Center: zeropath.com/trust-center
ZeroPath Trust Portal: zeropath.trust.site

Solução de problemas

A sincronização de regras falha ao buscar tarefas do SD Elements (404)

O ID do projeto SD Elements no mapeamento não existe mais no tenant SD Elements conectado. Confirme que o projeto existe no SD Elements e adicione o mapeamento novamente com o ID correto.

A chave de API não está visível no dashboard

Criar um token de API do ZeroPath exige o papel de admin. Se você tem o papel de Viewer ou Member, peça a um admin da organização que crie o token para você. Veja API Tokens.

Um repositório atrás de uma VPN não pode ser escaneado

O tráfego de saída do ZeroPath precisa alcançar o repositório. Libere os IPs de saída do ZeroPath (veja Acesso de rede).

A integração está apontando para a instância errada do SD Elements

Se você mantém mais de uma implantação do SD Elements, atualize a URL base e a chave de API da conexão (etapa 3) para apontar para a correta. Os mapeamentos existentes são preservados.

"Save connection settings (Base URL) first"

No dashboard, salve as configurações de conexão (URL base e token) antes de testar um projeto ou adicionar um mapeamento. O Test Connection roda contra a URL base salva.

A sincronização de regras diz que já está em execução

Apenas uma sincronização roda por mapeamento por vez. Aguarde a execução em andamento terminar e então inicie novamente.

A auditoria do mapeamento está vazia

A auditoria só fica disponível após uma sincronização bem-sucedida. Execute a sincronização do mapeamento primeiro, depois visualize ou exporte a auditoria.

Os status das contramedidas no SD Elements não atualizam depois de um scan

Verifique nesta ordem:

Há um mapeamento de status de tarefa configurado? Por padrão o ZeroPath escreve apenas a nota de verificação e deixa o status da tarefa como está. Confira o padrão da integração e a configuração do próprio mapeamento (veja Mapeamento de status de tarefa). Se a nota de verificação está na contramedida no SD Elements, o envio funcionou e nenhuma mudança de status foi solicitada.
O envio rodou? Confira o status do envio no card do mapeamento em Settings → Integrations → Security Compass. Se o envio falhou, ele é repetido automaticamente; uma falha persistente aparece como erro no mapeamento. Confirme que a integração continua habilitada e que a chave de API do SD Elements não foi rotacionada (se foi, atualize-a na etapa 3).
O mapeamento foi criado depois do último scan? Criar um mapeamento em uma integração habilitada envia o último scan completo finalizado automaticamente. Scans de PR nunca enviam. Para enviar de novo, por exemplo depois de mudar o mapeamento, use Push latest scan na linha do mapeamento.
A contramedida está como Not Applicable? O ZeroPath nunca altera uma contramedida que uma pessoa marcou como Not Applicable. Mude o status manualmente no SD Elements se ela deve voltar a ser verificada.

O envio falhou porque um status configurado do SD Elements não existe ou significa Not Applicable

Um mapeamento de status de tarefa aponta para um status que não está mais na sua instância do SD Elements (geralmente um status personalizado que foi excluído ou renomeado), ou para um cujo significado foi alterado para Not Applicable depois de ser mapeado. O ZeroPath confere cada status configurado com a instância antes de cada envio e não recorre a outro status. Como o problema está na configuração, o envio é marcado como falho de imediato, sem as repetições automáticas que um erro transitório recebe. Aponte o padrão da integração ou a configuração própria do mapeamento para um status existente com significado Complete ou Incomplete (ou restaure o status no SD Elements) e clique em Push latest scan.Um erro relacionado diz “Cannot validate the configured SD Elements status(es) … because <host> did not return its task statuses”. O mapeamento nomeia um status personalizado, e o token de API não conseguiu listar os status de tarefa da instância, então o ZeroPath não pôde confirmar que o status existe. Verifique as permissões do token no SD Elements, ou mapeie os status integrados Complete e Incomplete, que não precisam dessa consulta.

Os resultados foram enviados ao SD Elements antes de a primeira sincronização de regras terminar

O ZeroPath aguarda uma sincronização de regras bem-sucedida antes de enviar os resultados de um scan. Se um scan terminou antes de a primeira sincronização concluir, o envio é adiado automaticamente e tentado de novo quando a sincronização tem sucesso; nenhuma ação é necessária.

Perguntas frequentes

Um projeto SD Elements pode ser mapeado para vários repositórios?

Sim — e vários projetos podem ser mapeados para um repositório.

Quais provedores de controle de versão são suportados?

GitHub, GitLab, Bitbucket, Azure Repos, Gerrit, Git genérico e CVS.

O ZeroPath pode rodar on-premises junto a um SD Elements on-premises?

A configuração recomendada hoje é SaaS. Para requisitos on-premises, fale com o suporte da ZeroPath.

Existe um app do ZeroPath para instalar dentro do SD Elements?

Não. Não há uma entrada do ZeroPath na página de integrações do SD Elements, e nenhuma é necessária. Crie uma chave de API do SD Elements e forneça-a ao ZeroPath (no dashboard do ZeroPath, em Settings → Integrations) — isso completa a conexão.

A conexão com o SD Elements é configurada uma vez, ou por repositório?

Uma vez por organização. Você salva uma conexão (URL base e chave de API) e então adiciona um mapeamento para cada par de projeto SD Elements e repositório.

Quais contramedidas o ZeroPath sincroniza?

As contramedidas que o SD Elements marca como relevantes para o projeto — as produzidas ao completar o questionário do projeto. Termine o questionário antes de sincronizar para que o conjunto completo esteja disponível.

Onde ficam as regras geradas, e posso editá-las?

Cada regra que o ZeroPath cria a partir de uma contramedida é uma regra personalizada padrão, limitada ao repositório mapeado. Visualize, edite ou desabilite essas regras na página de Rules ou através do seu assistente, como qualquer outra regra personalizada.

O ZeroPath altera alguma coisa no SD Elements?

Sim, mas por padrão apenas por meio de notas de verificação. Quando cada scan completo termina, o ZeroPath enfileira um envio de resultados para cada mapeamento de projeto vinculado ao repositório. Cada envio roda de forma independente em segundo plano e escreve uma nota de verificação (Pass, Partial ou Fail), com a lista de achados e links de volta ao ZeroPath, em cada contramedida suportada. O status da tarefa da contramedida permanece inalterado, a menos que um admin tenha mapeado o resultado para um status do SD Elements: qualquer status existente cujo significado seja Complete ou Incomplete, integrado ou personalizado (por exemplo “ZeroPath-Verified”), definido no nível da integração e substituível por projeto. Veja Mapeamento de status de tarefa. Contramedidas que uma pessoa marcou como Not Applicable nunca são alteradas, e o ZeroPath nunca define Not Applicable. Se um repositório está mapeado para vários projetos SD Elements, cada projeto recebe seu próprio envio. Você pode conferir o status do envio de cada mapeamento em Settings → Integrations → Security Compass.

Por que o SD Elements mostra os resultados do ZeroPath como Manual Verification?

O SD Elements rotula uma nota de verificação com o conector que a produziu. O ZeroPath não está registrado no SD Elements como conector de verificação, então o SD Elements arquiva suas notas em Manual Verification e mostra o dono do token de API como quem atualizou. O rótulo é cosmético: o resultado, a lista de achados, o texto em Reference/Evidence e qualquer mudança de status da tarefa são todos registrados. Somente a Security Compass pode registrar o ZeroPath como conector de verificação no SD Elements; até lá o rótulo permanece. Para que quem atualizou apareça como “ZeroPath”, crie um usuário dedicado no SD Elements chamado ZeroPath e gere o token de API que você fornece ao ZeroPath como esse usuário (veja Credenciais necessárias).

Minhas contramedidas mudaram no SD Elements. Como atualizo o ZeroPath?

Execute a sincronização do mapeamento novamente. O ZeroPath lê as contramedidas no momento da sincronização, então uma nova sincronização captura adições, edições e remoções.

Os servidores MCP precisam ficar em execução para os scans?

Não. Os scans rodam na infraestrutura do ZeroPath, de forma agendada ou sob demanda. Os servidores MCP são apenas a forma como você conduz a configuração e as consultas a partir do seu assistente.

Quem pode configurar a integração e criar mapeamentos?

Gerenciar a conexão e os mapeamentos (criar, atualizar, excluir, adicionar e remover mapeamentos de projeto, disparar sincronizações, enviar o último scan, listar projetos e status de tarefa do SD Elements) exige o papel de admin, seja pelo dashboard, pelo servidor MCP ou pela API. As operações de leitura, como ver a auditoria ou as issues vinculadas, estão disponíveis a todos os membros. Criar um token de API do ZeroPath também exige o papel de admin. Veja Teams & Permissions.

Prompts de assistente que você mais usará

Configuração

“Mostre a integração do Security Compass configurada para a minha organização no ZeroPath.”
“Teste minha conexão do Security Compass contra o projeto <SDE project ID>.”

Mapeamento e sincronização

“Mapeie o projeto <ID> do SD Elements para o repositório <repo> no ZeroPath.”
“Sincronize as regras do mapeamento de <project> para <repo>.”
“Mostre a auditoria do mapeamento do projeto <ID>.”

Scans e resultados

“Execute um scan completo em <repo>.”
“Mostre os eventos recentes de sincronização do Security Compass.”
“Resuma os achados do scan mais recente de <repo>.”
“Envie o scan mais recente de <repo> ao SD Elements.”

Mapeamento de status de tarefa

“Quais status de tarefa do SD Elements o ZeroPath pode definir?”
“Defina o mapeamento de status de tarefa do mapeamento de <project> para <repo>: pass para ZeroPath-Verified, fail para Incomplete, partial sem alteração.”
“Use o padrão da integração no mapeamento de <project> para <repo>.”

​Visão geral

​Antes de começar

​Contas necessárias

​Software necessário

​Credenciais necessárias

​Acesso de rede

​Provisione seu tenant ZeroPath

​Peça à ZeroPath para habilitar o Security Compass

​Adicione colegas de equipe

​Conecte um repositório

​Configure seu projeto SD Elements

​Instale os servidores MCP

​Claude Code

​Cursor

​GitHub Copilot

​Acesso pela API

​Fluxo de trabalho de ponta a ponta

​ Conecte sua instância do SD Elements

​ Teste a conexão

​ Atualize as credenciais

​ Mapeie um projeto para um repositório

​ Sincronize regras a partir das contramedidas

​ Revise a auditoria do mapeamento

​ Dispare um scan

​ Verifique o histórico de sincronizações e scans

​ Revise os achados e os resultados no SD Elements

​Mapeamento de status de tarefa

​Execute o pipeline inteiro de uma vez

​Como o ZeroPath transforma contramedidas em regras

​Análise do repositório inteiro

​Onde os achados mapeados aparecem

​O que isso significa para a cobertura

​Como os achados são associados às contramedidas

​Scan de PR vs. scan de branch completa

​Scans completos

​Scans de PR

​Segurança e confiança

​Solução de problemas

​Perguntas frequentes

​Prompts de assistente que você mais usará

Visão geral

Antes de começar

Contas necessárias

Software necessário

Credenciais necessárias

Acesso de rede

Provisione seu tenant ZeroPath

Peça à ZeroPath para habilitar o Security Compass

Adicione colegas de equipe

Conecte um repositório

Configure seu projeto SD Elements

Instale os servidores MCP

Claude Code

Cursor

GitHub Copilot

Acesso pela API

Fluxo de trabalho de ponta a ponta

Conecte sua instância do SD Elements

Teste a conexão

Atualize as credenciais

Mapeie um projeto para um repositório

Sincronize regras a partir das contramedidas

Revise a auditoria do mapeamento

Dispare um scan

Verifique o histórico de sincronizações e scans

Revise os achados e os resultados no SD Elements

Mapeamento de status de tarefa

Execute o pipeline inteiro de uma vez

Como o ZeroPath transforma contramedidas em regras

Análise do repositório inteiro

Onde os achados mapeados aparecem

O que isso significa para a cobertura

Como os achados são associados às contramedidas

Scan de PR vs. scan de branch completa

Scans completos

Scans de PR

Segurança e confiança

Solução de problemas

Perguntas frequentes

Prompts de assistente que você mais usará