--- name: cli-cra-cli title: Code Risk Analyzer plug-in for IBM Cloud description: The IBM Cloud® command-line interface (CLI) provides commands for code risk analysis. You can use the IBM Cloud CLI to analyze your code for vulnerabilities and compliance with certain rules. Code Risk Analyzer is available in all IBM Cloud regions in which toolchains are supported. last-updated: 2026-05-01 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/cli?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Code Risk Analyzer plug-in for IBM Cloud {: #cra-cli-plugin} Code Risk Analyzer will be discontinued in all regions on 12 February 2027. However, if a region has no active Code Risk Analyzer usage, the service in that region may be discontinued earlier. [Learn more](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-faq_region_feature_consolidation&format=markdown) {: important} The IBM Cloud® command-line interface (CLI) provides commands for code risk analysis. You can use the IBM Cloud CLI to analyze your code for vulnerabilities and compliance with certain rules. Code Risk Analyzer is available in all IBM Cloud regions in which toolchains are supported. {: shortdesc} Use the CLI to complete the following tasks: * Generate a bill of materials (BOM) that lists the dependencies and available license information of all third-party OS packages and application packages. You can also generate this output in CycloneDX-specific format. * Discover vulnerabilities in packages that are listed in the BOM. You can also view the generated report in CycloneDX-specific format, or use vulnerability auto-remediation for Node.js, Maven, or Gradle (Groovy) applications. * Analyze Kubernetes files for compliance with certain rules. Beginning in January 2024, Code Risk Analyzer consumes vulnerability data that is provided by the [Clair open source project](https://quay.github.io/clair/){: external} instead of data from the commercial company Snyk Limited. No specific action is required on your part as a result of this change. However, you might observe some differences in the particulars of the CVEs reported by Code Risk Analyzer. {: note} ## Supported content {: #cra-supported-content} Code Risk Analyzer supports the Java™, Node.js, Python, and Go languages. The following table lists and describes the content that Code Risk Analyzer supports. |Content |Description | |:----------|:------------------------------| |Java | The repo requires Maven or Gradle for build automation. Maven uses `pom.xml` file to calculate dependencies, and Gradle uses `build.gradle(.kts)` file. Code Risk Analyzer can automate remediation for both Maven and Gradle (Groovy). | |Node.js |`package-lock.json` file computes the dependencies. For Node.js, Code Risk analyzer can also automate remediation. Ensure that the installed npm version matches the project's npm version. | |Python |Dependencies are computed by using the `requirements.txt` and `pyproject.toml` files. | |Golang |Supports `go mod` and `go dep` dependency management. For `go mod`, the `go.sum` file must be in the repo. For `go dep`, the `Gopkg.lock` file must be in the repo. | | Dockerfiles |Files with the `Dockerfile` pattern in the repo are considered. For container images, the Debian, Red Hat Enterprise Linux®, Alpine, and Ubuntu Linux distros are supported. | | Kubernetes |Files that are suffixed with `.yaml` and `.yml` are considered. The `kind` value must be set to `Pod`, `ReplicaSet`, `ReplicationController`, `Deployment`, `Daemonset`, `Statefulset`, `Job`, `CronJob`, `NetworkPolicy`, or `Ingress`. | | Calico |Files that are suffixed with `.yaml` and `.yml` are considered. The `kind` value must be set to `NetworkPolicy`, `GlobalNetworkPolicy`, `Profile`, `NetworkSet`, `GlobalNetworkSet`, or `HostEndpoint`. | |Terraform |The Terraform plan file must be generated by using IBM Cloud as the Terraform provider. | {: caption="Supported content" caption-side="top"} Code Risk Analyzer examines source code and image dependencies in your repositories for vulnerabilities. The following table shows the sources of vulnerability information that Code Risk Analyzer consults for different kinds of dependencies. | Dependency | Supported versions | Source of security notices | |------------|--------------------|----------------------------| | Alpine image | All stable versions with vendor security support. | [Alpine SecDB database](https://secdb.alpinelinux.org/){: external}. | | Debian image | All stable versions with vendor security support. \n \n CVEs on binary packages that are associated with the Debian source package `linux`, such as `linux-libc-dev`, are not reported. Most of these binary packages are kernel and kernel modules, which are not run in container images. | [Debian Security Bug Tracker](https://security-tracker.debian.org/tracker/){: external}. | | GoogleContainerTools distroless image | All stable versions with vendor security support. | [GoogleContainerTools distroless](https://github.com/GoogleContainerTools/distroless){: external} | | Red Hat® Enterprise Linux® (RHEL) image | RHEL 6, RHEL/UBI 7, RHEL/UBI 8, and RHEL/UBI 9 | [Red Hat Security Data API](https://docs.redhat.com/en/documentation/red_hat_security_data_api/1.0/html-single/red_hat_security_data_api/index){: external}. | | Ubuntu image | All stable versions with vendor security support. | [Ubuntu CVE Tracker](https://launchpad.net/ubuntu-cve-tracker){: external}. | | Go, npm (JavaScript), Maven (Java), PyPI (Python), RubyGems (Ruby), and Packagist (PHP) | All stable versions with vendor security support. | [Open Source Vulnerability database](https://osv-vulnerabilities.storage.googleapis.com/){: external}. | {: caption="Supported dependencies that Code Risk Analyzer checks for vulnerabilities" caption-side="top"} ## Known issues with Code Risk Analyzer {: #cra-known-issues} Code Risk Analyzer cannot discover vulnerabilities on application packages that do not use a versioning scheme, such as `major.minor.patch`. For example, pre-release versions or versions that contain build metadata are not supported. ## Prerequisites {: #prerequisites} * Install the IBM Cloud CLI. See [Download IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-getting-started&format=markdown) for instructions. * Install the Code Risk Analyzer CLI plug-in by running the following command: ```sh ibmcloud plugin install cra ``` {: codeblock} * Make sure that you can access a toolchain in one of the supported regions. The toolchain is not required to have any tools. For more information about toolchains, see [Creating a toolchain from an app](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-toolchains_getting_started&interface=ui&format=markdown#creating_a_toolchain_from_an_app). * Specify the toolchain ID by setting the `TOOLCHAIN_ID` environment variable: ```sh export TOOLCHAIN_ID=e22195a5-11e3-44ba-9533-e7c18a3a61a7 ``` {: codeblock} * Log in to a specific region of IBM Cloud by running the following command, where `[region]` is the region where the toolchain was created. ```sh ibmcloud login -r [region] ``` {: codeblock} * Optionally, For enhanced control and security over your data when using CLI, you have the option of using private routes to IBM Cloud endpoints. You must first enable virtual routing and forwarding in your account, and then you can enable the use of IBM Cloud private service endpoints. For more information about setting up your account to support the private connectivity option, see [Enabling VRF and service endpoints](https://cloud.ibm.com/docs/account?topic=account-vrf-service-endpoint&interface=ui&format=markdown). Use the following command to log in to a private endpoint where `[region]` is the region where the toolchain was created. ```sh ibmcloud login -a private.cloud.ibm.com -r [region] ``` {: codeblock} ## CLI usage commands {: #CLI-usage-commands} You receive notifications on the command line when updates to the IBM Cloud CLI and plug-ins are available. Make sure that you keep your CLI current so that you can use the latest commands. You can view the current version of all of the installed plug-ins by running the `ibmcloud plugin list` command. {: tip} ### Code Risk Analyzer help {: #cra-help} The following command displays the list of Code Risk Analyzer commands: ```sh ibmcloud cra --help ``` {: codeblock} ### Code Risk Analyzer command help {: #cra-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. ```sh ibmcloud cra --help ``` {: codeblock} ## Bill of materials (BOM) {: #bom-generate-command} The `bom-generate` command accesses artifacts in the specified directory path and performs deep discovery to identify all of the dependencies, including transitive dependencies. The command also identifies the licenses that these dependencies are distributed under. A BOM is created that captures a snapshot of all of the dependencies. You can generate the BOM in the standard format or in CycloneDX's SBOM format. ```sh ibmcloud cra bom-generate ``` {: codeblock} ### BOM command requirements {: #bom-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-generate`command 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: ```sh export DOCKERBUILDFLAGS="--build-arg IAM_USER --build-arg API_KEY" ``` {: codeblock} ### BOM command options {: #bom-options} The following table lists the command options that you can use to generate a BOM with the `bom-generate` command. | Command options | Required or optional | Description | | -------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--path` | Required | The project directory path to scan. | | `-r`, `--report` | Required | The file name in which to store the BOM report. | | `-a`, `--asset-type` | Optional | The security checks to run (apps, image, os, all). By default, this option is set to `all`. The `apps` option is used to limit discovery to application packages. The `image` option is used to limit discovery to base images that are used in Dockerfiles. The `os` option is used to limit discovery to build stages in Dockerfiles only. You can specify multiple values by using a comma to delimit the values, such as `-a os,image,apps`. | | `-p`, `--prev-report` | Optional | Use the previous BOM report to speed up the command. For example, if a Dockerfile was not updated since the last report was generated, the command skips the discovery of packages from that Dockerfile. The same scenario applies to other manifest files such as the `package-lock.json` file. | | `-c`, `--dockerbuildcontext` | Optional | If specified, CRA uses the directory in the path parameter as the Docker build context during build stage scanning. | | `-o`, `--output` | Optional | Select the BOM report format. You can generate the format output in either Standard BOM format (`standard`) or CycloneDX's SBOM format (`cyclonedx`). The default value is `standard`. You can store both formats by inputting each format separated by a comma with no space. | | `-f`, `--dockerbuildflags` | Optional | Customize the Docker build command for build stage scanning. Instead of using this command-line flag, you can specify the value in an environment variable named `DOCKERBUILDFLAGS`. By default, this command option is set to `''`. If you use this option, make sure that it is the last flag that is provided to the command. | | `-d`, `--dockerfilepattern` | Optional | The pattern to identify the Dockerfile in the repo. | | `-g`, `--gradle.excludeconfigurations` | Optional | Exclude the Gradle configurations, for example: `runtimeClasspath,testCompileClasspath`. By default, this command option is set to `''`. | | `-l`, `--gradleprops` | Optional | Customize the Gradle command with properties for Gradle dependency scanning. | | | `-m`, `--maven.excludescopes` | Optional | Exclude the Maven scopes, for example: `test,compile`. Example: 'test,compile'. By default, this command option is set to `''`. | | `-n`, `--nodejs.createpackagelock` | Optional | Enable the task to build the package-lock.json file for node.js projects. | | `--region` | Optional | The `ibmcloud` region where the toolchain is located. | | `--toolchainid` | Optional | The target toolchain ID to use. | | `-v`, `--verbose` | Optional | Enable verbose log messages. | {: caption="Command options for generating a BOM" caption-side="top"} ### Ignoring files {: #ignore-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](https://git-scm.com/docs/gitignore){: external}. Similar to a `.gitignore` file, the `.fileignore` file can include comments, directories to ignore, files to ignore, and other [patterns](https://git-scm.com/docs/gitignore#_pattern_format){: external}. The following example `.fileignore` file shows how to exclude bash scripts, node_modules, and the Dockerfile. ```text # 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 ``` {: screen} ### Setting Multiple Docker Build Contexts {: #docker-build-context} 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: ```json { "Dockerfile": "./", "path/to/different/Dockerfile": "./another/Path" } ``` {: codeblock} ### Example {: #bom-example} The following code snippets show how to use the `bom-generate` command: ```sh 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] ``` {: codeblock} ```sh ibmcloud cra bom --path . --report bomreport.json ``` {: codeblock} ## Vulnerability scan {: #vulnerability-command} The `vulnerability-scan` command expects a BOM in `standard` format as input and detects vulnerabilities in application packages and OS packages that are listed in the BOM. Based on rich threat intelligence harvested from multiple sources of Common Vulnerabilities and Exposures (CVEs), targeted fix recommendations are provided. Code Risk Analyzer can also perform auto-remediation on vulnerable packages for Node.js based applications only. You can also generate this report in the standard format or in CycloneDX's Vulnerability Exploitability Exchange (VEX) format. ```sh ibmcloud cra vulnerability-scan ``` {: codeblock} ### Vulnerability scan command options {: #vulnerability-options} The following table lists the options for using the `vulnerability-scan` command. | Command options | Required or optional | Description | | -------------------- | -------------------- | -------------------------------------------------------------------------- | | `-b`, `--bom` | Required | The file path of the BOM that was generated by using the `bom-generate` command. This BOM must be in `standard` format. | | `-a`, `--autofix` | Optional | Fixes specific types of app vulnerabilities. This option is available only for Node.js, Maven, and Gradle apps. | | `-f`, `--commentfile` | Optional | Specifies the file where the markdown report is created. This command is available only with `autofix`. | | `-c`, `--cveignore` | Optional | The file path of the CVE Ignore file that contains the list of CVEs to ignore. | | `-e`, `--excludedev` | Optional | Specifies that you do not want the command to report CVEs for development dependencies. | | `--force` | Optional | Forces an update for top-level node packages, even when the major version is different. This command is available only with `autofix`. | | `--include-nofix` | Optional | Include or exclude the reporting of CVEs that do not have known remediations. By default, this option is set to `app`. The `app` option is used to include only app package CVEs with no fixes. The `os` option is used to include only OS package CVEs with no fixes. The `all` option is used to include both app and OS package CVEs with no fixes. The `none` option is used to exclude both app and OS package CVEs with no fixes. | | `--path` | Required if `--autofix` enabled | The project directory path to scan. This command is available only with `autofix`. | | `--region` | Optional | The `ibmcloud` region for the toolchain. | | `-r`, `--report` | Optional | The path to the generated report. | | `-o`, `--output` | Optional | Selects the CVE report format. You can generate the format output in either Standard CVE format (`standard`) or CycloneDX's VEX format (`cyclonedx`). The default value is `standard`. | | `-s`, `--strict` | Optional | Results in command failure (exit status 2) when vulnerabilities are found. | | `--toolchainid` | Optional | The ID of the target toolchain. | {: caption="Command options for performing a vulnerability scan" caption-side="top"} ### Ignoring vulnerabilities {: #cra-omit-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: ```json [ { "cve": "string", "alwaysOmit": "bool", "untilRemediationAvailable": "bool", "expiration": "string" } ] ``` {: codeblock} 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: ```json [ { "cve": "CVE-2021-27290", "alwaysOmit": true }, { "cve": "CVE-2020-8244", "untilRemediationAvailable": true, } ] ``` {: codeblock} ### Example {: #vulnerability-example} The following code snippets show how to use the `vulnerability-scan` command: ```sh ibmcloud cra vulnerability-scan --bom BOM [--cveignore CVEIGNORE] [--report REPORT] [--excludedev] [--include-nofix app,os,all,none] [--region REGION] [--strict] [--toolchainid TOOLCHAINID] [--output OUTPUTFILE] ``` {: codeblock} ```sh ibmcloud cra cve --bom ./bom-file.json --cveignore ./cveignore-example.json --report ./output-vulnerability-report.json --excludedev --include-nofix all --strict ``` {: codeblock} ## Deployment {: #deployment-command} The `deployment-analyze` command runs configuration checks on Kubernetes deployment manifests. ```sh ibmcloud cra deployment-analyze ``` {: codeblock} This command provides prescriptive guidance for establishing a secure configuration posture for Docker containers. The Code Risk Analyzer uses these security configurations as a point of reference and identifies security controls to check in deployment artifacts, such as `.yaml` files, for Kubernetes applications. This command also provides risk assessments for each control failure. The following table lists the controls that you can implement within DevSecOps, as identified from CIS Docker 1.13.0. More controls are added based on open source references of the [Kubernetes Common Configuration Scoring System (KCCSS)](https://github.com/octarinesec/kccss){: external}. |ID | Rule | Risk | |---------|---------|:----------:| | 5.3| Ensure that containers do not have the `CAP_SYS_ADMIN` capability. | High| | 5.3| Ensure that containers do not have the `CAP_NET_RAW` capability. | High| | 5.4| Ensure that privileged containers are not used. | High| | 5.5| Ensure that sensitive host system directories are not mounted on containers. | Medium| | 5.7| Ensure that privileged ports are not mapped within containers. | Low| | 5.9| Ensure that the host's network namespace is not shared. | Medium| | 5.10| Ensure that the memory usage for the container is limited. | Medium| | 5.11| Ensure that the appropriate CPU priority is set on the container. | Medium| | 5.12| Ensure that the container's root file system is mounted as read-only. | Medium| | 5.15| Ensure that the host's process namespace is not shared. | Medium| | 5.16| Ensure that the host's IPC namespace is not shared. | Medium| | 5.31| Ensure that the Docker socket is not mounted inside any containers. | High| | -| Ensure that containers do not allow unsafe allocation of CPU resources. | Medium| | -| Ensure that containers do not allow privilege escalation. | Medium| | -| Ensure that containers do not expose unsafe parts of `/proc`. | Medium| | -| Ensure that containers are not exposed through a shared host port. | Medium| {: caption="Security controls" caption-side="top"} ### Deployment command options {: #deployment-options} The following table lists the command options that you can use for the `deployment-analyze` command. | Command options | Required or optional | Description | | -------------------- | -------------------- | ----------------------------------------------------------------------------------- | | `--path` | Required | The project directory path to scan. | | `-r`, `--report` | Required | The file name in which to create the report. | | `-f`, `--fileignore` | Optional | The file path of the `.fileignore` file. | | `-s`, `--strict` | Optional | The results of the command failure (exit status 2) when deployment risks are found. | {: caption="Command options for deployment analysis." caption-side="top"} ### Example {: #deployment-example} The following code snippets show how to use the `deployment-analyze` command: ```sh ibmcloud cra deployment-analyze --path PATH --report REPORT [--fileignore FILE_IGNORE] [--strict] ``` {: codeblock} ```sh ibmcloud cra depl --path ./sampleDir --report deployment-report.json --strict ``` {: codeblock} ## NetworkPolicy analysis {: #netpol-analyze-command} This is a beta feature that is available for evaluation and testing purposes. {: beta} The `netpol-analyze` command runs configuration checks on Kubernetes and Calico NetworkPolicy manifests. ```sh ibmcloud cra netpol-analyze ``` {: codeblock} This command checks the connectivity-configuration posture of a Kubernetes application against the [NIST SP 800-53 SC-7(5) control](https://csrc.nist.gov/projects/cprt/catalog#/cprt/framework/version/SP_800_53_5_1_0/home?element=SC-7){: external}. It verifies that the connectivity of every workload is controlled by at least one NetworkPolicy resource, and that nonsecure ports are blocked for both ingress and egress. The `netpol-analyze` command can also provide a connectivity report for the scanned application, showing all of the allowed connections between the application workloads. You can use this report as evidence for compliance, or to help debug connectivity issues. You can also use this command to provide lint results for the scanned network policies and then use these results to improve network-policy efficiency and readability. In some cases, lint results might also point to an error in the network policy definitions. ### NetworkPolicy analysis command options {: #netpol-analyze-options} The following table lists the command options that you can use for the `netpol-analyze` command. | Command options | Required or optional | Description | | --------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `--path` | Required | The project directory path to scan. | | `-r`, `--report` | Required | The file name in which to create the compliance report. | | `-c`, `--connectivity` | Optional | The file name in which to create the connectivity report. | | `-l`, `--lint` | Optional | The file name in which to create the lint report. | | `-s`, `--strict` | Optional | Results in command failure (exit status 2) when connectivity risks are found. | {: caption="Command options for performing network policy analysis" caption-side="top"} ### Example {: #netpol-analyze-example} The following sample code snippets show how you can use the `netpol-analyze` command: ```sh ibmcloud cra netpol-analyze --path PATH --report REPORT [--connectivity CONNFILE] [--lint LINTFILE] [--strict] ``` {: codeblock} ```sh ibmcloud cra np --path ./sampleDir --report netpol-report.json --strict ``` {: codeblock} ### Network config analyzer image {: #netpol-analyze-image} The `netpol-analyze` command runs as part of IBM's [Network Config Analyzer (NCA)](https://github.com/IBM/network-config-analyzer){: external}. Because this command runs NCA as a Docker image, you must install [Docker](https://www.docker.com/){: external} on your computer. The image URL for the network policy analyzer is `icr.io/continuous-delivery/cra/nca`. {: tip} 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. ## Using Code Risk Analyzer in Tekton pipelines {: #cra-tekton-pipelines} You can use the [`task-cra`](https://github.com/open-toolchain/tekton-catalog/tree/master/cra#cra){: external} task in Tekton pipelines. Use the [Tekton pipeline definition](https://github.com/open-toolchain/tekton-catalog/tree/master/cra/sample-v2){: external} when you create a pull request, a manual trigger, or issue a commit. You can also create your own Tekton tasks and run the Code Risk Analyzer from those tasks. ## Using Code Risk Analyzer in DevSecOps {: #cra-devsecops} You can use Code Risk Analyzer in [DevSecOps](https://cloud.ibm.com/docs/devsecops?topic=devsecops-devsecops_intro&format=markdown). The following table lists and describes the supported Code Risk Analyzer parameters for DevSecOps. For more information about the dependent utility commands that are required by the pipeline image to run the `bom-generate` command, see [BOM requirements](#bom-requirements). If commands are missing, you can use the `cra-custom-script-path` parameter to reference a script to install those commands. {: tip} |Name |Type |Description |Required or optional | |:----------|:------------------------------|:------------------|:----------| |artifactory-dockerconfigjson |SECRET |The base64-encoded Docker `config.json` file that stores credential information for Artifactory. |Optional | |baseimage-auth-user |text |The credentials for the base image of the application Dockerfile that is required by the Code Risk Analyzer scan. |Optional | |baseimage-auth-email |text |The credentials for the base image of the application Dockerfile that is required by the Code Risk Analyzer scan. |Optional | |baseimage-auth-host |text |The credentials for the base image of the application Dockerfile that is required by the Code Risk Analyzer scan. |Optional | |baseimage-auth-password |SECRET |The credentials for the base image of the application Dockerfile that is required by the Code Risk Analyzer scan. |Optional | |cra-cveignore-path |text |The path to the `cveignore` file that is relative to the root of the application repo. The default file path is `.cra/.cveignore`. |Optional | |cra-custom-script-path | text | The path to a custom script that runs before Code Risk Analyzer scanning. This script is sourced to provide the option to set `ENV` variables in the context of the Code Risk Analyzer BOM tool. | Optional | |cra-docker-buildflags |text |The custom Docker build command for build stage scanning. This parameter is empty by default. |Optional | |cra-docker-build-context | text |If specified, Code Risk Analyzer uses the directory in the path parameter as the Docker build context. |Optional | |cra-exclude-devdependencies |text |Specifies whether to exclude dev dependencies from scanning (`true` or `false`). The default value is `false`. |Optional | |cra-gradle-exclude-configs |text |Specifies which Gradle configurations to exclude dependencies from in scanning. For example, `runtimeClasspath,testCompileClasspath`. This parameter is empty by default. |Optional | |cra-maven-exclude-scopes |text |Specifies which Maven scopes to exclude dependencies from in scanning. For example, `test,compile`. This parameter is empty by default. |Optional | |cra-nodejs-create-package-lock |text |Enables Code Risk Analyzer discovery to build the `package-lock.json` file for node.js repos. This parameter is set to `false` by default. |Optional | |ibmcloud-api-key |SECRET |The IBM Cloud® API key that interacts with the `ibmcloud` CLI tool. |Required | |pipeline-dockerconfigjson |SECRET |The base64-encoded Docker `config.json` file that pulls images from a private registry. |Optional | |onepipeline-dockerconfigjson |SECRET |Deprecated. The base64-encoded Docker `config.json` file that pulls images from a private registry. |Optional | |pipeline-debug |select |The pipeline debug mode switch. |Optional | |opt-in-cra-auto-remediation |text |Enables Code Risk Analyzer to run the `cra auto remediation` command (`true` or `false`). The default value is `false`. This command is supported only in the Continuous Compliance Pipeline. |Optional | |opt-in-cra-auto-remediation-enabled-repos |text |Specifies the list of comma-separated repository names to enable for the `cra auto remediation` command. This parameter is considered only if `opt-in-cra-auto-remediation` is set to `true` and is supported only in the Continuous Compliance Pipeline. |Optional | |opt-in-cra-auto-remediation-force |text |Forces the `cra auto remediation` command to update the packages even if the major version is different from the current vulnerable package version (`true` or `false`). This parameter is considered only if `opt-in-cra-auto-remediation` is set to `true` and is supported only in the Continuous Compliance Pipeline. |Optional | {: caption="DevSecOps Code Risk Analyzer-based parameters" caption-side="top"} ### Example custom scripts for DevSecOps {: #devsecops-custom-script-examples} 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: ```bash #!/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) ``` {: codeblock} 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: ```bash #!/usr/bin/env bash if [[ "${PIPELINE_DEBUG:-0}" == 1 ]]; then trap env EXIT env | sort set -x fi python3 -m pip install --upgrade pip ``` {: codeblock} 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: ```bash #!/usr/bin/env bash if [[ "${PIPELINE_DEBUG:-0}" == 1 ]]; then trap env EXIT env | sort set -x fi ibmcloud cr login ``` {: codeblock} ### Debugging the Code Risk Analyzer in DevSecOps {: #debugging-cra-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)](#bom-generate-command). 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](#vulnerability-command). 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. ```text FAILED Error executing docker pull cmd: [docker pull us.icr.io/opentoolchain/ibmnode:14ubisecure] ``` {: screen} 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. ```text FAILED Error executing docker build cmd for stage-0: exit status 1 ``` {: codeblock} 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](#devsecops-custom-script-examples). ```text 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 ``` {: screen} 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. ## Removing stored Code Risk Analyzer data {: #cra-remove-data} The Code Risk Analyzer plug-in does not store any client data in its databases. However, earlier versions of Code Risk Analyzer Tekton tasks securely stored the results of vulnerability scans in its database. To request the removal of any client data that might be stored in the Code Risk Analyzer, contact [IBM Support](https://cloud.ibm.com/unifiedsupport/supportcenter){: external}. ## FAQs {: #faq} Get answers to frequently asked questions about using the Code Risk Analyzer CLI. ### How can I determine why the CLI failed? {: #faq-cli-failure} Before you call the Code Risk Analyzer CLI, set the `IBMCLOUD_TRACE` environment variable to true to turn on the debug log. ```sh export IBMCLOUD_TRACE=true ``` {: codeblock} 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. {: #faq-bom-failure} 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? {: #faq-bom-debug} * 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? {: #faq-clair-sbom} 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? {: #faq-clair-sev} 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.