@@ -9,12 +9,13 @@ Copacetic (Copa) is a CLI tool that patches container image vulnerabilities usin
99## Folder Structure
1010- ` pkg/patch/ ` : CLI commands and core patching logic
1111- ` pkg/buildkit/ ` : BuildKit integration and platform discovery
12- - ` pkg/pkgmgr/ ` : Package manager adapters (dpkg, rpm, apk)
12+ - ` pkg/pkgmgr/ ` : OS package manager adapters (dpkg, rpm, apk)
13+ - ` pkg/langmgr/ ` : Language (application/library) package managers (e.g. Python/pip)
1314- ` pkg/report/ ` : Vulnerability report parsing and scanner plugin interface
1415- ` pkg/imageloader/ ` : Container engine integration (Docker, Podman)
1516- ` pkg/types/ ` : Type definitions and configurations
1617- ` website/docs/ ` : Project documentation and user guides
17- - ` integration/ ` : Integration tests for multi-arch and single-arch scenarios
18+ - ` integration/ ` : Integration tests for multi-arch and single-arch scenarios (OS + language flows)
1819- ` main.go ` : Root CLI setup with Cobra framework
1920
2021## Libraries and Frameworks
@@ -36,19 +37,63 @@ Copacetic (Copa) is a CLI tool that patches container image vulnerabilities usin
3637## Key Architecture Concepts
3738- ** Patching modes** : Targeted (with vulnerability reports) or comprehensive (all available updates)
3839- ** Multi-platform support** : Handles amd64, arm64, and other architectures with QEMU emulation
39- - ** Package managers** : Debian (apt/dpkg), RHEL (yum/rpm), Alpine (apk), Azure Linux (tdnf)
40+ - ** OS package managers** : Debian (apt/dpkg), RHEL family (yum/rpm/dnf/microdnf/tdnf), Alpine (apk), Azure Linux / CBL-Mariner (tdnf)
41+ - ** Language (application/library) patching** : Experimental support for upgrading vulnerable application dependencies (currently Python via pip) with semantic version / patch-level controls.
4042- ** BuildKit integration** : Uses LLB operations for image building and manipulation
4143- ** Scanner plugins** : Supports custom vulnerability scanners via ` customParseScanReport ` interface
44+ - ** Selective package types** : User can choose to patch only OS, only library, or both via ` --pkg-types ` .
4245
43- ## Supported Operating Systems & Package Managers
44- - ** Debian/Ubuntu** : Uses ` dpkg ` and ` apt `
45- - ** RHEL/CentOS/Rocky/Alma/Oracle/Amazon** : Uses ` rpm ` , ` yum ` , and ` dnf `
46- - ** Alpine** : Uses ` apk `
47- - ** CBL-Mariner/Azure Linux** : Uses ` rpm ` and ` tdnf `
46+ ## Supported Targets
47+ ### Operating Systems (OS package layer)
48+ - ** Debian/Ubuntu** : ` dpkg ` + ` apt `
49+ - ** RHEL/CentOS/Rocky/Alma/Oracle/Amazon** : ` rpm ` , ` yum ` , ` dnf ` , ` microdnf ` , ` tdnf ` (as available)
50+ - ** Alpine** : ` apk `
51+ - ** CBL-Mariner/Azure Linux** : ` rpm ` + ` tdnf `
52+
53+ ### Language / Application Dependencies (Experimental)
54+ - ** Python** : pip-based site-packages upgrades with version validation and patch-level selection.
55+ - Controlled via ` --pkg-types library ` (or ` os,library ` ) and ` --library-patch-level ` .
56+ - Patch levels: ` patch ` (default), ` minor ` , ` major ` ; influences chosen fixed version when multiple are available.
57+ - Special per-package overrides supported (see ` getSpecialPackagePatchLevels() ` inside Python manager for curated exceptions).
4858
4959## Key Functions
60+
61+ ### CLI / Orchestration
5062- ` Patch() ` : Main entry point for patching operations
5163- ` patchSingleArchImage() ` / ` patchMultiPlatformImage() ` : Core patching logic
5264- ` DiscoverPlatformsFromReference() ` / ` DiscoverPlatformsFromReport() ` : Platform discovery
53- - ` InstallUpdates() ` : Package manager interface for applying updates
5465- ` InitializeBuildkitConfig() ` : Initializes BuildKit configuration for patching operations
66+
67+ ### OS Package Layer
68+ - ` pkgmgr.GetPackageManager() ` and concrete managers' ` InstallUpdates() ` methods
69+ - ` GetUniqueLatestUpdates() ` (OS) for deduplicating + selecting latest OS package versions
70+
71+ ### Language / Library Layer
72+ - ` langmgr.GetLanguageManagers() ` returns appropriate language managers based on manifest content
73+ - ` pythonManager.InstallUpdates() ` coordinates: selecting versions, performing pip upgrades, validating results
74+ - ` langmgr.GetUniqueLatestUpdates() ` (libraries) similar to OS but tolerant of empty sets & patch-level filtering
75+ - ` FindOptimalFixedVersionWithPatchLevel() ` (Trivy parsing path) chooses best fixed version under patch-level constraint
76+
77+ ### Report Parsing & Filtering
78+ - ` report.TryParseScanReport() ` / Trivy parser: builds unified UpdateManifest (OS + Lang)
79+ - Filtering by ` --pkg-types ` occurs early and again before build execution for safety.
80+
81+ ### Validation & VEX
82+ - ` vex.TryOutputVexDocument() ` generates optional VEX documents (only if report + updates applied)
83+
84+ ## Language Patching
85+ Language/library patching is gated behind ` COPA_EXPERIMENTAL=1 ` .
86+
87+ - ` --pkg-types ` : comma list of ` os ` , ` library ` (default ` os ` ). Determines which sections of the UpdateManifest are acted upon.
88+ - ` --library-patch-level ` : one of ` patch|minor|major ` (default ` patch ` ). Sets semantic version boundary for chosen upgrade version.
89+ - Behavior when report only has library vulns:
90+ - If ` --pkg-types ` includes ` library ` , proceed (even if no OS updates). Empty OS set no longer triggers an error.
91+ - If ` --pkg-types os ` only, library updates are ignored (manifest language section cleared early).
92+
93+ ## Library Patching Flow (Python)
94+ 1 . Trivy report parsed -> vulnerable Python packages aggregated with all candidate fixed versions.
95+ 2 . Patch level rule applied to select optimal fixed version per package (with per-package override map for exceptions).
96+ 3 . Upgrade executed in ephemeral tooling container (derives base Python image tag when possible; fallback tag ` 3-slim ` ).
97+ 4 . Post-upgrade validation via ` pip freeze ` subset matching: ensures requested versions actually installed.
98+ 5 . Failed installs or mismatches collected; errors either propagate or are logged based on ` --ignore-errors ` .
99+ 6 . Validated updates merged into final manifest fed to VEX generation.
0 commit comments