API de Relatórios SonarQube e Webhooks

Este artigo descreve como acessar programaticamente os relatórios de segurança SonarQube armazenados na plataforma Procurize. Ele cobre a API REST para listar e recuperar relatórios, baixar arquivos de relatório e assinar notificações webhook quando novos relatórios são ingeridos.

Visão geral

O submódulo de Relatórios SonarQube permite que as organizações armazenem e gerenciem centralmente relatórios de segurança e qualidade de código gerados pelo SonarQube. A plataforma Procurize expõe esses dados através de:

• Uma API REST para recuperar metadados sobre relatórios armazenados
• Um endpoint para baixar artefatos de relatório como arquivos ZIP
• Webhooks para notificações quase em tempo real quando novos relatórios se tornam disponíveis

Essas capacidades permitem integrações com pipelines CI/CD, sistemas GRC, painéis internos e ferramentas de gestão de risco de terceiros.

Autenticação e Autorização

Todas as solicitações de API descritas neste artigo não requerem autenticação.

ID da Organização

Um ID de organização é exigido para todas as solicitações descritas aqui.
Você pode encontrá‑lo no painel de configurações da Organização em https://dashboard.procurize.ai.
Note que o acesso ao painel de configurações requer autorização, e o acesso ao painel de configurações da organização requer que o usuário possua, no mínimo, a função de Administrador naquela organização.

URL Base

Todos os endpoints da API REST são servidos sob a seguinte URL base:

https://api.procurize.com

API REST de Relatórios SonarQube

Listar Relatórios

Recupera uma lista paginada de relatórios de segurança SonarQube armazenados na plataforma.

Endpoint

GET /security/report/list

Parâmetros de Consulta

• org (obrigatório): ID da organização.
• version (opcional): A versão exata dos produtos no formato Semantic Versioning.
• minver (opcional): A versão mínima dos produtos no formato Semantic Versioning.
• maxver (opcional): A versão máxima dos produtos no formato Semantic Versioning.

Observe que ao menos um dos parâmetros version, minver ou maxver é obrigatório para a requisição.

Exemplo de Requisição

curl "https://api.procurize.com/security/report/list?org=00000000-0000-0000-0000-000000000001&version=1.0"

Exemplo de Resposta

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

Baixar Arquivo de Relatório

Baixa um arquivo ZIP contendo todos os artefatos completos do relatório SonarQube. O arquivo inclui relatórios em HTML e PDF.

Endpoint

GET /security/report/files

• org (obrigatório): ID da organização.
• reports (obrigatório): Array de IDs de relatórios.

Exemplo de Requisição

curl "https://api.procurize.com/security/report/files?org=00000000-0000-0000-0000-000000000001&reports=00000000-0000-0000-0000-000000000002&reports=00000000-0000-0000-0000-000000000003"

Resposta

• Content-Type: application/zip
• O corpo da resposta contém o arquivo ZIP binário.

Os clientes devem fazer streaming da resposta e salvá‑la em disco.

Tratamento de Erros

A API utiliza códigos de status HTTP padrão.

• 200 OK: Requisição bem‑sucedida
• 204 No Content: Relatório não existe
• 400 Bad Request: Parâmetros inválidos ou requisição malformada
• 500 Internal Server Error: Erro inesperado no servidor

Respostas de erro incluem um código de erro legível por máquina e uma mensagem legível por humanos.

Webhooks

Webhooks da Procurize permitem que sistemas externos recebam notificações quando novos relatórios SonarQube são ingeridos ou atualizados.

Configurando webhooks

Webhooks podem ser adicionados ou editados no painel de configurações da Organização, seção Relatórios de segurança, em https://dashboard.procurize.ai.
Note que o acesso ao painel de configurações requer autorização, e o acesso ao painel de configurações da organização requer que o usuário possua, no mínimo, a função de Administrador naquela organização.

Para verificar webhooks, você pode usar serviços online populares como https://webhook-test.com

Payload do Webhook

Eventos de webhook são entregues como requisições HTTP POST com um payload JSON.

Exemplo de Payload

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

Segurança do Webhook

Para garantir autenticidade, as requisições de webhook incluem um cabeçalho de assinatura gerado usando um segredo compartilhado.

• A assinatura é calculada usando HMAC-SHA256
• Os clientes devem validar a assinatura antes de processar o payload

Isso impede entregas de webhook não autorizadas ou falsificadas.

Entrega e Repetições

• Webhooks esperam uma resposta 2xx para serem considerados entregues com sucesso
• Entregas falhas são automaticamente reenviadas a cada hora.
• Eventos podem ser entregues mais de uma vez; os consumidores devem implementar processamento idempotente

Casos de Uso Típicos

• Ingerir automaticamente achados SonarQube em painéis internos de segurança
• Acionar fluxos de trabalho de conformidade quando portas de qualidade falham
• Arquivar relatórios de segurança para auditorias e revisões de risco de fornecedores
• Manter sistemas de terceiros sincronizados com a postura de segurança de código mais recente