CodeQL CLI入門
一、CodeQL CLI 安裝和配置
1.下載CodeQL CLI 壓縮包
//github.com/github/codeql-cli-binaries/releases
2.創建CodeQL目錄，如$HOME/codeql-home
3.創建CodeQL查詢的本地拷貝
CodeQL倉庫包含分析C/C++, C#, Java, JavaScript、python等所需的查詢和庫文件。需要拷貝一份倉庫到codeql-home目錄，重命名倉庫文件夾為codeql-repo
倉庫下載地址：//github.com/github/codeql
- go的倉庫地址：//github.com/github/codeql-go/
- 假設CodeQL倉庫目錄為$HOME/codeql-home/codeql-repo，那麼go的倉庫目錄可以設置為$HOME/codeql-home/codeql-go
4.解壓CodeQL CLI 壓縮包$HOME/codeql-home目錄
5.運行CodeQL
（1）通過直接執行$HOME/codeql-home/codeql/codeql來運行CodeQL
（2）將$HOME/codeql-home/codeql目錄添加到環境變數
二、創建CodeQL資料庫
命令：
codeql database create <database> --language=<language-identifier>
參數說明：
<database>：創建的資料庫的路徑，必須是不存在的文件夾
–language：如下
| C/C++ | cpp |
| C# | csharp |
| Go | go |
| Java | java |
| JavaScript/TypeScript | javascript |
| Python | python |
其它參數：
–source-root 指定資料庫創建時的源文件根目錄，默認為當前目錄。
–command 指定語言的編譯命令，不要給python和JavaScript指定該命令。
非編譯型語言創建資料庫
codeql database create --language=javascript --source-root <folder-to-extract> <output-folder>/javascript-database
三、使用CodeQL CLI分析資料庫
命令：
codeql database analyze <database> <queries> --format=<format> --output=<output>
參數說明：
<database> 預分析的資料庫路徑
<queries> 要在資料庫上運行的查詢。可以指定一個或多個單獨的查詢文件，指定將以遞歸方式搜索查詢文件的目錄，或者命名定義了一組特定查詢的查詢套件。
–format 分析生成的結果文件的文件格式
–output 分析結果的輸出路徑
還可以通過--threads指定運行查詢時要使用的執行緒數。默認選項是1
示例：
codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
上述分析的結果會在新創建的文件夾js-analysis下的js-results.csv文件中輸出
運行目錄中的所有查詢
您可以通過提供目錄路徑而不是列出所有單個查詢文件來運行目錄中的所有查詢。路徑是遞歸搜索的，因此子文件夾中包含的所有查詢也將被執行。
重要
您不應在執行
database analyze時指定QL包的根目錄， 因為它包含一些並非為命令使用而設計的特殊查詢。相反，要運行各種有用的查詢，請運行LGTM.com查詢套件之一。
例如，要執行Functions 目錄中包含的所有Python查詢，您將運行：
codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
會生成一個SARIF結果文件。通過--format=sarif-latest可確保結果根據CodeQL支援的最新SARIF規範進行格式化。
結果
您可以將分析結果保存為多種不同格式，包括SARIF和CSV。
SARIF（數據分析結果交換格式）是定義輸出文件格式的OASIS 標準。 SARIF 標準用於簡化靜態分析工具分享其結果的方式。 有關更多資訊，請參見SARIF概述。
如果選擇將結果生成為CSV，則輸出的每條告警將包含以下資訊：
| 名稱 | 標識結果的查詢名稱。 | Inefficient regular expression |
| 描述 | 查詢的描述。 | A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks. |
| 嚴重程度 | 查詢的嚴重性。 | error |
| 資訊 | 告警消息。 | This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'. |
| 路徑 | 包含告警的文件的路徑。 | /vendor/codemirror/markdown.js |
| 起跑線 | 觸發告警的程式碼開始的文件行。 | 617 |
| 開始欄 | 起始行的列，用於標記告警程式碼的開始。第一列不包括在內。 | 32 |
| 終點線 | 觸發告警的程式碼結束的文件行。與起始行相同時不包括在內。 | 64 |
| 結束欄 | 可能的話，在結束行的列中標記告警程式碼的結尾。否則，將重複結束行。 | 617 |
結果文件可以集成到您自己的程式碼審查或調試基礎結構中。例如，SARIF文件輸出可通過IDE的SARIF查看插件在源程式碼中的正確告警位置進行突出顯示。
在CodeQL CLI中使用自定義查詢
您可以通過編寫自己的查詢來突出顯示特定的漏洞或錯誤，從而自定義CodeQL分析。
寫一個有效的查詢
在運行自定義分析之前，您需要編寫一個有效的查詢，並將其保存在帶有.ql擴展名的文件中。有大量可用的文檔可幫助您編寫查詢。有關更多資訊，請參閱學習CodeQL幫助中的CodeQL查詢。
包括查詢的元數據
查詢元數據包含在每個查詢文件的頂部。它為用戶提供有關查詢的資訊，並告訴CodeQL CLI如何處理查詢結果。
使用命令運行查詢時，必須包括以下兩個屬性，以確保正確解釋結果：database analyze
- 查詢標識符（
@id）：小寫字母或數字，通過分隔構成單詞序列/或-，識別和查詢進行分類。 - 查詢類型（
@kind）：標識查詢是警報（）還是路徑（）。@kind problem@kind path-problem
有關這些元數據屬性的更多資訊，請參見CodeQL查詢的元數據和《查詢元數據樣式指南》。
注意
如果要與其他應用程式一起使用查詢，則元數據要求可能會有所不同。有關更多資訊，請參見學習CodeQL幫助 中的關於CodeQL查詢。
