Code Risk Analyzer のヘルプ

以下のコマンドは、Code Risk Analyzer コマンドのリストを表示します。

ibmcloud cra --help

Code Risk Analyzer コマンド・ヘルプ

次のコマンドは、コマンドで使用されるフラグの詳細を表示します。 使用可能なコマンドを表示するには、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 の両方がサポートされています。

Dockerfile を使用している場合は、必ず、基本イメージのプル元のコンテナー・レジストリーにログインしてください。

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。Dockerfileのパスを対応するビルド・コンテキストにマッピングするJSONファイルである。

プロジェクト・ディレクトリに .cra/.dockerbuildcontext ファイルが存在する場合、CRA Docker ビルド・コマンドは、このファイルに指定されたパスを、関連するDockerfileのビルド・コンテキストとして使用します。 JSONオブジェクトのキーはDockerfileへの相対パスを表し、値はそれぞれのビルド・コンテキストへの相対パスを指定します。

以下は、複数のDockerfileに対して異なるビルド・コンテキストを定義する .dockerbuildcontext ファイルの例である：

{
  "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に設定されている場合、修復パスが使用可能になるまで脆弱性は省略されます。 修復が利用可能になると、脆弱性は除外されずにメッセージが表示されます。 このプロパティーは、有効期限日のプロパティー値より優先されます。
• 有効期限 - このプロパティーが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) の一部として実行される。 このコマンドはNCAを Docker イメージとして実行するため、コンピュータにインストールする必要があります。 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)

cra-custom-script-pathパラメーターは、プロジェクトに基づいて、DevSecOps 基本イメージ・ツールのバージョンが古くなっている可能性があるシナリオにも使用できます。 例えば、新しい pip バージョンを必要とする Python パッケージを検出するために、pip/pip3などのコマンドを更新できます。

以下の例は、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 レジストリーのイメージを使用する場合は、cra-custom-script-pathパラメーターを使用して、Code Risk Analyzer を実行する前にプライベート 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 での Code Risk Analyzer のデバッグ

デバッグを支援するために、独自のローカル・マシンで Code Risk Analyzer をコマンド・ライン・インターフェース (CLI) としてローカルに実行できます。 BOMを生成するための ibmcloud cra bom-generate コマンドの実行については、 部品表（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 が必要な場合、ARGS が欠落しているため、ビルド・ステージのdocker buildコマンドはビルドに失敗します。 ARGS を環境変数としてセットアップするには、cra-custom-script-pathが必要です。 カスタム・スクリプトのセットアップについて詳しくは、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コマンドを使用して、基本イメージが存在するレジストリーで認証されていることを確認します。

Dockerfile の分析に失敗した BOM コマンドをデバッグするにはどうすればよいですか?

• docker buildコマンドを実行し、成功することを確認して、Dockerfile に問題がないことを確認します。
• Dockerfile で ARG を渡す必要がある場合は、ARG が環境変数として設定されていることを確認してください。 DOCKERBUILDFLAG環境変数を使用することもできます。
• 基本イメージを含むレジストリーで認証します。

予想外の偽陽性の結果が出ている。 どうすればよいですか?

DevSecOps 継続的デプロイメント（CD）パイプラインを実行して、エビデンスロッカーに更新されたSBOMを生成する。 これは、 DevSecOps 継続的コンプライアンス（CC）パイプラインによって生成された古いSBOMの存在に起因する、偽陽性の潜在的な原因に対処する可能性がある。

報告書や問題の重大度が、関連する脆弱性リンクの重大度と異なるのはなぜですか?

最近、脆弱性情報のソースが変更されたため、特定の脆弱性に関連する深刻度が変更されていることがあります。 Code Risk Analyzer は、全ての脆弱性の原因の計算に基づいて、最適な重大度を決定します。