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

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

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

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

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

  • ‫buildinfo.zip: הקובץ הזה מכיל מטא-נתונים על פרטי ה-build של חבילה. המטא-נתונים האלה ישתנו במקרים נדירים מאוד, כמו בנייה מחדש של חבילה, רוטציה של אישורים והוספת שדות חדשים.
  • ‫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: שם הקובץ שפרטי ה-build חלים עליו.
    • ‫buildProvenance: מחרוזת שמייצגת את אישור המקור של ה-build של החבילה בפורמט SLSA בגרסה 0.2. הוא נוצר על ידי Cloud Build.
    • ‫envelope: מחרוזת שמייצגת מעטפת DSSE שאפשר להשתמש בה כדי לאמת את תקינות מסמך המקור. גם הוא נוצר על ידי Cloud Build.
    • ‫slsaLevel: מציין את רמת ה-SLSA שהמערכת לבניית גרסאות עומדת בה.
    • ‫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: לא נדרשה בדיקה של החבילה. לדוגמה, לא נדרשת בדיקת פאזינג בחבילה שמכילה רק ממשקים.
      • ‫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

כדי להוריד את כל סוגי המטא-נתונים, כמו פרטי ה-build, פרטי התקינות ופרטי ה-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

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