📘 תיעוד 27

איתור בעיות אבטחה בזמן שקלוד כותב קוד

התקינו את התוסף security-guidance כדי שקלוד יבדוק את שינויי הקוד שלו לאיתור פגיעויות ויתקן אותן באותו סשן.

תוסף ה-security-guidance גורם לקלוד לסקור את שינויי הקוד של עצמו לאיתור פגיעויות נפוצות בזמן עבודתו, ולתקן את מה שהוא מוצא באותו סשן. התוסף מאתר בעיות כגון הזרקה (injection), דה-סריאליזציה לא בטוחה (unsafe deserialization), וממשקי DOM API לא בטוחים (unsafe DOM APIs) לפני שהקוד מגיע ל-pull request, ובכך מפחית את היקף סקירת האבטחה שמוטל בהמשך על סוקרים אנושיים.

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

התוסף הוא השותף בתוך הסשן ל-Code Review, שרץ על pull requests. תוסף זה מצמצם את מה שמגיע ל-PR. ה-Code Review תופס את מה שכן מגיע. כדי לראות כיצד התוסף משתלב בשכבות עם סקירה לפי דרישה וסריקת CI, או כדי לסרוק קוד שכבר יש לכם במקום שינויים שקלוד כותב, ראו כיצד זה משתלב עם כלי אבטחה אחרים.

#דרישות מוקדמות

• Python 3.7 או גרסה חדשה יותר ב-PATH שלכם. סקירת ה-commit האג'נטית דורשת Python 3.10 או גרסה חדשה יותר, וכך גם כל הסקירות המבוססות על מודל כאשר Claude Code משתמש בספק צד שלישי כגון Amazon Bedrock או Agent Platform של Google Cloud. התוסף מעדיף את המפרשים בעלי הגרסה המפורשת מ-python3.13 עד python3.10, ולאחר מכן נסוג אל python3, python, ו-py -3.
• מאגר git עבור התיקייה שבה אתם עובדים. סקירות סוף התור וה-commit מבצעות diff מול מצב ה-git ומדלגות בשקט מחוץ למאגר. בדיקת התבניות לכל עריכה פועלת בכל מקום.

בהרצה הראשונה התוסף יוצר סביבה וירטואלית תחת ~/.claude/security/ ומתקין לתוכה את ה-Claude Agent SDK, פעולה הדורשת pip וגישה לרשת. אם ההתקנה הזו נכשלת, או שגרסת ה-Python הזמינה ישנה יותר מ-3.10, סקירת ה-commit באימות ישיר מול Anthropic נסוגה לסקירה יחידה במקום הסקירה האג'נטית; בספק צד שלישי כגון Amazon Bedrock או Agent Platform של Google Cloud, הסקירות המבוססות על מודל זקוקות ל-SDK בעצמן, ולכן הן מדלגות. התוסף מציג הודעה חד פעמית כאשר גרסת Python ישנה יותר היא הגורם לכך.

#התקנת התוסף

בסשן Claude Code במסוף, התקינו מתוך ה-marketplace הרשמי של Anthropic:

/plugin install security-guidance@claude-plugins-official

הפקודה /plugin פותחת חלונית אינטראקטיבית וזמינה רק ב-CLI של המסוף. אם קלוד משיב ש-/plugin אינו זמין בסביבה זו, התקינו בדרך אחרת:

• אפליקציית שולחן העבודה של Claude, סשן מקומי או סשן SSH: פתחו את דפדפן התוספים על ידי לחיצה על כפתור ה-+ ליד שורת הפקודה, לאחר מכן Plugins, ולאחר מכן Add plugin.
• Claude Code באינטרנט או סשן ענן בשולחן העבודה: הצהירו על התוסף ב-.claude/settings.json כפי שמוצג תחת הפעלה בסשנים בענן ובמאגרים משותפים.

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

אם ההתקנה נכשלת, התאימו להודעה ש-Claude Code מדווח:

• Marketplace "claude-plugins-official" not found: הוסיפו את ה-marketplace באמצעות /plugin marketplace add anthropics/claude-plugins-official, ולאחר מכן נסו שוב את ההתקנה.
• התוסף אינו נמצא ב-marketplace: בדקו את שם התוסף.

בדקו את סיכום ההתקנה. אם מדווח שם Run /reload-plugins to activate., ראו החלת שינויים בתוספים ללא הפעלה מחדש כדי להפעיל את התוסף בסשן הנוכחי שלכם.

#הפעלה בסשנים בענן ובמאגרים משותפים

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

{
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true
  }
}

מנהלי מערכת יכולים להפעיל את התוסף ברמת הארגון כולו על ידי הגדרת enabledPlugins בתוך הגדרות מנוהלות.

#מה התוסף בודק

התוסף סוקר את עבודתו של קלוד בשלוש נקודות, כל אחת בעומק שונה:

• בכל עריכת קובץ: התאמת תבניות מהירה לקריאות מסוכנות, ללא קריאה למודל.
• בסוף כל תור: סקירת רקע של מודל עבור כל מה שהשתנה באותו תור.
• בכל commit או push שקלוד מבצע: סקירה אג'נטית מעמיקה יותר הקוראת קוד מסביב.

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

#בכל עריכת קובץ

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

קטגוריות תבניות לדוגמה:

• הרצת קוד דינמית: eval(, new Function, os.system, child_process.exec.
• דה-סריאליזציה לא בטוחה: pickle.
• הזרקת DOM: dangerouslySetInnerHTML, .innerHTML =, document.write.
• קובצי תהליכי עבודה: עריכות תחת .github/workflows/, שיכולות להעניק הרשאות ברמת המאגר.

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

באפשרותכם להוסיף תבניות משלכם לשכבה זו באמצעות קובץ security-patterns.yaml.

#בסוף כל תור

תור הוא סבב אחד של מענה מצד קלוד: אתם שולחים הודעה, קלוד עובד ועונה, והתור מסתיים. לאחר כל תור, התוסף מחשב git diff של כל מה שהשתנה בעץ העבודה במהלך התור, כולל שינויים מכלי העריכה של קלוד, פקודות Bash ותת-סוכנים, ושולח אותו לסקירה נפרדת של קלוד המתמקדת באבטחה. הסקירה רצה ברקע, כך שתשובתו של קלוד אינה מתעכבת. אם הסקירה מוצאת בעיות, קלוד מקבל הנחיה חוזרת עם הממצאים ומטפל בהם כהמשך ישיר.

פעולה זו לוכדת בעיות שהתאמת מחרוזות אינה יכולה לתפוס, כגון:

• עקיפת הרשאות
• הפניות ישירות לא בטוחות לאובייקטים
• הזרקה
• זיוף בקשות בצד השרת
• הצפנה חלשה

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

#בכל commit או push שקלוד מבצע

כאשר קלוד מריץ git commit או git push דרך כלי ה-Bash שלו, התוסף מריץ ברקע סקירה אג'נטית מעמיקה יותר של השינוי. סקירה זו קוראת קוד מסביב, כולל קוד שקורא לפונקציות, מנקי קלט וקבצים קשורים, כדי להחליט אם ממצא הוא אמיתי לפני דיווח עליו. ההקשר הנוסף שומר על שיעור נמוך של התראות שווא על תבניות שנראות מסוכנות במבודד אך בטוחות בבסיס הקוד שלכם.

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

#עצמאות הסקירה ומגבלותיה

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

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

#הוספת כללים משלכם

לתוסף יש שתי נקודות הרחבה: קובץ הנחיות ב-Markdown עבור הסקירות המבוססות על מודל, וקובץ תבניות ב-YAML או JSON עבור התאמת המחרוזות לכל עריכה. שניהם מצטברים. באפשרותכם להוסיף בדיקות, אך אינכם יכולים להשבית בדיקות מובנות מתוך קבצים אלה.

#הוספת הנחיות לסקירות המבוססות על מודל

צרו את .claude/claude-security-guidance.md בפרויקט שלכם ותארו את מודל האיומים ואת רשימת הבדיקה שלכם בשפה פשוטה. הסקירות המבוססות על מודל טוענות אותו כהקשר נוסף לצד רשימת הפגיעויות המובנית.

הדוגמה הבאה מיועדת לשירות רשת עם נתיבי ניהול מוגבלי תפקידים ומדיניות רישום יומנים של נתוני לקוחות:

# Security guidance for this repo

- Do not log `customer_id` or `account_number` at INFO level or above.
- All routes under `/admin` must call `require_role("admin")` before any database read.
- Use `crypto.timingSafeEqual` for token comparison instead of `===`.

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

#הוספת תבניות מותאמות אישית לכל עריכה

צרו את .claude/security-patterns.yaml כדי להוסיף כללי regex או מחרוזות משנה אל בדיקת התבניות לכל עריכה. אלה פועלים כהתאמות מחרוזת דטרמיניסטיות לצד התבניות המובנות:

patterns:
  - rule_name: internal_api_key
    substrings: ["sk_live_", "AKIA"]
    reminder: "Hardcoded API key prefix. Load credentials from the secret manager."
  - rule_name: tenant_unfiltered_query
    regex: "\\.objects\\.all\\(\\)"
    paths: ["**/src/tenants/**"]
    reminder: "Multi-tenant code must filter by org_id."

התוסף קורא גם את .claude/security-patterns.yml ואת .claude/security-patterns.json באותו מבנה. קובץ JSON פועל בכל התקנת Python. תצורות ה-YAML דורשות שניתן יהיה לייבא את PyYAML, שהתוסף אינו מתקין עבורכם. התוסף טוען עד 50 כללים מותאמים אישית ומדלג על ביטויי regex שנראים מועדים לנסיגה קטסטרופלית.

#מיקומי חיפוש קובצי כללים

התוסף מחפש את claude-security-guidance.md ואת security-patterns.yaml באותם מיקומים, ללא תלות באופן שבו התוסף הופעל:

התוסף טוען את כל המיקומים הקיימים ומשרשר אותם, עם מגבלה כוללת של 8 KB עבור קובץ ההנחיות. מנהלי מערכת יכולים להפיץ כללים ברמת הארגון על ידי דחיפת הקובץ בטווח המשתמש אל ~/.claude/ באמצעות ניהול מכשירים. אותם נתיבים חלים גם על security-patterns.yaml.

#עלות שימוש

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

שתי הסקירות המבוססות על מודל משתמשות ב-Claude Opus 4.7 כברירת מחדל. הגדירו את SECURITY_REVIEW_MODEL כדי לבחור מודל שונה עבור סקירת סוף התור, ואת SG_AGENTIC_MODEL עבור סקירת ה-commit.

התוסף זמין בכל התוכניות.

#השבתה או הסרת התקנה

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

כדי להשהות את התוסף בטווח המשתמש שלכם:

/plugin disable security-guidance@claude-plugins-official

כדי להסיר אותו מטווח המשתמש שלכם:

/plugin uninstall security-guidance@claude-plugins-official

אם התוסף הופעל דרך קובץ .claude/settings.json של הפרויקט, הסרת ההתקנה שלו מתוך /plugin כותבת דריסה אל .claude/settings.local.json שלכם במקום לערוך את הקובץ שנשמר במאגר, כך שהתוסף נשאר כבוי עבורכם בעוד שחברי הצוות אינם מושפעים. אותה תיבת דו-שיח מציעה גם להסיר את התקנת התוסף עבור כולם על ידי הסרתו מקובץ .claude/settings.json המשותף. אם הוא הופעל דרך הגדרות מנוהלות, רק מנהל מערכת יכול להשבית אותו.

#כיצד התוסף משתלב עם Claude Code

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

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

#כיצד זה משתלב עם כלי אבטחה אחרים

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

כדי למצוא בעיות אבטחה בקוד שכבר יש לכם, ולא בשינויים שקלוד כותב, בקשו מקלוד בסשן לסקור קובץ או תיקייה ספציפיים לאיתור פגיעויות, או השתמשו ב-תוסף Claude Security לסריקה מעמיקה יותר מרובת סוכנים של המאגר כולו; הפקודה /security-review מכסה רק את השינויים בענף הנוכחי שלכם. כך או כך, הסקירה קוראת את קוד המקור בעותק המקומי שלכם, ולא אתר חי או שירות שנפרס.

#פתרון בעיות

התוסף כותב אבחון בזמן ריצה אל ~/.claude/security/log.txt. בדקו שם תחילה אם סקירות אינן מופיעות.

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

• התיקייה אינה מאגר git: סקירות סוף התור וה-commit דורשות מצב git ומדלגות מחוץ למאגר.
• לסשן אין אימות של Anthropic ואין ספק צד שלישי מוגדר: הסקירות המבוססות על מודל מדלגות ורק בדיקת התבניות לכל עריכה רצה.
• קובץ security-patterns.yaml קיים אך PyYAML אינו ניתן לייבוא: המערכת מתעלמת מהקובץ. השתמשו ב-security-patterns.json במקום זאת.

#משאבים קשורים

כדי להעמיק בחלקים שדף זה נוגע בהם:

• Code Review: הגדרת הסקירה מרובת הסוכנים בזמן PR.
• אוטומציה של פעולות באמצעות hooks: בניית בדיקות משלכם באותן נקודות במחזור החיים.
• גילוי והתקנת תוספים: עיון בתוספים רשמיים נוספים.