SonarQube Reports API וווב‑הוקים

מאמר זה מתאר כיצד לגשת באופן תכנותי לדוחות האבטחה של SonarQube המאוכסנים בפלטפורמת Procurize. הוא מתמקד ב‑REST API לרשימת ועדיכת דוחות, הורדת ארכיוני דוחות, והצטרפות לקבלת הודעות ווב‑הוק כאשר דוחות חדשים מתווספים.

סקירה כללית

תת‑מודול דו"חות SonarQube מאפשר לארגונים לאחסן ולנהל במרכזיות דוחות אבטחה ואיכות קוד שנוצרים על‑ידי SonarQube. פלטפורמת Procurize חושפת נתונים אלה דרך:

• REST API לקבלת מטא‑נתונים על דוחות מאוחסנים
• נקודת קצה להורדת ארכיון הדוחות כקבצי ZIP
• ווב‑הוקים לקבלת התראות בזמן כמעט אמת כאשר דוחות חדשים זמינים

יכולות אלו מאפשרות אינטגרציה עם צינורות CI/CD, מערכות GRC, לוחות מחוונים פנימיים, וכלים חיצוניים לניהול סיכונים.

אימות והרשאות

אין צורך באימות עבור כל בקשות ה‑API המתוארות במאמר זה.

מזהה ארגון

נדרש מזהה ארגון לכל הבקשות המתוארות כאן. ניתן למצוא אותו בלוח ההגדרות של הארגון בכתובת https://dashboard.procurize.ai. שימו לב שהגישה ללוח ההגדרות דורשת הרשאה, והגישה ללוח ההגדרות של הארגון מחייבת תפקיד משתמש של לפחות מנהל (Administrator) באותו ארגון.

כתובת בסיס

כל נקודות הקצה של REST API זמינות תחת כתובת הבסיס הבאה:

https://api.procurize.com

SonarQube Reports REST API

List Reports

מקבל רשימה ממודרת של דו"חות אבטחת SonarQube המאוחסנים בפלטפורמה.

נקודת קצה

GET /security/report/list

פרמטרים לשאילתה

• org (חובה): מזהה הארגון.
• version (אופציונלי): הגרסה המדויקת של המוצרים בפורמט Semantic Versioning.
• minver (אופציונלי): הגרסה המינימלית של המוצרים בפורמט Semantic Versioning.
• maxver (אופציונלי): הגרסה המרבית של המוצרים בפורמט Semantic Versioning.

שימו לב שיש צורך לפחות באחד מהפרמטרים version, minver או maxver לבקשה.

דוגמת בקשה

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

דוגמת תגובה

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

Download Report Archive

מוריד ארכיון ZIP המכיל את כל artefacts של דו"חות SonarQube. הארכיב כולל דוחות HTML ו‑PDF.

נקודת קצה

GET /security/report/files

• org (חובה): מזהה הארגון.
• reports (חובה): מערך של מזהי דוחות.

דוגמת בקשה

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"

תגובה

• Content-Type: application/zip
• גוף התגובה מכיל קובץ ZIP בינרי

הקוח צריך להזרים (stream) את התגובה ולשמור אותה לכונן.

טיפול בשגיאות

ה‑API משתמש בקודי סטטוס סטנדרטיים של HTTP.

• 200 OK: הבקשה בוצעה בהצלחה
• 204 No Content: הדוח אינו קיים
• 400 Bad Request: פרמטרים שגויים או בקשה לא תקינה
• 500 Internal Server Error: שגיאת שרת בלתי צפויה

תשובות השגיאה כוללות קוד שגיאה קריא למכונה והודעה קריאה לבן אדם.

ווב‑הוקים

ווב‑הוקים של Procurize מאפשרים למערכות חיצוניות לקבל התראות כאשר דו"חות SonarQube חדשים מתווספים או מתעדכנים.

קונפיגורציית ווב‑הוקים

ניתן להוסיף או לערוך ווב‑הוקים בלוח ההגדרות של הארגון, תחת מדור דו"חות אבטחה בכתובת https://dashboard.procurize.ai. שימו לב שהגישה ללוח ההגדרות דורשת הרשאה, והגישה ללוח ההגדרות של הארגון מחייבת תפקיד משתמש של לפחות מנהל (Administrator) באותו ארגון.

לבדיקת ווב‑הוקים ניתן להשתמש בשירותים מקוונים פופולאריים כגון https://webhook-test.com

Payload של ווב‑הוק

אירועי ווב‑הוק נשלחים כהבקשות HTTP POST עם Payload בפורמט JSON.

דוגמת 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"
    }
  ]
}

אבטחת ווב‑הוק

כדי להבטיח אמינות, בקשות ה‑webhook כוללות כותרת חתימה שנוצרה באמצעות סוד משותף.

• החתימה מחושבת עם HMAC‑SHA256
• הלקוחות צריכים לאמת את החתימה לפני עיבוד ה‑payload

זה מונע משלוח ווב‑הוקים לא מורשים או מזויפים.

אספקה וניסיונות חוזרים

• ווב‑הוקים נחשבים למסופקים רק אם מחזירים קוד תגובה 2xx.
• נכשלות נשלחות מחדש אוטומטית על בסיס שעתי.
• ייתכן שהאירועים יוכלו להימסר יותר מפעם אחת; לכן יש למימוש עיבוד אידמופוטנטי.

מקרים טיפוסיים

• ייבוא אוטומטי של ממצאי SonarQube ללוחות מחוונים פנימיים של אבטחה
• הפעלת תהליכי ציות כאשר שערי האיכות נכשלים
• ארכוב דוחות אבטחה לצורך ביקורות וסקירות סיכון של ספקים
• שמירת מערכות צד שלישי מסונכרנות עם המצב הנוכחי של אבטחת הקוד