גישה למטא-נתונים באמצעות Cloud Storage

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

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

  • Artifact Analysis API
  • Cloud Storage

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

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

מטא-נתוני האבטחה של כל גרסה של חבילת Assured OSS מפוזרים בין ארבעת הקבצים הבאים בקטגוריה של Cloud Storage:

  • ‫buildinfo.zip: הקובץ הזה מכיל מטא-נתונים על פרטי הגרסה של חבילה. המטא-נתונים האלה ישתנו בתרחישים נדירים מאוד, כמו בנייה מחדש של חבילה, החלפה של אישור והוספה של שדות חדשים.
  • ‫vexinfo.zip: הקובץ הזה מכיל את פרטי הפגיעות של חבילה בפורמט CycloneDX 1.4. הערך הזה צפוי להשתנות בכל פעם שיש מידע על פגיעות בחבילה.
  • ‫healthinfo.zip: הקובץ הזה מכיל פרטים על הבדיקות שבוצעו בחבילה. הערך הזה יכול להשתנות אם סטטוס הבדיקה של חבילה משתנה. לדוגמה, אם מתבצעת בדיקת אבטחה חדשה או אם תוצאת הכיסוי משתנה.
  • ‫licenseinfo.zip: הקובץ הזה מכיל מטא-נתונים שקשורים לפרטי הרישיון של חבילה. פרטי הרישיון של חבילה יכולים להשתנות אם המוציא לאור של החבילה משנה את הפרטים.

כל קובץ ZIP מכיל את שני הקבצים הבאים:

  • קובץ JSON שמכיל נתונים.
  • קובץ signature.zip שמכיל את החתימה של הנתונים האלה.

מבנה קובץ JSON

המבנה של קובצי ה-JSON מתואר בקטע הבא:

buildInfo.json

  • ‫creationTime: שעת היצירה של המסמך בפורמט מחרוזת RFC 3339.
  • creator: הבעלים של המסמך. הפרטים הבאים מסופקים:
    • ‫name: שם הארגון שיצר את המסמך הזה.
    • ‫email: כתובת האימייל של הארגון למקרה של שאלה או תלונה.
  • ‫buildDetails: הפרטים שקשורים ליצירת הקובץ הבינארי. הפרטים הבאים מסופקים:
    • ‫packageFileName: השם של הקובץ שאליו מתייחסים פרטי הבנייה.
    • ‫buildProvenance: מחרוזת שמייצגת את אישור המקור של Build של החבילה בפורמט SLSA v0.2. הוא נוצר על ידי Cloud Build.
    • ‫envelope: מחרוזת שמייצגת מעטפת DSSE שאפשר להשתמש בה כדי לאמת את השלמות של מסמך המקור. הוא נוצר גם על ידי Cloud Build.
    • ‫slsaLevel: מציין את רמת ה-SLSA שהמערכת שמבצעת את ה-build עומדת בה.
    • ‫buildTool: השם של הכלי שמשמש ליצירת החבילה, שהוא Cloud Build. מידע נוסף זמין במאמר בנושא Cloud Build.
    • ‫transitiveClosureState: זהו ENUM שמציין אם כל התלויות ב-build של החבילה (ישירות או עקיפות) קיימות גם בפורטפוליו של Assured OSS או לא. הערך של המאפיין הזה יכול להיות אחד משני הערכים הבאים:
      • ‫OPEN: אם Assured OSS תומך באפס או רק בחלק מהתלות הטרנזיטיבית.
      • ‫CLOSED: אם כל התלויות הטרנזיטיביות נתמכות על ידי Assured OSS.
  • ‫sourceInfo: המידע על קוד המקור ששימש לבניית החבילה. הפרטים הבאים מסופקים:
    • ‫sourceUrl: מחרוזת כתובת ה-URL של GitHub.
    • ‫commitHash: מחרוזת של גיבוב (hash) של קומיט שמצורפת לגרסה.
    • ‫tag: תג הגרסה שמשויך לגרסת החבילה.
    • ‫host: שם המערכת שמארחת את קוד המקור ב-GitHub.
    • ‫commitTime: השעה של ביצוע commit בפורמט מחרוזת RFC 3339.
  • ‫sbom – מחרוזת SBOM בפורמט SPDX 2.3.

vexInfo.json

  • ‫creationTime: שעת היצירה של המסמך בפורמט מחרוזת RFC 3339.
  • creator: הבעלים של המסמך. הפרטים הבאים מסופקים:
    • ‫name: שם הארגון שיצר את המסמך הזה.
    • ‫email: כתובת האימייל של הארגון למקרה של שאלה או תלונה.
  • ‫vexData: מחרוזת של Vulnerability Exploitability eXchange ‏ (VEX) בפורמט CycloneDX 1.4.

healthInfo.json

  • ‫creationTime: שעת היצירה של המסמך בפורמט מחרוזת RFC 3339.
  • creator: הבעלים של המסמך. הפרטים הבאים מסופקים:
    • ‫name: שם הארגון שיצר את המסמך הזה.
    • ‫email: כתובת האימייל של הארגון למקרה של שאלה או תלונה.
  • ‫testingData: הפרטים על בדיקות האבטחה שבוצעו בחבילה. הפרטים הבאים מסופקים:
    • ‫testType: סוג הבדיקה שבוצעה. לדוגמה, FUZZ.
    • ‫tool: השם של הכלי ששימש לביצוע הבדיקה.
    • ‫testStatus: הסטטוס של הבדיקה. הסטטוס יכול להיות אחד מהבאים:
      • ‫TESTED: הבדיקה בוצעה.
      • ‫NOT_REQUIRED: לא נדרש לבצע בדיקה לחבילה. לדוגמה, לא נדרשת בדיקת fuzzing בחבילה שמכילה רק ממשקים.
      • ‫UNTESTED: החבילה לא נבדקה.

licenseInfo.json

  • ‫package_name: השם של החבילה בפורמט מחרוזת.
  • ‫package_version: הגרסה של החבילה.
  • ‫license_info: הרישיון שמשויך לחבילה.

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

כדי לגשת למטא-נתונים של האבטחה מ-Cloud Storage, פועלים לפי השלבים הבאים:

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

למידע על הגדרת אימות, ראו הגדרת אימות.

שלב 2 – בניית כתובת ה-URL

אפשר להשתמש בפקודות gcloud storage או curl כדי להוריד את המטא-נתונים. כדי לבנות את כתובת ה-URL לשני המקרים, משתמשים בפרטים הבאים:

  • שפה: java או python. הערך חייב להיות באותיות קטנות.
  • ‫Package_ID: ב-Java, זה groupId:artifactId וב-Python, זה packageName. הערך חייב להיות באותיות קטנות.
  • גרסה: גרסת החבילה.
  • ‫Metadata_Type: בוחרים בין buildinfo.zip,‏ vexinfo.zip ו-healthinfo.zip.

כתובת ה-URL צריכה להיות בפורמט הבא:

gcloud

gs://cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>

שימו לב שכתובת ה-URL צריכה להיות באותיות קטנות.

כתובת URL לדוגמה ב-Python: gs://cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

כתובת URL לדוגמה ב-Java: ‏ gs://cloud-aoss-metadata/java/com.google.errorprone:error_prone_annotations/2.15.0/buildinfo.zip

curl

https://storage.googleapis.com/cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>

שימו לב שכתובת ה-URL צריכה להיות באותיות קטנות.

כתובת URL לדוגמה ב-Python: https://storage.googleapis.com/cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

כתובת URL לדוגמה ב-Java: ‏ https://storage.googleapis.com/cloud-aoss-metadata/java/com.google.errorprone:error_prone_annotations/2.15.0/buildinfo.zip

שלב 3 – הורדת המטא-נתונים

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

gcloud

gcloud storage cp  "gs://cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>" outputFolderLocation

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

gcloud storage cp "gs://cloud-aoss-metadata/<language>/<package_id>/<version>" outputFolderLocation --recursive

המטא-נתונים מפוזרים בין שלושה קובצי ZIP‏ (buildinfo.zip, ‏ healthinfo.zip, ‏ vexinfo.zip) ומורדים לתיקיית הפלט.

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type> -o output.zip

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

מחלצים את קובץ ה-ZIP. ב-macOS או ב-Linux, משתמשים בפקודה unzip: unzip input.zip -d outputFolder. כל קובץ ZIP מכיל קובץ JSON וקובץ signature.zip. קובץ ה-JSON מכיל את המטא-נתונים של האבטחה, וקובץ signature.zip מכיל קבצים לאימות החתימה של Google בקובץ ה-JSON.

הורדת פרטי הרישיון

מידע הרישיון של כל חבילות ה-Assured OSS זמין בקובץ JSON יחיד. כדי להוריד את הקובץ הזה, מריצים את הפקודה הבאה:

gcloud

gcloud storage cp  "gs://cloud-aoss/info/LicenseInfo.json" outputFolderLocation

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/cloud-aoss/info/LicenseInfo.json

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

gcloud

gcloud storage cp "gs://cloud-aoss/info/LicenseInfo.json-sig.zip" outputFolderLocation

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/cloud-aoss/info/LicenseInfo.json-sig.zip -o output.zip

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