在 CodeQL 中使用自定义查询

项目
11/02/2024

默认情况下，如果没有在管道设置中指定自定义配置文件，CodeQL 会运行 security-extended 查询包来分析代码。可以利用自定义 CodeQL 查询来编写自己的查询，以查找特定的漏洞和错误。还需要创建一个自定义配置文件，来修改 CodeQL 的默认分析。

若要查找现有的自定义查询或参与自己的自定义查询，请参阅参与 CodeQL。

使用自定义查询进行分析

开始使用自定义查询的最快方法是编写查询，并将其保存在本地 Azure DevOps 存储库中。可以根据需要对自定义查询的详细信息进行自定义，但它必须至少有一个规则 ID。有关如何编写自己的 CodeQL 查询的详细信息，请参阅编写 CodeQL 查询。还可以将多个查询捆绑到查询套件中，或者利用其他人发布的包。有关详细信息，请参阅发布及使用 CodeQL 包。

使用自定义配置文件

自定义配置文件是管理 CodeQL 对代码进行分析期间运行哪些查询的一种方式。可以指定要运行的其他查询或查询包，并更改或禁用默认 CodeQL 查询。

若要包含想要包含的特定查询，请使用查询文件 (.ql) 在存储库中的位置的名称和路径来指定查询。

若要包含想要包含的特定包，请指定包名称。可以在配置文件中指定任意数量的 CodeQL 查询包来运行。

下一步是创建 qlpack.yml 文件。此文件声明 CodeQL 包及其相关信息。与 qlpack.yml 在同一目录（或子目录）中的任何 *.ql 文件都被视为包的一部分。

提示

配置文件中的 packs 筛选器支持从 GitHub 中托管的存储库下载包，但 queries 筛选器不支持。如果包在 GitHub 中是私有的，则需要通过 AdvancedSecurity-Codeql-Init@1 任务提供一个 GitHub 访问令牌作为环境变量，且变量名称为 GITHUB_TOKEN，令牌的作用域为 read:packages。

下面是一个示例配置文件：

name: "Run custom queries"

# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
 
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
  - name: Use security-extended query suite
    uses: security-extended
  - name: Use local custom query (single query)
    uses: ./customQueries/javascript/FindTestFunctions.ql
  - name: Use local custom query (directory of queries)
    uses: ./customQueries/javascript/MemoryLeakQueries  
 
packs:
 - mygithuborg/mypackname
 
paths:
 - src
 
paths-ignore:
  - src/node_modules
  - '**/*.test.js'
 
query-filters:
 - include:
    kind: problem
 - include:
     precision: medium
 - exclude:
    id:
      - js/angular/disabling-sce
      - js/angular/insecure-url-allowlist

提示

配置文件规范会忽略，并优先于 AdvancedSecurity-Codeql-Init@1 任务的管道级别配置。 includepaths / ignorepaths 将被忽略，或者如果 paths/paths-ignore 存在，则用来自 paths/paths-ignore 的值覆盖。 querysuite 将被用 queries 或 packs 配置文件中指定的值覆盖。

如果你正在使用任何自定义查询，可以参阅自定义查询目录中放置的 qlpack.yml 示例：

version: 1.0.1
dependencies:
  codeql/javascript-all: "*"
  codeql/javascript-queries: "*"

dependencies 变量包含此包的所有依赖项及其兼容的版本范围。每个依赖项都作为 scope/name CodeQL 库包被引用。定义 dependencies 时，你的 qlpack.yml 取决于确切的核心语言包之一（例如 JavaScript、C#、Ruby 等），这决定了查询可以分析的语言。

有关配置文件的更具体建议和配置选项，请参阅自定义高级设置进行代码扫描，或者，有关 qlpack.yml 设置，请参阅 CodeQL 包结构。

一旦有了配置文件，就需要自定义运行 CodeQL 分析的管道，以利用新文件。下面是指向配置文件的示例管道：

trigger: none
 
pool:
  vmImage: windows-latest

# You can either specify your CodeQL variables in a variable block... 
variables:
# `configfilepath` must be an absolute file path relative to the repository root
  advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' 

# Or you can specify variables as variables for the task. You do not need both definitions. 
steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
    languages: 'javascript'
    loglevel: '2'
    configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
  env:
    GITHUB_TOKEN: $(githubtoken)

- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis

通过

在 CodeQL 中使用自定义查询

使用自定义查询进行分析

使用自定义配置文件

反馈

其他资源