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

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

مرور کلی#

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

• فهرست‌کردن فراداده‌های گزارش برای یک سازمان، یک گروه پروژه یا یک پروژه
• دانلود یک گزارش به‌صورت 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 نقاط انتهایی دانلود دسته‌ای پشتیبانی نمی‌شوند. برای نقاط انتهایی GET /security/report/project-files و GET /security/report/directory-files شناسه UUID دایرکتوری یا پروژه را پاس کنید.

URL پایه#

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

https://api.procurize.com

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

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

فهرست‌کردن گزارش‌های امنیتی موجود برای دامنه و نسخه انتخاب‌شده، بدون محتوای فایل‌های آن‌ها. از این نقطه انتهایی برای کشف شناسه‌های گزارش که می‌توانند به نقاط انتهایی دانلود پاس داده شوند، استفاده کنید.

Endpoint

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 گنجانده می‌شود.

Endpoint

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 (شناسه یا نام مستعار پروژه) و version (نسخه پروژه) را پاس دهید. پارامتر org در این حالت استفاده نمی‌شود.

اگر هم project و هم org مشخص شوند، org نادیده گرفته می‌شود.

دریافت گزارش به‌صورت HTML#

یک گزارش را به‌صورت صفحه HTML رندر می‌کند یا به‌صورت فایل HTML قابل دانلود برمی‌گرداند.

Endpoint

GET /security/report/html

پارامترهای پرس‌و‌جو

• rt (الزامی): نوع گزارش.
• rv (الزامی): نسخه گزارش.
• پارامترهای انتخاب گزارش: نگاه کنید به انتخاب گزارش.
• download (اختیاری): برای دریافت HTML به‌صورت فایل دانلود (Content-Disposition: attachment) مقدار true تنظیم کنید. اگر حذف شود یا false باشد، گزارش به‌صورت درون‌خطی برگردانده می‌شود.

نمونه درخواست

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 برمی‌گرداند.

Endpoint

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 است، برمی‌گرداند.

Endpoint

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 دانلود می‌کند.

Endpoint

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 دانلود می‌کند.

Endpoint

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 بارگذاری می‌کند. این سرویس آخرین داده‌های مشکل را از SonarQube دریافت، به نمایش‌های JSON از آخرین نسخه‌های گزارش‌های OWASP Top 10 و CWE Top 25 تبدیل و در پاسخ برمی‌گرداند.

Endpoint

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: خطای داخلی سرور

پاسخ‌های خطا شامل یک کد خطای قابل خواندن توسط ماشین و یک پیام قابل خواندن توسط انسان هستند.

همچنین ببینید:#

• وب‌هوک‌های گزارش‌های SonarQube
• توکن‌های API – تولید و مدیریت

مقالات مرتبط#

گزارش‌های امنیتی چیست؟

مخزن گزارش‌های امنیتی

چگونه گزارش‌های امنیتی را پیکربندی کنیم