API dei report SonarQube#

Questo articolo descrive come accedere programmaticamente ai report di sicurezza SonarQube memorizzati nella piattaforma Procurize. Copre l’API REST per elencare i report e scaricarli nei formati HTML, PDF e ZIP.

Panoramica#

Il sotto‑modulo SonarQube Reports consente alle organizzazioni di archiviare e gestire centralmente i report di sicurezza e di qualità del codice generati da SonarQube. La piattaforma Procurize espone questi dati tramite un’API REST pubblica che permette di:

• Elencare i metadati dei report per un’organizzazione, un gruppo di progetti o un progetto
• Scaricare un singolo report in formato HTML, PDF o ZIP
• Scaricare i report selezionati come archivio ZIP
• Scaricare tutti i report di un progetto o di un gruppo di progetti come archivio ZIP
• Recuperare gli ultimi report OWASP Top 10 e CWE Top 25 direttamente da un servizio SonarQube

Queste funzionalità consentono integrazioni con pipeline CI/CD, sistemi GRC, dashboard interne e strumenti di gestione del rischio di terze parti.

Endpoint#

Autenticazione e Autorizzazione#

Gli endpoint di elenco e download dei report descritti in questo articolo non richiedono autenticazione.

L’endpoint POST /security/reports/fetch richiede l’autenticazione con un token API — vedi Token API.

ID dell’organizzazione#

È richiesto un identificatore dell’organizzazione per la maggior parte delle richieste descritte qui. È possibile fornire sia l’ID dell’organizzazione (un UUID) sia il suo alias — vedi Identificatori e Alias. Lo trovi nel pannello delle impostazioni dell’organizzazione su https://dashboard.procurize.ai.
Nota che l’accesso al pannello delle impostazioni richiede autorizzazione, e l’accesso al pannello delle impostazioni dell’organizzazione richiede un ruolo utente di almeno Amministratore in quella organizzazione.

Identificatori e Alias#

I parametri di ambito accettano sia l’ID dell’entità (un UUID) sia un alias leggibile dall’uomo. Gli alias rendono le richieste più facili da leggere e sono stabili tra gli ambienti.

Ad esempio, le due richieste seguenti sono equivalenti:

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"

Nota: gli alias non sono supportati per il parametro id degli endpoint di download massivo. Passare l’UUID della directory o del progetto a GET /security/report/project-files e a GET /security/report/directory-files.

URL di base#

Tutti gli endpoint dell’API REST sono serviti sotto il seguente URL di base:

https://api.procurize.com

API REST dei report SonarQube#

Elenca i report#

Restituisce i report di sicurezza disponibili per l’ambito e la versione selezionati, senza i contenuti dei file. Usa questo endpoint per scoprire gli ID dei report che possono essere passati agli endpoint di download.

Endpoint

GET /security/report/list

Parametri di query

• org (opzionale): ID dell’organizzazione o alias (ad esempio, aspose o groupdocs). Ambito più ampio.
• directory (opzionale): ID della directory (gruppo di progetti) o alias (ad esempio, aspose-imaging o groupdocs-annotation). Ambito più ristretto.
• project (opzionale): ID del progetto o alias (ad esempio, aspose-imaging-net o groupdocs-annotation-java). Ambito più ristretto.
• version (opzionale): Versione esatta del progetto.
• minver (opzionale): Versione minima del progetto.
• maxver (opzionale): Versione massima del progetto.

È richiesto almeno uno dei parametri di ambito org, directory o project. Gli ambiti sono prioritizzati come segue: se è specificato project, viene cercato solo quel progetto; altrimenti, se è specificato directory, viene cercato l’intero gruppo di progetti; altrimenti viene cercata l’intera organizzazione (org). Quando org è specificato insieme a project o directory, il target è inoltre convalidato per appartenere a quell’organizzazione.

È richiesto almeno uno di version, minver o maxver. Se è specificato version, minver e maxver vengono ignorati.

Esempio di richiesta

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

Scoping a un gruppo di progetti o a un progetto per 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"

Esempio di risposta

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

Campi della risposta

• organizationId: L’organizzazione a cui appartengono i report.
• reports[].id: ID univoco del report. Passare questo valore agli endpoint di download.
• reports[].projectName: Nome visualizzato del prodotto.
• reports[].projectVersion: Versione del prodotto.
• reports[].reportType: Tipo di report (OWASP Top 10 o CWE Top 25).
• reports[].reportVersion: Versione (anno) dello standard del report.
• reports[].date: Data di generazione del report.
• reports[].uploadDate: Data di caricamento del report su Procurize.
• reports[].vulnerabilitiesCount: Numero di vulnerabilità trovate.
• reports[].securityRating: Valutazione complessiva della sicurezza (A–E, dove A è il migliore).

Scarica report per ID#

Scarica un archivio ZIP contenente i report selezionati. Ogni report è incluso sia in formato HTML sia in PDF.

Endpoint

GET /security/report/files

Parametri di query

• org (obbligatorio): ID dell’organizzazione o alias (ad esempio, aspose o groupdocs).
• reports (obbligatorio): ID dei report da includere. Ripetere il parametro per includere più report.

Esempio di richiesta

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

Risposta

• Content-Type: application/zip
• Il corpo della risposta contiene il file ZIP binario.

I client dovrebbero streammare la risposta e salvarla su disco.

Lavorare con un singolo report#

Gli endpoint /security/report/html, /security/report/pdf e /security/report/zip restituiscono un report specifico e condividono le stesse regole di selezione.

Selezione del report#

Il tipo e la versione del report sono sempre richiesti:

• rt (obbligatorio): Tipo di report. Valori supportati: OWASP Top 10 e CWE Top 25.
• rv (obbligatorio): Versione del report — l’anno dell’edizione dello standard, ad esempio 2025 per OWASP Top 10 o 2024 per CWE Top 25.

Il report esatto è poi selezionato in uno dei due modi:

• Per ID del report — passare id (ID del report) insieme a project (ID o alias del progetto) o org (ID o alias dell’organizzazione). Non passare version in questa modalità.
• Per versione del progetto — passare project (ID o alias del progetto, ad esempio aspose-imaging-net o groupdocs-annotation-java) e version (versione del progetto). Il parametro org non è usato in questa modalità.

Quando project e org sono entrambi specificati, org è ignorato.

Ottieni report in HTML#

Rende un singolo report come pagina HTML, oppure lo restituisce come file HTML scaricabile.

Endpoint

GET /security/report/html

Parametri di query

• rt (obbligatorio): Tipo di report.
• rv (obbligatorio): Versione del report.
• Parametri di selezione del report: vedi Selezione del report.
• download (opzionale): Impostare a true per restituire l’HTML come download del file (Content-Disposition: attachment). Quando omesso o false, il report è restituito inline.

Esempio di richiesta

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

Per scaricare il file HTML invece di renderizzarlo 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

Risposta

• Content-Type: text/html

Ottieni report in PDF#

Restituisce un singolo report come documento PDF.

Endpoint

GET /security/report/pdf

Parametri di query

• rt (obbligatorio): Tipo di report.
• rv (obbligatorio): Versione del report.
• Parametri di selezione del report: vedi Selezione del report.

Esempio di richiesta

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

Risposta

• Content-Type: application/pdf

Ottieni report in ZIP#

Restituisce un singolo report come archivio ZIP che contiene sia le versioni HTML sia PDF.

Endpoint

GET /security/report/zip

Parametri di query

• rt (obbligatorio): Tipo di report.
• rv (obbligatorio): Versione del report.
• Parametri di selezione del report: vedi Selezione del report.

Esempio di richiesta

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

Risposta

• Content-Type: application/zip

Scarica tutti i report di un progetto#

Scarica un archivio ZIP contenente tutti i report del progetto specificato, sia in HTML sia in PDF.

Endpoint

GET /security/report/project-files

Parametri di query

• id (obbligatorio): ID del progetto. Gli alias non sono supportati; passare l’UUID del progetto.
• rt (opzionale): Filtra per tipo di report. Valori supportati: OWASP Top 10 e CWE Top 25.
• rv (opzionale): Filtra per versione del report (anno).
• version (opzionale): Filtra per versione del progetto.

Se non vengono specificati filtri, vengono inclusi tutti i report del progetto. I parametri di filtro possono essere combinati e sono applicati indipendentemente.

Esempio di richiesta

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

Risposta

• Content-Type: application/zip

Scarica tutti i report di un gruppo di progetti#

Scarica un archivio ZIP contenente i report di tutti i progetti nella directory (gruppo di progetti) specificata, sia in HTML sia in PDF.

Endpoint

GET /security/report/directory-files

Parametri di query

• id (obbligatorio): ID della directory (gruppo di progetti). Gli alias non sono supportati; passare l’UUID della directory.
• rt (opzionale): Filtra per tipo di report. Valori supportati: OWASP Top 10 e CWE Top 25.
• rv (opzionale): Filtra per versione del report (anno).
• version (opzionale): Filtra per versione del progetto.

Se non vengono specificati filtri, vengono inclusi i report di tutti i progetti nella directory. I parametri di filtro possono essere combinati e sono applicati indipendentemente.

Esempio di richiesta

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

Risposta

• Content-Type: application/zip

Recupera report da SonarQube#

Carica i dati più recenti del report di sicurezza per un prodotto da un servizio SonarQube su Procurize. Il servizio recupera gli ultimi dati delle issue da SonarQube, li converte in rappresentazioni JSON delle versioni più recenti dei report OWASP Top 10 e CWE Top 25, e li restituisce nella risposta.

Endpoint

POST /security/reports/fetch

Autenticazione

Questo endpoint richiede un token API, passato nell’intestazione X-API-Key. Per i dettagli su come generare e usare i token, vedi Token API.

Parametri di query

La sorgente SonarQube è selezionata in uno dei due modi:

• Per progetto — passare project (ID o alias del progetto — vedi Identificatori e Alias). Non passare url o key.
• Per servizio SonarQube — passare url (URL del servizio SonarQube) e key (chiave del progetto SonarQube) insieme. Non passare project.

Esempio di richiesta

Recupera il report per un progetto tramite il suo alias:

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

Recupera il report direttamente da un servizio 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"

Esempio di risposta

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

La risposta è utile nelle pipeline di build di rilascio per decidere se interrompere una build quando vengono rilevate vulnerabilità nei formati di report di sicurezza pubblici.

Note

• Caricare un report richiede il permesso personale per il prodotto a cui appartengono i report. Se non disponi di questo permesso, invia comunque la richiesta: la piattaforma restituisce 403 Forbidden e notifica automaticamente gli amministratori della piattaforma, i quali esamineranno la richiesta e ti informeranno della decisione.
• Non tutti i servizi SonarQube potrebbero essere registrati sulla piattaforma Procurize. Per registrare un nuovo servizio, contatta l’amministratore della piattaforma; è necessario un token amministratore per quel servizio.

Gestione degli errori#

L’API utilizza i codici di stato HTTP standard.

• 200 OK: Richiesta riuscita
• 204 No Content: Il report non esiste
• 400 Bad Request: Parametri non validi o richiesta malformata
• 401 Unauthorized: Token API mancante o non valido
• 403 Forbidden: Accesso negato (ad esempio, permesso mancante per il prodotto)
• 500 Internal Server Error: Errore interno del server

Le risposte di errore includono un codice di errore leggibile da macchina e un messaggio leggibile da umano.

Vedi anche:#

• Webhook dei report SonarQube
• Token API – Generazione e gestione

Articoli correlati#

Che cosa sono i report di sicurezza?

Repository dei report di sicurezza

Come configurare i report di sicurezza