扫描执行策略

使用扫描执行策略根据默认或最新的 安全 CI 模板 强制执行极狐GitLab安全扫描，可以作为流水线的一部分或在指定的时间表上进行。

扫描执行策略在所有链接到安全策略项目并在策略范围内的项目中执行。对于没有 .gitlab-ci.yml 文件或禁用 AutoDevOps 的项目，安全策略隐式创建 .gitlab-ci.yml 文件。这确保了启用密钥检测、静态分析或其他不需要项目构建的扫描器执行的策略仍然可以运行并被强制执行。

与流水线执行策略相比，扫描执行策略提供了一条更快捷的路径来配置多个项目的极狐GitLab安全扫描以管理安全性和合规性。

如果以下任何情况属实，请改用流水线执行策略：

• 您需要高级配置设置。
• 您希望强制执行自定义 CI/CD 作业或脚本。
• 您希望通过强制执行的 CI/CD 作业启用第三方安全扫描。

限制#

• 您可以为每个策略分配最多五个规则。
• 您可以为每个安全策略项目分配最多五个扫描执行策略。
• 本地项目 YAML 文件不能覆盖扫描执行策略。这些策略优先于为流水线定义的任何配置，即使您在项目的 CI/CD 配置中使用相同的作业名称。
• 当您使用 override_ci 策略时，流水线执行策略可以 覆盖 扫描执行策略。

作业#

除了 DAST 扫描之外的扫描策略作业是在流水线的 test 阶段创建的。如果您从默认流水线中移除 test 阶段，作业将在 scan-policies 阶段运行。此阶段在评估时被注入到 CI/CD 流水线中，如果它不存在。如果存在 build 阶段，它将在 build 阶段之后注入，否则它将在流水线的开始处注入。DAST 扫描总是在 dast 阶段运行。如果此阶段不存在，则在流水线结束时注入 dast 阶段。

为了避免作业名称冲突，会在作业名称后附加一个连字符和一个数字。数字在每个策略动作中是唯一的。例如 secret-detection 变为 secret-detection-1。

扫描执行策略编辑器#

使用扫描执行策略编辑器创建或编辑扫描执行策略。

先决条件：

• 默认情况下，只有群组、子群组或项目所有者具有 权限 创建或分配安全策略项目。或者，您可以创建具有权限的自定义角色以 管理安全策略链接。

一旦您的策略完成，通过选择编辑器底部的 使用合并请求配置 保存它。您将被重定向到项目配置的安全策略项目中的合并请求。如果一个项目没有链接到您的项目，安全策略项目将自动创建。现有策略也可以通过选择编辑器底部的 删除策略 从编辑器界面中删除，以引入合并请求以从 policy.yml 文件中删除策略。

大多数策略更改在合并请求合并后立即生效。任何未通过合并请求直接提交到默认分支的更改可能需要长达 10 分钟才能生效。

扫描执行策略架构#

具有扫描执行策略的 YAML 文件由一个对象数组组成，这些对象与嵌套在 scan_execution_policy 键下的扫描执行策略架构匹配。您可以在 scan_execution_policy 键下配置最多 5 个策略。配置的其他策略在前 5 个之后不应用。

当您保存新策略时，极狐GitLab 会根据 此 JSON 架构 验证其内容。

扫描执行策略架构#

skip_ci 类型#

扫描执行策略提供对谁可以使用 [skip ci] 指令的控制。您可以指定允许使用 [skip ci] 的特定用户或服务帐户，同时仍然确保执行关键的安全和合规检查。

使用 skip_ci 关键字指定用户是否可以应用 skip_ci 指令以跳过流水线。 当未指定关键字时，skip_ci 指令被忽略，阻止所有用户绕过流水线执行策略。

pipeline 规则类型#

此规则在选定分支的流水线运行时强制执行定义的动作。

1. 您必须仅指定 branches 或 branch_type 中的一个。

schedule 规则类型#

使用 schedule 规则类型按照计划运行安全扫描器。

计划的流水线：

• 仅运行策略中定义的扫描器，而不是项目的 .gitlab-ci.yml 文件中定义的作业。
• 根据 cadence 字段定义的计划运行。
• 在项目中的 security_policy_bot 用户帐户下运行，具有访客角色和权限，以从 CI/CD 作业中创建流水线并读取存储库的内容。此帐户在策略链接到群组或项目时创建。

1. 您必须仅指定 branches、branch_type 或 agents 中的一个。

节奏#

使用 cadence 字段来安排您希望策略的动作运行的时间。cadence 字段使用 cron 语法，但有一些限制：

• 仅支持以下类型的 cron 语法：
  • 每小时一次的每日节奏，例如：0 18 * * *
  • 每周一次的每周节奏，在指定的日子和时间，例如：0 13 * * 0
• 不支持在分钟和小时中使用逗号（,）、连字符（-）或步进运算符（/）。使用这些字符的任何计划流水线都会被跳过。

在选择 cadence 字段的值时，请考虑以下事项：

• 时间基于 极狐GitLab SaaS 的 UTC 和 极狐GitLab 主机的系统时间用于 极狐GitLab 私有化部署。在测试新策略时，可能会出现流水线未正确运行的情况，实际上它们在服务器的时区中被安排。
• 计划的流水线在策略中提到的时间附近启动，当资源变得可用时创建。换句话说，流水线可能不会在策略中指定的时间精确开始。

当使用 schedule 规则类型与 agents 字段时：

• 极狐GitLab 的 Kubernetes 代理每 30 秒检查一次是否存在适用策略。当找到策略时，根据定义的 cadence 执行扫描。
• Cron 表达式使用 Kubernetes 代理 pod 的系统时间进行评估。

当使用 schedule 规则类型与 branches 字段时：

• Cron worker 每 15 分钟间隔运行一次，并启动任何计划在过去 15 分钟内运行的流水线。因此，计划的流水线可能会以最多 15 分钟的偏移量运行。
• 如果策略在大量项目或分支上强制执行，策略会以批处理方式处理，可能需要一些时间才能创建所有流水线。

agent 架构#

使用此架构在 schedule 规则类型 中定义 agents 对象。

策略示例#

yaml
1- name: Enforce Container Scanning in cluster connected through my-gitlab-agent for default and kube-system namespaces
2  enabled: true
3  rules:
4  - type: schedule
5    cadence: '0 10 * * *'
6    agents:
7      <agent-name>:
8        namespaces:
9        - 'default'
10        - 'kube-system'
11  actions:
12  - scan: container_scanning

计划规则的键是：

• cadence（必需）：扫描运行时的 Cron 表达式。
• agents:<agent-name>（必需）：用于扫描的代理名称。
• agents:<agent-name>:namespaces（可选）：要扫描的 Kubernetes 命名空间。如果省略，则扫描所有命名空间。

time_window 架构#

在 schedule 规则类型 中使用 time_window 对象定义计划扫描如何分配时间。您只能在策略编辑器的 YAML 模式中配置 time_window。

策略示例#

yaml
1- name: Enforce Container Scanning with a time window of 1 hour
2  enabled: true
3  rules:
4  - type: schedule
5    cadence: '0 10 * * *'
6    time_window:
7      value: 3600
8      distribution: random
9  actions:
10  - scan: container_scanning

优化大规模项目的计划流水线#

在启用跨多个项目的计划扫描时，请考虑性能。

如果未启用 scan_execution_pipeline_concurrency_control 功能标识：

• 计划的流水线在策略强制执行的所有项目和分支中同时运行。
• 每个项目中的第一次计划流水线执行会创建一个安全机器人用户，负责执行每个项目中的计划。

要优化大规模项目的性能：

• 逐步推出计划扫描执行策略，从部分项目开始。您可以利用安全策略范围来定位特定的群组、项目或具有给定合规框架标签的项目。
• 您可以配置策略在具有指定 tag 的 runner 上运行计划。考虑在每个项目中设置一个专用的 runner 来处理从策略强制执行的计划，以减少对其他 runner 的影响。
• 在生产环境中部署之前，请在暂存或较低的环境中测试您的实施。监控性能并根据结果调整您的推出计划。

并发控制#

当以下条件满足时，极狐GitLab 应用并发控制：

• 启用了 scan_execution_pipeline_concurrency_control 功能标识
• 您设置了 time_window 属性

并发控制根据策略中定义的 time_window 设置 分配计划的流水线。

scan 动作类型#

此动作执行选定的 scan，当定义策略中的至少一个规则的条件满足时，附加参数。

扫描器行为#

某些扫描器在 scan 动作中与常规的基于 CI/CD 流水线的扫描行为不同。

• 静态应用安全测试 (SAST)：仅在存储库中包含 SAST 支持的文件 时运行。
• 密钥检测：
  • 仅支持具有默认规则集的规则。替换 或 扩展 默认规则集不支持。相反，您可以配置 远程配置文件 来使用 SECRET_DETECTION_RULESET_GIT_REFERENCE 变量覆盖或禁用默认规则集中的规则。
  • 对于 scheduled 扫描执行策略，密钥检测默认情况下首先在 historic 模式下运行 (SECRET_DETECTION_HISTORIC_SCAN = true)。所有后续的计划扫描在默认模式下运行，将 SECRET_DETECTION_LOG_OPTIONS 设置为最后运行和当前 SHA 之间的提交范围。您可以通过在扫描执行策略中指定 CI/CD 变量来覆盖此行为。有关更多信息，请参阅 完整历史流水线密钥检测。
  • 对于 triggered 扫描执行策略，密钥检测的工作方式与常规扫描 在 .gitlab-ci.yml 中手动配置 相同。
• 容器扫描：为 pipeline 规则类型配置的扫描忽略在 agents 对象中定义的代理。agents 对象仅适用于 schedule 规则类型。必须为项目创建并配置一个在 agents 对象中提供名称的代理。

DAST 配置文件#

强制执行动态应用安全测试 (DAST) 时适用以下要求：

• 在策略范围内的每个项目中，必须存在指定的 站点配置文件 和 扫描器配置文件。如果这些不可用，则策略不适用，而是创建一个带有错误消息的作业。
• 当启用的扫描执行策略中命名了 DAST 站点配置文件或扫描器配置文件时，配置文件不能被修改或删除。要编辑或删除配置文件，您必须首先在策略编辑器中将策略设置为 禁用 或在 YAML 模式中设置 enabled: false。
• 当使用计划的 DAST 扫描配置策略时，安全策略项目存储库中的提交作者必须可以访问扫描器和站点配置文件。否则，扫描未能成功计划。

扫描设置#

scan_settings 参数支持以下设置：

CI/CD 变量#

扫描执行策略中定义的变量遵循标准的 CI/CD 变量优先级。

在任何项目中强制执行扫描执行策略时，以下 CI/CD 变量使用预配置值。它们的值可以被覆盖，但 仅 如果它们在策略中声明。它们 不能 被群组或项目 CI/CD 变量覆盖：

plaintext
1DS_EXCLUDED_PATHS: spec, test, tests, tmp
2SAST_EXCLUDED_PATHS: spec, test, tests, tmp
3SECRET_DETECTION_EXCLUDED_PATHS: ''
4SECRET_DETECTION_HISTORIC_SCAN: false
5SAST_EXCLUDED_ANALYZERS: ''
6DEFAULT_SAST_EXCLUDED_PATHS: spec, test, tests, tmp
7DS_EXCLUDED_ANALYZERS: ''

在 极狐GitLab 16.9 及更早版本：

• 如果在策略中声明了以 _EXCLUDED_PATHS 结尾的 CI/CD 变量，它们的值可以被群组或项目 CI/CD 变量覆盖。
• 如果在策略中声明了以 _EXCLUDED_ANALYZERS 结尾的 CI/CD 变量，它们的值会被忽略，无论它们在哪里定义：策略、群组或项目。

策略范围架构#

要自定义策略执行，您可以定义策略的范围以包括或排除指定的项目、群组或合规框架标签。有关详细信息，请参阅 Scope。

示例安全策略项目#

您可以在存储在 安全策略项目 中的 .gitlab/security-policies/policy.yml 文件中使用此示例：

yaml
1---
2scan_execution_policy:
3- name: Enforce DAST in every release pipeline
4  description: This policy enforces pipeline configuration to have a job with DAST scan for release branches
5  enabled: true
6  rules:
7  - type: pipeline
8    branches:
9    - release/*
10  actions:
11  - scan: dast
12    scanner_profile: Scanner Profile A
13    site_profile: Site Profile B
14- name: Enforce DAST and secret detection scans every 10 minutes
15  description: This policy enforces DAST and secret detection scans to run every 10 minutes
16  enabled: true
17  rules:
18  - type: schedule
19    branches:
20    - main
21    cadence: "*/10 * * * *"
22  actions:
23  - scan: dast
24    scanner_profile: Scanner Profile C
25    site_profile: Site Profile D
26  - scan: secret_detection
27    scan_settings:
28      ignore_default_before_after_script: true
29- name: Enforce Secret Detection and Container Scanning in every default branch pipeline
30  description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch
31  enabled: true
32  rules:
33  - type: pipeline
34    branches:
35    - main
36  actions:
37  - scan: secret_detection
38  - scan: sast
39    variables:
40      SAST_EXCLUDED_ANALYZERS: brakeman
41  - scan: container_scanning

在此示例中：

• 对于在匹配 release/* 通配符的分支上执行的每个流水线（例如，分支 release/v1.2.1）
  • DAST 扫描运行 Scanner Profile A 和 Site Profile B。
• DAST 和密钥检测扫描每 10 分钟运行一次。DAST 扫描运行 Scanner Profile C 和 Site Profile D。
• 密钥检测、容器扫描和 SAST 扫描运行于 main 分支上执行的每个流水线。SAST 扫描运行，SAST_EXCLUDED_ANALYZER 变量设置为 "brakeman"。

扫描执行策略编辑器示例#

您可以在 扫描执行策略编辑器 的 YAML 模式中使用此示例。 它对应于前一个示例中的单个对象。

yaml
1name: Enforce Secret Detection and Container Scanning in every default branch pipeline
2description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch
3enabled: true
4rules:
5  - type: pipeline
6    branches:
7      - main
8actions:
9  - scan: secret_detection
10  - scan: container_scanning

避免重复扫描#

扫描执行策略可能导致开发人员在项目的 .gitlab-ci.yml 文件中包含扫描作业时，同一类型的扫描器运行多次。这种行为是有意的，因为扫描器可以使用不同的变量和设置多次运行。例如，开发人员可能希望尝试运行一个 SAST 扫描，使用与安全和合规团队强制执行的不同变量。在这种情况下，两次 SAST 作业在流水线上运行，一个使用开发人员的变量，一个使用安全和合规团队的变量。

如果您想避免运行重复的扫描，您可以从项目的 .gitlab-ci.yml 文件中删除扫描，或者使用变量跳过本地作业。跳过作业不会阻止任何由扫描执行策略定义的安全作业运行。

要使用变量跳过扫描作业，您可以使用：

• SAST_DISABLED: "true" 跳过 SAST 作业。
• DAST_DISABLED: "true" 跳过 DAST 作业。
• CONTAINER_SCANNING_DISABLED: "true" 跳过容器扫描作业。
• SECRET_DETECTION_DISABLED: "true" 跳过密钥检测作业。
• DEPENDENCY_SCANNING_DISABLED: "true" 跳过依赖扫描作业。

有关可以跳过作业的所有变量的概述，请参阅 CI/CD 变量文档。