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.

Get 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 want to set or configure the following in your CI job specification:

• ANCHORECTL_URL
• ANCHORECTL_USERNAME
• ANCHORECTL_PASSWORD
• ANCHORECTL_UI_URL

The ANCHORECTL_UI_URL variable ensures that HTML outputs from anchorectl commands will contain deep links to the Anchore Enterprise GUI for assets.

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

Choose Your Pathway

Two CI integration shapes are supported in Anchore Enterprise v6. Pick the one that matches what your CI job is already doing — both work with any CI system and both use AnchoreCTL, but the Anchore Enterprise step in your pipeline is different in each case.

Pathway A fits teams who have standardized on producing SBOMs upstream and treat Anchore Enterprise as the evaluation, aggregation, and evidence layer over those SBOMs. Pathway B is a straightforward entry point for CI jobs that build container images — image in, results out, no app or version bookkeeping.

The rest of this quickstart documents both pathways. Click into the one that matches your situation and follow it through to the conclusion — the two pathways are independent.

Pathway A — SBOM Upload to an App Version

In this pathway your CI job has already produced an SBOM in an earlier step. Any supported SBOM format — CycloneDX, SPDX, or Syft-native JSON — can be uploaded. The Anchore Enterprise step then attaches the SBOM to an app version as an asset, and reads vulnerability and policy results back at the version level.

App and Version Setup

Pathway A presumes the target app and version already exist in Anchore Enterprise. You can create them once during release setup, or as part of the CI job itself:

anchorectl app add my-service --contact-name "Platform Team"
anchorectl app version add 1.4.0 --app my-service

For the full app and version reference, see Manage Apps and Manage App Versions.

Construct Your Workflow

A Pathway A CI job typically does the following:

1. Builds the artifact and produces an SBOM via the user’s chosen tool
2. Downloads AnchoreCTL from Anchore Enterprise
3. Uploads the SBOM as an asset on the target app version
4. Reads vulnerability and policy results back at the version level
5. Fails the CI job step if the policy evaluation result is fail

The sequence of commands looks something like this (simplified):

# Earlier step has produced ./api.sbom.json — any CycloneDX / SPDX / Syft JSON document

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

# Upload the SBOM as an asset on the target app version
anchorectl app version asset add sbom ./api.sbom.json \
  --app my-service \
  --version 1.4.0 \
  --asset api-image \
  --type container \
  --wait

# Get vulnerability results for the app version
anchorectl app version vuln list 1.4.0 --app my-service

# Get the per-finding detail — specific gates, triggers, and remediation recommendations behind the verdict
anchorectl app version policy findings list 1.4.0 --app my-service

# Check policy status
anchorectl app version policy status get 1.4.0 --app my-service -f

The --type flag on the asset-add declares what the SBOM describes — set container for a container image SBOM, filesystem for a directory analysis, library for a single library binary, and so on. See Asset Types for the full enum.

The --wait flag blocks until the asset-add job reaches a terminal state, so the subsequent vuln list and policy commands operate on fully processed data.

The -f flag — shorthand for --fail-based-on-results — gives the policy status get command a return code of 1 when the policy evaluation result is fail. The non-zero exit is what fails the CI job step.

Customize Artifacts

The app version vuln, app version policy, and app version export command trees all expose -o for output format selection. Common patterns:

• app version vuln list ... -o json — programmatic vulnerability results for downstream tooling.
• app version policy findings list ... -o json — programmatic policy results for build-gating logic.
• app version export vulnerabilities and app version export vex produce formal documents (CSV vulnerability report and CycloneDX VEX, respectively) that you can attach as build artifacts. See Evidence for the full export surface.

Use Policy Checks

Pathway A’s policy gating operates at the app-version level. Use the following command to retrieve the app version’s policy status and fail the CI job if it does not meet compliance requirements:

anchorectl app version policy status get 1.4.0 --app my-service -f

For the per-finding detail — the specific gates, triggers, and remediation recommendations behind a failing result — list the findings:

anchorectl app version policy findings list 1.4.0 --app my-service

For the full policy evaluation surface, see Evaluate an App Version.

Notes on Optimization and Stateless Scans

• Performance tuning happens upstream. Because the SBOM is generated by your CI’s chosen tool before the Anchore Enterprise step, SBOM-generation performance is determined by that tool’s settings rather than by AnchoreCTL. The ANCHORECTL_SYFT_PARALLELISM knob covered in Pathway B’s Optimize Performance section applies only when AnchoreCTL is the SBOM generator.
• No app-version equivalent of One-Time Scan. Pathway A currently has no stateless mode — every uploaded SBOM is stored against the app version. If you need a stateless evaluation flow, anchorectl image one-time-scan in Pathway B is the only path today.

← Back to Choose Your Pathway

Pathway B — Image Analysis

In this pathway your CI job builds a container image and asks Anchore Enterprise to analyze it directly. The image and its findings live in the image catalog; no app or app version is involved.

Choose Your Method of Analysis

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 registry --wait

This will cause AnchoreCTL in your job to download the image from the given source 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 analyze 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 put AnchoreCTL commands into your CI jobs. For a container-focused use-case, you will generally construct a job which:

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 looks 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 (distributed in this example) and wait for analysis to complete
anchorectl image add <DOCKER_USERNAME>/getting-started-todo-app --from registry --wait

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

# Get policy evaluation results for the image
anchorectl image check <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.

Customize Artifacts

The various anchorectl image commands have options for outputs, selected using the -o parameter. You might opt to return results as text, machine-readable JSON, CSV, or HTML. This material can be useful if you intend to have additional steps in your job work based on results, rather than just pass or fail.

AnchoreCTL supports an HTML format for vulnerability and policy check reports, for example:

anchorectl image check ghcr.io/place/thing:v0.1.0 --detail -f -o html > policy.html

If you set ANCHORECTL_UI_URL or ui-url in your AnchoreCTL configuration, you’ll get a handy link in the HTML which takes you straight into the Anchore Enterprise GUI for that image.

Optimize Performance

With a basic workflow constructed, you might want to optimize SBOM generation, vulnerability scan, and policy check times.

If you are using Distributed Analysis, ensure your CI runners have fast CPU and I/O to optimize 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 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 it 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 Enterprise 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:

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

The --detail flag provides the specific gate, trigger, and remediation recommendations needed to resolve policy violations — useful for developer-facing feedback.

The -f flag (shorthand for --fail-based-on-results) gives the command a return code of 1 if the policy evaluation result is fail. This is what fails the CI job step.

If you wish to store output as artifacts, use the -o parameter and save accordingly.

Switch to Stateless Scans (One-Time Scan)

By default, adding an image to Anchore Enterprise for analysis means the SBOM is stored persistently in the deployment, until archived or deleted. For some CI use cases you may not need the SBOM to persist.

Anchore Enterprise has a feature called One-Time Scan which delivers fast feedback in your pipeline jobs — vulnerability and policy analysis results — without persisting the SBOM. Use the anchorectl image one-time-scan command to conduct analysis in this mode. You can also pass a flag to fail the pipeline job if the policy analysis fails:

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

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

HTML output is also available:

anchorectl image one-time-scan ghcr.io/place/thing:v0.1.0 --from registry --fail-on-policy-error -o html > onetime.html

See One-Time Scan for further information.

← Back to Choose Your Pathway

Conclusion

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