התקנה והגדרה של ה-CLI

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

ארכיטקטורה ומודל אבטחה

‫CodeMender משתמש במודל הרצה מקומי:

• מנוע חשיבה רציונלית מתארח: חשיבה רציונלית סוכנית, מידול איומים ולוגיקה של תזמור פועלים בצורה מאובטחת ב- Cloud de Confiance by S3NS ב-Gemini Enterprise Agent Platform.
• ממשק שורת הפקודה (CLI) להפעלה מקומית: קוד המקור אף פעם לא יוצא מתחנת העבודה או מהקונטיינר של ה-CI/CD בכמויות גדולות. כלי ה-CLI המקומי של cm מבצע קריאות של קבצים, בדיקות של גרסאות build מקומיות ואימותים של ניצול פרצות (PoC) בארגז החול המקומי, ושולח רק קטעי קוד ספציפיים ותוצאות של הפעלת כלים לקצה העורפי בענן דרך Interactions API ב-Gemini Enterprise Agent Platform.

הגדרת הסביבה

כדי להתחיל להשתמש ב-CodeMender, מגדירים את הפרויקט ב- Cloud de Confiance , מורידים ומתקינים את ה-CLI, מגדירים את פרטי הכניסה ואת פרויקט היעד ומפעילים את סביבת העבודה.

הגדרת הפרויקט והרשאות IAM

לפני שמורידים את ה-CLI ומגדירים את פרטי הכניסה, צריך לוודא שפרויקט היעד ב- Cloud de Confiance מוגדר בצורה נכונה עם ממשקי ה-API וההרשאות הנדרשים.

ממשקי ה-API הנדרשים

מוודאים שממשקי Cloud de Confiance by S3NS ה-API הבאים מופעלים בפרויקט:

1. ‫Agent Platform API ‏ (aiplatform.googleapis.com) – מפעיל את הסטרימינג והניהול של סשנים פעילים.
2. ‫Cloud Resource Manager API‏ (cloudresourcemanager.googleapis.com) – מאמת את מצבי האימות של המשתמשים ואת המטא-נתונים של הפרויקט.

תפקיד מוגדר מראש מומלץ ב-IAM

כדי להריץ את פקודות ה-CLI, צריך להקצות למשתמשים את תפקיד ה-IAM הבא:

• משתמש ב-Agent Platform (roles/aiplatform.user) – מאפשר למשתמשים ליצור סשנים פעילים, להזרים אותם ולנהל אותם.

הורדה והתקנה של CodeMender CLI

קבצים בינאריים של CodeMender CLI מתארחים ב-Artifact Registry. בוחרים את הכרטיסייה של מערכת ההפעלה כדי להוריד ולהתקין את ה-CLI.

הגדרת Cloud de Confiance פרטי הכניסה והפרויקט

ממשק שורת הפקודה של CodeMender מתקשר עם מנוע החשיבה הרציונלית שמתארח בענן דרך Interactions API, לכן צריך להגדיר Cloud de Confiance by S3NS Application Default Credentials (ADC) ולציין את פרויקט היעד בסביבה.

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

   gcloud auth application-default login
   

2. מגדירים את משתנה הסביבה GOOGLE_CLOUD_PROJECT למזהה הפרויקט ב- Cloud de Confiance :

   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   

   אפשר גם להגדיר את הפרויקט הפעיל ב-CLI של gcloud:

   gcloud config set project PROJECT_ID
   

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

הפעלת סביבת העבודה

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

מריצים את cm init מתיקיית השורש של בסיס הקוד כדי ליצור קובצי מעקב אחרי המצב המקומי ולקבוע הגדרות בסיסיות:

cm init

משתמשים בדגל --verify כדי לבדוק את הקישוריות למנוע ההסקה שמתארח בענן ולאמת את הגדרות סביבת העבודה:

cm init --verify

פרמטרים של הגדרות (config.yaml)

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

מכיוון שסוכן ה-AI שמתארח מריץ פקודות מקומיות (כמו בניית קוד, הרצת בדיקות או עריכת קבצים) באמצעות לקוח ה-daemon המקומי, קובץ התצורה הזה משמש כגבול שמגדיר מה מותר ומה אסור לסוכן לעשות.

Usage

• מיקום: כברירת מחדל, ה-CLI קורא את הקובץ הזה מ-~/.codemender/config.yaml. כדי לשנות את ספריית סביבת העבודה וההגדרות, מגדירים את משתנה הסביבה CM_HOME (לדוגמה, CM_HOME=/path/to/custom/dir, שקורא /path/to/custom/dir/config.yaml).
• ביצוע: כשמריצים פקודות כמו cm find,‏ cm verify או cm fix, הלקוח המקומי קורא את הקובץ הזה כדי להגדיר פרמטרים של בטיחות, להחיל עקיפות של המערכת ולציין אילו קבצים או ספריות להתעלם מהם.

הגדרות ברירת המחדל של Core

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

• ‫human_confirmation: true (או require_confirmation: true)

  • מה זה אומר: כברירת מחדל, CodeMender לא יכול לשנות קבצים בדיסק או להריץ פקודות מעטפת בלי לבקש מכם אישור מפורש ב-[Y/n] בטרמינל.
  • למה זו הגדרת ברירת המחדל: יכול להיות ש-CodeMender ייצור תיקונים ספקולטיביים או ינסה להריץ סקריפטים של ניצול לרעה כדי לאמת פגיעות. הדרישה לאישור אנושי עוזרת למנוע שינויים מקריים במערכת או הפעלה לא מורשית של קוד בסביבה המקומית.
  • מעקף: בצינורות עיבוד נתונים של CI/CD לא אינטראקטיביים, אפשר להגדיר את הערך הזה ל-false.

• confirm_writes: false

  • מה זה אומר: משבית את ההנחיות האינטראקטיביות לשינוי קבצים, ומאפשר לסוכן CodeMender לכתוב תיקוני אבטחה ולשנות קובצי מקור ישירות בדיסק המקומי בלי לחכות לאישור אנושי.
  • למה זו ברירת המחדל: כברירת מחדל, CodeMender מגדיר את אמצעי הבטיחות הזה לערך true כדי לאכוף תהליך עבודה של "האדם שבתהליך". ‫CodeMender פועל על בסיס הקוד המקומי שלכם, ולכן דרישה לאישור ידני (לדוגמה, Write? [Y/n]) מונעת מהסוכן לבצע שינויים ספקולטיביים, שגויים או הרסניים בקובצי המקור. צריך להחליף את זה ל-false רק כשמריצים בסביבות ארגז חול מבודדות וחד-פעמיות או בצינורות עיבוד נתונים אוטומטיים של CI/CD ללא ממשק משתמש.

• include: [".py", ".java", ".go", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".c", ".cc", ".cpp", ".cxx", ".h", ".hpp", ".cs", ".rs", ".kt", ".kts", ".rb", ".php"]

  • מה זה אומר: ההגדרה הזו קובעת את הרשימה המפורשת של סיומות הקבצים שאתם מאשרים ל-CodeMender להטמיע ולנתח כשהוא סורק את סביבת העבודה שלכם. ‫CodeMender מדלג באופן אוטומטי על כל קובץ במאגר עם סיומת שלא צוינה ברשימה הזו.
  • למה זו ברירת המחדל: הרשימה הזו כוללת כברירת מחדל שפות תכנות עיקריות כדי למקסם את יעילות הסריקה ולמנוע מהנציג לבזבז זמן ואסימונים על קובצי טקסט לא רלוונטיים, פריטי מידע שנוצרו בתהליך פיתוח התוכנה או קבצים בינאריים. עם זאת, מכיוון שאפליקציות מודרניות מטמיעות לעיתים קרובות נקודות חולשה בהגדרות הפריסה או בכלי האוטומציה, אתם יכולים להרחיב באופן ידני את רשימת ברירת המחדל הזו ב-config.yaml כך שתכלול קובצי הגדרות אישיות, פורמטים של סקריפטים וקובצי IaC (לדוגמה, סקריפטים של מעטפת, קובצי XML, קובצי YAML, מאפיינים וקובצי JSON) כדי ש-CodeMender לא יתעלם מהם בלי להודיע.

• exclude_dirs: ["node_modules", "vendor", "dist", "bin", "target", "obj", "build", ".gradle"]

  • מה זה אומר: CodeMender ידלג לגמרי על הספריות האלה במהלך סריקת סביבת העבודה וניתוח הקוד.
  • למה זו ברירת המחדל: תיקיות גדולות של יחסי תלות או גרסאות build גורמות לעיכוב משמעותי ולצריכה מוגברת של טוקנים. ההחרגה שלהם כברירת מחדל מבטיחה ביצועים גבוהים וזמני תגובה מהירים. אפשר להתאים אישית את הרשימה הזו ב-config.yaml כדי לכלול או להחריג ספריות ספציפיות בהתאם למבנה הפרויקט.

• project_paths: []

  • הסבר: רשימה של נתיבי ספריות ש-CodeMender יכול לגשת אליהם (קריאה/כתיבה) במהלך הפעלת הכלי.
  • למה זו ברירת המחדל: כברירת מחדל, הספרייה ריקה, מה שמגביל את הסוכן לספריית יעד הסריקה. אם תהליך ה-build או הבדיקה דורש גישה לקבצים מחוץ לספריית היעד של הסריקה, צריך להוסיף את הנתיבים האלה כאן.
  • ספריית פריטי מידע שנוצרו בתהליך הפיתוח (Artifacts): הנציג יכול גם לכתוב לספריית פריטי מידע שנוצרו בתהליך הפיתוח לכל סשן (~/.codemender/artifacts/<session_id>/, או המקבילה ב-$CM_HOME).
  • קבצים זמניים: כשההגדרה של ארגז החול מופעלת, הספרייה המארחת /tmp תמיד חסומה, גם אם מוסיפים את /tmp אל project_paths. במקום זאת, כלים שפועלים בהתאם לTMPDIR משתמשים בספרייה זמנית בתוך ספריית הארטיפקטים.

• sandbox:

  • מה זה אומר: בלוק הגדרות לסביבת ארגז החול ברמת התהליך.
  • פרמטרים משניים:
    • ‫enabled: true: (ערך בוליאני) מפעיל או משבית את ארגז החול. אם מגדירים את הערך הזה ל-true (ברירת מחדל), הסוכן מפעיל כלים בתוך ארגז החול המקומי. אם מגדירים את ההגדרה ל-false, הסוכן מריץ כלים ישירות במערכת המארחת ללא בידוד.
    • ‫mounts: (אובייקט)
      • ‫target_dir: ".": (מחרוזת) הספרייה שצריך לטעון כסביבת העבודה הפעילה בתוך ארגז החול. ה-CLI פותר נתיבים יחסיים ביחס לשורש של סביבת העבודה.
    • ‫network: (אובייקט)
      • ‫profile: "permissive-closed": (מחרוזת) פרופיל גישה לרשת יוצאת בארגז החול. עדיין אין תמיכה בהוספה מפורטת לרשימת ההיתרים של דומיינים או תבניות URL ספציפיים. פרופילים נתמכים:
        • ‫permissive-closed (ברירת המחדל): בידוד רשת מלא. ארגז החול חוסם את כל החיבורים היוצאים.
        • ‫permissive-open: מאפשרת גישה מלאה לרשת יוצאת.

• security:

  • מה זה אומר: בלוק הגדרות למדיניות אבטחה.
  • פרמטרי משנה:
    • ‫protected_files: []: (רשימת מחרוזות) קבצים או ספריות במערכת המארחת שרוצים לטעון לקריאה בלבד בארגז החול כדי להגן עליהם מפני שינויים (לדוגמה, ["~/.ssh/*"]). יש תמיכה בהרחבת נתיבים (~) ובתווים כלליים (*).

• model: "gemini-3.8-flash"

  • מה זה אומר: מנוע ברירת המחדל של ה-AI שמפעיל את לולאות החשיבה הרציונלית של הקצה העורפי.
  • למה זה מוגדר כברירת מחדל: gemini-3.8-flash מציע את האיזון האופטימלי בין מהירות, עלות וחשיבה אנליטית שנדרשים כדי להציע תיקונים. (המשתמשים יכולים לשנות את ההגדרה הזו ל-gemini-4-argon (Gemini 4 Argon) כדי לקבל חשיבה מעמיקה ומורכבת יותר לפי הצורך).

• vcs: { type: "git" }

  • המשמעות: מגדיר את סוג מערכת לניהול גרסאות שבה נעשה שימוש בפרויקט באמצעות המפתח vcs. אם לא מגדירים את המדיניות, הכלי מנסה לזהות באופן אוטומטי מאגרי Git או Mercurial. אם מגדירים את vcs לערך none, ה-CLI מציג אזהרה אבל ממשיך לפעול בלי פונקציונליות של VCS. ‫CodeMender מסתמך על ההגדרה הזו כדי לנהל תיקוני אבטחה ספקולטיביים, לעקוב אחרי שינויים בבסיס הקוד ולשלב את המאגר המקומי שלכם.
  • למה זו הגדרת ברירת המחדל: CodeMender תומך ב-Git, ב-Mercurial או בהגדרות מותאמות אישית של מערכת בקרת גרסאות (VCS). ‫Git היא ברירת המחדל כי היא הסטנדרט המקובל בתחום למעקב אחרי ניהול גרסאות, והיא מבטיחה שילוב חלק של diff ובטיחות החזרה למצב קודם.

• build: { command: "make build && make test" }

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

הרצה בארגז חול (sandbox)

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

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

• ‫Linux: משתמש במרחבי שמות של ליבה (CLONE_NEWNS,‏ CLONE_NEWUSER וכו') ובמסנני seccomp כדי לבודד נקודות טעינה ולהגביל קריאות מערכת.
• ‫macOS: משתמש במנגנון sandbox-exec (Seatbelt) המובנה.
• ‫Windows (ניסיוני): משתמש בבידוד AppContainer וברשימות של בקרת גישה (ACL). ארגז החול ב-Windows הוא ניסיוני ויכול להיות שיידרשו הרשאות אדמין או שהוא לא יהיה תואם להגדרות מערכת מסוימות.

התנהגות ארגז החול

כשהארגז החול פעיל:

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

גישה לרשת במהלך הבנייה והאימות

בגלל שארגז החול מפעיל בידוד רשת כברירת מחדל (sandbox.network.profile מוגדר כברירת מחדל ל-permissive-closed), הנציג לא יכול לגשת לאינטרנט בזמן הפעלת הכלי.

זה יוצר מגבלות לפרויקטים שדורשים אחזור של יחסי תלות חיצוניים במהלך שלבי ה-build או האימות (לדוגמה, הפעלת npm install,‏ pip install או go get כחלק מ-build.command). אם תהליך ה-build ינסה לגשת לשירותי אינטרנט חיצוניים, הוא ייכשל.

טיפול ביחסי תלות ברשת

אם הפרויקט שלכם דורש גישה לרשת לצורך גרסאות build או בדיקות, יש לכם את האפשרויות הבאות:

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

• הפעלת גישה לרשת בארגז החול: משנים את פרופיל הרשת ב-config.yaml כדי לאפשר חיבורים יוצאים:

  sandbox:
    network:
      profile: "permissive-open"
  

• עקיפת ארגז החול: מריצים את הפקודה עם הדגל --unrestricted כדי להשבית לחלוטין את ארגז החול ואת הגבולות של מערכת הקבצים עבור ההרצה הזו.

הגדרות ארגז החול

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

• תצורה קבועה (config.yaml): אפשר להתאים אישית את ההתנהגות של ארגז החול, את נקודות החיבור של מערכת הקבצים, את הגישה לרשת ואת מדיניות האבטחה על ידי הוספת בלוקים של sandbox,‏ execution ו-security לקובץ config.yaml. פרטים נוספים זמינים במאמר פרמטרים של הגדרות.
• שליטה בארגז החול באמצעות ה-CLI‏ (--sandbox): אפשר להפעיל או להשבית את ארגז החול באופן מפורש להרצה אחת על ידי העברת --sandbox=true או --sandbox=false אל cm find,‏ cm verify או cm fix.
• עקיפת הבידוד באמצעות ה-CLI‏ (--unrestricted): אתם יכולים לעקוף באופן זמני את כל אמצעי ההגנה של ארגז החול להרצה אחת, על ידי העברת הדגל --unrestricted. הפעולה הזו משביתה את הגבולות של נתיב מערכת הקבצים (כך שהסוכן יכול לגשת לכל נתיב במארח) ומשביתה לחלוטין את הבידוד של הקונטיינר ברמת מערכת ההפעלה (כולל בידוד הרשת).

בחירת רמת בידוד

בהתאם לדרישות האבטחה ולסביבת הפיתוח שלכם, אתם יכולים לבחור את רמת הבידוד המתאימה להפעלת ה-CLI של CodeMender.

Telemetry

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

כברירת מחדל, הטלמטריה מופעלת. כדי להשבית את הטלמטריה, מגדירים את משתנה הסביבה CM_TELEMETRY_OPT_OUT לערך 1 או true.

עדכון ה-CLI

ל-CodeMender יש מנגנון עדכון מובנה שמוודא שאתם משתמשים בגרסה העדכנית של ה-CLI.

בדיקות עדכונים אוטומטיות

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

• הגבלת קצב העברת נתונים: כדי לצמצם את התקורה, הבדיקה האוטומטית מופעלת לכל היותר פעם ב-24 שעות.
• נדרש טרמינל אינטראקטיבי (TTY): ה-CLI בודק אם יש עדכונים ומציג בקשות רק כשמריצים אותו בטרמינל אינטראקטיבי. בסביבות לא אינטראקטיביות (כמו סקריפטים או צינורות עיבוד נתונים של CI/CD), המערכת מדלגת על הבדיקה ורושמת אזהרה ב-stderr פעם ביום לכל היותר.
• הנחיה: אם יש גרסה חדשה, תופיע הנחיה ב-stderr: none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): אם בוחרים "כן" (y או yes), CodeMender מוריד את העדכון, מחליף את הקובץ הבינארי ויוצא. כדי להריץ את הפקודה בגרסה החדשה, צריך להפעיל אותה שוב. אם תבחרו באפשרות 'לא', העדכון יידחה והפקודה המקורית תופעל.
• סבילות למצב אופליין: אם אתם במצב אופליין או שאי אפשר להגיע למאגר הגרסאות, הבדיקה נכשלת בלי להציג הודעה ו-CodeMender ממשיך להריץ את הפקודה.
• מעקף: אפשר לעקוף את בדיקת העדכונים האוטומטית על ידי העברת הדגל --yes או -y לכל פקודה.

עדכונים ידניים (cm update)

כדי לאלץ את CodeMender לבדוק אם יש עדכונים ולהחיל אותם באופן מיידי, אפשר להריץ את הפקודה update:

cm update

הפקודה cm update:

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

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

sudo cm update