📘 תיעוד 36

סרוק את מאגר הקוד לאיתור חולשות

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

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

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

התוסף רץ מקומית בסשן שלך, משתמש במודלים שיש לך גישה אליהם ב-Claude Code, וכל סריקה נספרת בשימוש שלך. אם אתה רוצה שירות מנוהל שמנטר את המאגרים שלך, או שאתה רוצה להריץ סריקות על Claude Mythos, ראה את מוצר Claude Security, הזמין בתוכנית Enterprise.

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

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

כדי להריץ את התוסף, אתה צריך:

• תוכנית בתשלום, גישה ל-API של Anthropic, או ספק צד שלישי, עבור תהליכי העבודה הדינמיים שהסריקה משתמשת בהם כדי לתזמר את הסוכנים שלה. ב-Pro, הפעל אותם משורת Dynamic workflows ב-/config.
• Python 3.9 או גרסה מאוחרת יותר, זמין ב-PATH שלך בתור python3. בדוק עם python3 --version. כלי התוסף משתמשים רק בספרייה הסטנדרטית של Python, כך ששום דבר לא מותקן.
• Linux, macOS, או Windows.
• Git, עבור סריקות שינויים ועבור הפיכת ממצאים לטלאים. המשימות האלה לא תומכות במערכות בקרת גרסאות אחרות. סריקה מלאה עובדת בכל תיקייה, עם בקרת גרסאות או בלי.

#מודלים וספקים

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

• מודל: הסוכנים שצדים חולשות, מאמתים ממצאים, וכותבים וסוקרים טלאים רצים על המודל של הסשן שלך. כדי לשנות אותו, הרץ /model בסשן שלך לפני שאתה מתחיל סריקה. כמה שלבי עזר, כגון מיפוי המאגר, משתמשים בכינוי sonnet במקום זאת.
• ספק: סריקות רצות על תוכנית בתשלום, עם גישה ל-API של Anthropic, או על ספק צד שלישי כגון Amazon Bedrock, Google Cloud's Agent Platform, או Microsoft Foundry.

אצל ספק צד שלישי, כינוי sonnet יכול להיפתר לגרסה שונה מזו שב-API של Anthropic. אם החשבון שלך לא יכול להשתמש בגרסה הזו, נעץ את גרסאות המודל שלך, כולל ANTHROPIC_DEFAULT_SONNET_MODEL.

נפילה אוטומטית למודל מריצה מחדש בקשה שמנגנוני ההגנה של מודל סימנו. ב-Amazon Bedrock, ב-Google Cloud's Agent Platform וב-Microsoft Foundry, הבקשה יכולה להסתיים בהודעת סירוב במקום זאת, בהתאם לאופן שבו הפריסה שלך מוגדרת.

#התקנת התוסף

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

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

הפקודה פותחת את פרטי התוסף, ושם אתה בוחר היקף התקנה כדי להתחיל את ההתקנה.

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

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

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

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

#עדכון התוסף

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

#הסרת התוסף

כדי להסיר את התוסף, הסר אותו מתפריט /plugin, או הרץ claude plugin uninstall claude-security בטרמינל שלך.

#סריקה ותיקון של מאגר הקוד

התוסף מוסיף פקודה אחת, /claude-security, שפותחת תפריט של שלוש המשימות שלו: סריקת מאגר הקוד, סריקת קבוצת שינויים, והצעת טלאים. התרחיש המוצלח מריץ סריקה מלאה, ואז הופך את הממצאים שלה לטלאים:

1. פתיחת תפריט Claude Security

   הרץ /claude-security ובחר Scan codebase.

2. בחירת מה לסרוק

   התוסף קורא קודם את המאגר שלך, ואז מציע את המאגר כולו או אזור ממוקד, כשלכל אפשרות מצוינים מספר הקבצים והעלות היחסית. בחר את המאגר כולו, או ענה "I don't know" והתוסף בוחר ברירת מחדל סבירה לפי גודל המאגר שלך.

3. אישור הריצה

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

4. קריאת הדוח

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

5. הפיכת ממצאים לטלאים

   הרץ שוב את /claude-security ובחר Suggest patches, ואז בחר אילו ממצאים לטפל בהם. טלאים שנסקרו נכתבים לתיקיית patches/ של הדוח. תיקון ממצאים מכסה איך כל טלאי נבנה ונסקר.

6. החלת הטלאים שאתה מקבל

   החל כל טלאי מהמעטפת שלך עם git apply, בבקשת משיכה משלו. טלאים אף פעם לא מוחלים אוטומטית.

אתה לא חייב להתחיל מהתפריט: בקש משימה ישירות, כארגומנטים לפקודה, כגון /claude-security scan my branch, או בשפה רגילה, כגון "scan commit abc1234". התוסף עובד הכי טוב במצב auto, שמאפשר לסוכני הסריקה להמשיך בלי בקשת הרשאה בכל שלב.

#סריקה של השינויים בלבד

כשלענף שלך יש commits שאין בבסיס שלו, תפריט /claude-security מציע לסרוק רק את ה-diff הזה, כדי שתוכל לבדוק ענף לפני מיזוג. אתה יכול גם לסרוק אחת מבקשות המשיכה הפתוחות שלך, או commit יחיד באמצעות בקשה לכך, כגון "scan commit abc1234". רק שינויים שבוצע להם commit נסרקים: בצע commit או stash לעריכות שעדיין בעבודה קודם, או הרץ סריקה מלאה, שקוראת את עץ העבודה.

סריקות שינויים צריכות מאגר git. סריקות מלאות של תיקייה בלי בקרת גרסאות עדיין עובדות. מציאת בקשות המשיכה הפתוחות שלך היא השלב היחיד שמגיע לרשת, והוא מוצע רק כשלסשן שלך כבר יש הרשאה להריץ את GitHub CLI ו-gh מחובר.

#הגדרת היקף במאגרים גדולים

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

#בחירת מאמץ הסריקה

מאמץ הסריקה קובע כמה עמוק סריקה הולכת. הממצאים שלך עוברים את אותו אימות עצמאי ב-low, ב-medium וב-high.

• low: מבט ראשון מהיר. הוא מדלג על מפת הארכיטקטורה ועל מודל האיומים כשאתה סורק את מאגר הקוד שלך.
• medium: ברירת המחדל.
• high: מה ש-medium עושה, ועוד ציד חולשות באותו קוד.

ציין את מאמץ הסריקה בבקשה שלך בשורת הקלט של Claude Code, כגון /claude-security scan my public API code at high או /claude-security scan my branch at high.

אם סריקה של מאגר גדול מוצאת פחות ממה שאתה מצפה, בחר מאמץ סריקה high, סרוק פעם שנייה, או עשה את שניהם. כל אחד יכול לדווח על ממצאים שסריקת medium אחת לא מדווחת עליהם.

#קריאת תוצאות הסריקה

כל סריקה כותבת את התוצאות שלה לתיקיית CLAUDE-SECURITY-<timestamp>/ עם חותמת זמן במאגר שלך:

• CLAUDE-SECURITY-RESULTS.md: הדוח, עם מזהה של כל ממצא, כגון F1, וגם ההשפעה שלו, תרחיש הניצול, החומרה, רמת הביטחון וההמלצה
• CLAUDE-SECURITY-RESULTS.jsonl: אותם ממצאים בצורה קריאה למכונה, אובייקט JSON אחד בכל שורה
• CLAUDE-SECURITY-RESULTS.sarif: אותם ממצאים כיומן SARIF 2.1.0 עבור סריקת קוד של GitHub וכל כלי אחר שקורא את התקן. הסריקה מסווגת ממצאים תחת קטגוריות החולשה CWE שלהם
• CLAUDE-SECURITY-REVISION-<commit>.json: חותמת הרוויזיה, שמתעדת איזה commit נסרק, באיזה מאמץ סריקה, האם שינויים שלא בוצע להם commit היו חלק מהעץ שנסרק, ועד כמה הריצה אומתה לעומק, כך שדוח תמיד קשור לקוד שהוא מתאר. סריקה מחוץ לבקרת גרסאות חותמת UNVERSIONED במקום ה-commit

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

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

#תיקון ממצאים

התחל את תהליך התיקון באמצעות בחירת Suggest patches מתפריט /claude-security, או בקש בשפה רגילה, כגון "fix finding F3", ואז בחר אילו ממצאים מהדוח לטפל בהם. טלאים נבנים מול קוד שבוצע לו commit, והדוח צריך עדיין לתאר את הקוד שיש לך: ממצאים שהקוד שלהם השתנה מאז מדולגים עם הערה, והתוסף מציע סריקה חדשה במקום לתקן מדוח לא עדכני. כל טלאי נכתב כטיוטה בעותק טיוטה של המאגר שלך, כך שקובצי המקור שלך נשארים ללא נגיעה עד שאתה מחיל טלאי בעצמך.

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

#טלאים אף פעם לא מוחלים אוטומטית

החלת טלאי היא תמיד ההחלטה שלך. טלאים נכתבים לתיקיית patches/ של הדוח, F<n>.patch אחד לכל ממצא, עם הערה לצדו שמסבירה את השינוי. החל אחד מהמעטפת שלך, או בקש מ-Claude להחיל אותו ולפתוח בקשת משיכה:

git apply CLAUDE-SECURITY-<timestamp>/patches/F1.patch

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

#איך התוסף משתלב עם כלי אבטחה אחרים

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

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

#פתרון בעיות

תפריט /claude-security נפתח עם אזהרת Python. התוסף צריך python3 בגרסה 3.9 או מאוחרת יותר ב-PATH שלך. כשהוא לא מוצא python3 בכלל, התפריט מזהיר ש-Claude Security לא יעבוד עד שיותקן אחד. כשה-python3 הראשון ב-PATH שלך ישן יותר, האזהרה מציינת את הגרסה שנמצאה. התקן את Python 3, או שים python3 חדש יותר ראשון ב-PATH, ואז פתח סשן חדש.

ייתכן שתראה הודעת "safeguards flagged this message" בסריקה על מודל Fable. ההודעה מציינת את המודל שרץ אצלך. מסווגי הבטיחות של Fable בתחום הסייבר מסמנים בקשות מסוימות, ו-Claude Code מריץ מחדש בקשה שסומנה על מודל Opus דרך נפילה אוטומטית למודל. זה צפוי. כשהבקשה רצה מחדש, הסריקה אמורה עדיין להסתיים בהצלחה.

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

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

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