Best Practices for using Anchore Enterprise in CI

This quickstart will walk you through the typical steps required to integrate Anchore Enterprise policy checks and vulnerability scans into your CI jobs.

Before You Start

In order to start instrumenting your CI pipelines with AnchoreCTL, you need to ensure the following:

1. You have access to a fully operational Anchore Enterprise deployment, with a provisioned account/tenant for your use.
2. The Anchore Enterprise API should be accessible from your CI runner(s).
3. Your Anchore Enterprise deployment and your CI runner(s) can reach any relevant container registries from which to source images.

Getting AnchoreCTL

Anchore Enterprise can be integrated into various CI systems in a vendor-agnostic manner using the AnchoreCTL tool. AnchoreCTL is a golang binary which can be used to interact with an Anchore Enterprise deployment. To ensure compatibility and simplify runner configuration, AnchoreCTL should always be version-aligned with your Anchore Enterprise deployment.

A recommended practice is to fetch AnchoreCTL directly from your Anchore Enterprise installation during the CI job. This guarantees the client version matches the server. Insert a command such as the following into your job before you want to conduct a scan and evaluation:

curl -X GET "https://my-anchore.example.com/v2/system/anchorectl?operating_system=linux&architecture=amd64" -H "accept: */*" | tar -zx anchorectl

For more details, see Deploying AnchoreCTL.

Access via API Keys

AnchoreCTL can talk to an Anchore Enterprise deployment using username and password for authentication, or via API keys. The latter is recommended and otherwise commonly used if you are signing into Anchore Enterprise via SSO.

Configure an API key so your job can talk to the Anchore Enterprise API, see Using API keys for instructions.

Add Environment Variables

You’ll typically want to store AnchoreCTL configuration such as connection details in environment variables for your CI job. At a minimum, you will need to set or configure the following in your CI job specification:

• ANCHORECTL_URL
• ANCHORECTL_USERNAME
• ANCHORECTL_PASSWORD

Alternatively, you could also construct an AnchoreCTL configuration file and use that. See Configuring AnchoreCTL for further details on possible parameters.

Choose Your Method of Analysis

Before you start creating a workflow in CI, you will need to determine which method of analysis you wish to use. Anchore Enterprise supports two primary modes of operation for image analysis in CI pipelines: Distributed Analysis or Centralized Analysis.

Both modes work with any CI/CD system as long as the AnchoreCTL binary can be installed and run, and you can access the Enterprise APIs directly.

Distributed Analysis (Recommended)

In Distributed Analysis, SBOM generation happens locally on the runner and is then sent to Anchore Enterprise for evaluation.

It is the recommended approach because it offers maximum flexibility in resourcing. You can potentially reduce the time to generate an SBOM by customising your anchoreCTL configuration and providing more CPU and fast I/O to your pipeline runners.

To use distributed analysis, construct your CI job to use AnchoreCTL with the --from parameter, for example:

anchorectl image add <DOCKER_USERNAME>/getting-started-todo-app --from [docker, registry] --wait

This will cause AnchoreCTL in your job to download the image from the given registry and generate the SBOM locally on the runner.

Centralized Analysis

In Centralized Analysis, the AnchoreCTL command is used to ask your Anchore Enterprise deployment to download and analyzes the image content. This is necessary if you require the malware scanning service to unpack and scan container layers.

To use centralized analysis, omit the --from parameter, for example:

anchorectl image add ghcr.io/place/thing:v0.1.0  --wait

Centralized analysis will have a different performance profile for SBOM generation, since you may not have direct control over resourcing of your Anchore Enterprise shared service.

Construct Your Workflow

You’re now ready to start putting AnchoreCTL commands into your CI jobs. For a container-focused use-case, you will generally look to construct a job which does the following:

1. Builds a container image and pushes to a staging registry
2. Downloads AnchoreCTL from Anchore Enterprise
3. Generates an SBOM of the container image
4. Conducts a vulnerability analysis, returning results
5. Conducts a policy check, returning the evaluation result

The sequence of commands will look something like this (simplified):

# Build a docker image for your project
docker build -t <DOCKER_USERNAME>/getting-started-todo-app . 

# Push the image to a staging registry (you can also skip this step by using --from docker in the next command)
docker push <DOCKER_USERNAME>/getting-started-todo-app

# Download AnchoreCTL
curl -X GET "https://my-anchore.example.com/v2/system/anchorectl?operating_system=linux&architecture=amd64" -H "accept: */*" | tar -zx anchorectl

# Generate the SBOM for the image (in this example, distributed) and wait for analysis to complete
anchorectl image add <DOCKER_USERNAME>/getting-started-todo-app --from [docker, registry] --wait

# Get vulnerability results for the image
anchorectl image vulns <DOCKER_USERNAME>/getting-started-todo-app 

Based on the results returned by Anchore Enterprise, you can then decide what additional steps to take in your CI job.

Optimize Performance

With a basic workflow constructed, you might want to try and optimise for SBOM-generation, vuln scan and policy check times.

If you are using Distributed Analysis, you will want to ensure that your CI runners have fast CPU and I/O, to optimise the cataloging and SBOM generation process used by AnchoreCTL.

If your container images contain a large number of files and packages, you may be able to significantly reduce SBOM generation time by enabling parallelism. AnchoreCTL (v5.18+) can run catalogers in parallel rather than sequentially.

You can configure the number of concurrent worker processes using the ANCHORECTL_SYFT_PARALLELISM environment variable (or set in anchorectl.yaml). For optimal performance, try aligning the number of workers with your runner’s available vCPUs.

# Example for an 8 vCPU runner
ANCHORECTL_SYFT_PARALLELISM=8

See Configuring AnchoreCTL for further information.

Use Policy Checks

Rather than just reviewing a raw list of vulnerabilities, which can be daunting and lack context, it is a best practice to use the Anchore Enforce policy engine to conduct compliance checks.

Policy-driven gating provides developers with precise, actionable feedback based on your own organizational policy or industry standards (e.g., NIST 800-53, CIS).

Use the following command to evaluate an image against your default policy and fail the CI job if it does not meet compliance requirements. You might add this to the end of your sequence of commands:

anchorectl image check <DOCKER_USERNAME>/getting-started-todo-app --detail -f

The --detail flag is essential for developers, as it provides the specific gate, trigger, and remediation recommendations needed to resolve policy violations.

The -f flag tells the command to give a return code of 1 in the result of the policy check being marked as fail. This can allow you to fail or break a workflow on this step.

Switch to Stateless Scans (One-Time Scan)

By default, adding an image to Anchore Enterprise for analysis means that the SBOM will be stored persistently in the deployment, until archived or deleted. This could mean your deployment stores more SBOMs than necessary; you may not care whether an SBOM for a CI build is persisted or not.

Anchore Enterprise has a featured called One Time Scan which can be used to deliver fast feedback in your pipeline jobs, namely vulnerability and policy analysis results, but doing so without persisting the SBOM in your Anchore Enterprise deployment. Use the anchorectl image one-time-scan command to conduct analysis in this mode. As with the anchorectl image check command, you can also pass a flag to fail the pipeline job if the policy analysis fails. For example:

anchorectl image one-time-scan <DOCKER_USERNAME>/getting-started-todo-app --from [docker, registry] --fail-on-policy-error

By default, this command will return a policy check. Using the -o json parameter, JSON results for policy check, vulnerability scan and the SBOM will be returned. These results can then be machine parsed by the CI job to determine actions.

See One Time Scan for further information.

Conclusion

You’ve now fully instrumented your pipeline to add hi-fidelity SBOM-based vulnerability and compliance checks to your CI jobs!