copacetic - 🧵 CLI tool for directly patching container images!

项目说明

Project Copacetic: Directly patch container image

!GitHub
![codecov]()
![OpenSSF Best Practices]()
![OpenSSF Scorecard]()

<img src="./images/copa-color.png" alt="Copa logo" width="25%" />
<br>
<br>

copa is a CLI tool written in Go and based on buildkit that can be used to directly patch container images without full rebuilds. copa can also patch container images using the scanning results from popular tools like Trivy.

For more details and how to get started, please refer to full documentation.

Ubuntu Chiseled images

Copa supports both apt-less Ubuntu images that retain a full
/var/lib/dpkg/status file and nati images that contain
/var/lib/chisel/manifest.wall. Full-status images support report-driven and
comprehensi. Nati images support comprehensi
only; omit --report so Copa can re-cut every installed slice.

For native manifest.wall images, use --chisel-release to select a named
release such as ubuntu-24.04, a local release directory, or a public HTTPS Git
URL with a mandatory pinned commit or tag fragment. Without an o, Copa
infers
ubuntu-<> from the target's /etc/os-release. Initial support uses
public archives only. As on July 31, 2026 with Copa's pinned Trivy
(v0.69.3), Trivy does not extract OS package in from native
manifest.wall files.
See Ubuntu Chiseled image
patching for behavior and limitations.

Demo

!intro

Why?

We needed the ability to patch containers quickly without going upstream for a full rebuild. As the window between disclosure and acti continues to narrow, there is a growing operational need to patch critical security in container images so they can be quickly redeployed into production. The need is especially acute when those are:

inherited from base images several levels deep and waiting on updated releases to percolate through the supply chain is not an option

found in 3rd party app images you don't maintain with update cadences that don't meet your security SLAs.

!direct image patching

In addition to filling the operational gap not met by left-shift security practices and tools, the ability of copa to patch a container without requiring a rebuild of the container image provides other benefits:

Allows users other than the image publishers to also patch container images, such as De engineers.

Reduces the storage and transmission costs of redistributing patched images by only creating an additional patch layer, instead of rebuilding the entire image which usually results in different layer hashes that break layer caching.

Reduces the turnaround time for patching a container image by not having to wait for base image updates and being a faster operation than a full image rebuild.

Reduces the complexity of patching the image from running a rebuild pipeline to running a single tool on the image.

How?

The copa tool is an extensible engine that:

1. Determines the update scope from a supported report or, for a comprehensi, from package metadata in the target image.
2. Obtains and processes the updates using the appropriate package-manager tooling or Chisel release definitions. New adapters can be written to support more package managers and report formats.
3. Applies the resulting update binaries to the container image using buildkit.

!report-dri patching

This approach is motivated by the core principles of making direct container patching broadly applicable and accessible:

Copa supports patching _existing_ container images.

- Devs don't need to build their images using specific tools or modify them in some way just to support container patching.

Copa works with the existing scanning and mitigation ecosystems.

- Image publishers don't need to create new workflows for container patching since Copa supports patching container images using the security update packages already being published today.
- Consumers do not need to migrate to a new and potentially more limited support ecosystem for custom distros or change their container scanning pipelines to include remediation, since Copa can be integrated seamlessly as an extra step to patch containers based on those scanning reports.

Copa reduces the technical expertise needed and waiting on dependencies needed to patch an image.

- For OS package , no specialized knowledge about a specific image is needed to be patch it as Copa relies on the remediation knowledge already embedded in the reports produced by popular container scanning tools today.

Contributing

There are several ways to get in:
* Join the mailing list to get notifications for releases, security announcements, etc.
* Join the biweekly community meetings to discuss de, issues, use cases, etc.
* Join the #copacetic channel on the CNCF Slack.

The project welcomes contributions and suggestions that abide by the CNCF Code of Conduct.

项目信息

开发语言：Go

Star 数：1722

技术要点

该项目属于漏洞知识库方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕🧵 CLI tool for directly patching container images!展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。