From f5b0afd320a91b5871100bcd0c9cb37f87477f72 Mon Sep 17 00:00:00 2001 From: Sertac Ozercan Date: Mon, 9 Oct 2023 20:08:47 +0000 Subject: [PATCH 1/5] docs: add plugin docs Signed-off-by: Sertac Ozercan --- website/docs/scanner-plugins.md | 93 +++++++++++++++++++++++++++++++++ website/sidebars.js | 1 + 2 files changed, 94 insertions(+) create mode 100644 website/docs/scanner-plugins.md diff --git a/website/docs/scanner-plugins.md b/website/docs/scanner-plugins.md new file mode 100644 index 00000000..bbe79d69 --- /dev/null +++ b/website/docs/scanner-plugins.md @@ -0,0 +1,93 @@ +--- +title: Scanner Plugins +--- + +# Motivation + +By default, `copa` uses [Trivy](https://github.com/aquasecurity/trivy) to scan container images for vulnerabilities. However, we understand that different organizations have different requirements and may want to use different vulnerability scanners. + +`copa` is designed to be extensible to support different vulnerability scanners. Plugin architecture allows users to use the vulnerability scanner of their choice to patch container images without having to modify `copa`'s core codebase. + +# Usage + +Scanner plugin binaries must be in `$PATH` and should be prefixed with `copa-`. Copa will automatically detect and use the scanner plugin if it is in `$PATH`. + +For example, if you have a scanner plugin binary called `copa-foo` in `$PATH`, you can run `copa` with the following command: + +```bash +copa patch --scanner foo --image $IMAGE ... +``` + +# Community Scanner Plugins + +If you have built a scanner plugin and would like to add it to this list, please submit a PR to update this page. + +If you have any issues with a specific plugin, please open an issue in the applicable plugin's repository. + + +# Writing a Scanner Plugin + +Please see [Scanner Plugin Template](https://github.com/project-copacetic/scanner-plugin-template) for a template to write your own scanner plugin. + +Here are the steps to write your own scanner plugin: + +1. Clone [Scanner Plugin Template](https://github.com/project-copacetic/scanner-plugin-template) repo +2. Rename the `scanner-plugin-template` repo to the name of your plugin +3. Update applicable types for [`FakeReport`](types.go) to match your scanner's structure +4. Update [`parse`](main.go) to parse your scanner's report format accordingly +5. Update `CLI_BINARY` in the [`Makefile`](Makefile) to match your scanner's CLI binary name (resulting binary must be prefixed with `copa-`) +5. Update this [`README.md`](README.md) to match your plugin's usage + +# Scanner Plugin Interface + +Scanner plugins must implement the following interface: + +## v1alpha1 + +```go +type UpdateManifest struct { + // API version of the interface (e.g. v1alpha1) + APIVersion string `json:"apiVersion"` + // OS Type (e.g. debian, alpine, etc.) + OSType string `json:"osType"` + // OS Version (e.g. 11.3) + OSVersion string `json:"osVersion"` + // OS Architecture (e.g. amd64) + Arch string `json:"arch"` + // Package information + Updates UpdatePackages `json:"updates"` +} + +type UpdatePackages []UpdatePackage + +type UpdatePackage struct { + // Package name + Name string `json:"name"` + // Installed version + InstalledVersion string `json:"installedVersion"` + // Fixed version + FixedVersion string `json:"fixedVersion"` + // Vulnerability ID + VulnerabilityID string `json:"vulnerabilityID"` +} +``` + +From the above, we can see that the plugin must return a JSON object via standard out with the following fields. For example: + +```json +{ + "apiVersion": "v1alpha1", + "ostype": "debian", + "osversion": "11.3", + "arch": "amd64", + "updates": [ + { + "name": "libcurl4", + "installedVersion": "7.74.0-1.3+deb11u1", + "fixedVersion": "7.74.0-1.3+deb11u2", + "vulnerabilityID": "CVE-2021-22945" + }, + ... + ] +} +``` diff --git a/website/sidebars.js b/website/sidebars.js index e7f1259f..63483a46 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -21,6 +21,7 @@ const sidebars = { 'troubleshooting', 'design', 'faq', + 'scanner-plugins', 'contributing', 'code-of-conduct', 'github-action', From 3c15fc7030ca36fff94297a610773291fe9f9af4 Mon Sep 17 00:00:00 2001 From: Sertac Ozercan Date: Mon, 16 Oct 2023 23:15:57 +0000 Subject: [PATCH 2/5] update with new changes Signed-off-by: Sertac Ozercan --- website/docs/scanner-plugins.md | 75 +++++++++++++++++++++------------ 1 file changed, 49 insertions(+), 26 deletions(-) diff --git a/website/docs/scanner-plugins.md b/website/docs/scanner-plugins.md index bbe79d69..0fdf0287 100644 --- a/website/docs/scanner-plugins.md +++ b/website/docs/scanner-plugins.md @@ -44,31 +44,48 @@ Scanner plugins must implement the following interface: ## v1alpha1 -```go +```golang type UpdateManifest struct { // API version of the interface (e.g. v1alpha1) - APIVersion string `json:"apiVersion"` + APIVersion string `json:"apiVersion"` + // Metadata contains information about the OS and config + Metadata Metadata `json:"metadata"` + // Updates is a list of UpdatePackage that contains information about the package updates + Updates UpdatePackages `json:"updates"` +} + +// UpdatePackages is a list of UpdatePackage +type UpdatePackages []UpdatePackage + +// Metadata contains information about the OS and config +type Metadata struct { + OS OS `json:"os"` + Config Config `json:"config"` +} + +type OS struct { // OS Type (e.g. debian, alpine, etc.) - OSType string `json:"osType"` + Type string `json:"type"` // OS Version (e.g. 11.3) - OSVersion string `json:"osVersion"` - // OS Architecture (e.g. amd64) - Arch string `json:"arch"` - // Package information - Updates UpdatePackages `json:"updates"` + Version string `json:"version"` } -type UpdatePackages []UpdatePackage +// Config contains information about the config +type Config struct { + // OS Architecture (e.g. amd64) + Arch string `json:"arch"` +} +// UpdatePackage contains information about the package update type UpdatePackage struct { // Package name - Name string `json:"name"` + Name string `json:"name"` // Installed version - InstalledVersion string `json:"installedVersion"` + InstalledVersion string `json:"installedVersion"` // Fixed version - FixedVersion string `json:"fixedVersion"` + FixedVersion string `json:"fixedVersion"` // Vulnerability ID - VulnerabilityID string `json:"vulnerabilityID"` + VulnerabilityID string `json:"vulnerabilityID"` } ``` @@ -76,18 +93,24 @@ From the above, we can see that the plugin must return a JSON object via standar ```json { - "apiVersion": "v1alpha1", - "ostype": "debian", - "osversion": "11.3", - "arch": "amd64", - "updates": [ - { - "name": "libcurl4", - "installedVersion": "7.74.0-1.3+deb11u1", - "fixedVersion": "7.74.0-1.3+deb11u2", - "vulnerabilityID": "CVE-2021-22945" - }, - ... - ] + "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" + }, + ... + ] } ``` From 1db64b56e3c923d4596396336b8dc34437e502d2 Mon Sep 17 00:00:00 2001 From: Sertac Ozercan Date: Mon, 16 Oct 2023 23:15:57 +0000 Subject: [PATCH 3/5] update with new changes Signed-off-by: Sertac Ozercan --- website/docs/scanner-plugins.md | 81 +++++++++++++++++++++------------ 1 file changed, 53 insertions(+), 28 deletions(-) diff --git a/website/docs/scanner-plugins.md b/website/docs/scanner-plugins.md index bbe79d69..42a4bb32 100644 --- a/website/docs/scanner-plugins.md +++ b/website/docs/scanner-plugins.md @@ -6,7 +6,7 @@ title: Scanner Plugins By default, `copa` uses [Trivy](https://github.com/aquasecurity/trivy) to scan container images for vulnerabilities. However, we understand that different organizations have different requirements and may want to use different vulnerability scanners. -`copa` is designed to be extensible to support different vulnerability scanners. Plugin architecture allows users to use the vulnerability scanner of their choice to patch container images without having to modify `copa`'s core codebase. +Starting with v0.5.0 and later, `copa` offers extensibility to support different vulnerability scanners. Plugin architecture allows users to use the vulnerability scanner of their choice to patch container images without having to modify `copa`'s core codebase. # Usage @@ -20,10 +20,13 @@ copa patch --scanner foo --image $IMAGE ... # Community Scanner Plugins -If you have built a scanner plugin and would like to add it to this list, please submit a PR to update this page. +If you have built a scanner plugin and would like to add it to this list, please submit a PR to update this section with your plugin. + +:::tip If you have any issues with a specific plugin, please open an issue in the applicable plugin's repository. +::: # Writing a Scanner Plugin @@ -44,31 +47,48 @@ Scanner plugins must implement the following interface: ## v1alpha1 -```go +```golang type UpdateManifest struct { // API version of the interface (e.g. v1alpha1) - APIVersion string `json:"apiVersion"` + APIVersion string `json:"apiVersion"` + // Metadata contains information about the OS and config + Metadata Metadata `json:"metadata"` + // Updates is a list of UpdatePackage that contains information about the package updates + Updates UpdatePackages `json:"updates"` +} + +// UpdatePackages is a list of UpdatePackage +type UpdatePackages []UpdatePackage + +// Metadata contains information about the OS and config +type Metadata struct { + OS OS `json:"os"` + Config Config `json:"config"` +} + +type OS struct { // OS Type (e.g. debian, alpine, etc.) - OSType string `json:"osType"` + Type string `json:"type"` // OS Version (e.g. 11.3) - OSVersion string `json:"osVersion"` - // OS Architecture (e.g. amd64) - Arch string `json:"arch"` - // Package information - Updates UpdatePackages `json:"updates"` + Version string `json:"version"` } -type UpdatePackages []UpdatePackage +// Config contains information about the config +type Config struct { + // OS Architecture (e.g. amd64) + Arch string `json:"arch"` +} +// UpdatePackage contains information about the package update type UpdatePackage struct { // Package name - Name string `json:"name"` + Name string `json:"name"` // Installed version - InstalledVersion string `json:"installedVersion"` + InstalledVersion string `json:"installedVersion"` // Fixed version - FixedVersion string `json:"fixedVersion"` + FixedVersion string `json:"fixedVersion"` // Vulnerability ID - VulnerabilityID string `json:"vulnerabilityID"` + VulnerabilityID string `json:"vulnerabilityID"` } ``` @@ -76,18 +96,23 @@ From the above, we can see that the plugin must return a JSON object via standar ```json { - "apiVersion": "v1alpha1", - "ostype": "debian", - "osversion": "11.3", - "arch": "amd64", - "updates": [ - { - "name": "libcurl4", - "installedVersion": "7.74.0-1.3+deb11u1", - "fixedVersion": "7.74.0-1.3+deb11u2", - "vulnerabilityID": "CVE-2021-22945" - }, - ... - ] + "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" + } + ] } ``` From 6e1ddb72871a154206edd86896176a48d4cc8b70 Mon Sep 17 00:00:00 2001 From: Sertac Ozercan Date: Tue, 17 Oct 2023 16:13:43 +0000 Subject: [PATCH 4/5] update Signed-off-by: Sertac Ozercan --- website/docs/scanner-plugins.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/website/docs/scanner-plugins.md b/website/docs/scanner-plugins.md index 42a4bb32..6f98f9d5 100644 --- a/website/docs/scanner-plugins.md +++ b/website/docs/scanner-plugins.md @@ -18,7 +18,7 @@ For example, if you have a scanner plugin binary called `copa-foo` in `$PATH`, y copa patch --scanner foo --image $IMAGE ... ``` -# Community Scanner Plugins +# Scanner Plugins from the Community If you have built a scanner plugin and would like to add it to this list, please submit a PR to update this section with your plugin. @@ -28,18 +28,11 @@ If you have any issues with a specific plugin, please open an issue in the appli ::: -# Writing a Scanner Plugin - -Please see [Scanner Plugin Template](https://github.com/project-copacetic/scanner-plugin-template) for a template to write your own scanner plugin. +- Grype: https://github.com/anubhav06/copa-grype -Here are the steps to write your own scanner plugin: +# Writing a Scanner Plugin -1. Clone [Scanner Plugin Template](https://github.com/project-copacetic/scanner-plugin-template) repo -2. Rename the `scanner-plugin-template` repo to the name of your plugin -3. Update applicable types for [`FakeReport`](types.go) to match your scanner's structure -4. Update [`parse`](main.go) to parse your scanner's report format accordingly -5. Update `CLI_BINARY` in the [`Makefile`](Makefile) to match your scanner's CLI binary name (resulting binary must be prefixed with `copa-`) -5. Update this [`README.md`](README.md) to match your plugin's usage +Please see instructions at [Scanner Plugin Template](https://github.com/project-copacetic/scanner-plugin-template) for a template to get started with writing a scanner plugin. # Scanner Plugin Interface @@ -75,7 +68,7 @@ type OS struct { // Config contains information about the config type Config struct { - // OS Architecture (e.g. amd64) + // OS Architecture (e.g. amd64, arm64) Arch string `json:"arch"` } From 04f24b7d9a6baa347a96f01c3f5430a42c0d4cfe Mon Sep 17 00:00:00 2001 From: Sertac Ozercan Date: Tue, 17 Oct 2023 23:50:55 +0000 Subject: [PATCH 5/5] update with comments Signed-off-by: Sertac Ozercan --- website/docs/scanner-plugins.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/website/docs/scanner-plugins.md b/website/docs/scanner-plugins.md index 6f98f9d5..c46163bf 100644 --- a/website/docs/scanner-plugins.md +++ b/website/docs/scanner-plugins.md @@ -10,7 +10,7 @@ Starting with v0.5.0 and later, `copa` offers extensibility to support different # Usage -Scanner plugin binaries must be in `$PATH` and should be prefixed with `copa-`. Copa will automatically detect and use the scanner plugin if it is in `$PATH`. +Scanner plugin binaries must be in `$PATH`, and should be prefixed with `copa-` and have executable permissions. Copa will automatically detect and use the scanner plugin if it is in `$PATH`. For example, if you have a scanner plugin binary called `copa-foo` in `$PATH`, you can run `copa` with the following command: @@ -22,7 +22,7 @@ copa patch --scanner foo --image $IMAGE ... If you have built a scanner plugin and would like to add it to this list, please submit a PR to update this section with your plugin. -:::tip +:::note If you have any issues with a specific plugin, please open an issue in the applicable plugin's repository. @@ -36,6 +36,12 @@ Please see instructions at [Scanner Plugin Template](https://github.com/project- # Scanner Plugin Interface +:::note + +`alpha` versions of the API are not guarenteed to be backwards compatible. Once the API graduates to `beta` and `stable`, it will be backwards compatible. + +::: + Scanner plugins must implement the following interface: ## v1alpha1