This is the multi-page printable view of this section. Click here to print.
Image Analysis
1 - Analyzing Images via CTL
Introduction
In this section you will learn how to analyze images with Anchore Enterprise using AnchoreCTL in two different ways:
- Distributed Analysis: Content analysis by AnchoreCTL where it is run and importing the analysis to your Anchore deployment
- Centralized Analysis: The Anchore deployment downloads and analyzes the image content directly
Using AnchoreCTL for Centralized Analysis
Overview
This method of image analysis uses the Enterprise deployment itself to download and analyze the image content. You’ll use AnchoreCTL to make API requests to Anchore to tell it which image to analyze but the Enterprise deployment does the work. You can refer to the Image Analysis Process document in the concepts section to better understand how centralized analysis works in Anchore.
sequenceDiagram
participant A as AnchoreCTL
participant R as Registry
participant E as Anchore Deployment
A->>E: Request Image Analysis
E->>R: Get Image content
R-->>E: Image Content
E->>E: Analyze Image Content (Generate SBOM and secret scans etc) and store results
E->>E: Scan sbom for vulns and evaluate complianceUsage
The anchorectl image add command instructs the Anchore Enterprise deployment to pull (download) and analyze an image from a registry. Anchore Enterprise will attempt to retrieve metadata about the image from the Docker registry and if successful will initiate a pull of the image and queue the image for analysis. The command will output details about the image including the image digest, image ID, and full name of the image.
# anchorectl image add docker.io/library/nginx:latest
anchorectl image add docker.io/library/nginx:latest
✔ Added Image
Image:
status: not-analyzed (active)
tag: docker.io/library/nginx:latest
digest: sha256:89020cd33be2767f3f894484b8dd77bc2e5a1ccc864350b92c53262213257dfc
id: 2b7d6430f78d432f89109b29d88d4c36c868cdbf15dc31d2132ceaa02b993763
For an image that has not yet been analyzed, the status will appear as not_analyzed. Once the image has been downloaded it will be queued for analysis. When the analysis begins the status will be updated to analyzing, after which te status will update to analyzed.
Anchore Enterprise can be configured to have a size limit for images being added for analysis. Attempting to add an image that exceeds the configured size will fail, return a 400 API error, and log an error message in the catalog service detailing the failure. This feature is disabled by default so see documentation for additional details on the functionality of this feature and instructions on how to configure the limit.
Using AnchoreCTL for Distributed Analysis
Overview
This way of adding images uses anchorectl to performs analysis of an image outside the Enterprise deployment, so the Enterprise deployment never downloads or touches the image content directly. The generation of the SBOM, secret searches, filesystem metadata, and content searches are all performed by AnchoreCTL on the host where it is run (CI, laptop, runtime node, etc) and the results are imported to the Enterprise deployment where it can be scanned for vulnerabilities and evaluated against policy.
sequenceDiagram
participant A as AnchoreCTL
participant R as Registry/Docker Daemon
participant E as Anchore Deployment
A->>R: Get Image content
R-->>A: Image Content
A->>A: Analyze Image Content (Generate SBOM and secret scans etc)
A->>E: Import SBOM, secret search, fs metadata
E->>E: Scan sbom for vulns and evaluate complianceConfiguration
Enabling the full set of analyzers, “catalogers” in AnchoreCTL terms, requires updates to the config file used by AnchoreCTL. See Configuring AnchoreCTL for more information on the format and options.
Usage
Note
To locally analyze an image that has been pushed to a registry, it is strongly recommended to use the ‘–from registry’ rather than ‘–from docker’.
This removes the need to have docker installed and also results in a consistent image digest for later use. The registry option gives anchorectl access to data that the docker source does not due to limitations with the Docker Daemon itself and how it handles manifests and image digests.
The anchorectl image add --from [registry|docker] command will run a local SBOM-generation and analysis (secret scans, filesystem metadata, and content searches) and upload the result to Anchore Enterprise without ever having that image touched or loaded by your Enterprise deployment.
# anchorectl image add docker.io/library/nginx:latest --from registry
anchorectl image add docker.io/library/nginx:latest --from registry -n
✔ Added Image
Image:
status: not-analyzed (active)
tag: docker.io/library/nginx:latest
digest: sha256:89020cd33be2767f3f894484b8dd77bc2e5a1ccc864350b92c53262213257dfc
id: 2b7d6430f78d432f89109b29d88d4c36c868cdbf15dc31d2132ceaa02b993763
For an image that has not yet been analyzed, the status will appear as not_analyzed. Once the image has been downloaded it will be queued for analysis. When the analysis begins the status will be updated to analyzing, after which te status will update to analyzed.
The ‘–platform’ option in distributed analysis specifies a different platform than the local hosts’ to use when retrieving the image from the registry for analysis by AnchoreCTL.
# anchorectl image add alpine:latest --from registry --platform linux/arm64
Adding images that you own
For images that you are building yourself, the Dockerfile used to build the image should always be passed to Anchore Enterprise at the time of image addition. This is achieved by adding the image as above, but with the additional option to pass the Dockerfile contents to be stored with the system alongside the image analysis data.
This can be achieved in both analysis modes.
For centralized analysis:
# anchorectl image add myrepo.example.com:5000/app/webapp:latest --dockerfile /path/to/Dockerfile
For distributed analysis:
# anchorectl image add myrepo.example.com:5000/app/webapp:latest --from registry --dockerfile /path/to/Dockerfile
To update an image’s Dockerfile, simply run the same command again with the path to the updated Dockerfile along with ‘–force’ to re-analyze the image with the updated Dockerfile. Note that running add without --force (see below) will not re-add an image if it already exists.
Providing Dockerfile content is supported in both push and pull modes for adding images.
Additional Options
When adding an image, there are some additional (optional) parameters that can be used. We show some examples below and all apply to both distributed and centralize analysis workflows.
# anchorectl image add docker.io/library/alpine:latest --force
✔ Added Image docker.io/library/alpine:latest
Image:
status: not-analyzed (active)
tags: docker.io/alpine:3
docker.io/alpine:latest
docker.io/dnurmi/testrepo:test0
docker.io/library/alpine:latest
digest: sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870
id: 9c6f0724472873bb50a2ae67a9e7adcb57673a183cea8b06eb778dca859181b5
distro: [email protected] (amd64)
layers: 1
the --force option can be used to reset the image analysis status of any image to not_analyzed, which is the base analysis state for an image. This option shouldn’t be necessary to use in normal circumstances, but can be useful if image re-analysis is needed for any reason desired.
# anchorectl image add myrepo.example.com:5000/app/webapp:latest --dockerfile /path/to/dockerfile --annotation owner=someperson --annotation [email protected]
the --annotation parameter can be used to specify ‘key=value’ pairs to associate with the image at the time of image addition. These annotations will then be carried along with the tag, and will appear in image records when fetched, and in webhook notification payloads that contain image information when they are sent from the system. To change an annotation, simply run the add command again with the updated annotation and the old annotation will be overriden.
# anchorectl image add alpine:latest --no-auto-subscribe
the ‘–no-auto-subscribe’ flag can be used if you do not wish for the system to automatically subscribe the input tag to the ’tag_update’ subscription, which controls whether or not the system will automatically watch the added tag for image content updates and pull in the latest content for centralized analysis. See Subscriptions for more information about using subscriptions and notifications in Anchore.
These options are supported in both distributed and centralized analysis.
Image Tags
In this example, we’re adding docker.io/mysql:latest, if we attempt to add a tag that mapped to the same image, for example docker.io/mysql:8 Anchore Enterprise will detect the duplicate image identifiers and return a detail of all tags matching that image.
Image:
status: analyzed (active)
tags: docker.io/mysql:8
docker.io/mysql:latest
digest: sha256:8191525e9110aa32b436a1ec772b76b9934c1618330cdb566ca9c4b2f01b8e18
id: 4390e645317399cc7bcb50a5deca932a77a509d1854ac194d80ed5182a6b5096
distro: [email protected] (amd64)
layers: 11
Deleting An Image
The following command instructs Anchore Enterprise to delete the image analysis from the working set using a tag. The --force option must be used if there is only one digest associated with the provided tag, or any active subscriptions are enabled against the referenced tag.
# anchorectl image delete mysql:latest --force
┌─────────────────────────────────────────────────────────────────────────┬──────────┐
│ DIGEST │ STATUS │
├─────────────────────────────────────────────────────────────────────────┼──────────┤
│ sha256:8191525e9110aa32b436a1ec772b76b9934c1618330cdb566ca9c4b2f01b8e18 │ deleting │
└─────────────────────────────────────────────────────────────────────────┴──────────┘
To delete a specific image record, the digest can be supplied instead to ensure it is the exact image record you want:
# anchorectl image delete sha256:899a03e9816e5283edba63d71ea528cd83576b28a7586cf617ce78af5526f209
┌─────────────────────────────────────────────────────────────────────────┬──────────┐
│ DIGEST │ STATUS │
├─────────────────────────────────────────────────────────────────────────┼──────────┤
│ sha256:899a03e9816e5283edba63d71ea528cd83576b28a7586cf617ce78af5526f209 │ deleting │
└─────────────────────────────────────────────────────────────────────────┴──────────┘
Deactivate Tag Subscriptions
Check if the tag has any active subscriptions.
# anchorectl subscription list
anchorectl subscription list
✔ Fetched subscriptions
┌──────────────────────────────────────────────────────────────────────┬─────────────────┬────────┐
│ KEY │ TYPE │ ACTIVE │
├──────────────────────────────────────────────────────────────────────┼─────────────────┼────────┤
│ docker.io/alpine:latest │ policy_eval │ false │
│ docker.io/alpine:3.12.4 │ policy_eval │ false │
│ docker.io/alpine:latest │ vuln_update │ false │
│ docker.io/redis:latest │ policy_eval │ false │
│ docker.io/centos:8 │ policy_eval │ false │
...
...
If the tag has an active subscription(s), then can disabled (deactivated) in order to permit deletion:
# anchorectl subscription deactivate docker.io/alpine:3.12.6 tag_update
✔ Deactivate subscription
Key: docker.io/alpine:3.12.6
Type: tag_update
Id: a6c7559deb7d5e20621d4a36010c11b0
Active: false
Advanced
Anchore Enterprise also allows adding images directly by digest / tag / timestamp tuple, which can be useful to add images that are still available in a registry but not associated with a current tag any longer.
To add a specific image by digest with the tag it should be associated with:
anchorectl image add docker.io/nginx:stable@sha256:f586d972a825ad6777a26af5dd7fc4f753c9c9f4962599e6c65c1230a09513a8
Note: this will submit the specific image by digest with the associated tag, but Anchore will treat that digest as the most recent digest for the tag, so if the image registry actually has a different history (e.g. a newer image has been pushed to that tag), then the tag history in Anchore may not accurately reflect the history in the registry.
Next Steps
Next, let’s find out how to Inspect Image Content
1.1 - Inspecting Image Content
Introduction
During the analysis of container images, Anchore Enterprise performs deep inspection, collecting data on all artifacts in the image including files, operating system packages and software artifacts such as Ruby GEMs and Node.JS NPM modules.
Inspecting images
The image content command can be used to return detailed information about the content of the container image.
# anchorectl image content INPUT_IMAGE -t CONTENT_TYPE
The INPUT_IMAGE can be specified in one of the following formats:
- Image Digest
- Image ID
- registry/repo:tag
the CONTENT_TYPE can be one of the following types:
- os: Operating System Packages
- files: All files in the image
- go: GoLang modules
- npm: Node.JS NPM Modules
- gem: Ruby GEMs
- java: Java Archives
- python: Python Artifacts
- nuget: .NET NuGet Packages
- binary: Language runtime locations and version (e.g. openjdk, python, node)
- malware: ClamAV mailware scan results, if enabled
You can always get the latest available content types using the ‘-a’ flag:
# anchorectl image content library/nginx:latest -a
✔ Fetched content [fetching available types] library/nginx:latest
binary
files
gem
go
java
malware
npm
nuget
os
python
For example:
# anchorectl image content library/nginx:latest -t files
✔ Fetched content [0 packages] [6099 files] library/nginx:latest
Files:
┌────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────┬───────┬─────┬─────┬───────┬───────────────┬──────────────────────────────────────────────────────────────────┐
│ FILE │ LINK │ MODE │ UID │ GID │ TYPE │ SIZE │ SHA256 DIGEST │
├────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┼───────┼─────┼─────┼───────┼───────────────┼──────────────────────────────────────────────────────────────────┤
│ /bin │ │ 00755 │ 0 │ 0 │ dir │ 0 │ │
│ /bin/bash │ │ 00755 │ 0 │ 0 │ file │ 1.234376e+06 │ d86b21405852d8642ca41afae9dcf0f532e2d67973b0648b0af7c26933f1becb │
│ /bin/cat │ │ 00755 │ 0 │ 0 │ file │ 43936 │ e9165e34728e37ee65bf80a2f64cd922adeba2c9f5bef88132e1fc3fd891712b │
│ /bin/chgrp │ │ 00755 │ 0 │ 0 │ file │ 72672 │ f47bc94792c95ce7a4d95dcb8d8111d74ad3c6fc95417fae605552e8cf38772c │
│ /bin/chmod │ │ 00755 │ 0 │ 0 │ file │ 64448 │ b6365e442b815fc60e2bc63681121c45341a7ca0f540840193ddabaefef290df │
│ /bin/chown │ │ 00755 │ 0 │ 0 │ file │ 72672 │ 4c1443e2a61a953804a462801021e8b8c6314138371963e2959209dda486c46e │
...
AnchoreCTL will output a subset of fields from the content view, for example for files on the file name and size are displayed. To retrieve the full output the --json parameter should be passed.
For example:
# anchorectl -o json image content library/nginx:latest -t files
✔ Fetched content [0 packages] [6099 files] library/nginx:latest
{
"files": [
{
"filename": "/bin",
"gid": 0,
"linkdest": null,
"mode": "00755",
"sha256": null,
"size": 0,
"type": "dir",
"uid": 0
},
...
Next Steps
- View security vulnerabilities in the image
- Subscribe to receive notifications when the image is updated, when the policy status changes, or when new vulnerabilities are detected.
- Scan Respositories
1.2 - Viewing Security Vulnerabilities
Introduction
The image vulnerabilities command can be used to return a list of vulnerabilities found in the container image.
# anchorectl image vulnerabilities INPUT_IMAGE -t VULN_TYPE
The INPUT_IMAGE can be specified in one of the following formats:
- Image Digest
- Image ID
- registry/repo:tag
The VULN_TYPE currently supports:
- os: Vulnerabilities against operating system packages (RPM, DPKG, APK, etc.)
- non-os: Vulnerabilities against language packages (NPM, GEM, Java Archive (jar, war, ear), Python PIP, .NET NuGet, etc.)
- all: Combination report containing both ‘os’ and ’non-os’ vulnerability records.
The system has been designed to incorporate 3rd party feeds for other vulnerabilites.
Examples
To generate a report of OS package (RPM/DEB/APK) vulnerabilities found in the image including CVE identifier, Vulnerable Package, Severity Level, Vulnerability details and version of fixed package (if available).
# anchorectl image vulnerabilities debian:latest -t os
Currently the following the system draws vulnerability data specifically matched to the following OS distros:
- Alpine
- CentOS
- Debian
- Oracle Linux
- Red Hat Enterprise Linux
- Red Hat Universal Base Image (UBI)
- Ubuntu
- Suse Linux
- Amazon Linux 2
- Google Distroless
To generate a report of language package (NPM/GEM/Java/Python) vulnerabilities, the system draws vulnerability data from the NVD data feed, and vulnerability reports can be viewed using the ’non-os’ vulnerability type:
# anchorectl image vulnerabilities node:latest -t non-os
To generate a list of all vulnerabilities that can be found, regardless of whether they are against an OS or non-OS package type, the ‘all’ vulnerability type can be used:
# anchorectl image vulnerabilities node:latest -t all
Finally, for any of the above queries, these commands (and other anchorectl commands) can be passed the -o json flag to output the data in JSON format:
# anchorectl -o json image vulnerabilities node:latest -t all
Other options can be reviewed by issuing anchorectl image vulnerabilities --help at any time.
Next Steps
- Subscribe to receive notifications when the image is updated, when the policy status changes or when new vulnerabilities are detected.
2 - Image Analysis via UI
Overview
In this section you will learn how to submit images for analysis using the user interface, and how to execute a bulk removal of pending items or previously-analyzed items from within a repository group.
Note: Only administrators and standard users with the requisite role-based access control permissions are allowed to submit items for analysis, or remove previously analyzed assets.
Getting Started
From within an authenticated session, click the Image Analysis button on the navigation bar:
You will be presented with the Image Analysis view. On the right-hand side of this view you will see the Analyze Repository and Analyze Tag buttons:
These controls allow you to add entire repositories or individual items to the Anchore analysis queue, and to also provide details about how you would like the analysis of these submissions to be handled on an ongoing basis. Both options are described below in the following sections.
Analyze a Repository
After clicking the Analyze Repository button, you are presented with the following dialog:
The following fields are required:
- Registry—for example:
docker.io - Repository—for example:
library/centos
Provided below these fields is the Watch Tags in Repository configuration toggle. By default, when One-Time Tag Analysis is selected all tags currently present in the repository will be analyzed; once initial analysis is complete the repository will not be watched for future additions.
Setting the toggle to Automatically Check for Updates to Tags specifies that the repository will be monitored for any new tag additions that take place after the initial analysis is complete. Note that you are also able to set this option for any submitted repository from within the Image Analysis view.
Once you have populated the required fields and click OK, you will be notified of the overhead of submitting this repository by way of a count that shows the maximum number of tags detected within that repository that will be analyzed:
You can either click Cancel to abandon the repository analysis request at this point, or click OK to proceed, whereupon the specified repository will be flagged for analysis.
Max image size configuration applies to repositories added via UI. See max image size
Analyze a Tag
After clicking the Analyze Tag button, you are presented with the following dialog:
The following fields are required:
- Registry—for example,
docker.io - Repository—for example,
library/centos - Tag—for example,
latest
Note: Depending upon where the dialog was invoked, the above fields may be pre-populated. For example, if you clicked the Analyze Tag button while looking at a view under Image Analysis that describes a previously-analyzed repository, the name of that repository and its associated registry will be displayed in those fields.
Some additional options are provided on the right-hand side of the dialog:
Watch Tag—enabling this toggle specifies that the tag should be monitored for image updates on an ongoing basis after the initial analysis
Force Reanalysis—if the specified tag has already been analyzed, you can force re-analysis by enabling this option. You may want to force re-analysis if you decide to add annotations (see below) after the initial analysis. This option is ignored if the tag has not yet been analyzed.
Add Annotation—annotations are optional key-pair values that can be added to the image metadata. They are visible within the Overview tab of the Image Analysis view once the image has been analyzed, as well as from within the payload of any webhook notification from Anchore that contains image information.
Once you have populated the required fields and click OK, the specified tag will be scheduled for analysis.
Max image size configuration applies to images added via UI. See max image size
Note: Anchore will attempt to download images from any registry without requiring further configuration. However, if your registry needs authentication then the corresponding credentials will need to be defined. See Configuring Registries for more information.
Repository Deletion
Shown below is an example of a repository view under Image Analysis:
From a repository view you can carry out actions relating to the bulk removal of items in that repository. The Analysis Cancellation / Repository Removal control is provided in this view, adjacent to the analysis controls:
After clicking this button you are presented with the following options:
Cancel Images Currently Pending Analysis—this option is only enabled if you have one or more tags in the repository view that are currently scheduled for analysis. When invoked, all pending items will be removed from the queue. This option is particularly useful if you have selected a repository for analysis that contains many tags, and the overall analysis operation is taking longer than initially expected.
Note: If there is at least one item present in the repository that is not pending analysis, you will be offered the opportunity to decide if you want the repository to be watched after this operation is complete.
Remove Repository and Analyzed Items—In order to remove a repository from the repository view in its entirety, all items currently present within the repository must first be removed from Anchore. When invoked, all items (in any state of analysis) will be removed. If the repository is being watched, this subscription is also removed.