גישה למטא-נתונים באמצעות Artifact Analysis API

ב-Assured Open Source Software (או Assured OSS) יש מטא-נתונים של אבטחה לכל חבילה ולכל גרסת חבילה שזמינות. אתם יכולים לגשת למטא-נתונים האלה ב-Artifact Analysis כדי לבדוק את פרטי ה-build, סטטוס נקודות החולשה, תוצאות הבדיקה ופרטי הרישיון.

המסמך הזה רלוונטי רק לתוכנית בחינם. במאמר גישה למטא-נתונים באמצעות Cloud Storage מוסבר איך לגשת למטא-נתונים באמצעות Cloud Storage.

מטא-נתונים של אבטחה

Artifact Analysis מספק אחסון של מטא-נתונים בהתאם למודל Grafeas בקוד פתוח. המידע הבא מוצג לכל גרסה של החבילה:

  • ‫PackageNote לכל גרסה של החבילה שפורסמה על ידי Assured OSS. הערת החבילה מכילה את הפרטים הבאים:

    • distribution כאשר כל distribution תואם לארטיפקט אחד שסופק על ידי Assured OSS. הוא כולל את המיקום ואת התקציר url (שמהם אפשר להוריד את החתימה והגיבוב) למקורות בינאריים וניתנים לשחזור.
    • relatedURL שמכיל קישורים למטא-נתונים כמו אישור המקור של ה-build, אישור הבדיקה ונקודות חולשה.

  • BuildOccurrence. הקישור למופע ה-build הזה מופיע בקטע relatedURL של הערת החבילה, לצד התווית BUILD_OCCURRENCE. השדה intotoStatement במופע ה-build מכיל את המקור של SLSA בגרסה 0.2.

  • ‫BuildOccurrenance שני. הקישור למופע ה-build הזה מופיע בקטע relatedURL של הערת החבילה, לצד התווית ORIGINAL_SOURCE_PROVENANCE. הקובץ הזה מכיל את פרטי המקור המקורי (GitHub) בפורמט Source.

  • AttestationOccurrence. הקישור למופע האימות הזה מופיע בקטע relatedURL של הערת החבילה, ליד התווית TEST_OCCURRENCE. המטען הייעודי (payload) שעבר סריאליזציה בהצהרה מכיל JSON שמייצג את כל בדיקות האבטחה שבוצעו בגרסת החבילה.

  • AttestationOccurrence שני. הקישור למופע האימות הזה מופיע בקטע relatedURL של הערת החבילה, לצד התווית PACKAGE_ATTESTATION_OCCURRENCE. המטען הייעודי (payload) שעבר סריאליזציה בפורמט JSON באימות הוא המטען הייעודי של הערת החבילה והחתימה שלה. האימות הזה משמש כדי לוודא את התקינות של תוכן הערת החבילה.

  • VulnerabilityNote ו-VulnerabilityOccurrence לכל נקודת חולשה שמשויכת לחבילה. השילוב של ההערה והמופע מספק מידע על נקודות החולשה, כמו סיכום או תיאור של נקודת החולשה, חומרת נקודת החולשה, ציון CVSSV3, מידע על הגרסה המושפעת והגרסה המתוקנת, ופתרון הבעיה.

גישה למטא-נתונים של אבטחה מ-Artifact Analysis

אתם יכולים לגשת למטא-נתונים של האבטחה מ-Artifact Analysis באמצעות לקוחות Artifact Analysis API שזמינים בשפות שונות. כדי להתחיל להשתמש בספריות הלקוח של Cloud ל-Artifact Analysis API, קראו את המאמר התקנת ספריות הלקוח הנדרשות של Artifact Analysis.

כדי לגשת למטא-נתונים של האבטחה:

שלב 1 – הגדרת אימות

מגדירים אימות באמצעות Application Default Credentials ‏(ADC).

שלב 2 – אחזור מטא-נתונים של אבטחה

כדי לאחזר מטא-נתונים של אבטחה, יוצרים חבילת note_name באמצעות המידע הבא:

  • ‫Project_ID: המזהה האלפאנומרי של הפרויקט ב- Google Cloud .
  • ‫Package Language: ‏Java או Python. השם חייב להתחיל באות גדולה.
  • ‫Package_ID: ב-Java זה groupId_artifactId וב-Python זה packageName. הערך הזה הוא תלוי אותיות רישיות. אפשר למצוא את האותיות הרישיות התקינות של שם הגרסה של החבילה במאמר הצגת כל החבילות ב-Assured OSS.
  • ‫Version: גרסת החבילה.

הערך של note_name צריך להיות במבנה הבא: projects/<project_id>/notes/<language>-<package_id>-<version>.

לדוגמה: projects/cloud-aoss/notes/JAVA-org.apache.commons_commons-compress-1.21

אפשרות 1:

אם אתם משתמשים בספריות הלקוח של Container Analysis, השתמשו ב-getNotes עם note_name כדי לשלוח שאילתה ל-PackageNote. בPackageNote יש קישורים לפתקים ולמופעים אחרים.

אפשרות 2:

אם משתמשים בפקודה curl, משתמשים בפקודה הבאה:

curl  -H "Content-Type: application/json" -H   "Authorization: Bearer $(gcloud auth print-access-token)" $URL
  • ב-Java, משתמשים בכתובת ה-URL: https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2
  • ב-Python, משתמשים בכתובת ה-URL: https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/PYTHON-Flask-Cors-3.0.10

מטא-נתונים לדוגמה

{
  "name": "projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2",
  "kind": "PACKAGE",
  "relatedUrl": [
    {
      "url": "projects/cloud-aoss/occurrences/621d7e7b-8e6c-4313-b24b-eae3a1d1b884",
      "label": "ORIGINAL_SOURCE_PROVENANCE"
    },
    {
      "url": "https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/occurrences/a0967d97-634c-4066-b6da-0a723273a165",
      "label": "BUILD_OCCURRENCE"
    },
    {
      "url": "projects/cloud-aoss/occurrences/6005db73-7310-44f9-9a36-6ca0174732a1",
      "label": "TEST_OCCURRENCE"
    },
    {
      "url": "projects/cloud-aoss/notes/GHSA-gp7f-rwcx-9369",
      "label": "VULNERABILITY_GHSA-gp7f-rwcx-9369"
    }
  ],
  "createTime": "2022-10-12T06:48:19.162016Z",
  "updateTime": "2022-10-18T05:31:15.081736Z",
  "package": {
    "distribution": [
      {
        "cpeUri": "cpe:2.3:a:JAVA::org.jsoup:jsoup:1.15.2:*:*:*:*:*:*:*",
        "url": "https://us-maven.pkg.dev/…/org/jsoup/jsoup/1.15.2/jsoup-1.15.2.jar",
        "description": "..."
      },
      {
        "cpeUri": "cpe:2.3:a:JAVA::org.jsoup:jsoup:1.15.2:*:*:*:*:*:*:*",
        "url": "https://us-maven.pkg.dev/…/org/jsoup/jsoup/1.15.2/jsoup-1.15.2-sources.jar",
        "description": "..."
      }
]}}

משתמשים בשמות של ההערות והמופעים שמופיעים במפה relatedURL כדי לאחזר נתונים נוספים שקשורים למקור, ל-build, לבדיקה ולנקודת החולשה. כדי לעשות את זה, משתמשים בממשקי ה-API‏ GetNote ו-GetOccurrence או בפקודות curl. בשביל BUILD_OCCURRENCE, צריך להסיר את הקידומת הראשונית של https://containeranalysis.googleapis.com/v1/ כשמשתמשים ב-API. בישויות אחרות, משתמשים בכתובות ה-URL ישירות בתור note_name או occurrence_name בפרמטר של ה-API.

סקריפט Python לדוגמה

סקריפט Python לדוגמה שמדפיס את כל המטא-נתונים שהורדו זמין במיקום הבא ב-Cloud Storage, יחד עם קובץ ה-README שלו:

gs://cloud-aoss/utils/python-download-metadata/v1.1

כדי להוריד את הסקריפט באמצעות Google Cloud CLI:

  1. מגדירים אימות באמצעות Application Default Credentials ‏(ADC).

  2. התקנה של ספריית הלקוח container-analysis. באופן ספציפי, הפקודה הזו צריכה להתקין את:

    pip install google-cloud-containeranalysis

  3. מתקינים את החבילות cloud-kms ו-cryptography באמצעות הפקודות הבאות:

    pip install --upgrade google-cloud-kms
pip install --upgrade cryptography

  4. מורידים את download_metadata.py למערכת באמצעות הפקודה הבאה:

    gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/download_metadata.py
PATH_TO_LOCAL_STORE --recursive

    מחליפים את PATH_TO_LOCAL_STORE בנתיב המקומי שבו רוצים לשמור את הקובץ.

  5. מורידים את README.md שמכיל את ההוראות לשימוש בסקריפט באמצעות הפקודה הבאה:

    gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/README.md PATH_TO_LOCAL_STORE --recursive

    מחליפים את PATH_TO_LOCAL_STORE בנתיב המקומי שבו רוצים לשמור את הקובץ.

פקודה לדוגמה

python ./download_metadata.py -l 'JAVA' -p 'org.apache.logging.log4j:log4j-core' -v '2.17.1'

כדי לאמת את החתימות במטא-נתונים של ניתוח מאגר הנתונים, מוסיפים את הפקודה הבאה לסקריפט:

python ./download_metadata.py -l 'JAVA' -p 'org.apache.logging.log4j:log4j-core' -v '2.17.1' -s`

המאמרים הבאים