הכנת מסד נתונים עבור CodeQL

  • 5 דקות

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

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

ניתוח CodeQL מסתמך על חילוץ נתונים יחסיים מהקוד שלך ומשתמש בו לבניית מסד נתונים של CodeQL. מסדי נתונים אלה מכילים את כל המידע החשוב אודות בסיס קוד.

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

הכנת מסד נתונים עבור CodeQL

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

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

עבור שפות מפורשות, המחלץ פועל ישירות על קוד המקור. יכולת זו מספקת ייצוג מדויק של בסיס הקוד ופותרת יחסי תלות.

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

הגדרת CLI

השתמש בשלבים הבאים כדי להגדיר את ה- CLI של CodeQL.

1. הורד את חבילת ה- CLI של חבילת ה- CLI .zip CodeQL

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

חבילת ההורדה של CLI של CodeQL .zip ארכיון המכיל כלים, קבצי Script וקבצים שונים הספציפיים ל- CodeQL. החבילה כוללת: ה- CLI של CodeQL, גירסאות תואמות של השאילתות והספריות מהמאפור של CodeQL GitHub וגירסאות ה- Precompiled של השאילתות הכלולות.

  1. עבור אל המהדורות של המאגר הציבורי CodeQL.
  2. הורד את החבילה הספציפית לפלטפורמה תחת נכסים.

בדף מהדורות, באפשרותך גם להציג את פריטי לוחות משתנים עבור מהדורות, יחד עם הורדות עבור גירסאות קודמות של החבילה CodeQL. במידת הצורך, באפשרותך להוריד codeql-bundle.tar.gz, המכיל את ה- CLI עבור כל הפלטפורמות הנתמכות.

2. חלץ את .zip הארכיון

אם אתה משתמש ב- Linux, Windows או macOS, באפשרותך לחלץ את .zip הארכיון לתוך מדריך הכתובות שתבחר.

משתמשי macOS Catalina (או גירסה חדשה יותר) צריכים לבצע שלבים נוספים. לקבלת מידע נוסף, עיין בתיעוד CodeQL אודות תחילת העבודה עם CLI.

3. הפעל תהליכי CodeQL

לאחר החילוץ, בצע אחד מהפעולות הבאות כדי להשתמש codeql קובץ ההפעלה כדי להפעיל את תהליכי CodeQL:

  • הפעל <extraction-root>/codeql/codeql, כאשר <extraction-root> היא התיקיה שבה חילץ את חבילת ה- CLI של CodeQL.
  • הוסף <extraction-root>/codeql לערך PATH שלך, כך שתוכל להפעיל את קובץ ההפעלה בדיוק codeql.

כעת באפשרותך להפעיל פקודות CodeQL.

אימות של הגדרת CLI

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

  • הפעל codeql resolve packs (אם הוספת codeql כדי PATH) כדי להראות אילו ערכות CodeQL ה- CLI יכול למצוא. אחרת, השתמש /<extraction-root>/codeql/codeql resolve packs. פקודה זו מציגה את השמות של ערכות CodeQL הכלולות בחבילה CLI של CodeQL, המוצגות בשלבים הקודמים כקובץ <extraction-root>.

    אם ה- CLI של CodeQL אינו מוצא את ערכות CodeQL עבור השפות הצפויות, בדוק שהורדת את החבילה CodeQL ולא עותק עצמאי של ה- CLI של CodeQL.

  • הפעל codeql resolve languages כדי להציג את השפות שבהן תומכת חבילת ממשקי ה- CLI של CodeQL כברירת מחדל.

יצירת מסד נתונים

צור מסד נתונים של CodeQL על-ידי הפעלת פקודה זו מתוך בסיס ההוצאה של הפרוייקט שלך:

codeql database create <database> --language=<language-identifier>

בפקודה:

  • החלף <database> בנתיב למסד הנתונים החדש שיש ליצור.
  • החלף <language-identifier> בהמזהה של השפה שבה אתה משתמש כדי ליצור את מסד הנתונים. באפשרותך להשתמש במזהה זה עם --db-cluster לקבל רשימות מופרדות באמצעות פסיקים, או לציין אותו יותר מפעם אחת.

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

  • השתמש --source-root כדי לזהות את תיקיית הבסיס עבור קבצי המקור הראשיים ליצירת מסד נתונים.
  • השתמש --db-cluster בסיסי קוד מרובי שפות כאשר ברצונך ליצור מסדי נתונים עבור יותר משפה אחת.
  • השתמש --command בעת יצירת מסד נתונים עבור שפה אחת או יותר הידור. אין צורך באפשרות זו אם אתה משתמש רק ב- Python וב- JavaScript.
  • השתמש --no-run-unnecessary-builds יחד עם --db-cluster להעלים את פקודת ה- Build עבור שפות שבהן ממשק שורת הפקודה של CodeQL אינו צריך לנטר את גירסת ה- Build.

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

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

מחלצים

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

כל מחלץ מגדיר קבוצה משלו של אפשרויות תצורה. הזנת codeql resolve extractor --format=betterjson התוצאות בנתונים המעוצבים כמו בדוגמה הבאה:

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

כדי לברר אילו אפשרויות זמינות עבור מחלץ השפה שלך, הזן codeql resolve languages --format=betterjson או codeql resolve extractor --format=betterjson. תבנית betterjson מספקת גם את הבסיס של המחלץ ואפשרויות אחרות הספציפיות לשפה.

נתונים במסד נתונים של CodeQL

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

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

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

מסד נתונים של CodeQL כולל שתי טבלאות ראשיות:

  • טבלת expressions מכילה שורה עבור כל ביטוי בקוד המקור ש- CodeQL נתח במהלך תהליך ה- Build.
  • הטבלה statements מכילה שורה עבור כל משפט בקוד המקור ש- CodeQL נתח במהלך תהליך גירסת ה- Build.

ספריית CodeQL מגדירה מחלקות כדי לספק שכבה של הפשטה בכל אחת מטבלאות אלה. שכבה זו כוללת את טבלאות עזר קשורות Expr ו- Stmt.

שגיאות פוטנציאליות ב- CodeQL

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

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

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

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

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

באפשרותך לקרוא מידע נוסף על שפות ספציפיות ועל השלבים autobuild המפורטים בתיעוד של פיתוח אוטומטי של CodeQL.

סיומת VS Code

באפשרותך להשתמש ב- Visual Studio Code (VS Code) ובסיומת CodeQL כדי לבצע הידור והפעלה של שאילתות, כל עוד אתה משתמש ב- VS Code 1.39 ואילך. באפשרותך להוריד את ההרחבה מ- Visual Studio Code Marketplace או על-ידי הורדת הקובץ CodeQL VSIX.

ההרחבה משתמשת ב- CLI המותקן PATH אם היא זמינה. אם לא, הסיומת מנהלת באופן אוטומטי את הגישה לקובץ ההפעלה של ה- CLI עבורך. ניהול אוטומטי מבטיח ש- CLI תואם להרחבת CodeQL.