代码风险分析器插件 IBM Cloud

代码风险分析器帮助

以下命令显示代码风险分析器命令列表：

ibmcloud cra --help

代码风险分析器命令帮助

以下命令显示命令中使用的标记的详细信息。 使用 ibmcloud cra --help 显示可用命令。

ibmcloud cra <command> --help

BOM 命令要求

bom-generate 命令依赖于某些外部命令：

• 如果路径中包含 Dockerfile，该命令会为每个 Dockerfile 中的每个构建阶段提取基础镜像和构建镜像。 在这种情况下，bom-generate 命令要求 Docker cli 和 tar 命令可用。
• 如果路径中包含 Maven 文件，该命令会使用 mvn 生成依赖项列表。 在这种情况下，bom-generate 命令要求 mvn 命令可用。
• 如果路径中包含 Gradle 文件，该命令将使用 gradle 建立依赖关系列表。 在这种情况下，bom-generate 命令要求 gradle 命令可用。
• 如果路径中包含 Node.js package-json 文件，且该命令用于生成相应的 package-lock.json 文件，则 bom-generate 命令会使用 npm 生成 package-lock.json 文件。 在这种情况下，该命令要求 npm 命令可用。
• 如果路径包含 Python requirements.txt 或 pyproject.toml 文件，命令会使用 pip 生成软件包依赖关系。 在这种情况下，bom-generate 命令要求 pip 命令可用。 Python 版本 2 和 Python 版本 3 都支持。

如果您使用的是 Dockerfiles，请务必登录容器注册中心，从那里提取基础映像。

如果您的 Dockerfile 需要 ARGS，请在运行命令前将单个 ARG 设置为环境变量。 例如，如果 Dockerfile 使用 IAM_USER ARG，则导出一个名为 IAM_USER: export IAM_USER='value' 的环境变量。 CLI 会自动将这些环境变量传递给 docker build 命令。

您也可以明确指定 DOCKERBUILDFLAGS 标志。 要使用 ARGS Docker 标志导出 DOCKERBUILDFLAGS，请键入以下命令：

export DOCKERBUILDFLAGS="--build-arg IAM_USER --build-arg API_KEY"

BOM 命令选项

下表列出了使用 bom-generate 命令生成 BOM 时可以使用的命令选项。

忽略文件

如果路径包含 .cra/.fileignore 文件，则不会扫描 .fileignore 文件中指定的文件以查找依赖关系。 .fileignore 文件必须遵循 .gitignore 文件的规则。 与 .gitignore 文件类似，.fileignore 文件也可以包含注释、要忽略的目录、要忽略的文件和其他 模式。

下面的 .fileignore 文件示例展示了如何排除 bash 脚本、node_modules 和 Dockerfile。

# Ignore nested functional_tests directory
**/functional_tests

# Ignore bash scripts
**/*.sh

# This should allow this one file
!test/gatling_tests/loginTobx.sh

# Ignore node_modules
node_modules

# Exclude the dockerfile from scanning
Dockerfile

设置多个 Docker 构建上下文

在单个项目中使用多个 Dockerfile 时，可能需要为每个 Dockerfile 定义单独的构建上下文。 这可以通过使用 .cra/.dockerbuildcontext 文件来实现，该文件是一个 JSON 文件，用于将 Dockerfile 路径映射到相应的构建上下文。

如果项目目录中存在 .cra/.dockerbuildcontext 文件，CRA Docker 构建命令将使用该文件中的指定路径作为相关 Dockerfile 的构建上下文。 JSON 对象中的键代表 Dockerfile 的相对路径，而值则指定各自构建上下文的相对路径。

下面是 .dockerbuildcontext 文件的一个示例，它为多个 Dockerfile 定义了不同的构建上下文：

{
  "Dockerfile": "./",
  "path/to/different/Dockerfile": "./another/Path"
}

示例

以下代码片段展示了如何使用 bom-generate 命令：

ibmcloud cra bom-generate --path PATH --report REPORT [--asset-type ASSET-TYPE] [--dockerbuildcontext] [--dockerbuildflags DOCKERBUILDFLAGS] [--dockerfilepattern DOCKERFILEPATTERN] [--gradle.excludeconfigurations GRADLE.EXCLUDECONFIGURATIONS] [--maven.excludescopes MAVEN.EXCLUDESCOPES] [--nodejs.createpackagelock] [--prev-report PREV-REPORT] [--region REGION] [--toolchainid TOOLCHAINID] [--verbose]

ibmcloud cra bom --path . --report bomreport.json

漏洞扫描命令选项

下表列出了使用 vulnerability-scan 命令的选项。

忽视漏洞

如果指定了 -c 或 --cveignore 参数，命令会查找该文件，但不会报告文件中指定的 CVE。 您可以对 CVE 进行配置，无限期地忽略它们，直到有补救措施为止，或直到指定的过期日期为止。

下面的示例显示了 .cveignore 文件的 JSON 模式：

[
    {
        "cve": "string",
	    "alwaysOmit": "bool",
	    "untilRemediationAvailable": "bool",
	    "expiration": "string"
    }
]

.cveignore 文件中的每个条目都支持以下属性：

• cve- 要省略的漏洞。 此属性的值为 CVE ID。
• alwaysOmit- 如果该属性设置为 true，则漏洞会被省略，直到其被更改。 该属性优先于其他属性值。
• untilRemediationAvailable- 如果该属性设置为 true，则漏洞会被省略，直到有补救路径为止。 如果有补救措施，漏洞不会被省略，并会显示一条信息。 该属性优先于过期属性值。
• expiration- 如果该属性设置为 true，且未到失效日期，则省略该漏洞。 如果过期，则不会省略漏洞，并显示一条信息。 使用 RFC3339 时间格式 (yyyy-MM-ddTHH:mm:ss[+-]Z) 定义此属性。

代码风险分析器只使用这些已定义的属性。 您可以添加对函数没有影响的属性。 如果 .cveignore 中定义的漏洞未被省略，则会生成日志解释原因。 如果省略 .cveignore 文件中定义的漏洞，则不会显示单个日志。 报告完成后，会记录漏报的数量和带有软件包名称的漏洞 ID 列表。

下面的代码片段显示了一个 .cveignore 文件示例：

[
    {
        "cve": "CVE-2021-27290",
        "alwaysOmit": true
    },
    {
        "cve": "CVE-2020-8244",
        "untilRemediationAvailable": true,
    }
]

示例

以下代码片段展示了如何使用 vulnerability-scan 命令：

ibmcloud cra vulnerability-scan --bom BOM [--cveignore CVEIGNORE] [--report REPORT] [--excludedev] [--include-nofix app,os,all,none] [--region REGION] [--strict] [--toolchainid TOOLCHAINID] [--output OUTPUTFILE]

ibmcloud cra cve --bom ./bom-file.json --cveignore ./cveignore-example.json --report ./output-vulnerability-report.json --excludedev --include-nofix all --strict

部署命令选项

下表列出了 deployment-analyze 命令的命令选项。

示例

以下代码片段展示了如何使用 deployment-analyze 命令：

ibmcloud cra deployment-analyze --path PATH --report REPORT [--fileignore FILE_IGNORE] [--strict]

ibmcloud cra depl --path ./sampleDir --report deployment-report.json --strict

NetworkPolicy 分析命令选项

下表列出了 netpol-analyze 命令的命令选项。

示例

以下示例代码片段展示了如何使用 netpol-analyze 命令：

ibmcloud cra netpol-analyze --path PATH --report REPORT [--connectivity CONNFILE] [--lint LINTFILE] [--strict]

ibmcloud cra np --path ./sampleDir --report netpol-report.json --strict

网络配置分析仪图像

netpol-analyze 命令作为 IBM网络配置分析器（NCA） 的一部分运行。 由于该命令以 Docker 映像运行 NCA，因此必须在计算机上安装 Docker 在您的计算机上安装。

网络策略分析器的图像 URL 是 icr.io/continuous-delivery/cra/nca.

如果本地注册表中还没有分析器映像，netpol-analyze 命令会从全局 IBM Cloud® Container Registry 中提取最新的分析器映像（包括对任何漏洞的修复）。

自定义脚本示例 DevSecOps

如果 Dockerfile 需要 ARGS，可以在运行命令前使用 cra-custom-script-path 参数将单个 ARG 设置为环境变量。 自定义脚本路径是用户项目中脚本的路径。 例如，如果 Dockerfile 使用 IAM_USER ARG，则在脚本中导出一个名为 IAM_USER: export IAM_USER='value' 的环境变量。 如果 Dockerfile 所需的 ARG 被设置为工具链中的环境属性，则可以使用 get_env 获取该值。 在这种情况下，您可以在 IAM_USER: export IAM_USER=$(get_env iam_user_environment_property_name) 脚本中导出一个环境变量。 run-cra 任务会自动获取这些环境变量，并将它们传递给 Docker 编译命令。

下面的示例显示了如何使用 cra-custom-script 导出 ENV 变量：

#!/usr/bin/env bash

if [[ "${PIPELINE_DEBUG:-0}" == 1 ]]; then
    trap env EXIT
    env | sort
    set -x
fi

export IAM_USER=$(get_env iam_user_environment_property_name)

您还可以根据项目情况，在 DevSecOps 基本图像工具版本可能过时的情况下使用 cra-custom-script-path 参数。 例如，你可以更新 pip/pip3 等命令，以发现需要更高 pip 版本的 Python 软件包。

下面的示例展示了如何使用 cra-custom-script 更新 pip 版本：

#!/usr/bin/env bash

if [[ "${PIPELINE_DEBUG:-0}" == 1 ]]; then
    trap env EXIT
    env | sort
    set -x
fi

python3 -m pip install --upgrade pip

如果您的 Dockerfile 使用来自私有 Docker 注册表的映像，您可以在运行 Code Risk Analyzer 之前使用 cra-custom-script-path 参数对私有 Docker 注册表进行身份验证，并允许 Code Risk Analyzer 提取该映像进行扫描。

下面的示例显示了如何使用 cra-custom-script 对 ibmcloud 容器注册表进行身份验证：

#!/usr/bin/env bash

if [[ "${PIPELINE_DEBUG:-0}" == 1 ]]; then
    trap env EXIT
    env | sort
    set -x
fi

ibmcloud cr login

代码风险分析器的调试 DevSecOps

为帮助调试，您可以在本地计算机上以命令行界面 (CLI) 的方式运行代码风险分析器。 有关运行 ibmcloud cra bom-generate 命令生成BOM，请参阅 物料清单（BOM）。 生成 BOM 后，使用 ibmcloud cra cve 命令列出任何漏洞。 有关运行 ibmcloud cra cve 命令的更多信息，请参阅 漏洞扫描。

确保 run-cra 任务不包含任何错误。 如果任务包含错误，请检查您的管道是否使用当前版本的 DevSecOps。 如果检查 DevSecOps, 的版本仍不能解决问题，下面的示例提供了一些常见错误和建议的解决方案。

FAILED
Error executing docker pull cmd: [docker pull us.icr.io/opentoolchain/ibmnode:14ubisecure]

您可以验证自己是否有访问私人注册表的权限。 如果没有访问权限，可以使用 cra-custom-script-path 参数，并指定在 Code Risk Analyzer 验证专用注册表之前运行的自定义脚本的路径。

FAILED
Error executing docker build cmd for stage-0: exit status 1

如果您的 Dockerfile 需要 ARGS，那么用于构建阶段的 docker build 命令就会因为缺少 ARGS 而构建失败。 cra-custom-script-path 需要将 ARGS 设置为环境变量。 有关设置自定义脚本的更多信息，请参阅 DevSecOps 的自定义脚本示例。

FAILED
Error executing docker build cmd for stage-0: exit status 1
...
COPY file-to-copy.js file-to-copy.js:
------
failed to compute cache key: "/file-to-copy.js" not found: not found

默认情况下，Code Risk Analyzer bom-generate 命令从 Dockerfile 本身位置的上下文构建 Dockerfile。 如果要从项目根目录的上下文构建 Dockerfile，请使用 cra-docker-build-context 参数允许代码风险分析器从该上下文构建 Dockerfile。

如何确定 CLI 失败的原因？

在调用 Code Risk Analyzer CLI 之前，请将 IBMCLOUD_TRACE 环境变量设置为 true，以打开调试日志。

export IBMCLOUD_TRACE=true

观察 API 调用和日志中显示的响应，以确定失败的确切原因。

如何调试无法从专用注册表中提取基本映像的 BOM 命令？

使用 ibmcloud cr login 命令或 docker login 命令，确保已通过基本映像所在注册表的身份验证。

如何调试无法分析 Docker 文件的 BOM 命令？

• 运行 docker build 命令并确保其通过，以验证 Dockerfile 没有任何问题。
• 如果 Dockerfile 要求传递 ARG，请确保将 ARG 设置为环境变量。 您也可以使用 DOCKERBUILDFLAG 环境变量。
• 使用包含基础映像的注册表进行验证。

我看到了意想不到的假阳性结果。 我该怎么做？

运行 DevSecOps Continuous Deployment (CD) 管道，在证据柜中生成更新的 SBOM。 这可能会解决因 DevSecOps Continuous Compliance (CC) 管道生成的旧 SBOM 的存在而导致误报的潜在原因。

为什么报告或问题的严重性与相关漏洞链接的严重性不同？

由于我们的漏洞信息来源最近发生了变化，您可能会看到与特定漏洞相关的严重性发生了变化。 代码风险分析器将根据对所有漏洞来源的计算结果，确定最佳严重程度。