API گزارش‌های SonarQube و وب‌هوک‌ها

این مقاله توضیح می‌دهد چگونه به‌صورت برنامه‌نویسی به گزارش‌های امنیتی SonarQube که در پلتفرم Procurize ذخیره شده‌اند دسترسی پیدا کنیم. این مقاله شامل REST API برای فهرست و بازیابی گزارش‌ها، دانلود آرشیوهای گزارش و اشتراک در اعلان‌های وب‌هوک هنگام ورود گزارش‌های جدید است.

مرور کلی

ماژول فرعی گزارش‌های SonarQube به سازمان‌ها امکان می‌دهد گزارش‌های امنیتی و کیفیت کد تولید شده توسط SonarQube را به‌صورت متمرکز ذخیره و مدیریت کنند. پلتفرم Procurize این داده‌ها را از طریق موارد زیر در دسترس قرار می‌دهد:

• یک REST API برای دریافت متادیتای گزارش‌های ذخیره‌شده
• یک نقطهٔ انتهایی برای دانلود آثار گزارش به‌صورت آرشیوهای ZIP
• وب‌هوک‌ها برای دریافت اعلان‌های تقریباً لحظه‌ای زمانی که گزارش‌های جدید در دسترس می‌باشند

این قابلیت‌ها امکان یکپارچه‌سازی با خطوط CI/CD، سیستم‌های GRC، داشبوردهای داخلی و ابزارهای مدیریت ریسک شخص ثالث را فراهم می‌آورند.

احراز هویت و اختصاص دسترسی

تمام درخواست‌های API که در این مقاله توضیح داده شده‌اند نیازی به احراز هویت ندارند.

شناسهٔ سازمان

برای تمام درخواست‌های زیر، شناسهٔ سازمان مورد نیاز است. می‌توانید آن را در پنل تنظیمات سازمان خود در https://dashboard.procurize.ai پیدا کنید.
لطفاً توجه داشته باشید دسترسی به پنل تنظیمات نیاز به مجوز دارد و برای دسترسی به پنل تنظیمات سازمان باید نقش کاربری حداقل Administrator در آن سازمان داشته باشید.

URL پایه

تمام نقاط انتهایی REST API تحت URL پایه زیر سرو می‌شوند:

https://api.procurize.com

REST API گزارش‌های SonarQube

فهرست گزارش‌ها

یک فهرست صفحه‌بندی‌شده از گزارش‌های امنیتی 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"
    }
  ]
}

دانلود آرشیو گزارش

یک آرشیو 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 استفاده کنید.

بارگذاری وب‌هوک

رویدادهای وب‌هوک به‌صورت درخواست‌های 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"
    }
  ]
}

امنیت وب‌هوک

برای اطمینان از اصالت، درخواست‌های وب‌هوک شامل هدر امضای ایجاد شده با استفاده از secret مشترک می‌باشند.

• امضا با HMAC‑SHA256 محاسبه می‌شود
• کلاینت‌ها باید قبل از پردازش payload، امضا را تأیید کنند

این مکانیزم از تحویل‌های غیرمجاز یا تقلبی وب‌هوک جلوگیری می‌کند.

تحویل و تلاش مجدد

• برای در نظر گرفتن وب‌هوک به‌عنوان تحویل موفق باید پاسخ 2xx بازگردانده شود
• تحویل‌های ناموفق به‌صورت خودکار هر ساعت یک‌بار دوباره تلاش می‌شوند.
• ممکن است رویدادها بیش از یک بار تحویل شوند؛ مصرف‌کنندگان باید پردازش‌های ایدمپوتنتی پیاده‌سازی کنند

موارد استفادهٔ معمول

• خودکارسازی وارد کردن یافته‌های SonarQube به داشبوردهای داخلی امنیت
• فعال‌سازی جریان‌های کاری انطباق زمانی که گیت‌های کیفیت شکست می‌خورند
• آرشیو کردن گزارش‌های امنیتی برای حسابرسی‌ها و بررسی‌های ریسک فروشندگان
• همگام‌سازی سیستم‌های شخص ثالث با آخرین وضعیت امنیتی کد