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

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

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

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

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

הגדרת הסביבה

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

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

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

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

מוודאים שממשקי ה-API הבאים של Google Cloud מופעלים בפרויקט:

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

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

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

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

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

Linux x86_64

כדי להוריד ולהתקין את CodeMender CLI ל-Linux‏ (x86_64):

  1. מורידים את החבילה באחת מהשיטות הבאות:
    • ה-CLI של gcloud: מריצים את הפקודה הבאה:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-linux-amd64.zip \
        --destination=./
    • ‫curl: מריצים את הפקודה הבאה:
      curl -L -o cm-linux-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-amd64.zip:download?alt=media"
  2. מתקינים את ה-CLI:
    unzip cm-linux-amd64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

‫Linux ARM64

כדי להוריד ולהתקין את CodeMender CLI ל-Linux (ARM64):

  1. מורידים את החבילה באחת מהשיטות הבאות:
    • ה-CLI של gcloud: מריצים את הפקודה הבאה:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-linux-arm64.zip \
        --destination=./
    • ‫curl: מריצים את הפקודה הבאה:
      curl -L -o cm-linux-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-arm64.zip:download?alt=media"
  2. מתקינים את ה-CLI:
    unzip cm-linux-arm64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

macOS Intel

כדי להוריד ולהתקין את CodeMender CLI ל-macOS (Intel):

  1. מורידים את החבילה באחת מהשיטות הבאות:
    • ה-CLI של gcloud: מריצים את הפקודה הבאה:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-darwin-amd64.zip \
        --destination=./
    • ‫curl: מריצים את הפקודה הבאה:
      curl -L -o cm-darwin-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-amd64.zip:download?alt=media"
  2. מתקינים את ה-CLI:
    unzip cm-darwin-amd64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

macOS Apple silicon

כדי להוריד ולהתקין את CodeMender CLI ל-macOS (Apple silicon):

  1. מורידים את החבילה באחת מהשיטות הבאות:
    • ה-CLI של gcloud: מריצים את הפקודה הבאה:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-darwin-arm64.zip \
        --destination=./
    • ‫curl: מריצים את הפקודה הבאה:
      curl -L -o cm-darwin-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-arm64.zip:download?alt=media"
  2. מתקינים את ה-CLI:
    unzip cm-darwin-arm64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

Windows x86_64

כדי להוריד ולהתקין את CodeMender CLI ל-Windows (x86_64):

  1. מורידים את החבילה באחת מהשיטות הבאות:
    • ‫gcloud CLI: מריצים את הפקודה הבאה ב-PowerShell:
      gcloud artifacts generic download `
        --project=cmoc-prod `
        --location=us `
        --repository=codemender-cli-production `
        --package=cm `
        --version=stable `
        --name=cm-windows-amd64.zip `
        --destination=./
    • ‫PowerShell: מריצים את הפקודה הבאה:
      Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-amd64.zip:download?alt=media" -OutFile cm-windows-amd64.zip
  2. מתקינים את ה-CLI:
    Expand-Archive -Path cm-windows-amd64.zip -DestinationPath ./
    # Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

Windows ARM64

כדי להוריד ולהתקין את CodeMender CLI ל-Windows (ARM64):

  1. מורידים את החבילה באחת מהשיטות הבאות:
    • ‫gcloud CLI: מריצים את הפקודה הבאה ב-PowerShell:
      gcloud artifacts generic download `
        --project=cmoc-prod `
        --location=us `
        --repository=codemender-cli-production `
        --package=cm `
        --version=stable `
        --name=cm-windows-arm64.zip `
        --destination=./
    • ‫PowerShell: מריצים את הפקודה הבאה:
      Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-arm64.zip:download?alt=media" -OutFile cm-windows-arm64.zip
  2. מתקינים את ה-CLI:
    Expand-Archive -Path cm-windows-arm64.zip -DestinationPath ./
    # Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

הגדרת פרטי הכניסה והפרויקט ב- Google Cloud

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

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

    gcloud auth application-default login
    
  2. מגדירים את משתנה הסביבה GOOGLE_CLOUD_PROJECT למזהה הפרויקט ב- Google Cloud :

    export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
    

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

    gcloud config set project PROJECT_ID
    

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

מאתחלים את סביבת העבודה

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

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

cm init

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

cm init --verify

בדיקת הקישוריות וההרשאות של השירות

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

cm health

הפקודה cm health מריצה ארבע בדיקות ברצף, ועוצרת בשכבה הראשונה שנכשלת. אפשר להריץ את cm health מכל ספרייה, אפילו לפני שמריצים את cm init. היא לא כותבת בדיסק ולא צורכת מכסת מודלים.

כדי לבצע בדיקות מקדימות אוטומטיות של CI/CD או מעקב סינתטי מתוזמן, משתמשים ב---strict כדי להיכשל כשמדלגים על בדיקות IAM ברמת הפרויקט, וב---json כדי להפיק דוח JSON בפורמט קריא למכונה:

cm health --strict --json

בטבלה הבאה מתוארים קודי היציאה של cm health:

קוד יציאה שכבה תיאור
0 — כל בדיקות התקינות עברו בהצלחה.
10 credentials ה-CLI לא הצליח לקבל טוקן חוקי של OAuth או של Application Default Credentials, או שהשרת דחה את הטוקן (401 Unauthorized).
20 config הקובץ המקומי config.yaml, הדגל --team-id או משתנה הסביבה CM_TEAM_ID לא תקינים.
30 reachability ה-CLI לא הצליח להגיע לנקודת קצה ל-API של Agent Platform (לדוגמה, בגלל מגבלות של DNS,‏ TLS, שרת proxy או VPC Service Controls).
40 authorization השרת הגיב, אבל למבצע הקריאה או לפרויקט אין הרשאה להריץ סריקות של CodeMender (לדוגמה, חסרות הרשאות roles/aiplatform.user).
50 — בדיקת התקינות חרגה ממשך הזמן של --timeout (ברירת המחדל היא 30s).

הדגלים הבאים נתמכים על ידי cm health:

דגל ברירת מחדל תיאור
--json false הפלט הוא אובייקט JSON יחיד לפלט סטנדרטי (stdout), כולל status,‏ exit_code,‏ backend,‏ endpoint,‏ location,‏ project_id,‏ agent_id,‏ duration_ms,‏ layers, וגם (אם קיימים) warnings ו-error.
--strict false התייחסות לאזהרות של בדיקת תקינות (כמו בדיקות של הרשאות IAM ברמת הפרויקט שלא אומתו או שדילגו עליהן) ככשלים של קוד יציאה 40.
--timeout 30s מגדיר את הזמן הקצוב הכולל לבדיקת התקינות.

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

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

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

שימוש

  • מיקום: כברירת מחדל, ה-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

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

  • tools.confirm_commands: true

    • מה זה אומר: כברירת מחדל, CodeMender מבקש אישור [Y/n] בטרמינל לפני הפעלת פקודות מעטפת (run_command). כש-cm find פועל עם ארגז חול ברמת מערכת ההפעלה (sandbox.enabled: true) ובידוד רשת שמוגדר כברירת מחדל (permissive-closed), סביבת העבודה נטענת לקריאה בלבד והמערכת מדלגת באופן אוטומטי על בקשות לאישור פקודות.
    • למה זו ברירת המחדל: יכול להיות ש-CodeMender יריץ פקודות build, חבילות מקרים לבדיקה או סקריפטים של ניצול לרעה במהלך האימות והתיקון. כדי למנוע הפעלה לא מכוונת של פקודות בסביבה המקומית, כדאי לדרוש אישור כשסביבת העבודה ניתנת לכתיבה או לא נמצאת בארגז חול.
    • מעקף: מעבירים את -y (או --yes) להרצה אחת, או מגדירים את tools.confirm_commands: false ב-config.yaml לצינורות עיבוד נתונים לא אינטראקטיביים של CI/CD.
  • tools.confirm_writes: true

    • מה זה אומר: מוצגת בקשה לאישור [Y/n] בטרמינל לפני שסוכן CodeMender כותב או משנה קבצים בדיסק (write_to_file ו-search_and_replace).
    • למה זו ברירת המחדל: הדרישה לאישור ידני מונעת מהסוכן לבצע שינויים ספקולטיביים או לא מכוונים בקובצי המקור במהלך cm fix או cm verify. צריך להגדיר את זה ל-false (או להעביר את -y / --yes) רק כשמריצים בסביבות מבודדות וחד-פעמיות או בצינורות עיבוד נתונים אוטומטיים של CI/CD.
  • execution.interactive_mode: true

    • מה זה אומר: מאפשר הנחיות אינטראקטיביות בטרמינל בזמן הרצת הכלי. צריך להגדיר את זה ל-false (או להעביר את -y / --yes) בסביבות CI/CD ללא ממשק משתמש (headless) שבהן לא מחובר מסוף.
  • execution.duration: ""

    • המשמעות: מגדיר משך זמן מקסימלי כברירת מחדל לכל הפעלה של פקודה (לדוגמה, "15m" או "1h") ב-cm find, ב-cm verify, ב-cm fix וב-cm session resume. כדי לא להגדיר מגבלת זמן, צריך להשאיר את השדה הזה ריק או להגדיר אותו לערך "0". אפשר לשנות את ההגדרה הזו באמצעות משתנה הסביבה CM_DURATION או הדגל --duration (או --timeout). כשהפקודה נעצרת במגבלת משך הזמן, היא שומרת את כל התוצאות שהושלמו ויוצאת עם הסטטוס 1 אם סריקת cm find --diff תואמת ל---fail-on, או עם הסטטוס 50 במקרים אחרים.
  • execution.stall_detection: false

    • מה זה אומר: כשהערך מוגדר ל-true (או כש-CM_STALL_DETECTION=on), המערכת עוצרת סשן של נציג שלא מתקדם בין תורות עוקבים של כלים. פקודות של סשן יחיד (סריקה אחת של cm find --quick,‏ cm verify,‏ cm fix ו-cm session resume) מסתיימות בסטטוס 50. בסריקות של מספר סשנים של --deep,‏ --diff ו---parallel, סשן שנתקע מתועד כנכשל והסריקה נמשכת.
  • scan.extensions.include: [".py", ".java", ".go", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".c", ".cc", ".cpp", ".cxx", ".h", ".hh", ".hpp", ".hxx", ".inl", ".ipp", ".cs", ".rs", ".kt", ".kts", ".rb", ".php", ".sol", ".tf", ".hcl"]

    • מה זה אומר: ההגדרה הזו קובעת את הרשימה המפורשת של סיומות הקבצים שאתם מאשרים ל-CodeMender להטמיע ולנתח כשהוא סורק את סביבת העבודה שלכם. ‫CodeMender מדלג באופן אוטומטי על כל קובץ במאגר עם סיומת שלא צוינה ברשימה הזו.
    • למה זו ברירת המחדל: הרשימה הזו כוללת כברירת מחדל שפות תכנות עיקריות כדי למקסם את יעילות הסריקה ולמנוע מהנציג לבזבז זמן ואסימונים על קובצי טקסט לא רלוונטיים, פריטי מידע שנוצרו בתהליך פיתוח התוכנה או קבצים בינאריים. עם זאת, מכיוון שאפליקציות מודרניות מטמיעות לעיתים קרובות נקודות חולשה בהגדרות פריסה או בכלים אוטומטיים, אתם יכולים להרחיב באופן ידני את רשימת ברירת המחדל הזו ב-config.yaml כך שתכלול קובצי הגדרות אישיות, פורמטים של סקריפטים וקובצי IaC (לדוגמה, סקריפטים של מעטפת, קובצי XML, ‏YAML, מאפיינים ו-JSON) כדי ש-CodeMender לא יתעלם מהם בלי להודיע.
  • scan.exclude_dirs: ["node_modules", "vendor", "dist", "/target", "/obj", "/build", ".gradle"]

    • מה זה אומר: CodeMender מדלג על התיקיות האלה במהלך סריקת סביבת העבודה וניתוח הקוד. רשומות שמתחילות ב-/ (כמו /target,‏ /obj ו-/build) תואמות רק לשורש הסריקה, כך שחבילות מקור בתצוגת עץ עם השמות האלה לא ידולגו.
    • למה זו ברירת המחדל: תיקיות גדולות של יחסי תלות או גרסאות build גורמות לעיכוב משמעותי ולצריכה מוגברת של טוקנים. כדי לשמור על ביצועים גבוהים וזמני תגובה מהירים, כברירת מחדל, המערכת לא כוללת את הנתונים האלה. אפשר להתאים אישית את הרשימה הזו ב-config.yaml כדי לכלול או להחריג תיקיות ספציפיות בהתאם למבנה הפרויקט.
  • project_paths: []

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

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

    • המשמעות: בלוק הגדרות למדיניות אבטחה.
    • פרמטרים משניים:
      • ‫protected_files: []: (רשימה של מחרוזות) קבצים או ספריות נוספים במערכת המארחת שרוצים לטעון כקריאה בלבד בתוך ארגז החול כדי להגן עליהם מפני שינויים. יש תמיכה בהרחבת נתיב (~) ובתווים כלליים לחיפוש (*). גם אם protected_files ריק, ארגז החול תמיד מגן על .git/hooks, .git/config, .hg/hgrc ו-.codemender כתיקיות לקריאה בלבד, ומחריג ספריות נפוצות של פרטי כניסה (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, ~/.config/gh, ~/.kube, ~/.docker).
  • ‫Model: המדיניות config.yaml לא מגדירה את הדגם. כדי לבחור מודל, מעבירים את --model אל cm find, cm verify או cm fix. במאמר ציון המודל מפורטים המודלים הנתמכים ומודל ברירת המחדל.

  • vcs: { type: "git" }

    • מה זה אומר: מגדיר את סוג מערכת לניהול גרסאות שבה הפרויקט משתמש באמצעות המפתח vcs. אם לא מגדירים את המדיניות הזו, הכלי מנסה לזהות באופן אוטומטי מאגרי Git או Mercurial. אם מגדירים את vcs לערך none, ה-CLI מציג אזהרה אבל ממשיך לפעול בלי פונקציונליות של VCS. ‫CodeMender מסתמך על ההגדרה הזו כדי לנהל תיקוני אבטחה ספקולטיביים, לעקוב אחרי שינויים בבסיס הקוד ולשלב עם המאגר המקומי.
    • למה זו ברירת המחדל: CodeMender תומך בהגדרות של Git,‏ Mercurial או VCS בהתאמה אישית. ‫Git היא ברירת המחדל כי היא הסטנדרט המקובל בתחום למעקב אחרי ניהול גרסאות, והיא מבטיחה שילוב חלק של diff ובטיחות החזרה למצב קודם.
  • build: { command: "make build && make test" }

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

בקשות אישור

‫CodeMender מבקש אישור לפני שהוא מריץ פקודת מעטפת (tools.confirm_commands) ולפני שהוא כותב קובץ (tools.confirm_writes). שתי ההגדרות לא תלויות זו בזו, ושתיהן מוגדרות כברירת מחדל ל-true. ההגדרות הבאות משביתות את ההנחיות האלה, לפי סדר העדיפות:

  1. ‫-y או --yes: אישור של כל הפקודות וההנחיות לכתיבת קבצים להרצה אחת, בלי קשר למה שכתוב ב-config.yaml.
  2. ‫execution.interactive_mode: false ב-config.yaml: משבית את ההנחיות להרצת פקודות ולכתיבת קבצים בכל הרצה.
  3. ‫tools.confirm_commands: false או tools.confirm_writes: false ב-config.yaml: משבית את ההנחיות של שורת הפקודה או של כתיבת הקובץ בכל הפעלה, באופן בלתי תלוי.

אם אף אחת מההגדרות האלה לא רלוונטית ואף אחד לא יכול לענות להנחיה, למשל במשימת CI/CD בלי מסוף, CodeMender לא מריץ את הפקודה ולא כותב את הקובץ.

בנפרד מההנחיות האלה, ה-CLI מזהיר אתכם שהסוכן יכול לשנות קבצים ולהריץ פקודות במערכת, ומבקש מכם לאשר את האזהרה. -y לא מדלג על האזהרה הזו. כדי לדלג עליו, צריך להעביר את --bypass-warning. בסביבה לא אינטראקטיבית בלי --bypass-warning, הפקודה cm נכשלת עם השגיאה warning not acknowledged. ‫cm find מדלג על האזהרה כשארגז החול מופעל עם פרופיל הרשת permissive-closed שמוגדר כברירת מחדל.

מדיניות הפקודות (command_policy.yaml)

בנוסף לארגז החול ברמת מערכת ההפעלה, אתם יכולים להגדיר רשימת פקודות חסומות ב-~/.codemender/command_policy.yaml (גלובלי) וב-<project>/.codemender/command_policy.yaml (ספציפי לפרויקט). אם שני הקבצים קיימים, CodeMender ממזג את הכללים שלהם.

בהפעלה הראשונה, CodeMender יוצר תבנית מסומנת כהערה ב-~/.codemender/command_policy.yaml. אפשר לבטל את ההערה או להוסיף כללים בשני מפתחות:

  • ‫block: רשימה של שמות בינאריים לחסימה בכל צינורות העיבוד של המעטפת, מעטפות המשנה והחלפות הפקודות (לדוגמה, curl,‏ wget,‏ ssh,‏ sudo,‏ rm).
  • ‫block_patterns: רשימה של ביטויים רגולריים שמותאמים לכל קטע פקודה (לדוגמה, '\bgit\s+(push|commit|rebase|reset\s+--hard|clean)\b').

כדי לעקוף את האכיפה של command_policy.yaml בהפעלה של פקודה אחת, מעבירים את הדגל --allow-all-commands.

  • output: { plain: false }
    • מה זה אומר: ההגדרה הזו קובעת אם ה-CLI של CodeMender יחליף אמוג'י, סמלי Unicode וצבעים של מסוף בטקסט ASCII בפלט של ה-CLI ובדוחות בפורמט.
    • למה זו ברירת המחדל: סגנון טרמינל עשיר וסמלי סטטוס מקלים על סריקה של סריקות אינטראקטיביות ודוחות מיוצאים. מגדירים את plain לערך true בשביל יומני CI/CD, קוראי מסך או מסופים מינימליים. במאמר הגדרת פלט של טקסט פשוט מוסבר על כללי קדימות ודגלים לשינוי ברירת המחדל.

הרצה בארגז חול

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

‫Google מספקת את ארגז החול של CodeMender כתכונת בטיחות מומלצת. הפעלת CodeMender מחוץ לסביבת ארגז חול היא באחריות הלקוח בלבד, בהתאם לסעיף 20(j) בתנאים הספציפיים לשירות.

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

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

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

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

  1. בידוד מערכת הקבצים: הנציג יכול לגשת רק לקבצים בספריות המותרות. במהלך cm find, סביבת העבודה והשורשים המותרים נטענים לקריאה בלבד, כך שהפקודות יכולות לכתוב רק בספריית פריטי המידע שנוצרו לכל סשן. בכל הפקודות (כולל cm verify ו-cm fix), .git/hooks, .git/config, .hg/hgrc ו-.codemender מותקנים לקריאה בלבד, כך שפקודות בארגז החול לא יכולות להתקין הוקים של Git או Mercurial או לשנות את ההגדרות של CodeMender.
  2. בידוד רשת: ארגז החול חוסם גישה לרשת יוצאת כברירת מחדל (sandbox.network.profile: "permissive-closed"). זה מונע מהסוכן (או מכלי ה-build שהוא מפעיל) ליצור חיבורים חיצוניים לא צפויים או להעביר נתונים מחוץ לסביבת העבודה.
  3. בידוד של פרטי כניסה וסודות: ארגז החול לא כולל ספריות נפוצות של פרטי כניסה למארח (~/.ssh,‏ ~/.gnupg,‏ ~/.aws,‏ ~/.config/gcloud,‏ ~/.config/gh,‏ ~/.kube,‏ ~/.docker ועוד) ומסיר משתני סביבה שתואמים לתבניות של סודות (*_TOKEN,‏ *_SECRET,‏ *_KEY,‏ *_PASSWORD,‏ *_CREDENTIALS וסיומות דומות) לפני הרצת פקודות.

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

מכיוון שארגז החול מפעיל בידוד רשת כברירת מחדל (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"
    
  • השבתת ארגז החול להרצה: מריצים את הפקודה עם הדגל --sandbox=false כדי להשבית את ארגז החול ברמת מערכת ההפעלה (כולל בידוד הרשת) להרצה הזו.

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

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

  • הגדרה קבועה (config.yaml ו-command_policy.yaml): התאמה אישית של התנהגות ארגז החול, טעינת מערכת הקבצים, גישה לרשת ורשימות חסימה של פקודות ב-config.yaml וב-command_policy.yaml. פרטים נוספים זמינים במאמרים פרמטרים של הגדרות אישיות ומדיניות פקודות.
  • שליטה בארגז החול ברמת מערכת ההפעלה (--sandbox): הפעלה או השבתה של ארגז החול ברמת מערכת ההפעלה באופן מפורש להרצה בודדת, על ידי העברת --sandbox=true או --sandbox=false אל cm find, cm verify, cm fix או cm session resume.
  • עקיפת גבולות הנתיב (--allow-all-paths): השבתת הבדיקה של גבולות הנתיב בסביבת העבודה להרצה אחת, כדי שכלי הסוכן יוכלו לגשת לנתיבים מחוץ לשורש הפרויקט ול-project_paths שהוגדר (בשילוב עם --sandbox=false כדי לגשת לנתיבי מארח שלא נטענו בתוך ארגז החול).
  • מדיניות פקודות עקיפה (--allow-all-commands): השבתת האכיפה של רשימת החסימה של command_policy.yaml להרצה אחת.

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

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

‏Method תיאור יתרונות חסרונות
ארגז חול מובנה (ברמת מערכת ההפעלה) התכונה מופעלת כברירת מחדל. אפשר להשבית אותה בקובץ config.yaml או לעקוף אותה באמצעות דגלים של CLI. שימוש בתכונות מובנות של מערכת ההפעלה (מרחבי שמות/seccomp,‏ sandbox-exec,‏ AppContainer (ניסיוני)) כדי לבודד את ההפעלה. קל משקל, ללא תקורה בהפעלה, גישה ישירה לכלי סביבת העבודה המקומית עם שליטה מפורטת. מומלץ לפיתוח מקומי יומיומי. האבטחה מסתמכת על תכונות של ליבת מערכת ההפעלה; פחות מבודד ממכונה וירטואלית מלאה; התמיכה ב-Windows היא ניסיונית ויכול להיות שתידרש הרשאת אדמין או שהיא לא תתאים לחלק מההגדרות.
קונטיינרים הפעלת הסוכן בקונטיינר (לדוגמה, Docker). בידוד טוב; סביבה סטנדרטית. נדרשת סביבת זמן ריצה של קונטיינר, יכול להיות כבד, לא מאפשר אינטראקציה ישירה עם כלים במכונה המקומית.
מכונות וירטואליות מלאות הפעלת הסוכן ב-VM ייעודי. אבטחה מקסימלית ובידוד מלא. תקורה גבוהה של משאבים, הפעלה איטית, לא מאפשר אינטראקציה ישירה עם כלים במכונה המקומית.

הגדרת פלט של טקסט פשוט

כברירת מחדל, ה-CLI של CodeMender משתמש באמוג'י, בסמלי Unicode ובצבעי טרמינל בפלט אינטראקטיבי ובדוחות בפורמט. כדי להשתמש בפלט של ASCII בלבד ביומני CI/CD, בקוראי מסך או במסופים מינימליים, צריך להפעיל את מצב הטקסט הפשוט. ‫CodeMender CLI בודק את ההגדרות האלה לפי סדר הקדימויות הבא, מהגבוהה לנמוכה:

  1. מעבירים את הדגל --plain לכל פקודת cm להרצה אחת, או מעבירים את --plain=false כדי לשנות את הגדרות הסביבה והתצורה:

    cm --plain find .
    
  2. מגדירים את משתנה הסביבה CM_PLAIN לערך true או 1 כדי להפעיל פלט של טקסט פשוט בכל הפקודות, או לערך false או 0 כדי להשבית אותו:

    export CM_PLAIN=true
    
  3. מגדירים את output.plain ל-true בקובץ ~/.codemender/config.yaml:

    output:
      plain: true
    
  4. מריצים סשן אינטראקטיבי בטרמינל שבו TERM=dumb, שמאפשר פלט של טקסט פשוט באופן אוטומטי.

במצב טקסט פשוט, אמוג'י הסטטוס מוחלפים בתגי ASCII כמו [OK],‏ [INFO],‏ [WARN],‏ [ERROR],‏ [PASS] ו-[FAIL]. בנוסף, CodeMender משבית ספינרים מונפשים ושכתובים של שורות במקום, ומציג גבולות של טבלאות ASCII. ב-cm report, מצב טקסט פשוט מסיר אמוג'י של ממשק המשתמש מהפורמטים table, md ו-html בלי לשנות את הפלט או את ההבדלים בקוד של json או sarif.

קבצים שהופנו וסטרימינג של CI/CD לא אינטראקטיביים שומרים על הערך false של plain כברירת מחדל, כדי שדוחות Markdown ו-HTML שיוצאו ישמרו על סמלי הסטטוס. כדי להסיר אמוג'י וסמלי Unicode ביומני CI/CD, מגדירים את CM_PLAIN=true, מעבירים את --plain או מגדירים את output.plain: true. תווי בריחה (escape) של צבעים במסוף מושמטים באופן אוטומטי בסטרימינג לא אינטראקטיבי וכשמגדירים את משתנה הסביבה NO_COLOR.

Telemetry

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

אירועי טלמטריה יכולים להכיל את הפרטים הבאים:

  • מזהה החשבון ב-Google או מזהה חשבון השירות, מזהה הפרויקט ב- Google Cloud ומזהה הצוות, אם הגדרתם אחד כזה.
  • מזהה אקראי לכל פקודה, שם הפקודה, מזהה הסשן בשרת, המודל שנבחר וגרסת ה-CLI.
  • משפחת מערכת ההפעלה, הפלטפורמה והגרסה.
  • אם ארגז החול מופעל, ואם -y (--yes) מוגדר לדלג על הודעות אישור.
  • ביציאה: משך הזמן, קוד היציאה והתוצאה, מספר האסימונים, מספר השורות, הקבצים והבייטים שנסרקו והשפות שזוהו, ומספר הממצאים לפי חומרה או תוצאה של אימות או תיקון.
  • במקרה של שגיאה: קטגוריית השגיאה והסיבה, ודוח קריסות של הקוד של ה-CLI עצמו.

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

כברירת מחדל, הטלמטריה מופעלת. כדי להשבית את הטלמטריה, מגדירים את משתנה הסביבה 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