סריקת מיומנויות לאיתור בעיות אבטחה

בעזרת Agent Registry אתם יכולים להגדיר סריקת אבטחה אוטומטית של מיומנויות נפרדות, לאכוף כללי מדיניות לסריקה בכל הארגון באמצעות שירות מדיניות הארגון, ולמיין ממצאי אבטחה כדי למנוע ממיומנויות שנחשפו להגיע לסוכנים.

כשמעלים גרסה של מיומנות, Agent Registry סורק את קובץ ההוראות של SKILL.md, את הסקריפטים האופציונליים ואת הנכסים התומכים כדי לאתר סיכוני אבטחה כמו זליגת נתונים לא מורשית, פרטי כניסה חשופים והחדרת פרומפטים.

בסריקת האבטחה של המיומנויות נעשה שימוש במודלים גדולים של שפה (LLM) כדי להעריך את ההוראות, את הלוגיקה של הקוד ואת הכוונה הסמנטית. מכיוון שהניתוח של LLM הוא הסתברותי, הסריקות עשויות להניב תוצאות חיוביות מוטעות או תוצאות שליליות מוטעות, והתוצאות עשויות להשתנות בין הרצות שונות. בנוסף, הפרטים על הממצאים עשויים להיות משוערים ועלולים לכלול הזיות. המפתחים צריכים לבדוק ולאמת את ממצאי הסריקה לפני שהם מבצעים שינויים לתיקון הבעיות.

לפני שמתחילים

  1. הגדרת Agent Registry.

  2. אם אתם משתמשים בפרויקט אחד, אתרו את מזהה הפרויקט של פרויקט הפיקוח שבו מופעל Agent Registry. אם הגדרתם גבול ניהול לכמה פרויקטים, השתמשו במזהה של פרויקט הניהול כדי לגלות ולרשום את כל הפרויקטים בגבול, או ציינו מזהה של פרויקט חבר כדי לבצע פעולות בפרויקט יחיד.

  3. לרשום מיומנות עצמאית ב-Agent Registry.

  4. כדי להשתמש בפקודות של Google Cloud CLI שמופיעות במסמך הזה, צריך להגדיר את סביבת ה-CLI של gcloud.

התפקידים הנדרשים

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

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

יכול להיות שגם תפקידים אחרים ב-Agent Registry כוללים את ההרשאות שנדרשות כדי להגדיר סריקה ולראות מיומנויות. מידע נוסף זמין במאמר תפקידים והרשאות ב-Agent Registry.

מגבלות על גודל המטען הייעודי (payload) הלא דחוס

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

  • הגודל הכולל של הסקיל הלא דחוס: עד 10MB לארכיון שחולץ.
  • גודל הקובץ ללא דחיסה: עד 1MB לכל קובץ בנפרד בחבילת המיומנות.

אם הסריקה מופעלת במיומנות והיא חורגת מהמגבלות האלה, יצירת גרסה של המיומנות נכשלת עם השגיאה INVALID_ARGUMENT או שסטטוס הסריקה של הגרסה הופך ל-UNSUPPORTED_FORMAT.

אם הסריקה מושבתת באופן מפורש, Agent Registry עוקף את מגבלות הגודל הספציפיות לסריקה, אבל מגבלות המערכת הכלליות עדיין חלות. מידע נוסף על מגבלות המערכת זמין במאמר מכסות ומגבלות המערכת.

הגדרת מדיניות סריקה למיומנות

כברירת מחדל, המיומנויות משתמשות במדיניות הסריקה מופעלת (חסימה) (ENABLED_BLOCKING), שסורקת באופן אוטומטי גרסאות מיומנות שהועלו כדי לאתר סיכוני אבטחה כמו זליגת נתונים לא מורשית, פרטי כניסה חשופים והחדרת פרומפטים. הבעיות שזוהו מוצגות כמשאבי Finding לקריאה בלבד בפרויקט הפיקוח projects/PROJECT_NUMBER/locations/LOCATION/findings/FINDING_ID.

אם בוחרים באפשרות מופעל (חסימה), מאגר הסוכנים חוסם הורדה של גרסאות עם ממצאי אבטחה ומונע קידום של גרסאות עם ממצאים או סריקות בהמתנה בתור גרסת ברירת המחדל של המיומנות.

אפשר גם להגדיר מדיניות סריקה למצב ביקורת ללא חסימה (ENABLED_NONBLOCKING) או להשבית את הסריקה (DISABLED). מידע נוסף על מדיניות סריקה נתמכת זמין במאמר מדיניות סריקה.

הגדרה או עדכון של הגדרות סריקת המיומנויות

אם מפעילים או מעדכנים את הסריקה במיומנות קיימת, השינוי חל רק על גרסאות של המיומנות שנוצרו אחרי השינוי בהגדרות. הסריקה לא מופעלת באופן רטרואקטיבי על גרסאות שכבר נוצרו. כדי לסרוק תוכן של מיומנות שהועלה כשהסריקה הייתה מושבתת, צריך ליצור גרסה חדשה של המיומנות.

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

המסוף

  1. נכנסים לדף Agent Registry במסוף Google Cloud :

    כניסה ל-Agent Registry

  2. לוחצים על הכרטיסייה מיומנויות.

  3. לוחצים על הוספת מיומנות או בוחרים מיומנות קיימת ולוחצים על עריכה.

  4. בקטע סריקת אבטחה, בוחרים את מדיניות הסריקה הרצויה.

  5. לוחצים על שמירה או על יצירה.

gcloud

  • יצירת מיומנות עם סריקה מופעלת (חסימה): מריצים את הפקודה gcloud agent-registry skills create כשהדגל --scanning-policy מוגדר ל-enabled-blocking. לדוגמה, אם אתם רושמים מיומנות באמצעות ארכיון ZIP מקטגוריה של Cloud Storage:

    gcloud agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --target-state=disabled \
    --scanning-policy=enabled-blocking \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

  • יצירת מיומנות עם סריקה מופעלת (ללא חסימה): מריצים את הפקודה gcloud agent-registry skills create עם הדגל --scanning-policy שמוגדר ל-enabled-nonblocking. לדוגמה, אם אתם רושמים מיומנות באמצעות ארכיון ZIP מקטגוריה של Cloud Storage:

    gcloud agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --target-state=disabled \
    --scanning-policy=enabled-nonblocking \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

  • עדכון מדיניות הסריקה במיומנות קיימת: מריצים את הפקודה gcloud agent-registry skills update עם הדגל --scanning-policy שמוגדר למדיניות שנבחרה, לדוגמה enabled-nonblocking:

    gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=enabled-nonblocking

  • השבתת הסריקה במיומנות: מריצים את הפקודה gcloud agent-registry skills update כשהדגל --scanning-policy מוגדר לערך disabled:

    gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=disabled

  • תיאור הגדרת הסריקה במיומנות קיימת: מריצים את הפקודה gcloud agent-registry skills describe כשהדגל --format מוגדר ל-value(scanningConfig.policy):

    gcloud agent-registry skills describe SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(scanningConfig.policy)"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫SKILL_ID: מזהה המיומנות. כשמעדכנים או מתארים מיומנות קיימת שנרשמה באופן ידני, צריך לכלול את הקידומת private-, למשל private-my-skill.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: המיקום של המרשם.
  • ‫BUCKET_NAME: השם של הקטגוריה ב-Cloud Storage שמכילה את חבילת ה-ZIP. לפני שמייבאים מקטגוריה, צריך לוודא שלסוכן השירות של Agent Registry יש את ההרשאה storage.objects.get בקטגוריה. מידע נוסף זמין במאמר רישום מיומנות.
  • ‫SKILL_PACKAGE: השם של חבילת המיומנות שמכילה את המטען הייעודי של המיומנות.

REST

כדי להגדיר סריקה באמצעות ה-API בארכיטקטורת REST, צריך לכלול את האובייקט scanningConfig בגוף הבקשה:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
        "scanningConfig": {
          "policy": "ENABLED_BLOCKING"
        }
      }' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=scanningConfig"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: המיקום של המרשם.
  • ‫SKILL_ID: מזהה המיומנות. למיומנויות שנרשמו באופן ידני, צריך לכלול את הקידומת private-, למשל private-my-skill.

אכיפת הסריקה באמצעות שירות מדיניות הארגון

כדי לאכוף מדיניות סריקה ברמת הארגון, אתם יכולים להגדיר אילוץ מותאם אישית של שירות מדיניות הארגון במשאב Skill שמעריך את מדיניות הסריקה, עם פטורים אופציונליים של תגי מנהל המשאבים.

במאמר אכיפת מדיניות הארגון מוסבר איך אוכפים את מדיניות הארגון ב-Agent Registry, מה היכולות ומה המגבלות.

הגדרת האילוץ המותאם אישית

יוצרים קובץ YAML בשם skills-scan-constraint.yaml עם המפרט הבא:

name: organizations/ORGANIZATION_ID/customConstraints/custom.skillsScanningEnforcement
resourceTypes:
- agentregistry.googleapis.com/Skill
methodTypes:
- CREATE
- UPDATE
condition: resource.scanningConfig.policy == "DISABLED"
actionType: DENY
displayName: Prevent Disabling Skills Scanning
description: Prevents creating or updating skills with scanning disabled.

מחליפים את ORGANIZATION_ID במזהה הארגון המספרי.

כדי לדרוש מצב חסימה בכל המיומנויות ולמנוע את מדיניות הסריקה של DISABLED ושל ENABLED_NONBLOCKING, אפשר להגדיר את condition: resource.scanningConfig.policy == "ENABLED_BLOCKING" ואת actionType: ALLOW.

הגדרת האילוץ המותאם אישית

מעלים ורושמים את האילוץ המותאם אישית בארגון באמצעות הפקודה gcloud org-policies set-custom-constraint:

gcloud org-policies set-custom-constraint skills-scan-constraint.yaml

החלת המדיניות עם פטורים מותנים

יוצרים קובץ הגדרת מדיניות בשם skills-scan-policy.yaml שאוכף את האילוץ בכל הפרויקטים הרגילים, אבל מחריג, לדוגמה, פרויקטים לבדיקה שתייגתם בתג exempt-scanning-enforcement: true:

name: organizations/ORGANIZATION_ID/policies/custom.skillsScanningEnforcement
spec:
  rules:
  # Enforce scanning on all standard projects
  - enforce: true
    condition:
      expression: "!resource.matchTag('ORGANIZATION_ID/exempt-scanning-enforcement', 'true')"
      title: "Enforce Scanning"
      description: "Enforce scanning on all non-exempt projects"
  # Bypass enforcement for tagged projects
  - enforce: false
    condition:
      expression: "resource.matchTag('ORGANIZATION_ID/exempt-scanning-enforcement', 'true')"
      title: "Exempt Testing Projects"
      description: "Allow scanning to be disabled for testing projects"

מחליפים את ORGANIZATION_ID במזהה הארגון המספרי.

מחילים את המדיניות על הארגון באמצעות הפקודה gcloud org-policies set-policy:

gcloud org-policies set-policy skills-scan-policy.yaml

אימות המדיניות

כדי לוודא שהמדיניות פעילה בפרויקט, מריצים את הפקודה gcloud org-policies describe:

gcloud org-policies describe custom.skillsScanningEnforcement \
    --project=PROJECT_ID \
    --effective

מחליפים את PROJECT_ID במזהה הפרויקט.

בדיקת תוצאות הסריקה וסטטוס הבדיקה

כשמפרסמים גרסה של סקיל, הסורק פועל באופן אסינכרוני ברקע. כדי לבדוק את המטא-נתונים של הגרסה ולוודא את תוצאת הסריקה, מריצים את הפקודה gcloud agent-registry skills revisions describe:

gcloud agent-registry skills revisions describe REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION

מחליפים את מה שכתוב בשדות הבאים:

  • ‫REVISION_ID: המזהה של גרסת הסקיל.
  • ‫SKILL_ID: המזהה של מאגר המיומנויות. במיומנויות שנרשמו ידנית, צריך לכלול את הקידומת private-, למשל private-my-skill.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: המיקום של המרשם.

הפלט מכיל את הבלוק scanResult, שנראה כמו בדוגמה הבאה:

name: projects/my-project/locations/us-central1/skills/private-my-skill/revisions/rev-v1
createTime: '2026-08-10T09:15:00.000000Z'
state: ACTIVE
scanResult:
  scanState: SUCCEEDED
  scanTime: '2026-08-10T09:16:22.000000Z'
  findings:
  - projects/my-project/locations/us-central1/findings/b9a8c7d6-e5f4-4321-89ab-cdef01234567

הערכים האפשריים של scanResult.scanState הם:

  • ‫SUCCEEDED: הסריקה הסתיימה. אם זוהו בעיות אבטחה, שמות המשאבים שלהן מופיעים במערך scanResult.findings. אם לא זוהו בעיות, השדה scanResult.findings ריק.
  • ‫RUNNING: הסריקה מתבצעת בפועל.
  • ‫DISABLED: הסריקה נעקפת כי מדיניות הסריקה של המיומנות מוגדרת ל-DISABLED בזמן שנוצרת גרסת המיומנות.
  • ‫UNSUPPORTED_FORMAT: הסורק לא יכול לנתח את הארכיון שהועלה, למשל כי הגודל שלו אחרי פריסה חורג ממגבלות הסריקה או כי פורמט הארכיון לא נתמך. פרטים נוספים מופיעים במאמר scanResult.errorMessage.
  • ‫FAILED: אי אפשר להשלים את הסריקה בגלל שגיאה פנימית. פרטים נוספים זמינים במאמר scanResult.errorMessage.

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

מיון ראשוני של ממצאי אבטחה

כשסריקה מזהה בעיות אבטחה, נתוני טלמטריה מפורטים מתפרסמים ב-Agent Registry כמשאבי Finding ברמת הפרויקט והמיקום. כדי לצפות בממצאים, צריך את התפקיד "אדמין של Agent Registry API"‏ (roles/agentregistry.admin).

  • הצגת רשימה של כל הממצאים של גרסת מיומנות: מריצים את הפקודה gcloud agent-registry findings list:

    gcloud agent-registry findings list \
    --project=PROJECT_ID \
    --location=LOCATION \
    --filter="resource=\"projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID\""

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט.
    • ‫LOCATION: המיקום של המרשם.
    • ‫SKILL_ID: המזהה של מאגר המיומנויות, למשל private-my-skill.
    • ‫REVISION_ID: המזהה של גרסת הסקיל.

    הפלט אמור להיראות כך:

    NAME                                                                                  SEVERITY           FINDING_CLASS  CREATE_TIME
projects/my-project/locations/us-central1/findings/FINDING_ID  SEVERITY_CRITICAL  VULNERABILITY  2026-08-10T09:16:22.104Z

  • תיאור פרטי הממצא: מריצים את הפקודה gcloud agent-registry findings describe:

    gcloud agent-registry findings describe FINDING_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format=json

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫FINDING_ID: המזהה של המשאב Finding.
    • ‫PROJECT_ID: מזהה הפרויקט.
    • ‫LOCATION: המיקום של המרשם.

    פלט לדוגמה של ממצא:

    {
  "name": "projects/my-project/locations/us-central1/findings/FINDING_ID",
  "uid": "FINDING_ID",
  "createTime": "2026-08-10T09:16:22.104Z",
  "updateTime": "2026-08-10T09:16:22.104Z",
  "resource": "projects/my-project/locations/us-central1/skills/private-my-skill/revisions/rev-v1",
  "severity": "SEVERITY_CRITICAL",
  "findingClass": "VULNERABILITY",
  "files": [
    {
      "path": "resources/helper.py",
      "lineNumber": "12"
    }
  ],
  "detail": "Involves unauthorized outbound network requests transmitting sensitive local files or environment variables. Detected inside resources/helper.py at line 12."
}

    כל משאב של Finding כולל את שדות המפתח הבאים:

    • ‫resource: שם המשאב המלא של גרסת המיומנות שמשויכת לממצא.
    • ‫severity: רמת החומרה. הערכים המותרים הם:
      • SEVERITY_CRITICAL
      • SEVERITY_HIGH
      • SEVERITY_MEDIUM
      • SEVERITY_LOW
      • SEVERITY_UNSPECIFIED
    • ‫findingClass: סוג הממצא:
      • ‫VULNERABILITY: חולשה בתוכנה או בהוראות.
      • ‫SECRET: פרטי כניסה, מפתחות או אסימונים חשופים בטקסט פשוט.
    • ‫files: רשימת הקבצים המושפעים בארכיון המיומנות, כולל path ו-lineNumber יחסיים. הערך 0 מציין שהממצא רלוונטי לכל הקובץ.
    • ‫detail: הסבר מפורט על בעיית האבטחה שזוהתה.

תיקון ממצאים ועדכון מיומנויות

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

  1. בודקים את השדה detail של הממצא ואת הקובץ הבעייתי path ו-lineNumber במערך files. הסריקה האוטומטית משתמשת במודלי LLM כדי לבדוק את הקוד הסמנטי ואת ההוראות, לכן חשוב לאמת את מספרי השורות והממצאים שדווחו לפני שמשנים את הקבצים.
  2. כדי לפתור את הבעיה, מעדכנים את קובצי המקור בסביבת הפיתוח המקומית. לדוגמה, להסיר קריאות לא מורשות לרשת, להסיר פרטי כניסה חשופים או להסיר דפוסים של החדרת פרומפטים.
  3. אורזים את הקבצים המעודכנים בארכיון ZIP חדש.
  4. יצירת גרסה חדשה של מיומנות.
  5. מוודאים שהגרסה החדשה של scanResult.scanState נפתרת ל-SUCCEEDED בלי ממצאים ברשימה.
  6. מעדכנים את גרסת ברירת המחדל של המיומנות כך שתצביע על הגרסה המאומתת.

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