API de Relatórios SonarQube#

Este artigo descreve como acessar programaticamente os relatórios de segurança do SonarQube armazenados na plataforma Procurize. Ele cobre a API REST para listar relatórios e baixá‑los nos formatos HTML, PDF e ZIP.

Visão geral#

O submódulo SonarQube Reports permite que 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 por meio de uma API REST pública que permite:

• Listar metadados de relatórios para uma organização, um grupo de projetos ou um projeto
• Baixar um único relatório em HTML, PDF ou ZIP
• Baixar relatórios selecionados como um arquivo ZIP
• Baixar todos os relatórios de um projeto ou de um grupo de projetos como um arquivo ZIP
• Obter os relatórios mais recentes do OWASP Top 10 e CWE Top 25 diretamente de um serviço SonarQube

Essas funcionalidades permitem integrações com pipelines CI/CD, sistemas GRC, dashboards internos e ferramentas de gerenciamento de risco de terceiros.

Endpoints#

Autenticação e Autorização#

Os endpoints de listagem e download de relatórios descritos neste artigo não exigem autenticação.

O endpoint POST /security/reports/fetch requer autenticação com um token de API — veja Tokens de API.

ID da Organização#

Um identificador de organização é necessário para a maioria das requisições descritas aqui. Você pode passar tanto o ID da organização (um UUID) quanto seu alias — veja Identificadores e Alias.
Você pode encontrá‑lo no painel de configurações da organização em https://dashboard.procurize.ai.
Observe que o acesso ao painel de configurações requer autorização, e o acesso ao painel de configurações da organização requer um papel de usuário de, no mínimo, Administrador nessa organização.

Identificadores e Alias#

Os parâmetros de escopo aceitam tanto o ID da entidade (um UUID) quanto um alias legível por humanos. Alias tornam as requisições mais fáceis de ler e são estáveis entre ambientes.

Por exemplo, as duas requisições a seguir são equivalentes:

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

Observação: Alias não são suportados para o parâmetro id dos endpoints de download em massa. Passe o UUID do diretório ou do projeto para GET /security/report/project-files e GET /security/report/directory-files.

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#

Retorna os relatórios de segurança disponíveis para o escopo e versão selecionados, sem o conteúdo dos arquivos. Use este endpoint para descobrir IDs de relatórios que podem ser passados aos endpoints de download.

Endpoint

GET /security/report/list

Parâmetros de Consulta

• org (opcional): ID ou alias da organização (ex.: aspose ou groupdocs). Escopo mais amplo.
• directory (opcional): ID ou alias do diretório (grupo de projetos) (ex.: aspose-imaging ou groupdocs-annotation). Escopo mais restrito.
• project (opcional): ID ou alias do projeto (ex.: aspose-imaging-net ou groupdocs-annotation-java). Escopo mais restrito.
• version (opcional): Versão exata do projeto.
• minver (opcional): Versão mínima do projeto.
• maxver (opcional): Versão máxima do projeto.

É necessário informar ao menos um dos parâmetros de escopo org, directory ou project. A prioridade dos escopos é a seguinte: se project for especificado, apenas esse projeto será pesquisado; caso contrário, se directory for especificado, todo o grupo de projetos será pesquisado; caso contrário, toda a organização (org) será pesquisada. Quando org for especificado junto com project ou directory, o alvo também será validado para pertencer àquela organização.

É necessário informar ao menos um dos parâmetros version, minver ou maxver. Se version for especificado, minver e maxver são ignorados.

Exemplo de Requisição

curl "https://api.procurize.com/security/report/list?org=aspose&version=1.0"

Escopo por grupo de projetos ou por projeto usando alias:

curl "https://api.procurize.com/security/report/list?directory=aspose-imaging&minver=1.0&maxver=2.0"

curl "https://api.procurize.com/security/report/list?project=aspose-imaging-net&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"
    }
  ]
}

Campos da Resposta

• organizationId: A organização à qual os relatórios pertencem.
• reports[].id: ID único do relatório. Passe este valor para os endpoints de download.
• reports[].projectName: Nome exibido do produto.
• reports[].projectVersion: Versão do produto.
• reports[].reportType: Tipo de relatório (OWASP Top 10 ou CWE Top 25).
• reports[].reportVersion: Versão (ano) do padrão do relatório.
• reports[].date: Data em que o relatório foi gerado.
• reports[].uploadDate: Data em que o relatório foi enviado para a Procurize.
• reports[].vulnerabilitiesCount: Número de vulnerabilidades encontradas.
• reports[].securityRating: Avaliação geral de segurança (A–E, onde A é a melhor).

Baixar Relatórios por ID#

Baixa um arquivo ZIP contendo os relatórios selecionados. Cada relatório é incluído nos formatos HTML e PDF.

Endpoint

GET /security/report/files

Parâmetros de Consulta

• org (obrigatório): ID ou alias da organização (ex.: aspose ou groupdocs).
• reports (obrigatório): IDs dos relatórios a serem incluídos. Repita o parâmetro para incluir vários relatórios.

Exemplo de Requisição

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

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.

Trabalhando com um Relatório Único#

Os endpoints /security/report/html, /security/report/pdf e /security/report/zip retornam um relatório específico e compartilham as mesmas regras de seleção.

Seleção de Relatório#

O tipo e a versão do relatório são sempre obrigatórios:

• rt (obrigatório): Tipo de relatório. Valores suportados: OWASP Top 10 e CWE Top 25.
• rv (obrigatório): Versão do relatório — o ano da edição do padrão, por exemplo 2025 para OWASP Top 10 ou 2024 para CWE Top 25.

O relatório exato é então selecionado de uma das duas formas:

• Por ID do relatório — passe id (ID do relatório) junto com project (ID ou alias do projeto) ou org (ID ou alias da organização). Não passe version neste modo.
• Por versão do projeto — passe project (ID ou alias do projeto, ex.: aspose-imaging-net ou groupdocs-annotation-java) e version (versão do projeto). O parâmetro org não é usado neste modo.

Quando project e org são ambos especificados, org é ignorado.

Obter Relatório como HTML#

Renderiza um único relatório como página HTML, ou o devolve como um arquivo HTML baixável.

Endpoint

GET /security/report/html

Parâmetros de Consulta

• rt (obrigatório): Tipo de relatório.
• rv (obrigatório): Versão do relatório.
• Parâmetros de seleção de relatório: veja Seleção de Relatório.
• download (opcional): Defina como true para devolver o HTML como download de arquivo (Content-Disposition: attachment). Quando omitido ou false, o relatório é retornado inline.

Exemplo de Requisição

curl "https://api.procurize.com/security/report/html?rt=OWASP+Top+10&rv=2025&id=00000000-0000-0000-0000-000000000004&project=aspose-imaging-net"

Para baixar o arquivo HTML em vez de renderizá‑lo inline:

curl "https://api.procurize.com/security/report/html?rt=OWASP+Top+10&rv=2025&project=aspose-imaging-net&version=1.0&download=true" -o report.html

Resposta

• Content-Type: text/html

Obter Relatório como PDF#

Retorna um único relatório como documento PDF.

Endpoint

GET /security/report/pdf

Parâmetros de Consulta

• rt (obrigatório): Tipo de relatório.
• rv (obrigatório): Versão do relatório.
• Parâmetros de seleção de relatório: veja Seleção de Relatório.

Exemplo de Requisição

curl "https://api.procurize.com/security/report/pdf?rt=CWE+Top+25&rv=2024&project=aspose-imaging-net&version=1.0" -o report.pdf

Resposta

• Content-Type: application/pdf

Obter Relatório como ZIP#

Retorna um único relatório como um arquivo ZIP que contém as versões HTML e PDF.

Endpoint

GET /security/report/zip

Parâmetros de Consulta

• rt (obrigatório): Tipo de relatório.
• rv (obrigatório): Versão do relatório.
• Parâmetros de seleção de relatório: veja Seleção de Relatório.

Exemplo de Requisição

curl "https://api.procurize.com/security/report/zip?rt=CWE+Top+25&rv=2024&id=00000000-0000-0000-0000-000000000004&org=groupdocs" -o report.zip

Resposta

• Content-Type: application/zip

Baixar Todos os Relatórios de um Projeto#

Baixa um arquivo ZIP contendo todos os relatórios do projeto especificado, nos formatos HTML e PDF.

Endpoint

GET /security/report/project-files

Parâmetros de Consulta

• id (obrigatório): ID do projeto. Alias não são suportados; passe o UUID do projeto.
• rt (opcional): Filtrar por tipo de relatório. Valores suportados: OWASP Top 10 e CWE Top 25.
• rv (opcional): Filtrar por versão do relatório (ano).
• version (opcional): Filtrar por versão do projeto.

Se nenhum filtro for especificado, todos os relatórios do projeto serão incluídos. Os filtros podem ser combinados e são aplicados de forma independente.

Exemplo de Requisição

curl "https://api.procurize.com/security/report/project-files?id=00000000-0000-0000-0000-000000000005" -o project-reports.zip

Resposta

• Content-Type: application/zip

Baixar Todos os Relatórios de um Grupo de Projetos#

Baixa um arquivo ZIP contendo os relatórios de todos os projetos no diretório (grupo de projetos) especificado, nos formatos HTML e PDF.

Endpoint

GET /security/report/directory-files

Parâmetros de Consulta

• id (obrigatório): ID do diretório (grupo de projetos). Alias não são suportados; passe o UUID do diretório.
• rt (opcional): Filtrar por tipo de relatório. Valores suportados: OWASP Top 10 e CWE Top 25.
• rv (opcional): Filtrar por versão do relatório (ano).
• version (opcional): Filtrar por versão do projeto.

Se nenhum filtro for especificado, os relatórios de todos os projetos no diretório serão incluídos. Os filtros podem ser combinados e são aplicados de forma independente.

Exemplo de Requisição

curl "https://api.procurize.com/security/report/directory-files?id=00000000-0000-0000-0000-000000000006" -o directory-reports.zip

Resposta

• Content-Type: application/zip

Buscar Relatórios do SonarQube#

Envia os dados mais recentes de relatórios de segurança de um produto a partir de um serviço SonarQube para a Procurize. O serviço recupera os últimos dados de issues do SonarQube, converte‑os em representações JSON das versões mais recentes dos relatórios OWASP Top 10 e CWE Top 25, e os devolve na resposta.

Endpoint

POST /security/reports/fetch

Autenticação

Este endpoint requer um token de API, passado no cabeçalho X-API-Key. Para detalhes sobre como gerar e usar tokens, veja Tokens de API.

Parâmetros de Consulta

A origem do SonarQube é selecionada de uma das duas formas:

• Por projeto — passe project (ID ou alias do projeto — veja Identificadores e Alias). Não passe url nem key.
• Por serviço SonarQube — passe url (URL do serviço SonarQube) e key (chave do projeto SonarQube) juntos. Não passe project.

Exemplo de Requisição

Buscar o relatório para um projeto pelo seu alias:

curl -X POST "https://api.procurize.com/security/reports/fetch?project=aspose-imaging-net" \
  -H "X-API-Key: YOUR_API_TOKEN"

Buscar o relatório diretamente de um serviço SonarQube:

curl -X POST "https://api.procurize.com/security/reports/fetch?url=https://sonarqube.example.com&key=my-project-key" \
  -H "X-API-Key: YOUR_API_TOKEN"

Exemplo de Resposta

{
  "Owasp10_2025": {
    "TOTAL_SECURITY_RATING": "A",
    "TOTAL_COUNT": 0,
    ...
  },
  "Cwe25_2025": {
    "TOTAL_SECURITY_RATING": "A",
    "TOTAL_COUNT": 0,
    ...
  }
}

A resposta é útil em pipelines de build de release para decidir se a build deve ser interrompida quando vulnerabilidades são detectadas nos formatos públicos de relatórios de segurança.

Observações

• O upload de um relatório requer permissão pessoal para o produto ao qual os relatórios pertencem. Se você não possuir essa permissão, envie a requisição mesmo assim: a plataforma retornará 403 Forbidden e notificará automaticamente os administradores da plataforma, que analisarão a solicitação e informarão a decisão.
• Nem todo serviço SonarQube pode estar registrado na plataforma Procurize. Para registrar um novo serviço, entre em contato com o administrador da plataforma; um token de administrador para esse serviço é necessário.

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 mal‑formada
• 401 Unauthorized: Token de API ausente ou inválido
• 403 Forbidden: Acesso negado (por exemplo, permissão ausente para o produto)
• 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.

Veja também:#

• Webhooks de Relatórios SonarQube
• Tokens de API – Geração & Gerenciamento

Artigos Relacionados#

O que são Relatórios de Segurança?

Repositório de relatórios de segurança

Como Configurar Relatórios de Segurança