SonarQube ataskaitų API ir webhook’ai

Šiame straipsnyje aprašoma, kaip programiškai pasiekti SonarQube saugumo ataskaitas, saugomas Procurize platformoje. Aptariamas REST API, skirtas ataskaitų sąrašui ir gavimui, ataskaitų archyvų atsisiuntimui bei webhook’ų prenumeravimui, kai naujos ataskaitos įkeliamas.

Apžvalga

SonarQube ataskaitų submodulis leidžia organizacijoms centralizuotai saugoti ir valdyti saugumo bei kodo kokybės ataskaitas, kurias generuoja SonarQube. Procurize platforma šiuos duomenis atveria per:

• REST API, skirta gauti metaduomenis apie saugomas ataskaitas
• Galutinį tašką, skirtą ataskaitų artefaktams atsisiųsti ZIP archyvu
• Webhook’us, skirti beveik realaus laiko pranešimams, kai prieinama nauja ataskaita

Šios galimybės leidžia integruoti su CI/CD kanalais, GRC sistemomis, vidiniais prietaisų skydeliais ir tretiesios šalies rizikos valdymo įrankiais.

Autentifikacija ir autorizacija

Visi šio straipsnio aprašyti API užklausos nereikalauja autentifikacijos.

Organizacijos ID

Visoms čia aprašytoms užklausoms būtinas organizacijos ID. Jį galite rasti Organizacijos nustatymų skydelyje adresu https://dashboard.procurize.ai. Atkreipkite dėmesį, kad prieiga prie nustatymų skydelio reikalauja autorizacijos, o prieiga prie organizacijos nustatymų skydelio – bent administratoriaus vaidmens toje organizacijoje.

Bazinis URL

Visi REST API galutiniai taškai yra pasiekiami per šį bazinį URL:

https://api.procurize.com

SonarQube ataskaitų REST API

Sąrašo gavimas

Gauti puslapiuotą SonarQube saugumo ataskaitų, saugomų platformoje, sąrašą.

Galutinis taškas

GET /security/report/list

Užklausos parametrai

• org (privalomas): Organizacijos ID.
• version (pasirenkamas): Tikslus produktų versijos numeris Semantinėje versijavimo (Semantic Versioning) formatu.
• minver (pasirenkamas): Mažiausia produktų versija Semantinėje versijavimo formatu.
• maxver (pasirenkamas): Didžiausia produktų versija Semantinėje versijavimo formatu.

Atkreipkite dėmesį, kad bent vienas iš parametrų version, minver arba maxver yra privalomas užklausai.

Užklausos pavyzdys

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

Atsakymo pavyzdys

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

Ataskaitos archyvo atsisiuntimas

Atsisiųsti ZIP archyvą, kuriame yra visi SonarQube ataskaitų artefaktai. Archyve yra HTML ir PDF ataskaitos.

Galutinis taškas

GET /security/report/files

• org (privalomas): Organizacijos ID.
• reports (privalomas): Ataskaitų ID masyvas.

Užklausos pavyzdys

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"

Atsakymas

• Content-Type: application/zip
• Atsakymo kūnas turi binarinį ZIP failą

Klientai turėtų transliuoti atsakymą ir išsaugoti jį diske.

Klaidos tvarkymas

API naudojasi standartinėmis HTTP būsenų kodų reikšmėmis.

• 200 OK: Užklausa sėkminga
• 204 No Content: Ataskaita neegzistuoja
• 400 Bad Request: Netinkami parametrai arba neteisinga užklausa
• 500 Internal Server Error: Netikėta serverio klaida

Klaidos atsakymai apima mašininiu būdu skaitomą klaidos kodą ir žmogui skaitomą pranešimą.

Webhook’ai

Procurize webhook’ai leidžia išorinėms sistemoms gauti pranešimus, kai naujos SonarQube ataskaitos įkeliamos arba atnaujinamos.

Webhook’ų konfigūravimas

Webhook’ai gali būti pridėti arba redaguoti Organizacijos nustatymų skydelyje, Saugumo ataskaitų sekcijoje adresu https://dashboard.procurize.ai. Atkreipkite dėmesį, kad prieiga prie nustatymų skydelio reikalauja autorizacijos, o prieiga prie organizacijos nustatymų skydelio – bent administratoriaus vaidmens toje organizacijoje.

Norėdami patikrinti webhook’us, galite naudoti populiarias internetines paslaugas, pvz., https://webhook-test.com

Webhook’o duomenų struktūra

Webhook įvykiai siunčiami kaip HTTP POST užklausos su JSON duomenų krūva.

Pavyzdinis duomenų krūva

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

Webhook’o saugumas

Siekiant užtikrinti autentiškumą, webhook užklausos turi parašo antraštę, sugeneruotą naudojant bendrą slaptažodį.

• Parašas apskaičiuojamas naudojant HMAC‑SHA256
• Klientai turėtų patikrinti parašą prieš apdorodami duomenų krūvą

Tai apsaugo nuo neautorizuotų ar apgaulingų webhookų pristatymų.

Pristatymas ir pakartojimai

• Webhook’ai laikomi sėkmingai pristatytais, jei gaunami 2xx atsakymai
• Nepavykę pristatymai automatiškai kartojami kas valandą.
• Įvykiai gali būti pristatyti kelis kartus; vartotojai turėtų įgyvendinti idempotentinį apdorojimą

Įprastos naudojimo atvejai

• Automatiškai įkelti SonarQube radinius į vidinius saugumo prietaisų skydelius
• Iškviesti atitikties darbalaukius, kai kokybės vartai nepraeina
• Archyvuoti saugumo ataskaitas auditams ir tiekėjų rizikos peržiūroms
• Išlaikyti trečiųjų šalių sistemas sinchronizuotas su naujausia kodo saugumo būsena