Code Risk Analyzer plug-in for IBM Cloud

Code Risk Analyzer help

The following command displays the list of Code Risk Analyzer commands:

ibmcloud cra --help

Code Risk Analyzer command help

The following command displays the details of flags that are used with a command. Use ibmcloud cra --help to display the available commands.

ibmcloud cra <command> --help

BOM command requirements

The bom-generate command depends on certain external commands:

• If the path contains Dockerfiles, this command pulls down base images and build images for every build stage in each Dockerfile. In this scenario, the bom-generate command requires that the Docker cli and tar commands are available.
• If the path contains Maven files, this command uses mvn to build a list of dependencies. In this scenario, the bom-generate command requires the mvn command to be available.
• If the path contains Gradle files, this command uses gradle to build a list of dependencies. In this scenario, the bom-generate command requires the gradle command to be available.
• If the path contains Node.js package-json files and this command is used to generate a corresponding package-lock.json file, the bom-generate command uses npm to build the package-lock.json file. In this scenario, the command requires the npm command to be available.
• If the path contains the Python requirements.txt or pyproject.toml files, the command uses pip to generate the package dependencies. In this scenario, the bom-generatecommand requires the pip command to be available. Both Python version 2 and Python version 3 are supported.

If you are using Dockerfiles, make sure to log in to your container registry from where the base images are to be pulled.

If your Dockerfile requires ARGS, set an individual ARG as an environment variable before you run the command. For example, if the Dockerfile is using an IAM_USER ARG, export an environment variable that is named IAM_USER: export IAM_USER='value'. The CLI automatically passes these environment variables to the docker build command.

You can also specify the DOCKERBUILDFLAGS flag explicitly. To export DOCKERBUILDFLAGS with the ARGS Docker flag, type the following command:

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

BOM command options

The following table lists the command options that you can use to generate a BOM with the bom-generate command.

Ignoring files

If the path contains the .cra/.fileignore file, files that are specified in the .fileignore file are not scanned for dependencies. The .fileignore file must follow the rules of .gitignore files. Similar to a .gitignore file, the .fileignore file can include comments, directories to ignore, files to ignore, and other patterns.

The following example .fileignore file shows how to exclude bash scripts, node_modules, and the 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

Setting Multiple Docker Build Contexts

When working with multiple Dockerfiles within a single project, you may want to define separate build contexts for each Dockerfile. This can be achieved by using a .cra/.dockerbuildcontext file, which is a JSON file that maps Dockerfile paths to their corresponding build contexts.

If a .cra/.dockerbuildcontext file exists in your project directory, the CRA Docker build commands will use the specified paths in this file as the build contexts for the associated Dockerfiles. The keys in the JSON object represent the relative paths to the Dockerfiles, while the values specify the relative paths to the respective build contexts.

Here’s an example of a .dockerbuildcontext file that defines different build contexts for multiple Dockerfiles:

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

Example

The following code snippets show how to use the bom-generate command:

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 command options

The following table lists the options for using the vulnerability-scan command.

Ignoring vulnerabilities

If the -c or --cveignore parameter is specified, the command looks for that file and does not report the CVEs that are specified in the file. You can configure the CVEs to omit them indefinitely until a remediation is available, or until a specified expiration date.

The following example shows a JSON schema for the .cveignore file:

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

The following properties are supported for each entry in the .cveignore file:

• cve - The vulnerability to omit. The value of this property is a CVE ID.
• alwaysOmit - If this property is set to true, the vulnerability is omitted until it is changed. This property takes precedence over other property values.
• untilRemediationAvailable - If this property is set to true, the vulnerability is omitted until a remediation path is available. If a remediation becomes available, the vulnerability is not omitted and a message is displayed. This property takes precedence over the expiration property value.
• expiration - If this property is set to true and the expiration date is not reached, the vulnerability is omitted. If the expiration date is reached, the vulnerability is not omitted and a message is displayed. Use the RFC3339 time format (yyyy-MM-ddTHH:mm:ss[+-]Z) to define this property.

The Code Risk Analyzer uses only these defined properties. You can add properties with no effect on functions. If a vulnerability that is defined in the .cveignore is not omitted, a log is generated that explains the reason. If a vulnerability that is defined in the .cveignore file is omitted, no individual logging is displayed. The number of omissions and a list of the vulnerability IDs, with the package name, that are omitted are logged after a report is completed.

The following code snippet shows a sample .cveignore file:

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

Example

The following code snippets show how to use the vulnerability-scan command:

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 command options

The following table lists the command options that you can use for the deployment-analyze command.

Example

The following code snippets show how to use the deployment-analyze command:

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

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

NetworkPolicy analysis command options

The following table lists the command options that you can use for the netpol-analyze command.

Example

The following sample code snippets show how you can use the netpol-analyze command:

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

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

Network config analyzer image

The netpol-analyze command runs as part of IBM's Network Config Analyzer (NCA). Because this command runs NCA as a Docker image, you must install Docker on your computer.

The image URL for the network policy analyzer is icr.io/continuous-delivery/cra/nca.

If the analyzer image is not already in your local registry, the netpol-analyze command pulls the latest analyzer image (including fixes for any vulnerabilities) from the global IBM Cloud® Container Registry.

Example custom scripts for DevSecOps

If your Dockerfile requires ARGS, you can use the cra-custom-script-path parameter to set an individual ARG as an environment variable before you run the command. The custom script path is the path to a script that resides in the user's project. For example, if the Dockerfile uses IAM_USER ARG, export an environment variable inside the script that is named IAM_USER: export IAM_USER='value'. If the ARG that is required by your Dockerfile is set as an environment property within toolchains, you can use get_env to get the value. In this instance, you can export an environment variable within the IAM_USER: export IAM_USER=$(get_env iam_user_environment_property_name) script. The run-cra task automatically picks up these environment variables and passes them to the Docker build commands.

The following example shows how to use the cra-custom-script to export the ENV variable:

#!/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)

You can also use the cra-custom-script-path parameter for scenarios in which the DevSecOps base image tool versions might be outdated, based on your project. For example, you can update commands such as pip/pip3 for discovering Python packages that require a later pip version.

The following example shows how to use the cra-custom-script to update the pip version:

#!/usr/bin/env bash

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

python3 -m pip install --upgrade pip

If your Dockerfile uses an image from a private Docker registry, you can use the cra-custom-script-path parameter to authenticate to a private Docker registry before you run Code Risk Analyzer and to allow Code Risk Analyzer to pull this image for scanning.

The following example shows how to use the cra-custom-script to authenticate to the ibmcloud container registry:

#!/usr/bin/env bash

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

ibmcloud cr login

Debugging the Code Risk Analyzer in DevSecOps

To help with debugging, you can run the Code Risk Analyzer locally as a command-line interface (CLI) on your own local machine. For information about running the ibmcloud cra bom-generate command to generate a BOM, see Bill of materials (BOM). After you generate the BOM, use the ibmcloud cra cve command to list any vulnerabilities. For more information about running the ibmcloud cra cve command, see Vulnerability scan.

Make sure that the run-cra task does not contain any errors. If the task contains errors, check whether your pipeline uses the current version of DevSecOps. If the issue is not resolved by checking the version of DevSecOps, the following examples provide some common errors and proposed solutions.

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

You can verify that you have access to the private registry. If you do not have access, you can use the cra-custom-script-path parameter and specify the path to a custom script that runs before Code Risk Analyzer to authenticate to the private registry.

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

If your Dockerfile requires ARGS, the docker build command for the build stages fails to build because of the missing ARGS. The cra-custom-script-path is required to set up the ARGS as environment variables. For more information about setting up the custom script, see Example custom scripts for 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

By default, the Code Risk Analyzer bom-generate command builds the Dockerfiles from the context of the location of the Dockerfile itself. If you want to build the Dockerfiles from the context of the root project directory, use the cra-docker-build-context parameter to allow the Code Risk Analyzer to build the Dockerfiles from this context.

How can I determine why the CLI failed?

Before you call the Code Risk Analyzer CLI, set the IBMCLOUD_TRACE environment variable to true to turn on the debug log.

export IBMCLOUD_TRACE=true

Observe the API calls and the responses that are shown in the log to determine the exact reason for failure.

How can I debug a BOM command that fails to pull a base image from a private registry.

Make sure that you are authenticated with the registry where the base image resides by using the ibmcloud cr login command or the docker login command.

How can I debug a BOM command that is failing to analyze a Dockerfile?

• Verify that the Dockerfile does not have any issues by running the docker build command and making sure that it passes.
• If your Dockerfile requires ARG to be passed, make sure that the ARG is set as an environment variable. You can also use the DOCKERBUILDFLAG environment variable.
• Authenticate with the registry that contains the base images.

I am seeing unexpected false positive results. What should I do?

Run the DevSecOps Continuous Deployment (CD) pipeline to generate an updated SBOM in the evidence locker. This might address a potential cause of false positives that results from the presence of an older SBOM that was generated by the DevSecOps Continuous Compliance (CC) pipeline.

Why is the severity of the report or issue different from the one of the associated vulnerability link?

Since our source of vulnerability information has changed recently, you might see that the severity associated with a particular vulnerability has changed. Code Risk Analyzer will determine the optimal severity based on a computation of all the sources of vulnerabilities.