API של דוחות SonarQube#

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

סקירה כללית#

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

• רשימת מטא‑נתוני דוחות עבור ארגון, קבוצת פרויקטים או פרויקט
• הורדת דוח יחיד ב‑HTML, PDF או ZIP
• הורדת דוחות נבחרים כקובץ ZIP
• הורדת כל הדוחות של פרויקט או קבוצת פרויקטים כקובץ ZIP
• משיכת דוחות OWASP Top 10 ו‑CWE Top 25 העדכניים ביותר ישירות משירות SonarQube

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

נקודות קצה#

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

נקודות הקצה לרשימת והורדת דוחות המתוארות במאמר זה אינן דורשות אימות.

נקודת הקצה POST /security/reports/fetch דורשת אימות באמצעות אסימון API — ראה אסימוני API.

מזהה ארגון#

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

מזהים וכינויים#

פרמטרי ההקשר מקבלים או את מזהה הישות (UUID) או כינוי קריא לבני אדם. כינויים מקלים על קריאת הבקשות והם יציבים בין סביבות.

לדוגמה, שתי הבקשות הבאות שוות ערך:

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"

הערה: כינויים אינם נתמכים עבור פרמטר id של נקודות הקצה להורדה מרובה. יש להעביר את ה‑UUID של הספרייה או הפרויקט ל‑GET /security/report/project-files ול‑GET /security/report/directory-files.

כתובת בסיס#

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

https://api.procurize.com

REST API של דוחות SonarQube#

רשימת דוחות#

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

נקודת קצה

GET /security/report/list

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

• org (אופציונלי): מזהה ארגון או כינוי (לדוגמה, aspose או groupdocs). ההקשר הרחב ביותר.
• directory (אופציונלי): מזהה ספרייה (קבוצת פרויקטים) או כינוי (לדוגמה, aspose-imaging או groupdocs-annotation). הקשר מצומצם יותר.
• project (אופציונלי): מזהה פרויקט או כינוי (לדוגמה, aspose-imaging-net או groupdocs-annotation-java). הקשר הצר ביותר.
• version (אופציונלי): גרסת פרויקט מדויקת.
• minver (אופציונלי): גרסת פרויקט מינימלית.
• maxver (אופציונלי): גרסת פרויקט מרבית.

לפחות אחד מהפרמטרים org, directory או project נדרש. סדר העדיפויות הוא: אם מצוין project, מחפשים רק בפרויקט זה; אחרת, אם מצוין directory, מחפשים בכל קבוצת הפרויקטים; אחרת, מחפשים בכל הארגון (org). כאשר org מצוין יחד עם project או directory, היעד נבדק גם שהוא שייך לאותו ארגון.

לפחות אחד מהפרמטרים version, minver או maxver נדרש. אם מצוין version, הפרמטרים minver ו‑maxver מתעלמים.

דוגמת בקשה

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

הקשר לקבוצת פרויקטים או לפרויקט באמצעות כינוי:

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"

דוגמת תגובה

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

שדות בתגובה

• organizationId: מזהה הארגון שאליו שייכים הדוחות.
• reports[].id: מזהה דוח ייחודי. העבירו ערך זה לנקודות הקצה של ההורדה.
• reports[].projectName: שם המוצר להצגה.
• reports[].projectVersion: גרסת המוצר.
• reports[].reportType: סוג הדוח (OWASP Top 10 או CWE Top 25).
• reports[].reportVersion: גרסת (שנת) התקן של הדוח.
• reports[].date: תאריך יצירת הדוח.
• reports[].uploadDate: תאריך העלאת הדוח ל‑Procurize.
• reports[].vulnerabilitiesCount: מספר הפגיעות שנמצאו.
• reports[].securityRating: דירוג אבטחה כולל (A–E, כאשר A הוא הטוב ביותר).

הורדת דוחות לפי מזהה#

מוריד ארכיון ZIP המכיל את הדוחות שנבחרו. כל דוח נכלל גם ב‑HTML וגם ב‑PDF.

נקודת קצה

GET /security/report/files

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

• org (נדרש): מזהה ארגון או כינוי (לדוגמה, aspose או groupdocs).
• reports (נדרש): מזהי דוחות לכלול. ניתן לחזור על הפרמטר כדי לכלול מספר דוחות.

דוגמת בקשה

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

תגובה

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

יש להזרים את התגובה ולשמור אותה על הדיסק.

עבודה עם דוח יחיד#

הנקודות /security/report/html, /security/report/pdf ו‑/security/report/zip מחזירות דוח ספציפי ומשתפות את אותם כללי בחירה.

בחירת דוח#

סוג הדוח והגרסה תמיד נדרשים:

• rt (נדרש): סוג הדוח. ערכים נתמכים: OWASP Top 10 ו‑CWE Top 25.
• rv (נדרש): גרסת הדוח — שנת המהדורה, לדוגמה 2025 עבור OWASP Top 10 או 2024 עבור CWE Top 25.

הדוח המדויק נבחר באחת משתי דרכים:

• לפי מזהה דוח — העבירו id (מזהה הדוח) יחד עם project (מזהה או כינוי של פרויקט) או org (מזהה או כינוי של ארגון). אל תעבירו version במצב זה.
• לפי גרסת פרויקט — העבירו project (מזהה או כינוי של פרויקט, לדוגמה aspose-imaging-net או groupdocs-annotation-java) ו‑version (גרסת הפרויקט). פרמטר org אינו משמש במצב זה.

כאשר מצוין גם project וגם org, org מתעלמים.

קבלת דוח כ‑HTML#

מציג דוח יחיד כעמוד HTML, או מחזיר אותו כקובץ HTML להורדה.

נקודת קצה

GET /security/report/html

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

• rt (נדרש): סוג הדוח.
• rv (נדרש): גרסת הדוח.
• פרמטרי בחירת דוח: ראה בחירת דוח.
• download (אופציונלי): אם true מוחזר HTML כקובץ להורדה (Content-Disposition: attachment). אם לא מצוין או false, הדוח מוחזר inline.

דוגמת בקשה

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

להורדת קובץ HTML במקום הצגת הדף:

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

תגובה

• Content-Type: text/html

קבלת דוח כ‑PDF#

מחזיר דוח יחיד כקובץ PDF.

נקודת קצה

GET /security/report/pdf

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

• rt (נדרש): סוג הדוח.
• rv (נדרש): גרסת הדוח.
• פרמטרי בחירת דוח: ראה בחירת דוח.

דוגמת בקשה

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

תגובה

• Content-Type: application/pdf

קבלת דוח כ‑ZIP#

מחזיר דוח יחיד כארכיון ZIP המכיל את גרסאות ה‑HTML וה‑PDF.

נקודת קצה

GET /security/report/zip

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

• rt (נדרש): סוג הדוח.
• rv (נדרש): גרסת הדוח.
• פרמטרי בחירת דוח: ראה בחירת דוח.

דוגמת בקשה

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

תגובה

• Content-Type: application/zip

הורדת כל הדוחות של פרויקט#

מוריד ארכיון ZIP המכיל את כל הדוחות של הפרויקט שנבחר, בגרסאות HTML ו‑PDF.

נקודת קצה

GET /security/report/project-files

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

• id (נדרש): מזהה פרויקט. כינויים אינם נתמכים; יש להעביר את ה‑UUID של הפרויקט.
• rt (אופציונלי): סינון לפי סוג דוח. ערכים נתמכים: OWASP Top 10 ו‑CWE Top 25.
• rv (אופציונלי): סינון לפי גרסת דוח (שנה).
• version (אופציונלי): סינון לפי גרסת פרויקט.

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

דוגמת בקשה

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

תגובה

• Content-Type: application/zip

הורדת כל הדוחות של קבוצת פרויקטים#

מוריד ארכיון ZIP המכיל דוחות של כל הפרויקטים בקבוצת הפרויקטים (ספרייה) שנבחרה, בגרסאות HTML ו‑PDF.

נקודת קצה

GET /security/report/directory-files

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

• id (נדרש): מזהה ספרייה (קבוצת פרויקטים). כינויים אינם נתמכים; יש להעביר את ה‑UUID של הספרייה.
• rt (אופציונלי): סינון לפי סוג דוח. ערכים נתמכים: OWASP Top 10 ו‑CWE Top 25.
• rv (אופציונלי): סינון לפי גרסת דוח (שנה).
• version (אופציונלי): סינון לפי גרסת פרויקט.

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

דוגמת בקשה

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

תגובה

• Content-Type: application/zip

משיכת דוחות מ‑SonarQube#

מעלה את נתוני דוחות האבטחה העדכניים עבור מוצר משירות SonarQube ל‑Procurize. השירות שולף את נתוני ה‑issues העדכניים מ‑SonarQube, ממיר אותם לייצוגי JSON של גרסאות ה‑OWASP Top 10 ו‑CWE Top 25, ומחזיר אותם בתגובה.

נקודת קצה

POST /security/reports/fetch

אימות

נקודה זו דורשת אסימון API, המועבר בכותרת X-API-Key. לפרטים על יצירת ושימוש באסימונים, ראה אסימוני API.

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

מקור ה‑SonarQube נבחר באחת משתי דרכים:

• לפי פרויקט — העבירו project (מזהה או כינוי של פרויקט — ראה מזהים וכינויים). אל תעבירו url או key.
• לפי שירות SonarQube — העבירו יחדיו url (כתובת שירות SonarQube) ו‑key (מפתח פרויקט SonarQube). אל תעבירו project.

דוגמת בקשה

משיכת הדוח עבור פרויקט לפי כינויו:

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

משיכת הדוח ישירות משירות 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"

דוגמת תגובה

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

התגובה שימושית בצינורות בניית גרסאות כדי להחליט אם לעצור בנייה כאשר מתגלות פגיעות בפורמטים הציבוריים של דוחות האבטחה.

הערות

• העלאת דוח דורשת הרשאה אישית למוצר שאליו שייכים הדוחות. אם אין ברשותכם הרשאה זו, שלחו את הבקשה בכל זאת: הפלטפורמה תחזיר 403 Forbidden ותודיע אוטומטית למנהלי הפלטפורמה, שיבדקו את הבקשה וידעו אתכם על ההחלטה.
• לא כל שירות SonarQube רשום ב‑Procurize. כדי לרשום שירות חדש, פנו למנהל הפלטפורמה שלכם; נדרש אסימון מנהל עבור השירות.

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

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

• 200 OK: הבקשה הצליחה
• 204 No Content: הדוח אינו קיים
• 400 Bad Request: פרמטרים שגויים או בקשה פגומה
• 401 Unauthorized: חסר או אסימון API שגוי
• 403 Forbidden: גישה נדחתה (לדוגמה, חסרה הרשאה למוצר)
• 500 Internal Server Error: שגיאת שרת בלתי צפויה

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

ראה גם:#

• Webhooks של דוחות SonarQube
• אסימוני API – יצירה וניהול

מאמרים קשורים#

מהם דוחות אבטחה?

מאגר דוחות אבטחה של SonarQube

כיצד להגדיר דוחות אבטחה