ניהול סשנים וייצוא דוחות

‫CodeMender עוקב אחרי כל סריקה, אימות וניסיון תיקון כסשן עם שמירת מצב (stateful) שמגובה במסד נתונים מקומי של SQLite (state.db). אתם יכולים לבדוק סשנים פעילים, להמשיך משימות שהושהו ולייצא דוחות מפורטים של הממצאים.

ניהול הפעלות

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

רשימה של סשנים פעילים וקודמים

מריצים את הפקודה הבאה כדי להציג את כל הסשנים, הסטטוסים שלהם (RUNNING,‏ WAITING_FOR_TOOL,‏ COMPLETED,‏ FAILED,‏ CANCELLED) ונתיבי היעד:

cm session list

המשך סשן שהופסק

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

cm session resume SESSION_ID

אפשר להעביר את --yes (-y),‏ --sandbox,‏ --allow-all-paths,‏ --allow-all-commands ו---bypass-warning אל cm session resume כדי לשלוט בהודעות האישור, בארגז החול ובגבולות המדיניות של ההרצה שהופעלה מחדש.

ביטול סשן פעיל

כדי לסיים סשן פעיל ולהפסיק את פעולת החישוב של הסוכן בקצה העורפי:

cm session cancel SESSION_ID

צפייה בדוחות וייצוא תיקונים

הצגת ממצאי הסשן, סטטוסי האימות ופרטי התיקון באמצעות cm report.

פורמטים של פלט

טבלת מסוף (ברירת מחדל)

רשימה מסוכמת של הממצאים.

cm report

דוח HTML

יצירת דוח HTML בפורמט. משתמשים ב---open (או ב--o) כדי להפעיל אותו באופן אוטומטי בדפדפן ברירת המחדל.

cm report --format html --open

Markdown

יצירת דוח Markdown בסגנון GitHub.

cm report --format md

JSON

ייצוא כל פרטי הממצאים של הסשן כקובץ JSON גולמי.

cm report --format json

SARIF

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

cm report --format sarif

סינון ומיון של דגלים

  • הצגת תיקוני קוד מוצעים (--patches): הכללת השוואות מלאות ומאוחדות של תיקונים שנוצרו בדוח. bash cm report --patches
  • סינון לפי חומרה (--severity): הצגת ממצאים שתואמים לרמה מסוימת (CRITICAL,‏ HIGH,‏ MEDIUM,‏ LOW). bash cm report --severity HIGH
  • סינון לפי סטטוס (--status): הצגת ממצאים שתואמים למצב (OPEN,‏ FIXED,‏ DISMISSED,‏ REOPENED). bash cm report --status OPEN
  • סינון לפי סשן (--session): הצגת ממצאים לפי תחילית ספציפית של מזהה סשן. 
    cm report --session SESSION_ID_PREFIX
  • הצגת פריטי מידע שנוצרו על ידי הסוכן (--artifacts): כולל נתיבים לפריטי מידע שנוצרו על ידי הסוכן (כמו יומנים, סקריפטים של ניצול פרצות). bash cm report --artifacts
  • מיון הממצאים (--sort): מיון התוצאות לפי severity (ברירת המחדל) או time. bash cm report --sort time
  • סינון לפי מזהה הממצא: מעבירים מזהה ממצא ספציפי (או קידומת) כארגומנט מיקום כדי להציג פרטים של ממצא יחיד. 
    cm report FINDING_ID_PREFIX

מצבי הממצאים של נקודות החולשה

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

  • OPEN
    • המשמעות: נקודת החולשה זוהתה בהצלחה במהלך סריקה (או יובאה מכלי של צד שלישי), אבל עדיין לא אומתה, תוקנה או סומנה כלא פעילה.
    • איך מטפלים בזה: זהו המצב הראשוני של כל פגם אבטחה חדש שמתגלה. חולשות אבטחה בסטטוס OPEN נמצאות בתור לאימות (cm verify) או לתיקון (cm fix).
  • FIXED
    • מה זה אומר: CodeMender יצר תיקון לנקודת החולשה, החיל את ההבדלים על בסיס הקוד המקומי, וקימפל והריץ בהצלחה בדיקות אימות כדי להוכיח שהניצול לרעה כבר לא מצליח.
    • איך הבעיה מטופלת: אחרי שמאשרים שהתיקון פותר את הבעיה בלי לשבש את הלוגיקה של הקוד הקיים, CodeMender מעביר את הממצא לסטטוס FIXED. הוא יישאר במצב הזה, אלא אם סריקה עתידית תזהה רגרסיה.
  • DISMISSED
    • מה זה אומר: נקודת החולשה מוגדרת כלא פעילה, כי היא זוהתה כחיובית מוטעית או שהיא כבר תוקנה, או שרמת הסבירות של הממצא לא מספיקה כדי לאשר שאפשר לנצל אותה (כולל מול מודל האיומים של הפרויקט, אם סופק כזה במהלך ההצטרפות).
    • איך זה עובד: סימון פריט כ-DISMISSED משתיק התראות עתידיות ומחריג את הממצא מהפלט הפעיל של ה-CLI עם cm report --status OPEN. אם מריצים מחדש את cm verify על ממצא שנדחה, הפריטים שנדחו נבדקים מחדש או משוחזרים.
  • REOPENED
    • המשמעות: נקודת חולשה שסומנה בעבר כ-FIXED או כ-DISMISSED זוהתה מחדש בסריקה הבאה של בסיס הקוד.
    • איך מטפלים בזה: המצב הזה מצביע על רגרסיה (כמו מיזוג git שגוי שמבטל את התיקון) או על אסטרטגיית הפחתה שנכשלה. הוא מסמן את הבעיה להערכה מחדש מיידית, ומחייב את המפתחים לבדוק את תהליך התיקון.

רמות החומרה של נקודות חולשה

‫CodeMender מסווג את הממצאים לפי רמות החומרה הבאות:

  • CRITICAL
    • המשמעות: נקודת החולשה מהווה סיכון מיידי וחמור לאפליקציה או לתשתית הבסיסית, ועלולה להוביל לפגיעה מלאה במערכת.
    • למה היא מסווגת כקריטית: היא עומדת בסף ההשפעה של השלכות חמורות (כמו הרצת קוד מרחוק או כתיבה ברמת הבסיס), אפשר להגיע אליה ישירות מגבולות לא מהימנים בלי דרישות מוקדמות, והיא מגובה בניתוח זרימת נתונים ברמת סמך גבוהה או בהוכחת היתכנות (PoC) מאומתת שבוצעה בתוך ארגז החול של CodeMender.
  • HIGH
    • המשמעות: פרצת האבטחה מייצגת פגם חמור באבטחה שעלול להוביל לשליטה לא מורשית במערכת, להסלמת הרשאות או לחשיפה משמעותית של נתונים, אבל נדרשים תנאים ספציפיים כדי לבצע את הפעולה.
    • למה היא מסווגת כ"גבוהה": למרות שההשפעה של ניצול הפרצה היא גבוהה (לדוגמה, קריאות שרירותיות של מסד נתונים או חטיפת הרשאות ניהול), יכולת הניצול מוגבלת מעט. יכול להיות שהתוקף יצטרך אימות משתמש רגיל, שהניצול יהיה תלוי בהגדרת מערכת ספציפית או שיידרש רצף פעולות מדויק מאוד.
  • MEDIUM
    • המשמעות: נקודת החולשה מהווה סיכון בינוני, ובדרך כלל חושפת נתונים מוגבלים או מאפשרת שיבושים מקומיים, אבל הסיכון למערכת המארחת נמוך.
    • למה הוא מסווג כבינוני: הניצול לרעה מוגבל מאוד בגלל נגישות או מורכבות. בדרך כלל נדרשת אינטראקציה פעילה של המשתמש (כמו לחיצה על קישור זדוני), הרשאות עמוקות או תנאים מורכבים כדי לעקוף את שכבות ההגנה, והאזור המושפע בסופו של דבר מוגבל.
  • LOW
    • המשמעות: הממצא מייצג סיכון אבטחה קל או חוסר כללי בהיגיינה של הגנה לעומק, שלא מהווה איום מיידי בפני עצמו.
    • למה היא מסווגת כנמוכה: יש לה יכולת ניצול נמוכה מאוד או השפעה מינימלית. בדרך כלל, תוקפים משתמשים בממצא הזה כדי לבצע שלב איסוף המידע או לזהות את טביעת האצבע של ההגדרות, ולא כדי לפרוץ ישירות. אי אפשר להשתמש בו כדי להריץ קוד שרירותי או לחלץ נתונים רגישים של אפליקציות.

מעקב אחרי השימוש בטוקנים

‫CodeMender כותב יומני סשנים לכל הפעלה באופן מקומי בנתיב ~/.codemender/logs/sessions/. אפשר להשתמש ב-cm stats כדי לבדוק את השימוש בטוקנים אופליין, את שיעורי המציאה במטמון (cache hit), את מספר הסקרים ואת משך הביצוע של פקודות או של סשן ספציפי, בלי לבצע קריאות לקצה העורפי.

  • ‫סיכום הפעילות האחרונה (--since): הצגת השימוש בטוקנים לפי סוג הפקודה בחלון זמן אחרון (ברירת המחדל היא 168h, או 7 ימים). bash cm stats cm stats --since 24h
  • בדיקת סשן ספציפי (--session): הצגת השימוש בטוקנים לכל פנייה לפי מזהה סשן או תחילית ייחודית של מזהה סשן, כולל הפעלות של cm find --deep ו-cm find --diff עם כמה וורקרים. 
    cm stats --session SESSION_ID_PREFIX
  • ‫ייצוא JSON‏ (--json ו---jsonl): פולט JSON עם כניסה באמצעות --json, או פולט JSON בשורה אחת באמצעות --jsonl להטמעת יומן מובנה. פלט ה-JSON כולל את model (או models כשמופיעים כמה מודלים) ואת team_id (או team_ids כשמצטברים כמה צוותים). 
    cm stats --json
cm stats --jsonl
cm stats --session SESSION_ID_PREFIX --jsonl
  • שימוש במאפיינים לפי צוות (--team-id או CM_TEAM_ID): מגדירים מזהה צוות (1 עד 63 תווים שתואמים ל-[A-Za-z0-9._-]) כשמריצים סריקות או תיקונים עם הדגל --team-id, משתנה הסביבה CM_TEAM_ID או team_id ב-~/.codemender/config.yaml. סשנים שרצו בלי צוות מוגדר נשארים ללא שיוך בפלט ה-JSON של cm stats. כשבחלון השאילתה אין רשומות של סשנים, --team-id,‏ CM_TEAM_ID או config.yaml מספקים את התווית team_id ברמה העליונה. 
    CM_TEAM_ID=TEAM_ID cm find .
cm stats --jsonl

במשימות של Cloud Run ובשלבים של Cloud Build שבהם קובצי היומן המקומיים לא נשמרים, תוכלו לקרוא את המאמר ייצוא נתוני טלמטריה של טוקנים ל-Cloud Logging.

איסוף נתוני אבחון בשביל התמיכה

אם אתם פונים לתמיכה לגבי בעיה ב-CodeMender, הפעילו את cm support-bundle כדי לאסוף את נתוני האבחון שהתמיכה צריכה לארכיון .tar.gz יחיד. הפקודה קוראת קבצים מקומיים ובודקת את פרטי הכניסה, ההגדרות והחיבור ל-CodeMender. הוא לא מעלה שום דבר, אלא אתם בודקים את הארכיון ומצרפים אותו לבקשת התמיכה.

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

cm support-bundle --session SESSION_ID

בלי --session, הפקודה אוספת פעילות מ-72 השעות האחרונות. כדי לשנות את החלון, משתמשים ב---since:

cm support-bundle --since 24h

הפקודה כותבת את cm-support-bundle-TIMESTAMP.tar.gz לספרייה הנוכחית ומדפיסה את הנתיב שלה. כדי לבחור את הנתיב, משתמשים ב---output (או ב--o).

מה הארכיון מכיל

כברירת מחדל, הארכיון לא כולל קוד מקור, הבדלים וקלט ופלט של כלים. הוא מכיל את הפרטים הבאים:

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

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

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

cm support-bundle --session SESSION_ID --include-content

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

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

תחזוקת סביבת העבודה

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

cm clean