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

ב-Assured OSS מסופקים מטא-נתונים של אבטחה לכל חבילה זמינה. לכל גרסה של החבילה יש מטא-נתונים משלה. בדף הזה מוסבר איזה מידע מסופק כחלק מהמטא-נתונים ואיך אפשר לגשת למטא-נתונים האלה.

אפשר לגשת למטא-נתוני האבטחה באמצעות אחת מהאפשרויות הבאות:

  • Artifact Analysis API
  • Cloud Storage

הדף הזה רלוונטי רק לתוכנית החינמית.

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

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

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

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

  • ‫BuildOccurrence. הקישור למופע הבנייה הזה מופיע בקטע relatedURL של הערת החבילה לצד התווית BUILD_OCCURRENCE. ה-intotoStatement במופע ה-build מכיל את ה-provenance של SLSA v0.2.

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

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

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

  • 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. הערך הזה הוא תלוי אותיות רישיות. אפשר למצוא את האיות הנכון של שם הגרסה של החבילה במאמר Listing all Packages in 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 המפה כדי לאחזר נתונים נוספים שקשורים למקור, לבנייה, לבדיקה ולפגיעות. כדי לעשות את זה, משתמשים בממשקי ה-API‏ GetNote ו-GetOccurrence או בפקודות curl. כשמשתמשים ב-API, צריך להסיר את הקידומת הראשונית של https://containeranalysis.googleapis.com/v1/ עבור BUILD_OCCURRENCE. לגבי ישויות אחרות, משתמשים בכתובות ה-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`

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