Skip to content

ROX-27689: provide example for non-delegated roxctl image scan #87112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: rhacs-docs-main
Choose a base branch
from
Open

ROX-27689: provide example for non-delegated roxctl image scan #87112

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 59 additions & 3 deletions cli/image-scanning-by-using-the-roxctl-cli.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,58 @@ toc::[]
[role="_abstract"]
You can scan images stored in image registries, including cluster local registries such as the {ocp} integrated image registry by using the `roxctl` CLI.

[id="scanning-images-by-using-a-remote-cluster_{context}"]
== Scanning images by using the Central cluster
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure how to best message this, but IF the delegated scanning config has an entry matching the image being scanned, it will be sent to a secured cluster / not scanned by Central.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
== Scanning images by using the Central cluster
== Scanning images by using StackRox Scanner or Scanner V4 installed in the Central cluster


The following outlines the procedure for scanning images via the StackRox Scanner or Scanner V4 installed in the Central cluster.
Copy link
Contributor

@agantony agantony Jan 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The following outlines the procedure for scanning images via the StackRox Scanner or Scanner V4 installed in the Central cluster.
To scan the images, you can use StackRox Scanner or Scanner V4 installed in the Central cluster.


.Procedure

* Run the following command to scan the specified image:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Run the following command to scan the specified image:
* To scan the specified image, run the following command:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#procedure-step-that-introduces-a-command

+
[source,terminal,subs="+quotes"]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[source,terminal,subs="+quotes"]
[source,terminal]

----
$ roxctl image scan \
--image=_<image_registry>_/_<image_name>_[_<reference>_] \// <1>
[flags] <2>
Comment on lines +23 to +25
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
$ roxctl image scan \
--image=_<image_registry>_/_<image_name>_[_<reference>_] \// <1>
[flags] <2>
$ roxctl image scan \
--image=<image_registry>/<image_name>[reference] \// <1>
[flags] <2>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#command-syntax-for-replaceable-values

----
+
--
<1> For `<image_registry>`, specify the registry where the image is located, for example, `registry.redhat.io`.
For `<image_name>`, specify the name of the image you want to scan, for example, `default/image`.
<reference> may be:
* blank
* a tag preceded by a colon, for example, `:latest`
* a digest preceded by an at sign, for example, `@sha256:710ecc84318c54c9d1e08fe89d03e74cc09350909e5b12e5d07ac6941fd02b27`
Comment on lines +29 to +34
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<1> For `<image_registry>`, specify the registry where the image is located, for example, `registry.redhat.io`.
For `<image_name>`, specify the name of the image you want to scan, for example, `default/image`.
<reference> may be:
* blank
* a tag preceded by a colon, for example, `:latest`
* a digest preceded by an at sign, for example, `@sha256:710ecc84318c54c9d1e08fe89d03e74cc09350909e5b12e5d07ac6941fd02b27`
<1> For `<image_registry>`, specify the registry where the image is located, for example, `registry.redhat.io`.
+
For `<image_name>`, specify the name of the image you want to scan, for example, `default/image`.
+
Optional: For `[reference]`, choose the appropriate method to specify the version or identifier of the image.
+
* To scan the default image, leave it blank.
* To specify a tag, precede it with a colon (:). For example,`:latest`.
* To specify a digest, precede it with an at sign (@). For example, `@sha256:710ecc84318xxxxxx`.

<2> Optional: For `[flags]`, you can specify parameters to modify the behavior of the command.
+
For more information about optional parameters, see xref:../cli/image-scanning-by-using-the-roxctl-cli.adoc#roxctl-image-scan-command-options_image-scanning-by-using-the-roxctl-cli[roxctl image scan command options].
--
+
.Example output
+
[source,text,subs=attributes+]
----
{
"Id": "sha256:3f439d7d71adb0a0c8e05257c091236ab00c6343bc44388d091450ff58664bf9", <1>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"Id": "sha256:3f439d7d71adb0a0c8e05257c091236ab00c6343bc44388d091450ff58664bf9", <1>
"Id": "sha256:3f439d7d71adb0axxxxxx", <1>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"Id": "sha256:3f439d7d71adb0a0c8e05257c091236ab00c6343bc44388d091450ff58664bf9", <1>
"Id": "sha256:3f439d7d71adb0axxxxxx", <1>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Due to security reasons

"name": { <2>
"registry": "registry.redhat.io", <3>
"remote": "default/image", <4>
"tag": "latest", <5>
"fullName": "registry.redhat.iodefault/image:latest" <6>
},
[...]
----
+
--
<1> A unique identifier for the image that serves as a fingerprint for the image. It helps ensure the integrity and authenticity of the image.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<1> A unique identifier for the image that serves as a fingerprint for the image. It helps ensure the integrity and authenticity of the image.
<1> A unique identifier for the image that serves as a fingerprint for the image.

<2> Contains specific details about the image.
<3> The location of the image registry where the image is stored.
<4> The remote path to the image.
<5> The version or tag associated with this image.
<6> The complete name of the image, combining the registry, remote path, and tag.
--

[id="scanning-images-by-using-a-remote-cluster_{context}"]
== Scanning images by using a remote cluster

Expand All @@ -26,14 +78,18 @@ For more information about how to configure delegated image scanning, see xref:.
[source,terminal,subs="+quotes"]
----
$ roxctl image scan \
--image=_<image_registry>_/_<image_name>_ \// <1>
--image=_<image_registry>_/_<image_name>_[_<reference>_] \// <1>
--cluster=_<cluster_detail>_ \// <2>
[flags] <3>
----
+
--
<1> For `<image_registry>`, specify the registry where the image is located, for example, `image-registry.openshift-image-registry.svc:5000/`.
For `<image_name>`, specify the name of the image you want to scan, for example, `default/image-stream:latest`.
<1> For `<image_registry>`, specify the registry where the image is located, for example, ``image-registry.openshift-image-registry.svc:5000`.
For `<image_name>`, specify the name of the image you want to scan, for example, `default/image-stream`.
<reference> may be:
* blank
* a tag preceded by a colon, for example, `:latest`
* a digest preceded by an at sign, for example, `@sha256:710ecc84318c54c9d1e08fe89d03e74cc09350909e5b12e5d07ac6941fd02b27`
Copy link

@dcaravel dcaravel Jan 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would adding the actual characters render correctly / be more clear here? For example:

Suggested change
* a digest preceded by an at sign, for example, `@sha256:710ecc84318c54c9d1e08fe89d03e74cc09350909e5b12e5d07ac6941fd02b27`
* a digest preceded by '@', for example, `@sha256:710ecc84318c54c9d1e08fe89d03e74cc09350909e5b12e5d07ac6941fd02b27`

Or perhaps stating that the reference must be valid per... (and link the spec?)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should shorten the SHA id for security reasons?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW - the SHAs (digests) are not secrets in the image context, from a risk perspective it's generally recommended to reference images by digest instead of the tags because tags change, digests do not. Are other ways to address this 'tag change' risk, but a bit off-topic for this PR.

To be a valid sha256 the length has to be exactly 64 'hex' characters (each character represent 4 bits, for a total of 256 bits).

<2> For `<cluster_detail>`, specify the name or ID of the remote cluster. For example, specify the name `remote`.
<3> Optional: For `[flags]`, you can specify parameters to modify the behavior of the command.
+
Expand Down