在 CodeQL 中使用自定义查询

默认情况下,如果没有在管道设置中指定自定义配置文件,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 将被用 queriespacks 配置文件中指定的值覆盖。

如果你正在使用任何自定义查询,可以参阅自定义查询目录中放置的 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