CodeQL 的核心概念
CodeQL 是由 GitHub 開發的語義程式碼分析引擎。它的核心理念是將程式碼視為數據。
傳統的工具可能只是搜尋特定的字串或語法結構，但 CodeQL 會將你的原始碼編譯成一個關係型資料庫。開發者可以使用一種類似 SQL 的查詢語言（稱為 QL）來查詢這個資料庫，尋找複雜的邏輯漏洞。例如，你可以編寫查詢來追蹤：某個來自使用者輸入的變數，是否在沒有經過過濾的情況下，流向了敏感的資料庫執行函數。
如何使用 CodeQL
使用 CodeQL 主要有三種方式，取決於你的開發場景：
1. GitHub 預設設定（最簡單）
直接在 GitHub 儲存庫的 Settings > Code security > Code scanning 中點選 Set up，選擇 Default 模式。GitHub 會自動偵測語言並建立 Action 工作流。
2. GitHub Actions 進階設定
如果你需要自定義掃描規則或處理複雜的編譯環境，可以使用 github/codeql-action。這通常包含三個標準步驟：
- Initialize：安裝 CodeQL 執行環境並建立空資料庫。
- Autobuild / Build：編譯程式碼，CodeQL 會在此時觀察並捕捉程式碼結構。
- Analyze：執行查詢規則並將結果上傳至 GitHub Security 標籤頁。
3. CodeQL CLI
如果你想在本地電腦或自己的 CI 環境執行掃描，可以下載 CodeQL CLI 工具。流程如下：
- 使用
codeql database create指令將原始碼轉為資料庫。 - 使用
codeql database analyze執行官方提供的安全性查詢套件（Queries）。 - 產出 SARIF 格式的報告進行查看。
建議的使用時間點
為了達到最佳的安全防護，建議在以下三個時間點觸啟動掃描：
拉取請求（Pull Request）
這是最重要的時間點（Shift-left）。在程式碼合併到主分支之前進行掃描，可以防止新的漏洞進入正式環境。GitHub 會直接在 PR 頁面顯示掃描結果，讓開發者即時修復。
定期掃描（Scheduled Scan）
建議每週或每天固定執行一次全量掃描。這是因為 CodeQL 的漏洞資料庫會持續更新，過去認為安全的程式碼，可能會因為新發現的漏洞攻擊手法而被標記為不安全。
推送至主分支（Push to Main Branch）
當新的程式碼合併到主軸時執行，確保最終合併後的版本在與其他模組整合後，依然符合安全標準。
在現有的 CI/CD 流程中加入 CodeQL，需要參考具體的 YAML 設定範例
針對 GitHub Actions 的設定，這裡提供一個標準的 YAML 範例。你可以將這段程式碼存放在專案目錄下的 .github/workflows/codeql.yml 位置。
GitHub Actions 設定範例
這是一個針對 Java 與 JavaScript 專案的典型配置，它涵蓋了初始化、自動編譯與分析三個核心步驟。
YAML
name: "CodeQL Security Scan"
on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
schedule:
- cron: '30 0 * * 1' # 每週一凌晨執行一次
jobs:
analyze:
name: Analyze
runs-on: ubuntu-latest
permissions:
actions: read
contents: read
security-events: write
strategy:
fail-fast: false
matrix:
language: [ 'java', 'javascript' ]
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Initialize CodeQL
uses: github/codeql-action/init@v3
with:
languages: ${{ matrix.language }}
# 如果有自定義的查詢規則，可以在這裡指定
# queries: security-extended,security-and-quality
- name: Autobuild
uses: github/codeql-action/autobuild@v3
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v3
with:
category: "/language:${{matrix.language}}"
關鍵步驟說明
權限設定 (Permissions)
在 Job 層級必須宣告 security-events: write。這是因為 CodeQL 分析完畢後，需要將結果（SARIF 檔案）上傳到 GitHub 的安全性看版，若沒有這個權限，掃描結果將無法顯示在 UI 介面上。
語言矩陣 (Strategy Matrix)
透過 matrix 可以同時掃描多種語言。CodeQL 會為每種語言啟動一個獨立的 Runner 進行分析。這對於包含前端 (JavaScript) 與後端 (Java/C#) 的全端專案非常有效率。
自動編譯 (Autobuild)
對於需要編譯的語言（如 Java, C++, C#），CodeQL 的 autobuild 會嘗試偵測建置系統並執行編譯。如果你的專案有特殊的編譯指令（例如特定的 Maven Profile 或複雜的環境變數），建議移除 autobuild 步驟，改用手動編譯指令：
YAML
- name: Manual Build
run: |
mvn clean install -DskipTests
掃描結果查看
當 Workflow 執行完成後，你可以到 GitHub 儲存庫上方的 Security 分頁，選擇 Code scanning。這裡會列出所有偵測到的漏洞，包含漏洞的預期路徑、嚴重程度以及修復建議。
CodeQL 的收費方式主要取決於你的專案性質（公開或私有）以及使用的環境。以下整理 2026 年最新的收費架構：
公開儲存庫 (Public Repositories)
對於開源專案，CodeQL 是完全免費的。
- 掃描功能：你可以無限制地使用 CodeQL 掃描公開專案，且不收費。
- 執行成本：如果使用 GitHub 託管的標籤執行器 (GitHub-hosted runners)，在公開專案上執行 Actions 也是免費的。
私有儲存庫 (Private Repositories)
對於公司或個人的私有專案，CodeQL 通常需要付費，其模式分為兩部分：
1. 功能授權費 (GitHub Advanced Security)
CodeQL 屬於 GitHub Advanced Security (GHAS) 套件的一部分。
- 企業用戶：必須購買 GHAS 授權才能在私有專案啟用 CodeQL。收費通常是根據「活躍提交者」(Active Committer) 數量計算，大約每人每月 30 美元。
- 個人/小團隊：如果你使用的是 GitHub Free 或 Team 方案，預設無法在私有專案使用 CodeQL。
2. 運算成本 (Actions Minutes)
執行 CodeQL 掃描需要消耗運算資源：
- GitHub 託管執行器：會消耗你的 Actions 免費額度（例如 Free 方案每月 2,000 分鐘）。超過額度後，會根據機器規格按分鐘計費。
- 自託管執行器 (Self-hosted Runners)：從 2026 年 3 月起，GitHub 對於自託管執行器也開始收取每分鐘約 0.002 美元的雲端平台服務費，不再是完全免費。
特別例外與免費方案
- 學生與教職員：透過 GitHub Student Developer Pack 認證，可以免費獲得許多進階安全功能。
- 開源貢獻者：如果你是知名開源專案的維護者，有機會獲得免費的 Pro 或更高階授權。
- 研究用途：CodeQL 的 CLI 工具在非商業的安全研究用途下通常是免費的。
| 專案類型 | CodeQL 功能 | GitHub Actions 運算 |
| 公開 (Public) | 免費 | 免費 |
| 私有 (Private) | 需購買 GHAS 授權 | 消耗分鐘數額度或付費 |