diff --git a/cli/command-reference/roxctl-image.adoc b/cli/command-reference/roxctl-image.adoc index 759df73440cd..666db346af34 100644 --- a/cli/command-reference/roxctl-image.adoc +++ b/cli/command-reference/roxctl-image.adoc @@ -6,37 +6,17 @@ include::modules/common-attributes.adoc[] toc::[] -Commands that you can run on a specific image. +[role="_abstract"] +Use the `roxctl image` command to run operations on container images, including scanning for vulnerabilities, checking for policy violations, and generating Software Bill of Materials (SBOM) reports. This reference covers the command syntax, available subcommands, and configuration options. -.Usage -[source,terminal] ----- -$ roxctl image [command] [flags] ----- +//roxctl image overview +include::modules/roxctl-image-overview.adoc[leveloffset=+1] -.Available commands -[cols="2,2",options="header"] -|=== -|Command |Description +include::modules/roxctl-image-usage.adoc[leveloffset=+2] -|`check` -|Check images for build time policy violations, and report them. +include::modules/roxctl-image-available-commands.adoc[leveloffset=+2] -|`sbom` -|Generate an SPDX 2.3 SBOM from an image scan. You must have write permissions for the `Image` resource. - -|`scan` -|Scan the specified image, and return the scan results. -|=== - - -.Options -[cols="2,2",options="header"] -|=== - -|`-t`, `--timeout duration` -|Set the timeout for API requests representing the maximum duration of a request. The default value is `10m0s`. -|=== +include::modules/roxctl-image-options.adoc[leveloffset=+2] //Options inherited from the parent command :commandname: roxctl image @@ -46,8 +26,20 @@ include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] //roxctl image sbom include::modules/roxctl-image-sbom.adoc[leveloffset=+1] +include::modules/roxctl-image-sbom-usage.adoc[leveloffset=+2] + +include::modules/roxctl-image-sbom-options.adoc[leveloffset=+2] + //roxctl image scan include::modules/roxctl-image-scan.adoc[leveloffset=+1] +include::modules/roxctl-image-scan-usage.adoc[leveloffset=+2] + +include::modules/roxctl-image-scan-options.adoc[leveloffset=+2] + //roxctl image check -include::modules/roxctl-image-check.adoc[leveloffset=+1] \ No newline at end of file +include::modules/roxctl-image-check.adoc[leveloffset=+1] + +include::modules/roxctl-image-check-usage.adoc[leveloffset=+2] + +include::modules/roxctl-image-check-options.adoc[leveloffset=+2] \ No newline at end of file diff --git a/modules/options-inherited-from-the-parent-command.adoc b/modules/options-inherited-from-the-parent-command.adoc index ac52a7e2a577..8d9a300bd144 100644 --- a/modules/options-inherited-from-the-parent-command.adoc +++ b/modules/options-inherited-from-the-parent-command.adoc @@ -25,6 +25,7 @@ endif::[] [id="options-inherited-from-the-parent-command_{context}"] = {commandname} command options inherited from the parent command +[role="_abstract"] The `{commandname}` command supports the following options inherited from the parent `roxctl` command: [cols="2,2",options="header"] diff --git a/modules/roxctl-image-available-commands.adoc b/modules/roxctl-image-available-commands.adoc new file mode 100644 index 000000000000..524dda86cd88 --- /dev/null +++ b/modules/roxctl-image-available-commands.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * cli/command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-available-commands_{context}"] += Available commands + +[role="_abstract"] +Available commands for the `roxctl image` command. + +[cols="2,2",options="header"] +|=== +|Command |Description + +|`check` +|Check images for build time policy violations, and report them. + +|`sbom` +|Generate an SPDX 2.3 SBOM from an image scan. You must have write permissions for the `Image` resource. + +|`scan` +|Scan the specified image, and return the scan results. +|=== diff --git a/modules/roxctl-image-check-options.adoc b/modules/roxctl-image-check-options.adoc new file mode 100644 index 000000000000..ef3d914d5270 --- /dev/null +++ b/modules/roxctl-image-check-options.adoc @@ -0,0 +1,64 @@ +// Module included in the following assemblies: +// +// * cli/command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-check-options_{context}"] += Options + +[role="_abstract"] +Options for the `roxctl image check` command. + +.Options +[cols="5,4",options="header"] +|=== +|Option |Description + +|`-c`, `--categories strings` +|List of the policy categories that you want to run. By default, the command uses all policy categories. + +|`--cluster string` +|Define the cluster name or ID that you want to use as the context for evaluation. + +|`--compact-output` +|Print JSON output in a compact format. The default value is `false`. + +|`-f`, `--force` +|Bypass the Central cache for the image and force a new pull from the Scanner. The default value is `false`. + +|`--headers strings` +|Define headers to print in a tabular output. The default values include `POLICY`, `SEVERITY`, `BREAKS BUILD`, `DESCRIPTION`, `VIOLATION`, and `REMEDIATION`. + +|`--headers-as-comments` +|Print headers as comments in a CSV tabular output. The default value is `false`. + +|`-i`, `--image string` +|Specify the image name and reference. For example, `nginx:latest` or `nginx@sha256:...)`. + +|`--junit-suite-name string` +|Set the name of the JUnit test suite. Default value is `image-check`. + +|`--merge-output` +|Merge duplicate cells in a tabular output. The default value is `false`. + +|`--namespace` +|Specify a namespace on the secured cluster from which to read context information, specifically pull secrets to access the image registry, when delegating image scans. + +|`--no-header` +|Do not print headers for a tabular output. The default value is `false`. + +|`-o`, `--output string` +|Choose the output format. Output formats include `junit`, `sarif`, `table`, `csv`, and `json`. The default value is `table`. + +|`-r`, `--retries int` +|Set the number of retries before exiting as an error. The default value is `3`. + +|`-d`, `--retry-delay int` +|Set the time to wait between retries in seconds. The default value is `3`. + +|`--row-jsonpath-expressions string` +|Create a row from the JSON object by using JSON path expression. For more details, run the `roxctl image check --help` command. + +|`--send-notifications` +|Define whether you want to send notifications if violations occur. The default value is `false`. +|=== diff --git a/modules/roxctl-image-check-usage.adoc b/modules/roxctl-image-check-usage.adoc new file mode 100644 index 000000000000..6a8834d9af72 --- /dev/null +++ b/modules/roxctl-image-check-usage.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * cli/command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-check-usage_{context}"] += roxctl image check usage + +[role="_abstract"] +Usage syntax for the `roxctl image check` command. + +.Usage +[source,terminal] +---- +$ roxctl image check [flags] +---- diff --git a/modules/roxctl-image-check.adoc b/modules/roxctl-image-check.adoc index c03907c02967..10804af7ed34 100644 --- a/modules/roxctl-image-check.adoc +++ b/modules/roxctl-image-check.adoc @@ -1,69 +1,10 @@ // Module included in the following assemblies: // -// * command-reference/roxctl-image.adoc +// * cli/command-reference/roxctl-image.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="roxctl-image-check_{context}"] = roxctl image check -Check images for build time policy violations, and report them. - -.Usage -[source,terminal] ----- -$ roxctl image check [flags] ----- - -.Options -[cols="5,4",options="header"] -|=== -|Option |Description - -|`-c`, `--categories strings` -|List of the policy categories that you want to execute. By default, all the policy categories are used. - -|`--cluster string` -|Define the cluster name or ID that you want to use as the context for evaluation. - -|`--compact-output` -|Print JSON output in a compact format. The default value is `false`. - -|`-f`, `--force` -|Bypass the Central cache for the image and force a new pull from the Scanner. The default value is `false`. - -|`--headers strings` -|Define headers to print in a tabular output. The default values include `POLICY`, `SEVERITY`, `BREAKS BUILD`, `DESCRIPTION`, `VIOLATION`, and `REMEDIATION`. - -|`--headers-as-comments` -|Print headers as comments in a CSV tabular output. The default value is `false`. - -|`-i`, `--image string` -|Specify the image name and reference. For example, `nginx:latest` or `nginx@sha256:...)`. - -|`--junit-suite-name string` -|Set the name of the JUnit test suite. Default value is `image-check`. - -|`--merge-output` -|Merge duplicate cells in a tabular output. The default value is `false`. - -|`--namespace` -|Specify a namespace on the secured cluster from which to read context information, specifically pull secrets to access the image registry, when delegating image scans. - -|`--no-header` -|Do not print headers for a tabular output. The default value is `false`. - -|`-o`, `--output string` -|Choose the output format. Output formats include `junit`, `sarif`, `table`, `csv`, and `json`. The default value is `table`. - -|`-r`, `--retries int` -|Set the number of retries before exiting as an error. The default value is `3`. - -|`-d`, `--retry-delay int` -|Set the time to wait between retries in seconds. The default value is `3`. - -|`--row-jsonpath-expressions string` -|Create a row from the JSON object by using JSON path expression. For more details, run the `roxctl image check --help` command. - -|`--send-notifications` -|Define whether you want to send notifications in the event of violations. The default value is `false`. -|=== \ No newline at end of file +[role="_abstract"] +Check images for build time policy violations, and report them. \ No newline at end of file diff --git a/modules/roxctl-image-options.adoc b/modules/roxctl-image-options.adoc new file mode 100644 index 000000000000..9f99837495bb --- /dev/null +++ b/modules/roxctl-image-options.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * cli/command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-options_{context}"] += Options + +[role="_abstract"] +Options for the `roxctl image` command. + +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-t`, `--timeout duration` +|Set the timeout for API requests representing the maximum duration of a request. The default value is `10m0s`. +|=== diff --git a/modules/roxctl-image-overview.adoc b/modules/roxctl-image-overview.adoc new file mode 100644 index 000000000000..e2647b5473a5 --- /dev/null +++ b/modules/roxctl-image-overview.adoc @@ -0,0 +1,10 @@ +// Module included in the following assemblies: +// +// * cli/command-reference/roxctl-image.adoc + +:_mod-docs-content-type: CONCEPT +[id="roxctl-image-overview_{context}"] += roxctl image + +[role="_abstract"] +Commands that you can run on a specific image. diff --git a/modules/roxctl-image-sbom-options.adoc b/modules/roxctl-image-sbom-options.adoc new file mode 100644 index 000000000000..f78fb47baeb2 --- /dev/null +++ b/modules/roxctl-image-sbom-options.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * cli/command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-sbom-options_{context}"] += Options + +[role="_abstract"] +Options for the `roxctl image sbom` command. + +.Options +[cols="5,4",options="header"] +|=== +|Option |Description + +|`--cluster` string +|Cluster name or ID that you want to delegate the image scan to. + +|`--namespace` string +|Namespace on the secured cluster from which to read context information when delegating image scans, specifically pull secrets for accessing the image registry. + +|`-f, --force` +|Bypass Central's cache for the image and force a new pull from the scanner. The default is `false`. + +|`-d, --retry-delay integer` +|Sets the time to wait between retries in seconds. The default is 3. + +|`-i, --image string` +|Image name and reference, for example, `nginx:latest` or `nginx@sha256:...`. + +|`-r, --retries integer` +|Sets the number of times that Scanner V4 should retry before exiting with an error. The default is 3. +|=== diff --git a/modules/roxctl-image-sbom-usage.adoc b/modules/roxctl-image-sbom-usage.adoc new file mode 100644 index 000000000000..d1a815b5a33a --- /dev/null +++ b/modules/roxctl-image-sbom-usage.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * cli/command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-sbom-usage_{context}"] += roxctl image sbom usage + +[role="_abstract"] +Usage syntax for the `roxctl image sbom` command. + +.Usage +[source,terminal] +---- +$ roxctl image sbom [flags] +---- diff --git a/modules/roxctl-image-sbom.adoc b/modules/roxctl-image-sbom.adoc index b7fd6b838377..1c05a8358012 100644 --- a/modules/roxctl-image-sbom.adoc +++ b/modules/roxctl-image-sbom.adoc @@ -1,39 +1,10 @@ // Module included in the following assemblies: // -// * command-reference/roxctl-image.adoc +// * cli/command-reference/roxctl-image.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="roxctl-image-sbom_{context}"] = roxctl image sbom -Generate an SPDX 2.3 SBOM from an image scan. You must have write permissions for the `Image` resource. - -.Usage -[source,terminal] ----- -$ roxctl image sbom [flags] ----- - -.Options -[cols="5,4",options="header"] -|=== -|Option |Description - -|`--cluster` string -|Cluster name or ID that you want to delegate the image scan to. - -|`--namespace` string -|Namespace on the secured cluster from which to read context information when delegating image scans, specifically pull secrets for accessing the image registry. - -|`-f, --force` -|Bypass Central's cache for the image and force a new pull from the scanner. The default is `false`. - -|`-d, --retry-delay integer` -|Sets the time to wait between retries in seconds. The default is 3. - -|`-i, --image string` -|Image name and reference, for example, `nginx:latest` or `nginx@sha256:...`. - -|`-r, --retries integer` -|Sets the number of times that Scanner V4 should retry before exiting with an error. The default is 3. -|=== \ No newline at end of file +[role="_abstract"] +Generate an SPDX 2.3 SBOM from an image scan. You must have write permissions for the `Image` resource. \ No newline at end of file diff --git a/modules/roxctl-image-scan-options.adoc b/modules/roxctl-image-scan-options.adoc new file mode 100644 index 000000000000..af7636c0d6df --- /dev/null +++ b/modules/roxctl-image-scan-options.adoc @@ -0,0 +1,65 @@ +// Module included in the following assemblies: +// +// * cli/command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-scan-options_{context}"] += Options + +[role="_abstract"] +Options for the `roxctl image scan` command. + +.Options +[cols="5,4",options="header"] +|=== +|Option |Description + +|`--cluster string` +|Specify the cluster name or ID to which you want to delegate the image scan. + +|`--compact-output` +|Print JSON output in a compact format. The default value is `false`. + +|`--fail` +|Fail if the scan finds vulnerabilities. The default value is `false`. + +|`-f`, `--force` +|Ignore Central's cache and force a fresh re-pull from Scanner. The default value is `false`. + +|`--headers strings` +|Specify the headers to print in a tabular output. The default values include `COMPONENT`, +`VERSION`,`CVE`,`SEVERITY`, and `LINK`. + +|`--headers-as-comments` +|Print headers as comments in a CSV tabular output. The default value is `false`. + +|`-i`, `--image string` +|Specify the image name and reference to scan. For example, `nginx:latest` or `nginx@sha256:...`. + +|`-a`, `--include-snoozed` +|Include snoozed and unsnoozed CVEs in the scan results. The default value is `false`. + +|`--merge-output` +|Merge duplicate cells in a tabular output. The default value is `true`. + +|`--namespace` +|Specify a namespace on the secured cluster from which to read context information, specifically pull secrets to access the image registry, when delegating image scans. + +|`--no-header` +|Do not print headers for a tabular output. The default value is `false`. + +|`-o`, `--output string` +|Specify the output format. Output formats include `table`, `csv`, `json`, and `sarif`. + +|`-r`, `--retries int` +|Specify the number of retries before exiting as an error. The default value is `3`. + +|`-d`, `--retry-delay int` +|Set the time to wait between retries in seconds. The default value is `3`. + +|`--row-jsonpath-expressions string` +|Specify JSON path expressions to create a row from the JSON object. For more details, run the `roxctl image scan --help` command. + +|`--severity strings` +|List of severities to include in the output. Use this to filter for specific severities. The default values include `LOW`, `MODERATE`, `IMPORTANT`, and `CRITICAL`. +|=== diff --git a/modules/roxctl-image-scan-usage.adoc b/modules/roxctl-image-scan-usage.adoc new file mode 100644 index 000000000000..71875a532b13 --- /dev/null +++ b/modules/roxctl-image-scan-usage.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * cli/command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-scan-usage_{context}"] += roxctl image scan usage + +[role="_abstract"] +Usage syntax for the `roxctl image scan` command. + +.Usage +[source,terminal] +---- +$ roxctl image scan [flags] +---- diff --git a/modules/roxctl-image-scan.adoc b/modules/roxctl-image-scan.adoc index ab1cabe5c595..13b8d425ddb0 100644 --- a/modules/roxctl-image-scan.adoc +++ b/modules/roxctl-image-scan.adoc @@ -1,70 +1,10 @@ // Module included in the following assemblies: // -// * command-reference/roxctl-image.adoc +// * cli/command-reference/roxctl-image.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="roxctl-image-scan_{context}"] = roxctl image scan -Scan the specified image, and return the scan results. - -.Usage -[source,terminal] ----- -$ roxctl image scan [flags] ----- - -.Options -[cols="5,4",options="header"] -|=== -|Option |Description - -|`--cluster string` -|Specify the cluster name or ID to which you want to delegate the image scan. - -|`--compact-output` -|Print JSON output in a compact format. The default value is `false`. - -|`--fail` -|Fail if vulnerabilities have been found. The default value is `false`. - -|`-f`, `--force` -|Ignore Central's cache and force a fresh re-pull from Scanner. The default value is `false`. - -|`--headers strings` -|Specify the headers to print in a tabular output. The default values include `COMPONENT`, -`VERSION`,`CVE`,`SEVERITY`, and `LINK`. - -|`--headers-as-comments` -|Print headers as comments in a CSV tabular output. The default value is `false`. - -|`-i`, `--image string` -|Specify the image name and reference to scan. For example, `nginx:latest` or `nginx@sha256:...`. - -|`-a`, `--include-snoozed` -|Include snoozed and unsnoozed CVEs in the scan results. The default value is `false`. - -|`--merge-output` -|Merge duplicate cells in a tabular output. The default value is `true`. - -|`--namespace` -|Specify a namespace on the secured cluster from which to read context information, specifically pull secrets to access the image registry, when delegating image scans. - -|`--no-header` -|Do not print headers for a tabular output. The default value is `false`. - -|`-o`, `--output string` -|Specify the output format. Output formats include `table`, `csv`, `json`, and `sarif`. - -|`-r`, `--retries int` -|Specify the number of retries before exiting as an error. The default value is `3`. - -|`-d`, `--retry-delay int` -|Set the time to wait between retries in seconds. The default value is `3`. - -|`--row-jsonpath-expressions string` -|Specify JSON path expressions to create a row from the JSON object. For more details, run the `roxctl image scan --help` command. - -|`--severity strings` -|List of severities to include in the output. Use this to filter for specific severities. The default values include `LOW`, `MODERATE`, `IMPORTANT`, and `CRITICAL`. -|=== \ No newline at end of file +[role="_abstract"] +Scan the specified image, and return the scan results. \ No newline at end of file diff --git a/modules/roxctl-image-usage.adoc b/modules/roxctl-image-usage.adoc new file mode 100644 index 000000000000..fd4aab62a77e --- /dev/null +++ b/modules/roxctl-image-usage.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * cli/command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-usage_{context}"] += roxctl image usage + +[role="_abstract"] +Usage syntax for the `roxctl image` command. + +.Usage +[source,terminal] +---- +$ roxctl image [command] [flags] +----