程式碼風險分析器說明

以下指令會顯示 Code Risk Analyzer 指令清單：

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) 定義此屬性。

Code Risk Analyzer 只使用這些定義的屬性。 您可以新增對函數沒有影響的屬性。 如果 .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 ' Network Config Analyzer(NCA) 的一部分。 由於此指令是以 Docker image 執行 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) 的方式執行 Code Risk Analyzer。 有關執行 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 參數允許 Code Risk Analyzer 從這個上下文建立 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 持續部署 (CD) 管道，在證據櫃中製作更新的 SBOM。 這可能會解決因 DevSecOps Continuous Compliance (CC) pipeline 所產生的舊版 SBOM 而導致誤判的潛在原因。

為何報告或問題的嚴重性與相關弱點連結的嚴重性不同？

由於我們的弱點資訊來源最近有所變更，您可能會發現與特定弱點相關的嚴重性已經改變。 Code Risk Analyzer 會根據所有弱點來源的計算結果，決定最佳的嚴重性。