API Αναφορών SonarQube#

Αυτό το άρθρο περιγράφει πώς να έχετε προγραμματιστική πρόσβαση στις αναφορές ασφαλείας SonarQube που αποθηκεύονται στην πλατφόρμα Procurize. Καλύπτει το REST API για την καταγραφή των αναφορών και τη λήψη τους σε μορφές HTML, PDF και ZIP.

Επισκόπηση#

Το υπομοντέλο SonarQube Reports επιτρέπει σε οργανισμούς να αποθηκεύουν κεντρικά και να διαχειρίζονται αναφορές ασφαλείας και ποιότητας κώδικα που δημιουργούνται από το SonarQube. Η πλατφόρμα Procurize εκθέτει αυτά τα δεδομένα μέσω ενός δημόσιου REST API που επιτρέπει:

• Καταγραφή μεταδεδομένων αναφορών για έναν οργανισμό, μια ομάδα έργων ή ένα έργο
• Λήψη μιας μεμονωμένης αναφοράς σε HTML, PDF ή μορφή ZIP
• Λήψη επιλεγμένων αναφορών ως αρχείο ZIP
• Λήψη όλων των αναφορών ενός έργου ή μιας ομάδας έργων ως αρχείο ZIP
• Λήψη των πιο πρόσφατων αναφορών OWASP Top 10 και CWE Top 25 απευθείας από μια υπηρεσία SonarQube

Αυτές οι δυνατότητες επιτρέπουν ενσωμάτωση με pipelines CI/CD, συστήματα GRC, εσωτερικούς πίνακες ελέγχου και εργαλεία διαχείρισης κινδύνου τρίτων.

Τελικά σημεία (Endpoints)#

Αυθεντικοποίηση και Εξουσιοδότηση#

Τα τερματικά λίστας και λήψης αναφορών που περιγράφονται σε αυτό το άρθρο δεν απαιτούν αυθεντικοποίηση.

Το τερματικό POST /security/reports/fetch απαιτεί αυθεντικοποίηση με API token — δείτε την ενότητα API Tokens.

Αναγνωριστικό Οργανισμού (Organization ID)#

Για τις περισσότερες αιτήσεις απαιτείται το αναγνωριστικό του οργανισμού. Μπορείτε να περάσετε είτε το UUID του οργανισμού είτε το ψευδώνυμό του — δείτε την ενότητα Identifiers and Aliases.
Το βρίσκετε στον πίνακα ρυθμίσεων του οργανισμού στο https://dashboard.procurize.ai.
Σημειώστε ότι η πρόσβαση στον πίνακα ρυθμίσεων απαιτεί εξουσιοδότηση, και η πρόσβαση στον πίνακα ρυθμίσεων του οργανισμού απαιτεί ρόλο χρήστη τουλάχιστον Administrator σε εκείνο τον οργανισμό.

Αναγνωριστικά και Ψευδώνυμα (Identifiers and Aliases)#

Οι παράμετροι πεδίου δέχονται είτε το αναγνωριστικό οντότητας (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.

Βασική Διεύθυνση URL (Base URL)#

Όλα τα τερματικά REST API εξυπηρετούνται κάτω από την ακόλουθη βασική διεύθυνση URL:

https://api.procurize.com

SonarQube Reports REST API#

Λίστα Αναφορών (List Reports)#

Επιστρέφει τις διαθέσιμες αναφορές ασφαλείας για το επιλεγμένο πεδίο και έκδοση, χωρίς τα περιεχόμενα των αρχείων. Χρησιμοποιήστε αυτό το τερματικό για να ανακαλύψετε τα IDs των αναφορών που μπορούν να περαστούν στα τερματικά λήψης.

Τερματικό

GET /security/report/list

Παράμετροι Ερωτήματος

• org (προαιρετικό): ID ή ψευδώνυμο οργανισμού (π.χ. aspose ή groupdocs). Το ευρύτερο πεδίο.
• directory (προαιρετικό): ID ή ψευδώνυμο καταλόγου (ομάδας έργων) (π.χ. aspose-imaging ή groupdocs-annotation). Περισσότερο περιορισμένο πεδίο.
• project (προαιρετικό): ID ή ψευδώνυμο έργου (π.χ. 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: Μοναδικό 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 είναι το καλύτερο).

Λήψη Αναφορών με ID (Download Reports by ID)#

Κατεβάζει ένα αρχείο ZIP που περιέχει τις επιλεγμένες αναφορές. Κάθε αναφορά περιλαμβάνει τόσο την HTML όσο και την PDF μορφή.

Τερματικό

GET /security/report/files

Παράμετροι Ερωτήματος

• org (απαιτείται): ID ή ψευδώνυμο οργανισμού (π.χ. aspose ή groupdocs).
• reports (απαιτείται): IDs των αναφορών που θα συμπεριληφθούν. Επαναλάβετε την παράμετρο για πολλαπλές αναφορές.

Παράδειγμα Αιτήματος

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.

Οι πελάτες πρέπει να ρέουν (stream) την απάντηση και να την αποθηκεύουν στο δίσκο.

Εργασία με Μία Μοναδική Αναφορά#

Τα τερματικά /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 αναφοράς — περάστε id (ID αναφοράς) μαζί με είτε project (ID ή ψευδώνυμο έργου) είτε org (ID ή ψευδώνυμο οργανισμού). Μην περάσετε version σε αυτή τη λειτουργία.
• Με έκδοση έργου — περάστε project (ID ή ψευδώνυμο έργου, π.χ. 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 (απαιτείται): 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 (απαιτείται): 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 (Fetch Reports from SonarQube)#

Ανεβάζει τα πιο πρόσφατα δεδομένα αναφοράς ασφαλείας για ένα προϊόν από μια υπηρεσία SonarQube στην Procurize. Η υπηρεσία ανακτά τα πιο πρόσφατα δεδομένα ζητημάτων από το SonarQube, τα μετατρέπει σε JSON αναπαραστάσεις των τελευταίων εκδόσεων των αναφορών OWASP Top 10 και CWE Top 25, και τα επιστρέφει στην απάντηση.

Τερματικό

POST /security/reports/fetch

Αυθεντικοποίηση

Απαιτείται API token, που περνιέται στην κεφαλίδα X-API-Key. Για λεπτομέρειες σχετικά με τη δημιουργία και χρήση tokens, δείτε την ενότητα API Tokens.

Παράμετροι Ερωτήματος

Η πηγή SonarQube επιλέγεται με έναν από τους δύο τρόπους:

• Με έργο — περάστε project (ID ή ψευδώνυμο έργου — δείτε την ενότητα Identifiers and Aliases). Μην περάσετε url ή key.
• Με υπηρεσία SonarQube — περάστε ταυτόχρονα url (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,
    ...
  }
}

Η απάντηση είναι χρήσιμη σε pipelines εκδόσεων για να αποφασιστεί εάν θα σταματήσει η κατασκευή όταν εντοπιστούν ευπάθειες στα δημόσια πρότυπα αναφορών ασφαλείας.

Σημειώσεις

• Η μεταφόρτωση μιας αναφοράς απαιτεί προσωπική άδεια για το προϊόν στο οποίο ανήκουν οι αναφορές. Αν δεν διαθέτετε αυτήν την άδεια, στείλτε την αίτηση ούτως ή άλλως: η πλατφόρμα θα επιστρέψει 403 Forbidden και θα ειδοποιήσει αυτόματα τους διαχειριστές της πλατφόρμας, οι οποίοι θα εξετάσουν το αίτημα και θα σας ενημερώσουν για την απόφαση.
• Δεν είναι απαραίτητο κάθε SonarQube service να είναι καταχωρημένο στην πλατφόρμα Procurize. Για την καταχώρηση νέας υπηρεσίας, επικοινωνήστε με τον διαχειριστή της πλατφόρμας· απαιτείται token διαχειριστή για τη συγκεκριμένη υπηρεσία.

Διαχείριση Σφαλμάτων (Error Handling)#

Το API χρησιμοποιεί τυπικούς κωδικούς κατάστασης HTTP.

• 200 OK: Η αίτηση ήταν επιτυχής
• 204 No Content: Η αναφορά δεν υπάρχει
• 400 Bad Request: Μη έγκυρες παράμετροι ή κακή μορφή αίτησης
• 401 Unauthorized: Λείπει ή είναι μη έγκυρο το API token
• 403 Forbidden: Άρνηση πρόσβασης (π.χ. έλλειψη άδειας για το προϊόν)
• 500 Internal Server Error: Απρόσμενο σφάλμα διακομιστή

Οι απαντήσεις σφαλμάτων περιλαμβάνουν κωδικό σφάλματος μηχανής και ανθρώπινο μήνυμα.

Δείτε επίσης:#

• SonarQube Reports Webhooks
• API Tokens – Generation & Management

Σχετικά άρθρα#

Τι είναι οι Αναφορές Ασφαλείας;

Αποθετήριο Αναφορών ασφαλείας

Πώς να Διαμορφώσετε τις Αναφορές Ασφαλείας