Skip to main content
Version: Next

Docker Build Integration

The copa generate command enables you to leverage Docker's native build capabilities for patching container images. By producing a standard Docker build context, it allows you to use familiar docker build commands and options like --platform, --push, --cache-from, and --output that aren't available with copa patch. This integration with Docker's build system provides maximum flexibility for incorporating security patches into your existing container workflows.

Overview​

Instead of directly patching and pushing images like copa patch, the generate command produces a tar stream containing:

  • A Dockerfile with instructions to apply the patch
  • A patch layer directory with the security updates

This output can be piped directly to docker build or saved as a tar file for later use, giving you full control over the build process with all of Docker's advanced features.

Key Advantages over copa patch​

With copa generate, you can use any Docker build flag:

# Multi-platform builds
copa generate -i nginx:1.21.6 | docker buildx build --platform linux/amd64,linux/arm64 -t nginx:patched --push -

# Use build cache
copa generate -i nginx:1.21.6 | docker build --cache-from nginx:cache -t nginx:patched -

# Export to different formats
copa generate -i nginx:1.21.6 | docker build --output type=tar,dest=patched.tar -

# Set custom build arguments
copa generate -i nginx:1.21.6 | docker build --build-arg HTTP_PROXY=http://proxy:8080 -t nginx:patched -

# Specify target registry directly
copa generate -i nginx:1.21.6 | docker build -t myregistry.io/nginx:patched --push -

Use Cases​

The copa generate command is ideal for:

  • Docker Build Integration - Use native Docker build flags and features not available in copa patch
  • Multi-platform Builds - Leverage docker buildx for cross-platform patching
  • CI/CD Pipelines - Integrate patches using standard Docker commands your team already knows
  • Build Cache Optimization - Use Docker's layer caching mechanisms for faster builds
  • Air-gapped Environments - Create patch contexts offline and apply them later
  • Custom Registries - Push directly to any registry using Docker's native push capabilities

Command Syntax​

copa generate [flags]

Flags​

FlagShortDescriptionDefault
--image-iApplication image name and tag to patch (required)
--report-rVulnerability report file path (optional)
--tag-tTag for the patched image
--tag-suffixSuffix for the patched image (if no explicit --tag provided)patched
--output-contextPath to save the generated tar context (instead of stdout)stdout
--scanner-sScanner that generated the reporttrivy
--addr-aAddress of buildkitd servicelocal docker daemon
--working-folder-wWorking foldersystem temp folder
--timeoutTimeout for the operation5m
--ignore-errorsIgnore errors during patchingfalse
--format-fOutput format for VEX documentopenvex
--output-oOutput file path for VEX document
--loader-lLoader to use for loading images (docker, podman, or empty for auto-detection)auto-detect
--platformTarget platform(s) for multi-arch images (e.g., linux/amd64,linux/arm64). Valid platforms: linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6all platforms
--cacertAbsolute path to buildkitd CA certificate
--certAbsolute path to buildkit client certificate
--keyAbsolute path to buildkit client key

Basic Usage​

Pipe to Docker Build​

The most common usage is piping the generated context directly to docker build:

# Generate and immediately build the patched image
copa generate -i nginx:1.21.6 | docker build -t nginx:1.21.6-patched -

Save to File​

Save the build context for later use:

# Generate and save the build context
copa generate -i nginx:1.21.6 --output-context patch-context.tar

# Later, build the patched image
docker build -t nginx:1.21.6-patched - < patch-context.tar

With Vulnerability Report​

Use a specific vulnerability report for targeted patching:

# First, generate a vulnerability report
trivy image --vuln-type os --ignore-unfixed -f json -o nginx-report.json nginx:1.21.6

# Generate patch context using the report
copa generate -i nginx:1.21.6 -r nginx-report.json | docker build -t nginx:1.21.6-patched -

With VEX Output​

Generate a VEX (Vulnerability Exploitability eXchange) document alongside the patch context:

# Generate patch context and VEX document
copa generate -i nginx:1.21.6 -r nginx-report.json \
  -f openvex -o nginx-patched.vex.json \
  --output-context patch-context.tar

# Build the patched image
docker build -t nginx:1.21.6-patched - < patch-context.tar

# The VEX document can be used for compliance and attestation
cat nginx-patched.vex.json

Note: The VEX document generated by copa generate uses the image tag as the reference (e.g., nginx:1.21.6-patched), since the image digest is not available until after the Docker build completes. If you need the digest in your VEX document, use copa patch instead.

Build Context Structure​

The generated tar file contains:

├── Dockerfile              # Instructions to apply the patch
└── patch/                  # Directory with updated packages
    ├── usr/
    ├── lib/
    └── ...                 # Other patched files

Generated Dockerfile​

The Dockerfile in the build context looks like:

FROM nginx:1.21.6
COPY patch/ /
LABEL sh.copa.image.patched="2024-03-20T10:30:00Z"

Comparison with copa patch​

Featurecopa patchcopa generate
OutputPatched image in registry/daemonBuild context tar stream
Registry AccessRequired for pushNot required
Use CaseDirect patchingPipeline integration
FlexibilityLess flexibleHighly flexible
PerformanceSingle operationCan be parallelized
VEX OutputYes (with image digest)Yes (with image tag only)
Docker Build FeaturesLimited (no buildx flags)Full (all docker build flags)

Best Practices​

1. Always Verify Output​

When using stdout, ensure the output is valid before piping:

# Verify the context first
copa generate -i nginx:1.21.6 --output-context test.tar
tar -tf test.tar  # Check contents

# Then use in production
copa generate -i nginx:1.21.6 | docker build -t nginx:patched -

2. Handle TTY Detection​

Copa refuses to write tar data to a terminal. Always redirect output:

# ❌ Wrong - outputs to terminal
copa generate -i nginx:1.21.6

# ✅ Correct - redirect to file or pipe
copa generate -i nginx:1.21.6 > patch.tar
copa generate -i nginx:1.21.6 | docker build -t nginx:patched -

3. Use Specific Reports for Reproducibility​

For consistent results across environments:

# Generate report once
trivy image --vuln-type os -f json -o report.json nginx:1.21.6

# Use the same report for all patch generations
copa generate -i nginx:1.21.6 -r report.json --output-context patch.tar

4. Optimize for CI/CD​

Cache generated contexts when possible:

# Generate context with cache key
CACHE_KEY=$(sha256sum report.json | cut -d' ' -f1)
CACHE_FILE="patch-cache/${CACHE_KEY}.tar"

if [ ! -f "$CACHE_FILE" ]; then
  copa generate -i nginx:1.21.6 -r report.json --output-context "$CACHE_FILE"
fi

docker build -t nginx:patched - < "$CACHE_FILE"

Troubleshooting​

"No local sources enabled" Error​

This error from docker build indicates an invalid or empty build context:

# Check if copa generate succeeded
copa generate -i nginx:1.21.6 --output-context test.tar || echo "Generation failed"

# Verify tar contents
tar -tf test.tar

Empty Patch Layer​

If the image has no upgradable packages, Copa will log a message and return nothing:

# Copa will log when an image is already up-to-date
copa generate -i alpine:latest --output-context patch.tar
# Output: INFO[0005] Image is already up-to-date. No packages to upgrade.

# Resulting patch.tar will not be created.

BuildKit Connection Issues​

If BuildKit isn't detected automatically, specify the address:

# Use Docker's BuildKit
copa generate -i nginx:1.21.6 --addr docker://

# Use a specific buildx builder
docker buildx create --name copa-builder --use
copa generate -i nginx:1.21.6 --addr buildx://copa-builder

Summary​

The copa generate command provides a flexible way to integrate Copa's patching capabilities into any container build workflow. By producing standard Docker build contexts, it enables:

  • Seamless CI/CD integration
  • Offline patching workflows
  • Custom build pipelines
  • Parallel processing of multiple images

Whether you're automating security updates in production or integrating patches into complex build systems, copa generate offers the flexibility and control needed for enterprise container security.

Next Steps​