Dependency Scanning

原文：https://docs.gitlab.com/ee/user/application_security/dependency_scanning/

• Overview
• Requirements
• Supported languages and package managers
• Contribute your scanner
• Configuration
  • Customizing the Dependency Scanning settings
  • Overriding Dependency Scanning jobs
  • Available variables
    • Configuring Dependency Scanning
    • Configuring Docker-in-Docker orchestrator
    • Configuring specific analyzers used by Dependency Scanning
  • Using private Maven repos
  • Enabling Docker-in-Docker
• Interacting with the vulnerabilities
• Solutions for vulnerabilities (auto-remediation)
• Security Dashboard
• Vulnerabilities database update
• Dependency List
• Reports JSON format
• Versioning and release process
• Contributing to the vulnerability database
• Running Dependency Scanning in an offline environment
  • Requirements for offline Dependency Scanning
  • Make GitLab Dependency Scanning analyzer images available inside your Docker registry
  • Set Dependency Scanning CI job variables to use local Dependency Scanning analyzers
  • Specific settings for languages and package managers
    • JavaScript (npm and yarn) projects
    • Ruby (gem) projects
    • Python (setuptools)
• Limitations
  • Referencing local dependencies using a path in JavaScript projects
• Troubleshooting
  • Error response from daemon: error processing tar file: docker-tar: relocation error

Dependency Scanning

Introduced in GitLab Ultimate 10.7.

在开发和测试应用程序时，例如当应用程序使用已知的易受攻击的外部（开源）库时，”依赖关系扫描”有助于自动在依赖项中查找安全漏洞.

Overview

如果您使用的是GitLab CI / CD ，则可以使用”依赖关系扫描”来分析依赖关系中的已知漏洞. 扫描所有依赖项，包括传递性依赖项（也称为嵌套依赖项）. 您可以通过在现有.gitlab-ci.yml文件中包括依赖扫描模板 ，或通过隐式使用Auto DevOps提供的自动依赖扫描来利用依赖扫描 .

GitLab 检查”依赖性扫描”报告，比较发现的源分支和目标分支之间的漏洞，并显示有关合并请求的信息.

结果按漏洞的严重性排序：

1. Critical
2. High
3. Medium
4. Low
5. Unknown
6. 其他一切

Requirements

要运行依赖扫描作业，默认情况下，你需要 GitLab 亚军与docker或kubernetes执行. 如果您在 GitLab.com 上使用共享的 Runners，则默认启用该功能.

注意：如果使用自己的 Runners，请确保已安装的 Docker 版本不是 19.03.0 . 有关详细信息 ，请参见故障排除信息 .

从 GitLab 13.0 开始，仅当您已启用 Docker-in-Docker 进行依赖项扫描时，才需要 Docker 特权模式.

Supported languages and package managers

GitLab 依赖于rules来启动相关分析器，具体取决于存储库中检测到的语言. 当前的检测逻辑将最大搜索深度限制为两个级别. 例如，如果存储库包含Gemfile或api/Gemfile文件，则启用gemnasium-dependency_scanning作业，但如果唯一受支持的依赖性文件是api/client/Gemfile .

支持以下语言和依赖项管理器：

正在制定支持以下语言，依赖性管理器和依赖性文件的计划. 有关详细信息，请参见每个的问题链接.

Contribute your scanner

安全扫描程序集成文档说明了如何将其他安全扫描程序集成到 GitLab 中.

Configuration

To enable Dependency Scanning for GitLab 11.9 and later, you must include the Dependency-Scanning.gitlab-ci.yml template that’s provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you can copy and use the job as defined that template.

将以下内容添加到您的.gitlab-ci.yml文件中：

include:
  - template: Dependency-Scanning.gitlab-ci.yml

随附的模板将在 CI / CD 管道中创建”依赖关系扫描”作业，并扫描项目的源代码以查找可能的漏洞. 结果将保存为” 依赖关系扫描”报告工件 ，您以后可以下载和分析该工件 . 由于实施限制，我们始终采用最新的”依赖关系扫描”工件.

Customizing the Dependency Scanning settings

可以使用.gitlab-ci.yml的variables参数通过环境变量来更改”依赖项扫描”设置. 例如：

include:
  - template: Dependency-Scanning.gitlab-ci.yml
variables:
  DS_PYTHON_VERSION: 2

因为模板是在管道配置之前评估的，所以最后提到的变量将具有优先权.

Overriding Dependency Scanning jobs

弃用：从 GitLab 13.0 开始，不再支持only和except的使用. 覆盖模板时，必须使用rules .

要覆盖作业定义（例如，更改诸如variables或dependencies类的属性），请声明一个与要覆盖的作业同名的新作业. 将此新作业放置在包含模板之后，并在其下指定其他任何键. 例如，这将禁用DS_REMEDIATE为gemnasium分析器：

include:
  - template: Dependency-Scanning.gitlab-ci.yml
gemnasium-dependency_scanning:
  variables:
    DS_REMEDIATE: "false"

Available variables

可以使用环境变量配置依赖性扫描.

Configuring Dependency Scanning

以下变量允许配置全局依赖项扫描设置.

Configuring Docker-in-Docker orchestrator

以下变量配置 Docker-in-Docker 协调器，因此仅在启用 Docker-in-Docker 模式时才使用.

Configuring specific analyzers used by Dependency Scanning

以下变量用于配置特定的分析器（用于特定的语言/框架）.

Using private Maven repos

如果您的私有 Maven 存储库需要登录凭据，则可以使用MAVEN_CLI_OPTS环境变量.

阅读有关如何使用私有 Maven 存储库的更多信息 .

Enabling Docker-in-Docker

在 GitLab Ultimate 12.5 中引入 .

如果需要，可以启用 Docker-in-Docker 来还原 GitLab 13.0 之前存在的 Dependency Scanning 行为. 请按照以下步骤操作：

1. 在特权模式下使用 Docker-in-Docker 配置 GitLab Runner.

2. Set the DS_DISABLE_DIND variable to false:

   include:
     - template: Dependency-Scanning.gitlab-ci.yml
   variables:
     DS_DISABLE_DIND: "false"

这将在您的 CI / CD 管道中创建一个dependency_scanning作业，而不是多个<analyzer-name>-dependency_scanning作业.

Interacting with the vulnerabilities

一旦发现漏洞，便可以与其进行交互. 阅读有关如何与漏洞进行交互的更多信息.

Solutions for vulnerabilities (auto-remediation)

可以通过应用 GitLab 自动生成的解决方案来修复某些漏洞. 阅读有关漏洞解决方案的更多信息.

Security Dashboard

在”安全仪表板”中，您可以概览您的组，项目和管道中的所有安全漏洞. 阅读有关安全仪表板的更多信息 .

Vulnerabilities database update

有关漏洞数据库更新的更多信息，请查看维护表 .

Dependency List

依赖项扫描的另一个好处是能够查看项目的依赖项及其已知漏洞. 阅读有关依赖列表的更多信息.

Reports JSON format

依赖关系扫描工具将发出 JSON 报告文件. 有关更多信息，请参见此报告的架构 .

这是一个示例依赖性扫描报告：

{  "version":  "2.0",  "vulnerabilities":  [  {  "id":  "51e83874-0ff6-4677-a4c5-249060554eae",  "category":  "dependency_scanning",  "name":  "Regular Expression Denial of Service",  "message":  "Regular Expression Denial of Service in debug",  "description":  "The debug module is vulnerable to regular expression denial of service when untrusted user input is passed into the `o` formatter. It takes around 50k characters to block for 2 seconds making this a low severity issue.",  "severity":  "Unknown",  "solution":  "Upgrade to latest versions.",  "scanner":  {  "id":  "gemnasium",  "name":  "Gemnasium"  },  "location":  {  "file":  "yarn.lock",  "dependency":  {  "package":  {  "name":  "debug"  },  "version":  "1.0.5"  }  },  "identifiers":  [  {  "type":  "gemnasium",  "name":  "Gemnasium-37283ed4-0380-40d7-ada7-2d994afcc62a",  "value":  "37283ed4-0380-40d7-ada7-2d994afcc62a",  "url":  "https://deps.sec.gitlab.com/packages/npm/debug/versions/1.0.5/advisories"  }  ],  "links":  [  {  "url":  "https://nodesecurity.io/advisories/534"  },  {  "url":  "https://github.com/visionmedia/debug/issues/501"  },  {  "url":  "https://github.com/visionmedia/debug/pull/504"  }  ]  },  {  "id":  "5d681b13-e8fa-4668-957e-8d88f932ddc7",  "category":  "dependency_scanning",  "name":  "Authentication bypass via incorrect DOM traversal and canonicalization",  "message":  "Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js",  "description":  "Some XML DOM traversal and canonicalization APIs may be inconsistent in handling of comments within XML nodes. Incorrect use of these APIs by some SAML libraries results in incorrect parsing of the inner text of XML nodes such that any inner text after the comment is lost prior to cryptographically signing the SAML message. Text after the comment therefore has no impact on the signature on the SAML message.\r\n\r\nA remote attacker can modify SAML content for a SAML service provider without invalidating the cryptographic signature, which may allow attackers to bypass primary authentication for the affected SAML service provider.",  "severity":  "Unknown",  "solution":  "Upgrade to fixed version.\r\n",  "scanner":  {  "id":  "gemnasium",  "name":  "Gemnasium"  },  "location":  {  "file":  "yarn.lock",  "dependency":  {  "package":  {  "name":  "saml2-js"  },  "version":  "1.5.0"  }  },  "identifiers":  [  {  "type":  "gemnasium",  "name":  "Gemnasium-9952e574-7b5b-46fa-a270-aeb694198a98",  "value":  "9952e574-7b5b-46fa-a270-aeb694198a98",  "url":  "https://deps.sec.gitlab.com/packages/npm/saml2-js/versions/1.5.0/advisories"  },  {  "type":  "cve",  "name":  "CVE-2017-11429",  "value":  "CVE-2017-11429",  "url":  "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-11429"  }  ],  "links":  [  {  "url":  "https://github.com/Clever/saml2/commit/3546cb61fd541f219abda364c5b919633609ef3d#diff-af730f9f738de1c9ad87596df3f6de84R279"  },  {  "url":  "https://github.com/Clever/saml2/issues/127"  },  {  "url":  "https://www.kb.cert.org/vuls/id/475445"  }  ]  }  ],  "remediations":  [  {  "fixes":  [  {  "id":  "5d681b13-e8fa-4668-957e-8d88f932ddc7",  }  ],  "summary":  "Upgrade saml2-js",  "diff":  "ZGlmZiAtLWdpdCBhL...OR0d1ZUc2THh3UT09Cg=="  // some content is omitted for brevity  }  ]  }

Versioning and release process

请检查发布过程文档 .

Contributing to the vulnerability database

您可以搜索gemnasium-db项目，以在 Gemnasium 数据库中找到漏洞. 您还可以提交新漏洞 .

Running Dependency Scanning in an offline environment

对于在通过 Internet 限制，限制或间歇性访问外部资源的环境中进行自我管理的 GitLab 实例，需要进行一些调整才能使”依赖关系扫描”作业成功运行. 有关更多信息，请参阅脱机环境 .

Requirements for offline Dependency Scanning

以下是在脱机环境中使用依赖关系扫描的要求：

• Keep Docker-In-Docker disabled (default).
• GitLab 亚军与docker或kubernetes执行 .
• Docker 容器注册表以及 Dependency Scanning 分析器映像的本地可用副本.
• 托管gemnasium-db 咨询数据库的脱机 Git 副本
• 仅在扫描 Ruby 项目时 ：托管咨询数据库的脱机 Git 副本.
• 仅在扫描 npm / yarn 项目时 ：托管retire.js 节点和js咨询数据库的脱机副本.

注意： GitLab Runner 的默认pull policy为always ，这意味着即使本地副本可用，Runner 也会尝试从 GitLab 容器注册表中拉取 Docker 映像. 如果您只喜欢使用本地可用的 Docker 映像，则可以在离线环境pull_policy GitLab Runner 的pull_policy设置为if-not-present . 但是，如果不在离线环境中，我们建议将拉取策略设置保持为always ，因为这样可以在 CI / CD 管道中使用更新的扫描仪.

Make GitLab Dependency Scanning analyzer images available inside your Docker registry

对于具有所有受支持的语言和框架的依赖关系扫描，请将以下默认的依赖关系扫描分析器映像从registry.gitlab.com导入本地 Docker 容器注册表 ：

registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium:2
registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven:2
registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python:2
registry.gitlab.com/gitlab-org/security-products/analyzers/retire.js:2
registry.gitlab.com/gitlab-org/security-products/analyzers/bundler-audit:2

将 Docker 映像导入本地脱机 Docker 注册表的过程取决于您的网络安全策略 . 请咨询您的 IT 员工，以找到可以导入或临时访问外部资源的已接受和批准的流程. 请注意，这些扫描程序会定期使用新定义进行更新 ，因此请考虑是否可以自己进行定期更新.

有关将 Docker 映像保存和传输为文件的详细信息，请参阅 Docker 有关docker save ， docker load ， docker export和docker import的文档.

Set Dependency Scanning CI job variables to use local Dependency Scanning analyzers

将以下配置添加到您的.gitlab-ci.yml文件. 您必须替换SECURE_ANALYZERS_PREFIX才能引用本地 Docker 容器注册表：

include:
  - template: Dependency-Scanning.gitlab-ci.yml
variables:
  SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers"
  GEMNASIUM_DB_REMOTE_URL: "gitlab.example.com/gemnasium-db.git"
  GIT_SSL_NO_VERIFY: "true"

请参阅配置部分中以上变量的说明.

Specific settings for languages and package managers

请参阅以下各节，以配置特定的语言和程序包管理器.

JavaScript (npm and yarn) projects

将以下内容添加到.gitlab-ci.yml的变量部分：

RETIREJS_JS_ADVISORY_DB: "example.com/jsrepository.json"
RETIREJS_NODE_ADVISORY_DB: "example.com/npmrepository.json"

Ruby (gem) projects

将以下内容添加到.gitlab-ci.yml的变量部分：

BUNDLER_AUDIT_ADVISORY_DB_REF_NAME: "master"
BUNDLER_AUDIT_ADVISORY_DB_URL: "gitlab.example.com/ruby-advisory-db.git"

Python (setuptools)

当为私有 PyPi 存储库使用自签名证书时，不需要额外的作业配置（除了上面的模板.gitlab-ci.yml ）. 但是，您必须更新setup.py以确保它可以到达您的私有存储库. 这是一个示例配置：

1. 更新setup.py ，以为install_requires列表中的每个依赖项创建一个指向您的私有存储库的dependency_links属性：

   install_requires=['pyparsing>=2.0.3'],
   dependency_links=['https://pypi.example.com/simple/pyparsing'],

2. 从存储库 URL 中获取证书并将其添加到项目中：

   echo -n | openssl s_client -connect pypi.example.com:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt

3. 将setup.py指向新下载的证书：

   import setuptools.ssl_support
   setuptools.ssl_support.cert_paths = ['internal.crt']

Limitations

Referencing local dependencies using a path in JavaScript projects

Retire.js分析器不支持使用 JavaScript 项目的package.json的本地路径进行的依赖项引用. 依赖项扫描针对此类引用输出以下错误：

ERROR: Could not find dependencies: <dependency-name>. You may need to run npm install

解决方法是，从DS_DEFAULT_ANALYZERS删除retire.js分析器.

Troubleshooting

Error response from daemon: error processing tar file: docker-tar: relocation error

当运行 Dependency Scanning 作业的 Docker 版本为19.03.00时，会发生此错误. 考虑更新到 Docker 19.03.1或更高版本. 旧版本不受影响. 阅读本期的更多内容.