### Build and Install from Source

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/installation.md

Clone the repository, build the copacetic CLI tool, and optionally install it to a pathed folder. Ensure you have Go, Docker, and optionally Trivy installed.

```bash
git clone https://github.com/project-copacetic/copacetic
cd copacetic
make
# OPTIONAL: install copa to a pathed folder (i.e. /usr/local/bin)
# Note: if you installed copa via Homebrew, you will need to uninstall it first
make install
```

--------------------------------

### Install Local Tooling

Source: https://github.com/project-copacetic/copacetic/blob/main/CLAUDE.md

Installs pinned versions of golangci-lint and gofumpt for local development.

```bash
make setup
```

--------------------------------

### Start Local Development Server

Source: https://github.com/project-copacetic/copacetic/blob/main/website/README.md

Starts a local development server for live preview. Changes are reflected without server restart.

```bash
$ yarn start
```

--------------------------------

### Verify QEMU Emulation Installation on Linux

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/multiplatform-patching.md

After installing QEMU emulation support using the docker run command, verify the installation by listing the registered QEMU handlers in the /proc/sys/fs/binfmt_misc directory.

```bash
# Install QEMU emulation support
docker run --privileged --rm tonistiigi/binfmt --install all

# Verify installation
ls /proc/sys/fs/binfmt_misc/qemu-*
```

--------------------------------

### Multi-arch Patch Summary Example

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/multiplatform-patching.md

This is an example of the summary output after a multi-platform patching run, showing the status for each platform.

```text
Multi-arch patch summary:
PLATFORM        STATUS   REFERENCE                                        MESSAGE
linux/amd64     Patched  docker.io/library/nginx:1.27.1-patched-amd64     Successfully patched image (linux/amd64)
linux/arm/v7    Patched  docker.io/library/nginx:1.27.1-patched-arm-v7    Successfully patched image (linux/arm/v7)
linux/arm64     Patched  docker.io/library/nginx:1.27.1-patched-arm64     Successfully patched image (linux/arm64)
linux/386       Error    -                                                Emulation is not enabled for platform linux/386
linux/mips64le  Patched  docker.io/library/nginx:1.27.1-patched-mips64le  Successfully patched image (linux/mips64le)
linux/ppc64le   Patched  docker.io/library/nginx:1.27.1-patched-ppc64le   Successfully patched image (linux/ppc64le)
linux/s390x     Patched  docker.io/library/nginx:1.27.1-patched-s390x     Successfully patched image (linux/s390x)
```

--------------------------------

### Build Documentation Site

Source: https://github.com/project-copacetic/copacetic/blob/main/CLAUDE.md

Installs dependencies and builds the documentation website from the website directory.

```bash
cd website && yarn install --frozen-lockfile && yarn build
```

--------------------------------

### Build Copacetic from Source

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/installation.md

Follow these steps to clone the repository, build the copacetic CLI, and optionally install it to a pathed directory. Ensure Go and Docker are installed. Trivy is optional.

```bash
git clone https://github.com/project-copacetic/copacetic
cd copacetic
make
# OPTIONAL: install copa to a pathed folder (i.e. /usr/local/bin)
# Note: if you installed copa via Homebrew, you will need to uninstall it first
make install
```

--------------------------------

### Example: Solve busyBoxApplied Stage to Docker Image

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/development-tips.md

This example demonstrates how to use `buildkit.SolveToDocker` to create a Docker image for the `busyBoxApplied` stage. The resulting image is tagged with a specific suffix for easy identification and inspection.

```go
busyBoxApplied := dm.config.ImageState.File(llb.Copy(toolImage, "/bin/busybox", "/bin/busybox"))
if err := buildkit.SolveToDocker(ctx, dm.config.Client, &busyBoxApplied, dm.config.ConfigData, dm.config.ImageName+"-busyBoxApplied"); err != nil {
    return nil, err
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/project-copacetic/copacetic/blob/main/website/README.md

Installs project dependencies using Yarn. Run this command in the project root.

```bash
$ yarn
```

--------------------------------

### Install and Register QEMU Emulation Binaries on Linux

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/multiplatform-patching.md

Use this command to install QEMU emulation support for multi-platform builds on Linux. This registers static binaries with the kernel's binfmt_misc handler.

```bash
# Install QEMU emulation support
docker run --privileged --rm tonistiigi/binfmt --install all

# Verify installation
ls /proc/sys/fs/binfmt_misc/qemu-*
```

--------------------------------

### Install Copacetic via Homebrew

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/installation.md

Use this command to install the copacetic CLI on macOS and Linux systems that have Homebrew installed.

```bash
brew install copa
```

--------------------------------

### CI/CD Integration with GitHub Actions

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/buildkit-frontend.md

An example GitHub Actions workflow to automate the container image patching process. It includes steps for setting up Buildx, installing Trivy, generating vulnerability reports, and patching the image.

```yaml
name: Patch Container Images
on: [push]

jobs:
  patch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Install Trivy
        run: |
          curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin

      - name: Generate vulnerability report
        run: |
          mkdir build-context
          trivy image --format json --output build-context/report.json nginx:1.21.6
          touch build-context/Dockerfile

      - name: Patch image with Copa frontend
        run: |
          docker buildx build \
            --build-arg BUILDKIT_SYNTAX=ghcr.io/project-copacetic/copacetic-frontend:v0.13.0 \
            --build-arg image=nginx:1.21.6 \
            --build-arg report=report.json \
            --build-context report=./build-context \
            --output type=image,name=nginx:1.21.6-patched,push=true \
            ./build-context
```

--------------------------------

### Multi-platform patching with BuildKit

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/buildkit-frontend.md

Patch a multi-architecture image using platform-specific vulnerability reports. This example includes steps for creating reports, patching, and cleanup.

```bash
# Create reports directory
mkdir reports

# Generate reports for each platform
trivy image --platform linux/amd64 --format json --output reports/linux-amd64.json nginx:1.21.6
trivy image --platform linux/arm64 --format json --output reports/linux-arm64.json nginx:1.21.6

# Patch all platforms
buildctl build \
  --frontend=gateway.v0 \
  --opt source=ghcr.io/project-copacetic/copacetic-frontend:latest \
  --opt image=docker.io/library/nginx:1.21.6 \
  --opt report=. \
  --opt scanner=trivy \
  --opt platform=linux/amd64,linux/arm64 \
  --local report=./reports \
  --opt context:report=local:report \
  --output type=image,name=nginx:1.21.6-multiarch-patched

# Clean up reports
rm reports/linux-*.json
rmdir reports
```

--------------------------------

### Nightly Sweep Patching Example

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/bulk-image-patching.md

Example command for a nightly sweep, patching the three latest matching minor versions for nginx and all specified python versions, then pushing the results.

```bash
copa patch --config ./copa-bulk-config.yaml --push --timeout 20m
```

--------------------------------

### Multi-platform Patching with Trivy and Buildctl

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/buildkit-frontend.md

This example demonstrates patching a multi-architecture image using platform-specific reports generated by Trivy. It involves organizing reports and then using buildctl for the patching process.

```bash
# Generate reports for each platform
trivy image --platform linux/amd64 --format json --output linux-amd64.json nginx:1.21.6
trivy image --platform linux/arm64 --format json --output linux-arm64.json nginx:1.21.6

# Organize reports
mkdir reports
mv linux-*.json reports/

# Patch all platforms
buildctl build \
  --frontend=gateway.v0 \
  --opt source=ghcr.io/project-copacetic/copacetic-frontend:latest \
  --opt image=nginx:1.21.6 \
  --opt report=. \
  --opt scanner=trivy \
  --opt platform=linux/amd64,linux/arm64 \
  --local report=./reports \
  --opt context:report=local:report \
  --output type=image,name=nginx:1.21.6-multiarch-patched
```

--------------------------------

### v1alpha1 Scanner Plugin JSON Output Example

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/scanner-plugins.md

Example JSON output for a v1alpha1 scanner plugin, detailing OS updates.

```json
{
  "apiVersion": "v1alpha1",
  "metadata": {
    "os": {
        "type": "debian",
        "version": "11.3"
    },
    "config": {
      "arch": "amd64"
    }
  },
  "updates": [
      {
          "name": "libcurl4",
          "installedVersion": "7.74.0-1.3+deb11u1",
          "fixedVersion": "7.74.0-1.3+deb11u2",
          "vulnerabilityID": "CVE-2021-22945"
      }
  ]
}
```

--------------------------------

### Scan and Patch Node.js Packages

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/app-level-patching.md

This example demonstrates scanning a Node.js image for vulnerabilities and then applying patch-level updates to Node.js packages. Ensure experimental features are enabled if necessary.

```bash
export COPA_EXPERIMENTAL=1
export IMAGE=node:18

# Scan for Node.js package vulnerabilities
trivy image --vuln-type os,library --ignore-unfixed -f json -o nodejs-scan.json $IMAGE

# Apply patch-level Node.js package updates
copa patch \
    -i $IMAGE \
    -r nodejs-scan.json \
    --pkg-types os,library \
    --library-patch-level patch
```

--------------------------------

### Run Copa Demo Script

Source: https://github.com/project-copacetic/copacetic/blob/main/demo/README.md

Navigate to the demo directory and execute a specific demo script, such as copa-demo.sh, to start the patching workflow.

```bash
cd demo
bash copa-demo.sh
```

--------------------------------

### Install copa via Homebrew

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/installation.md

Use this command to install the copacetic CLI tool on macOS and Linux systems using Homebrew.

```bash
brew install copa
```

--------------------------------

### Example OpenVEX Document Structure

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/output.md

This is an example of a VEX document generated in the OpenVEX format. It details a fixed vulnerability, its associated products and subcomponents, and the status of the fix.

```json
{
  "@context": "https://openvex.dev/ns",
  "@id": "https://openvex.dev/docs/public/vex-e635674468f708838b7bd1b61b1c39bcf98639318eebfb510db519d947a5c204",
  "author": "Project Copacetic",
  "timestamp": "2025-09-10T16:52:53.988017858Z",
  "version": 1,
  "tooling": "Project Copacetic",
  "statements": [
    {
      "vulnerability": {
        "@id": "CVE-2024-0727"
      },
      "products": [
        {
          "@id": "pkg:oci/azure-cli@sha256:b40133b2ab18d506f54e4d42083cb95f814d8397d7ef95abe28e897c18e3091d",
          "subcomponents": [
            {
              "@id": "pkg:apk/alpine/libcrypto3@3.1.4-r5?arch=amd64"
            },
            {
              "@id": "pkg:apk/alpine/libssl3@3.1.4-r5?arch=amd64"
            },
            {
              "@id": "pkg:apk/alpine/openssl@3.1.4-r5?arch=amd64"
            },
            {
              "@id": "pkg:apk/alpine/openssl-dev@3.1.4-r5?arch=amd64"
            },
            {
              "@id": "pkg:pypi/cryptography@41.0.6"
            }
          ]
        }
      ],
      "status": "fixed"
    }
  ]
}
```

--------------------------------

### Example Multi-arch Patch Summary Output

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/multiplatform-patching.md

This table displays a typical output summary after a multi-platform image patching operation, indicating the status for each platform and providing messages, including potential errors like emulation not being enabled.

```text
Multi-arch patch summary:
PLATFORM        STATUS   REFERENCE                                        MESSAGE
linux/amd64     Patched  docker.io/library/nginx:1.27.1-patched-amd64     Successfully patched image (linux/amd64)
linux/arm/v7    Patched  docker.io/library/nginx:1.27.1-patched-arm-v7    Successfully patched image (linux/arm/v7)
linux/arm64     Patched  docker.io/library/nginx:1.27.1-patched-arm64     Successfully patched image (linux/arm64)
linux/386       Error    -                                                Emulation is not enabled for platform linux/386
linux/mips64le  Patched  docker.io/library/nginx:1.27.1-patched-mips64le  Successfully patched image (linux/mips64le)
linux/ppc64le   Patched  docker.io/library/nginx:1.27.1-patched-ppc64le   Successfully patched image (linux/ppc64le)
linux/s390x     Patched  docker.io/library/nginx:1.27.1-patched-s390x     Successfully patched image (linux/s390x)
```

--------------------------------

### Run BuildKit in a Docker Container and Use with Copa

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/custom-address.md

This example shows how to run BuildKit in a detached Docker container and then use Copa to connect to this containerized BuildKit instance.

```bash
docker run \
    --detach \
    --rm \
    --privileged \
    --name buildkitd \
    --entrypoint buildkitd \
    "moby/buildkit:$BUILDKIT_VERSION"

# Use the containerized BuildKit
copa patch -i docker.io/library/nginx:1.21.6 -r nginx.1.21.6.json -t 1.21.6-patched --addr docker-container://buildkitd
```

--------------------------------

### Troubleshoot Frontend Image Not Found Error

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/buildkit-frontend.md

Resolve the 'failed to resolve frontend image' error by verifying the frontend image reference. This example shows the correct argument for Docker Buildx.

```bash
--build-arg BUILDKIT_SYNTAX=ghcr.io/project-copacetic/copacetic-frontend:latest
```

--------------------------------

### Multi-platform Builds with Docker

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/docker-build.md

Use `copa generate` to create a Docker build context and pipe it to `docker buildx build` for multi-platform patching. This example targets both amd64 and arm64 architectures and pushes the patched image.

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

--------------------------------

### Use Custom Scanner Plugin

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/scanner-plugins.md

Example of how to invoke Copacetic with a custom scanner plugin named 'foo'. Ensure the 'copa-foo' binary is executable and in your system's PATH.

```bash
copa patch --scanner foo --image $IMAGE ...
```

--------------------------------

### Run Patched Image

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/quick-start.md

Start a container from the patched image in detached mode and map port 8080 on the host to port 80 in the container. This is for testing the application's functionality.

```bash
docker run -d --name test-nginx -p 8080:80 $IMAGE-patched
```

--------------------------------

### Run Patched Image Locally

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/quick-start.md

Start a Docker container from the patched image and map port 8080 to the container's port 80. This allows for testing the application's functionality.

```bash
docker run -d --name test-nginx -p 8080:80 $IMAGE-patched
```

--------------------------------

### Troubleshoot Context Not Found Error

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/buildkit-frontend.md

Address the 'failed to read report from context' error by ensuring the report context is properly mounted. This example shows the correct arguments for Docker Buildx.

```bash
--build-arg report=report.json \
--build-context report=./build-context
```

--------------------------------

### Patch Specific Platforms in a Multi-Platform Image

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/multiplatform-patching.md

This example shows how to selectively patch only the specified platforms (e.g., linux/amd64 and linux/arm64) within a multi-platform Docker image. Other platforms will remain unchanged.

```bash
# Patch only linux/amd64 and linux/arm64 platforms
# Rest of the platforms will be preserved unchanged
copa patch --image $IMAGE \
  --platform linux/amd64,linux/arm64 \
  --tag nginx:1.25.0-patched
```

--------------------------------

### Deploy Website (SSH)

Source: https://github.com/project-copacetic/copacetic/blob/main/website/README.md

Builds the website and deploys it using SSH. Assumes SSH is configured for deployment.

```bash
$ USE_SSH=true yarn deploy
```

--------------------------------

### Run Demo Scripts Locally

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/demos.md

Instructions for running the provided demo scripts locally using bash. Assumes the demo scripts are located in the `demo/` directory.

```bash
cd demo
bash copa-demo-python.sh
```

--------------------------------

### Complete Bulk Patching Workflow

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/bulk-image-patching.md

Demonstrates the three-step workflow for bulk patching with skip detection. This includes initial patching, scanning, and a subsequent patch run with reports.

```bash
# 1. Initial bulk patch
copa patch --config bulk.yaml --push

# 2. Scan patched images (user's responsibility)
# Name files however you want - Copa reads ArtifactName from the JSON
trivy image registry.io/nginx:1.25.3-patched -f json -o reports/nginx-patched.json
trivy image registry.io/alpine:3.19-patched -f json -o reports/alpine-patched.json

# 3. Run bulk patch with skip detection
copa patch --config bulk.yaml --push -r ./reports
# Skips images with clean reports, re-patches images with vulnerabilities
```

--------------------------------

### Verify Build Context and Pipe to Docker

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/docker-build.md

Verify the generated context by listing its contents and then pipe it directly to `docker build` for creating a patched image.

```bash
# 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 -
```

--------------------------------

### Get Latest BuildKit Version

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/custom-address.md

This command retrieves the latest BuildKit version tag from GitHub releases, which can be used to pull the correct image.

```bash
# Get the latest BuildKit version from GitHub releases
export BUILDKIT_VERSION=$(curl -s https://api.github.com/repos/moby/buildkit/releases/latest | grep "tag_name:" | sed -E 's/.*"([^"]+)".*/\1/')
```

--------------------------------

### Create Build Context for Patching

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/buildkit-frontend.md

Prepare the build context directory by copying the vulnerability report and creating a Dockerfile. This is necessary for the Docker buildx build command.

```bash
mkdir build-context
cp report.json build-context/
touch build-context/Dockerfile
```

--------------------------------

### Debian Tooling Image Selection

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/faq.md

Copa selects Debian-based tooling images by stripping minor.patch versions and appending '-slim'. For example, nginx:1.21.6 results in debian:11-slim.

```text
ghcr.io/project-copacetic/copacetic/debian:11-slim
```

--------------------------------

### Build CLI

Source: https://github.com/project-copacetic/copacetic/blob/main/CLAUDE.md

Compiles the Copacetic command-line interface.

```bash
make build
```

--------------------------------

### Example DCO Commit Message

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/contributing.md

A commit message must include a 'Signed-off-by' line to certify adherence to the DCO. This line is typically added automatically by Git.

```text
This is my commit message

Signed-off-by: Random J Developer <random@developer.example.org>
```

--------------------------------

### Deploy Website (No SSH)

Source: https://github.com/project-copacetic/copacetic/blob/main/website/README.md

Builds the website and deploys it without using SSH. Requires specifying the GitHub username.

```bash
$ GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Run Bulk Patching and Push Results

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/bulk-image-patching.md

Executes bulk patching using a specified configuration file and pushes the patched images and manifest lists to the registry. Includes a job timeout.

```bash
copa patch --config ./copa-bulk-config.yaml --push --timeout 15m
```

--------------------------------

### Example LLB Graph JSON Output: Merging Node

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/development-tips.md

This JSON represents a merging operation node in the LLB graph, detailing its inputs and the merge operation itself.

```json
{
    "Op": {
        "inputs": [
            {
                "digest": "sha256:a86ddb9065d07c67dc838e11a81ff54020531c4ca2d85fb20574088222da8b30",
                "index": 0
            },
            {
                "digest": "sha256:1c3ad84c0de7e1384d727f6168db3f1f8fb632c0086760aff1786a7e89562d13",
                "index": 0
            },
            {
                "digest": "sha256:f337f99144ab75fee8593ec6531caa9ebace06aaca07614778b7c0ca5c816135",
                "index": 0
            }
        ],
        "Op": {
            "merge": {

```

--------------------------------

### Inspect Intermediate LLB Stage with SolveToDocker

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/development-tips.md

Add a call to `buildkit.SolveToDocker` at a specific LLB stage to generate a Docker image for inspection. This allows verification of the stage's output before proceeding with the build.

```go
busyBoxApplied := dm.config.ImageState.File(llb.Copy(toolImage, "/bin/busybox", "/bin/busybox"))
if err := buildkit.SolveToDocker(ctx, dm.config.Client, &busyBoxApplied, dm.config.ConfigData, dm.config.ImageName+"-busyBoxApplied"); err != nil {
    return nil, err

```

--------------------------------

### Check Platform-Specific Report Naming

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/buildkit-frontend.md

Verify platform-specific report file naming conventions when no report is found for the expected platform. For example, 'linux-amd64.json' is expected for the linux/amd64 platform.

```bash
# Error: no report found for platform
# Solution: Check platform-specific report file naming
# Expected: linux-amd64.json for linux/amd64 platform
```

--------------------------------

### Run BuildKit in a Podman Container and Connect Copa

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/custom-address.md

This snippet demonstrates running BuildKit in a detached Podman container and then configuring Copa to connect to it using the podman-container address format.

```bash
podman run \
    --detach \
    --rm \
    --privileged \
    --name buildkitd \
    --entrypoint buildkitd \
    "moby/buildkit:$BUILDKIT_VERSION"

# Connect Copa to Podman-managed BuildKit
copa patch -i docker.io/library/nginx:1.21.6 -r nginx.1.21.6.json -t 1.21.6-patched --addr podman-container://buildkitd
```

--------------------------------

### PatchConfig Example with Target Registry

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/bulk-image-patching.md

Configure global target registry for all patched images. Copa automatically extracts the image name from the source and appends it to the target registry.

```yaml
apiVersion: copa.sh/v1alpha1
kind: PatchConfig

# Global target: all patched images go to ghcr.io/myorg
target:
  registry: "ghcr.io/myorg"

images:
  - name: "redis"
    image: "quay.io/opstree/redis"  # Source: quay.io/opstree/redis
    tags:
      strategy: "list"
      list: ["v8.2.1"]
    # Result: patched image pushed to ghcr.io/myorg/redis:v8.2.1-patched
```

--------------------------------

### Build Static Website

Source: https://github.com/project-copacetic/copacetic/blob/main/website/README.md

Generates the static content for the website into the 'build' directory. This output can be hosted anywhere.

```bash
$ yarn build
```

--------------------------------

### Example LLB Graph JSON Output: Diffing Node

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/development-tips.md

This JSON snippet illustrates a diffing operation node within the LLB graph, showing its inputs and metadata.

```json
{
    "Op": {
        "inputs": [
            {
                "digest": "sha256:cbc31a96266caa8cd5ced38a1f8e97de9f13fafb23dbe9e342125569cd4d5018",
                "index": 0
            },
            {
                "digest": "sha256:9f798b2e38e054aadf1ee66c7eb7230c65be324c26d8739a3d5fa2d5da90e5de",
                "index": 0
            }
        ],
        "Op": {
            "diff": {
                "lower": {
                    "input": 0
                },
                "upper": {
                    "input": 1
                }
            }
        },
        "constraints": {}
    },
    "Digest": "sha256:f337f99144ab75fee8593ec6531caa9ebace06aaca07614778b7c0ca5c816135",
    "OpMetadata": {
        "caps": {
            "diffop": true
        }
    }
}
```

--------------------------------

### Example Dependency Conflict Error

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/app-level-patching.md

Illustrates a typical dependency conflict error encountered during application-level patching when package versions are incompatible. This highlights the need for manual dependency resolution.

```shell
#8 8.971 ERROR: Cannot install azure-cli and paramiko==3.4.0 because these package versions have conflicting dependencies.
#8 8.971
#8 8.971 The conflict is caused by:
#8 8.971     The user requested paramiko==3.4.0
#8 8.971     azure-cli-core 2.40.0 depends on paramiko<3.0.0 and >=2.0.8
#8 8.971
#8 8.971 To fix this you could try to:
#8 8.971 1. loosen the range of package versions you've specified
#8 8.971 2. remove package versions to allow pip attempt to solve the dependency conflict
```

--------------------------------

### Setting Custom Build Arguments

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/docker-build.md

Pass custom build arguments to `docker build` when using `copa generate`. This example sets the `HTTP_PROXY` build argument for the build process.

```bash
copa generate -i nginx:1.21.6 | docker build --build-arg HTTP_PROXY=http://proxy:8080 -t nginx:patched -
```

--------------------------------

### Patch Image with Docker Buildx

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/buildkit-frontend.md

Use Docker Buildx to create a build context, generate a vulnerability report, and then patch the image. Ensure BuildKit syntax is correctly set.

```bash
mkdir build-context

trivy image --format json --output build-context/report.json nginx:1.21.6

docker buildx create --name copa-builder

docker buildx build \
  --builder copa-builder \
  --build-arg BUILDKIT_SYNTAX=ghcr.io/project-copacetic/copacetic-frontend:latest \
  --build-arg image=docker.io/library/nginx:1.21.6 \
  --build-arg report=report.json \
  --build-context report=./build-context \
  --output type=image,name=nginx:1.21.6-patched \
  -f /dev/null \
  ./build-context

docker buildx rm copa-builder
rm build-context/report.json
rmdir build-context
```

--------------------------------

### Build multi-platform directory context

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/buildkit-frontend.md

Use this command for multi-platform patching when you have platform-specific vulnerability reports organized in a directory.

```bash
# Directory structure
reports/
├── linux-amd64.json
├── linux-arm64.json
└── linux-arm-v7.json

# Command
buildctl build \
  --opt report=. \
  --opt platform=linux/amd64,linux/arm64,linux/arm/v7 \
  --local report=./reports \
  --opt context:report=local:report \
  # ... other options
```

--------------------------------

### Run BuildKit in Podman Container

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/custom-address.md

This snippet demonstrates running BuildKit in a detached Podman container and connecting Copa to it using the `podman-container://` address format.

```bash
# Get the latest BuildKit version from GitHub releases
export BUILDKIT_VERSION=$(curl -s https://api.github.com/repos/moby/buildkit/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
```

```bash
podman run \
    --detach \
    --rm \
    --privileged \
    --name buildkitd \
    --entrypoint buildkitd \
    "moby/buildkit:$BUILDKIT_VERSION"
```

```bash
# Connect Copa to Podman-managed BuildKit
copa patch -i docker.io/library/nginx:1.21.6 -r nginx.1.21.6.json -t 1.21.6-patched --addr podman-container://buildkitd
```

--------------------------------

### Patch Python Image with Copa

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/demos.md

Demonstrates patching a Python 3.11 Alpine image, updating OS packages and pip dependencies. This example requires creating a BuildKit instance before patching.

```bash
# Step 1: Scan the image for vulnerabilities
trivy image --scanners vuln --pkg-types library --ignore-unfixed python:3.11-alpine

# Step 2: Export scan results to JSON
trivy image --scanners vuln --pkg-types os,library --ignore-unfixed -f json -o python-scan.json python:3.11-alpine

# Step 3: Create a BuildKit instance
docker buildx create --name copademo-python

# Step 4: Patch the image with Copa
COPA_EXPERIMENTAL=1 copa patch -i python:3.11-alpine \
    -r python-scan.json -t 3.11-alpine-patched -a buildx://copademo-python \
    --pkg-types os,library --library-patch-level major --ignore-errors --timeout 20m

# Step 5: Verify the fix
trivy image --scanners vuln --pkg-types library --ignore-unfixed python:3.11-alpine-patched
```

--------------------------------

### Patch Go Binaries and Rebuild Workflow

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/app-level-patching.md

This workflow demonstrates how to patch Go module files, extract them, rebuild the application, and create a new image with the updated binary. It highlights that Copa only updates go.mod and go.sum, requiring manual rebuilding.

```bash
# Step 1: Patch the image (updates go.mod/go.sum only)
copa patch -i myapp:1.0 -r scan.json --pkg-types library -t myapp:1.0-patched

# Step 2: Extract updated module files
docker run --rm myapp:1.0-patched cat /app/go.mod > go.mod
docker run --rm myapp:1.0-patched cat /app/go.sum > go.sum

# Step 3: Rebuild your application
go build -o myapp ./cmd/myapp

# Step 4: Create new image with rebuilt binary
docker build -t myapp:1.0-fully-patched .
```

--------------------------------

### Example LLB Graph JSON Output: Source Node

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/development-tips.md

This JSON represents an initial target image source node in the LLB graph. It includes the operation details, platform, and metadata.

```json
{
    "Op": {
        "Op": {
            "source": {
                "identifier": "docker-image://mcr.microsoft.com/oss/open-policy-agent/opa:0.46.0"
            }
        },
        "platform": {
            "Architecture": "amd64",
            "OS": "linux"
        },
        "constraints": {}
    },
    "Digest": "sha256:a86ddb9065d07c67dc838e11a81ff54020531c4ca2d85fb20574088222da8b30",
    "OpMetadata": {
        "caps": {
            "source.image": true
        }
    }
}
```

--------------------------------

### Run Unit Tests

Source: https://github.com/project-copacetic/copacetic/blob/main/CLAUDE.md

Executes all unit tests within the pkg directory, including code coverage reporting.

```bash
make test
```

--------------------------------

### Verify VCS Metadata in Binary

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/app-level-patching.md

Use the 'go version -m' command to check if VCS information, such as the Git revision and build time, is embedded in a binary.

```bash
go version -m /path/to/binary | grep vcs
# Expected output:
#   build   vcs=git
#   build   vcs.revision=abc123...
#   build   vcs.time=2024-01-01T00:00:00Z
```

--------------------------------

### Format Go Code

Source: https://github.com/project-copacetic/copacetic/blob/main/CLAUDE.md

Applies Go code formatting using gofumpt.

```bash
make format
```

--------------------------------

### Use Native Scanner Report

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.14.x/scanner-plugins.md

Example of how to use the 'native' scanner flag with Copacetic to submit a scan report in v1alpha1 format. Requires the '-r <report>' flag to specify the report file.

```bash
copa patch --scanner native -r <report> ...
```

--------------------------------

### Verify Build Context Output

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/docker-build.md

Before piping to Docker build, verify the generated context by saving it to a file and checking its contents. This helps ensure the context is valid and complete.

```bash
copa generate -i nginx:1.21.6 --output-context test.tar
tar -tf test.tar
copa generate -i nginx:1.21.6 | docker build -t nginx:patched -
```

--------------------------------

### Python Dependency Conflict Example

Source: https://github.com/project-copacetic/copacetic/blob/main/website/versioned_docs/version-v0.13.x/app-level-patching.md

This error message illustrates a dependency conflict that can occur during Python application-level patching when updated packages are incompatible with existing dependencies. Copa does not perform dependency resolution.

```shell
#8 8.971 ERROR: Cannot install azure-cli and paramiko==3.4.0 because these package versions have conflicting dependencies.
#8 8.971
#8 8.971 The conflict is caused by:
#8 8.971     The user requested paramiko==3.4.0
#8 8.971     azure-cli-core 2.40.0 depends on paramiko<3.0.0 and >=2.0.8
#8 8.971
#8 8.971 To fix this you could try to:
#8 8.971 1. loosen the range of package versions you've specified
#8 8.971 2. remove package versions to allow pip attempt to solve the dependency conflict
```