API pre Správy SonarQube#

Tento článok popisuje, ako programaticky pristupovať k bezpečnostným správam SonarQube uloženým na platforme Procurize. Pokrýva REST API na výpis správ a ich sťahovanie vo formátoch HTML, PDF a ZIP.

Prehľad#

Podmodul SonarQube Reports umožňuje organizáciám centrálne ukladať a spravovať bezpečnostné a kvalitatívne správy generované SonarQube. Platforma Procurize vystavuje tieto dáta prostredníctvom verejného REST API, ktoré umožňuje:

• Zobraziť metadáta správ pre organizáciu, skupinu projektov alebo projekt
• Stiahnuť jednu správu vo formáte HTML, PDF alebo ZIP
• Stiahnuť vybrané správy ako ZIP archív
• Stiahnuť všetky správy projektu alebo skupiny projektov ako ZIP archív
• Načítať najnovšie správy OWASP Top 10 a CWE Top 25 priamo zo služby SonarQube

Tieto možnosti umožňujú integráciu s CI/CD pipeline, GRC systémami, internými dashboardmi a nástrojmi na riadenie rizík tretích strán.

Koncové body#

Overovanie a autorizácia#

Koncové body na výpis a sťahovanie správ popísané v tomto článku nevyžadujú overovanie.

Koncový bod POST /security/reports/fetch vyžaduje overenie pomocou API tokenu – pozri API tokeny.

ID organizácie#

Pre väčšinu požiadaviek je potrebný identifikátor organizácie. Môžete použiť buď ID organizácie (UUID), alebo jej alias – pozri Identifikátory a aliasy.
Nájdete ho v paneli nastavení organizácie na https://dashboard.procurize.ai.
Upozorňujeme, že prístup k panelu nastavení vyžaduje oprávnenie a prístup k nastaveniam organizácie vyžaduje rolu používateľa aspoň Administrátor v danej organizácii.

Identifikátory a aliasy#

Parametre rozsahu akceptujú buď ID entity (UUID), alebo ľudsky čitateľný alias. Aliasy uľahčujú čítanie požiadaviek a sú stabilné naprieč prostrediami.

Napríklad, nasledujúce dve požiadavky sú ekvivalentné:

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"

Poznámka: Aliasy nie sú podporované pre parameter id koncových bodov hromadného sťahovania. Pre GET /security/report/project-files a GET /security/report/directory-files použite UUID adresára alebo projektu.

Základná URL#

Všetky koncové body REST API sú dostupné pod nasledujúcou základnou URL:

https://api.procurize.com

SonarQube Reports REST API#

Zoznam správ#

Vráti bezpečnostné správy dostupné pre zvolený rozsah a verziu, bez ich obsahu. Použite tento koncový bod na zistenie ID správ, ktoré môžete odovzdať koncovým bodom na sťahovanie.

Koncový bod

GET /security/report/list

Parametre dotazu

• org (voliteľné): ID organizácie alebo alias (napr. aspose alebo groupdocs). Najširší rozsah.
• directory (voliteľné): ID adresára (skupiny projektov) alebo alias (napr. aspose-imaging alebo groupdocs-annotation). Užší rozsah.
• project (voliteľné): ID projektu alebo alias (napr. aspose-imaging-net alebo groupdocs-annotation-java). Najužší rozsah.
• version (voliteľné): Presná verzia projektu.
• minver (voliteľné): Minimálna verzia projektu.
• maxver (voliteľné): Maximálna verzia projektu.

Aspoň jeden z parametrov org, directory alebo project je povinný. Priorita rozsahov je nasledovná: ak je zadaný project, vyhľadáva sa len tento projekt; inak, ak je zadaný directory, vyhľadáva sa celá skupina projektov; inak sa vyhľadáva celá organizácia (org). Keď je org zadaný spolu s project alebo directory, cieľ sa navyše overí, že patrí do danej organizácie.

Aspoň jeden z parametrov version, minver alebo maxver je povinný. Ak je zadaný version, parametre minver a maxver sa ignorujú.

Príklad požiadavky

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

Rozsahovanie na skupinu projektov alebo projekt podľa aliasu:

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"

Príklad odpovede

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

Polia odpovede

• organizationId: Organizácia, ktorej správy patrí.
• reports[].id: Jedinečné ID správy. Použite ho pri sťahovaní.
• reports[].projectName: Zobrazovaný názov produktu.
• reports[].projectVersion: Verzia produktu.
• reports[].reportType: Typ správy (OWASP Top 10 alebo CWE Top 25).
• reports[].reportVersion: Rok verzie štandardu správy.
• reports[].date: Dátum generovania správy.
• reports[].uploadDate: Dátum nahrania správy do Procurize.
• reports[].vulnerabilitiesCount: Počet nájdených zraniteľností.
• reports[].securityRating: Celkové bezpečnostné hodnotenie (A–E, kde A je najlepšie).

Sťahovanie správ podľa ID#

Stiahne ZIP archív obsahujúci vybrané správy. Každá správa je zahrnutá vo formátoch HTML aj PDF.

Koncový bod

GET /security/report/files

Parametre dotazu

• org (povinné): ID organizácie alebo alias (napr. aspose alebo groupdocs).
• reports (povinné): ID správ, ktoré sa majú zahrnúť. Parameter môžete opakovať pre viacero správ.

Príklad požiadavky

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

Odpoveď

• Content-Type: application/zip
• Telo odpovede obsahuje binárny ZIP súbor.

Klienti by mali streamovať odpoveď a uložiť ju na disk.

Práca s jednou správou#

Koncové body /security/report/html, /security/report/pdf a /security/report/zip vracajú konkrétnu správu a používajú rovnaké pravidlá výberu.

Výber správy#

Typ a verzia správy sú vždy povinné:

• rt (povinné): Typ správy. Podporované hodnoty sú OWASP Top 10 a CWE Top 25.
• rv (povinné): Verzia správy – rok vydania štandardu, napr. 2025 pre OWASP Top 10 alebo 2024 pre CWE Top 25.

Konkrétna správa sa potom vyberá jedným z dvoch spôsobov:

• Podľa ID správy – odovzdajte id (ID správy) spolu s buď project (ID alebo alias projektu) alebo org (ID alebo alias organizácie). V tomto režime neodovzdávajte version.
• Podľa verzie projektu – odovzdajte project (ID alebo alias projektu, napr. aspose-imaging-net alebo groupdocs-annotation-java) a version (verzia projektu). Parameter org sa v tomto režime nepoužíva.

Keď sú zadané oba parametre project aj org, parameter org sa ignoruje.

Získanie správy ako HTML#

Vykreslí jednu správu ako HTML stránku alebo ju vráti ako stiahnuteľný HTML súbor.

Koncový bod

GET /security/report/html

Parametre dotazu

• rt (povinné): Typ správy.
• rv (povinné): Verzia správy.
• Parametre výberu správy: pozri Výber správy.
• download (voliteľné): Nastavte na true, ak chcete HTML vrátiť ako súbor na stiahnutie (Content-Disposition: attachment). Ak je vynechané alebo false, správa sa vráti inline.

Príklad požiadavky

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

Pre stiahnutie HTML súboru namiesto inline vykreslenia:

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

Odpoveď

• Content-Type: text/html

Získanie správy ako PDF#

Vráti jednu správu ako PDF dokument.

Koncový bod

GET /security/report/pdf

Parametre dotazu

• rt (povinné): Typ správy.
• rv (povinné): Verzia správy.
• Parametre výberu správy: pozri Výber správy.

Príklad požiadavky

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

Odpoveď

• Content-Type: application/pdf

Získanie správy ako ZIP#

Vráti jednu správu ako ZIP archív, ktorý obsahuje oba formáty – HTML aj PDF.

Koncový bod

GET /security/report/zip

Parametre dotazu

• rt (povinné): Typ správy.
• rv (povinné): Verzia správy.
• Parametre výberu správy: pozri Výber správy.

Príklad požiadavky

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

Odpoveď

• Content-Type: application/zip

Stiahnutie všetkých správ projektu#

Stiahne ZIP archív obsahujúci všetky správy zvoleného projektu, vo formátoch HTML aj PDF.

Koncový bod

GET /security/report/project-files

Parametre dotazu

• id (povinné): ID projektu. Alias nie je podporovaný; odovzdajte UUID projektu.
• rt (voliteľné): Filter podľa typu správy. Podporované hodnoty sú OWASP Top 10 a CWE Top 25.
• rv (voliteľné): Filter podľa verzie správy (rok).
• version (voliteľné): Filter podľa verzie projektu.

Ak nie sú zadané žiadne filtre, zahrnú sa všetky správy projektu. Filterové parametre je možné kombinovať a aplikujú sa nezávisle.

Príklad požiadavky

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

Odpoveď

• Content-Type: application/zip

Stiahnutie všetkých správ skupiny projektov#

Stiahne ZIP archív obsahujúci správy všetkých projektov v zadanom adresári (skupine projektov), vo formátoch HTML aj PDF.

Koncový bod

GET /security/report/directory-files

Parametre dotazu

• id (povinné): ID adresára (skupiny projektov). Alias nie je podporovaný; odovzdajte UUID adresára.
• rt (voliteľné): Filter podľa typu správy. Podporované hodnoty sú OWASP Top 10 a CWE Top 25.
• rv (voliteľné): Filter podľa verzie správy (rok).
• version (voliteľné): Filter podľa verzie projektu.

Ak nie sú zadané žiadne filtre, zahrnú sa správy všetkých projektov v adresári. Filterové parametre je možné kombinovať a aplikujú sa nezávisle.

Príklad požiadavky

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

Odpoveď

• Content-Type: application/zip

Načítanie správ zo SonarQube#

Nahrať najnovšie dáta bezpečnostných správ pre produkt zo služby SonarQube do Procurize. Služba načíta najnovšie údaje o problémoch zo SonarQube, prevedie ich do JSON reprezentácií najnovších verzií správ OWASP Top 10 a CWE Top 25 a vráti ich v odpovedi.

Koncový bod

POST /security/reports/fetch

Overovanie

Tento koncový bod vyžaduje API token, odovzdaný v hlavičke X-API-Key. Podrobnosti o generovaní a používaní tokenov nájdete v API tokenoch.

Parametre dotazu

Zdroj SonarQube sa vyberá jedným z dvoch spôsobov:

• Podľa projektu – odovzdajte project (ID alebo alias projektu – pozri Identifikátory a aliasy). Neodovzdávajte url ani key.
• Podľa služby SonarQube – odovzdajte url (URL služby SonarQube) a key (kľúč projektu SonarQube) spoločne. Neodovzdávajte project.

Príklad požiadavky

Načítanie správy pre projekt podľa aliasu:

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

Načítanie správy priamo zo služby 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"

Príklad odpovede

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

Odpoveď je užitočná v pipeline pre vydanie, aby sa rozhodlo, či zastaviť build pri zistení zraniteľností v verejných formátoch bezpečnostných správ.

Poznámky

• Nahrávanie správy vyžaduje osobné oprávnenie pre produkt, ku ktorému správy patria. Ak toto oprávnenie nemáte, pošlite požiadavku aj tak: platforma vráti 403 Forbidden a automaticky upozorní administrátorov platformy, ktorí požiadavku preskúmajú a oznámia vám rozhodnutie.
• Nie každá služba SonarQube musí byť registrovaná na platforme Procurize. Pre registráciu novej služby kontaktujte svojho administrátora platformy; je potrebný administrátorský token pre danú službu.

Spracovanie chýb#

API používa štandardné HTTP status kódy.

• 200 OK: Požiadavka úspešná
• 204 No Content: Správa neexistuje
• 400 Bad Request: Neplatné parametre alebo nesprávna požiadavka
• 401 Unauthorized: Chýbajúci alebo neplatný API token
• 403 Forbidden: Prístup odmietnutý (napr. chýbajúce oprávnenie pre produkt)
• 500 Internal Server Error: Neočakávaná chyba servera

Odpovede na chyby obsahujú strojovo čitateľný kód chyby a ľudsky čitateľnú správu.

Ďalšie informácie:#

• SonarQube Reports Webhooks
• API tokeny – Generovanie a správa

Súvisiace články#

Čo sú bezpečnostné správy?

Úložisko bezpečnostných správ

Ako konfigurovať bezpečnostné správy