如何配置CodeQL SAST扫描为预提交钩子并实现自动化部署？

核心实现步骤 #

1. 自动安装CodeQL CLI #

编写跨平台脚本，在预提交扫描前自动检测本地是否存在CodeQL CLI，不存在则根据系统（Windows/Mac）自动下载并部署到项目本地目录（避免全局安装，不干扰开发者环境）。

示例脚本片段（bash）：

# 定义本地存储路径
CODEQL_ROOT=".codeql"
CODEQL_BIN="$CODEQL_ROOT/codeql"

# 检查CLI是否存在，不存在则下载安装
if [ ! -f "$CODEQL_BIN" ]; then
    mkdir -p "$CODEQL_ROOT"
    OS=$(uname | tr '[:upper:]' '[:lower:]')
    case "$OS" in
        darwin)
            DOWNLOAD_URL="https://github.com/github/codeql-cli-binaries/releases/latest/download/codeql-osx64.zip"
            ;;
        windows)
            DOWNLOAD_URL="https://github.com/github/codeql-cli-binaries/releases/latest/download/codeql-win64.zip"
            ;;
        *)
            echo "Unsupported OS: $OS"
            exit 1
            ;;
    esac
    # 下载并解压
    curl -L "$DOWNLOAD_URL" -o "$CODEQL_ROOT/codeql.zip"
    unzip "$CODEQL_ROOT/codeql.zip" -d "$CODEQL_ROOT"
    # 移动CLI到指定目录并清理冗余文件
    mv "$CODEQL_ROOT/codeql-"*"/codeql" "$CODEQL_ROOT/"
    rm -rf "$CODEQL_ROOT/codeql-"* "$CODEQL_ROOT/codeql.zip"
fi

2. 自动创建CodeQL数据库 #

根据项目语言自动生成对应数据库，扫描前确保数据库基于当前最新代码。需注意不同语言需要对应构建命令（确保代码被正确编译/依赖安装）。

示例脚本片段：

DB_DIR="$CODEQL_ROOT/db"
# 可根据项目文件自动检测语言，比如检查package.json设为javascript，pom.xml设为java
DETECTED_LANG="javascript"
BUILD_CMD="npm install" # 对应语言的构建命令，Java用mvn compile，Python可省略

# 清理旧数据库并创建新数据库
rm -rf "$DB_DIR"
"$CODEQL_BIN" database create "$DB_DIR" --language="$DETECTED_LANG" --command="$BUILD_CMD"

3. 配置预提交钩子 #

将上述逻辑整合到预提交钩子中，实现提交前自动触发扫描。

方式一：直接使用Git钩子

在项目根目录创建.githooks/pre-commit文件，写入完整扫描逻辑，并设置可执行权限：

#!/bin/bash
# 引入上述CLI安装和数据库创建脚本逻辑
# ...（省略重复代码）

# 执行CodeQL扫描
"$CODEQL_BIN" database analyze "$DB_DIR" "codeql/javascript-queries" --format=sarif-latest --output=codeql-results.sarif

# 判断扫描结果，若存在高危漏洞则阻止提交
if grep -q "error" codeql-results.sarif; then
    echo "CodeQL扫描发现高危漏洞，提交已阻止"
    exit 1
fi

然后运行一次配置命令，让Git使用自定义钩子目录：

git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

方式二：使用预提交框架（推荐）

创建.pre-commit-config.yaml配置文件，引入自定义扫描脚本：

repos:
-   repo: local
    hooks:
    -   id: codeql-sast-scan
        name: CodeQL SAST Scan
        entry: .scripts/codeql-scan.sh
        language: script
        pass_filenames: false

将扫描逻辑写入.scripts/codeql-scan.sh，开发者只需执行pre-commit install即可完成钩子配置。

4. 透明化部署优化 #

• 将.codeql目录加入.gitignore，避免提交到仓库
• 编写项目初始化脚本（如setup.sh），自动完成钩子配置：

#!/bin/bash
git config core.hooksPath .githooks
chmod +x .githooks/pre-commit
echo "CodeQL预提交钩子已配置完成"

• 若为Node.js项目，可将初始化命令加入package.json的postinstall脚本，实现拉取项目后自动配置：

{
  "scripts": {
    "postinstall": "./setup.sh"
  }
}

注意事项 #

• 首次运行钩子会下载CodeQL CLI和创建数据库，耗时较长，需提前告知开发者
• 不同语言的构建命令需根据项目实际调整，确保CodeQL能捕获完整代码信息
• Windows环境需确保开发者使用Git Bash或WSL执行钩子脚本，避免兼容性问题
• 可优化数据库创建逻辑，仅在代码有变更时重新生成，提升扫描效率

内容的提问来源于stack exchange，提问作者nnay84