diff --git a/content/chainguard/libraries/go/build-configuration.md b/content/chainguard/libraries/go/build-configuration.md index d8fe72c3e8..123c0823fe 100644 --- a/content/chainguard/libraries/go/build-configuration.md +++ b/content/chainguard/libraries/go/build-configuration.md @@ -4,7 +4,7 @@ linktitle: "Configure build tools" description: "Configuring Chainguard Libraries for Go on your workstation" type: "article" date: 2026-09-25T00:00:00+00:00 -lastmod: 2026-10-14T14:52:48+00:00 +lastmod: 2026-10-14T16:30:14+00:00 draft: false tags: ["Chainguard Libraries", "Go"] menu: @@ -17,7 +17,7 @@ toc: true Chainguard Libraries for Go implements the standard [GOPROXY protocol](https://go.dev/ref/mod#goproxy-protocol). To use it, configure Go to retrieve modules through the Chainguard Go module proxy. -This page is a reference for configuring Go projects and CI/CD environments. It covers authentication, proxy configuration, cache clearing, and verification.. Apply these changes on every workstation and build server that downloads Go modules, including CI/CD systems such as GitHub Actions, Jenkins, and TeamCity. +This page is a reference for configuring Go projects and CI/CD environments. It covers authentication, proxy configuration, cache clearing, verification, and using Chainguard-remediated module versions. Apply these changes on every workstation and build server that downloads Go modules, including CI/CD systems such as GitHub Actions, Jenkins, and TeamCity. The Chainguard Go module proxy endpoint, `https://libraries.cgr.dev/go`, is also the [Chainguard Repository](/chainguard/chainguard-repository/overview/) endpoint for Go. It serves requested versions from upstream [under Chainguard security controls](/chainguard/libraries/introduction/overview/#upstream-fallback-and-controls). @@ -94,6 +94,14 @@ Check the effective configuration: go env GOPROXY GONOSUMDB GOSUMDB ``` +### Checksum database settings + +Chainguard-remediated versions are not available from public upstream origins, so they cannot be verified by the public Go checksum database. `GONOSUMDB=*` tells Go not to use the public checksum database for modules retrieved through the configured proxy. The authenticated HTTPS proxy and the project’s `go.sum` file continue to protect module retrieval. + +Do not use `GOPRIVATE` for modules that should be retrieved through Chainguard. `GOPRIVATE` also sets `GONOPROXY` and can cause Go to bypass Chainguard. + +Do not use `GONOSUMCHECK`; it is not a current Go configuration variable. + ## Verify the configuration Use a clean module cache when testing the configuration for the first time. This prevents previously cached modules from hiding proxy or authentication problems: @@ -120,3 +128,23 @@ go mod verify ``` A successful `go mod verify` confirms that the downloaded module content matches the checksums recorded in `go.sum`. + +### Use remediated Go versions + +Chainguard-remediated Go versions use the `-cgr.N` prerelease suffix. For example: `v1.2.5-cgr.1`. + +A remediated version is a distinct module source archive. It does not replace the upstream bytes for another version. + +Go does not select `-cgr.N` versions automatically through `@latest`, minimal version selection, or `go get -u`. Adopt a remediated version explicitly: + +```bash +go get example.com/module@v1.2.5-cgr.1 +go mod tidy +go mod verify +``` + +Replace the module path and version with the remediated version available for your dependency. You can also update the require directive in `go.mod` directly: + +```bash +require example.com/module v1.2.5-cgr.1 +``` diff --git a/content/chainguard/libraries/go/global-configuration.md b/content/chainguard/libraries/go/global-configuration.md index f802d678c7..fcd03434ef 100644 --- a/content/chainguard/libraries/go/global-configuration.md +++ b/content/chainguard/libraries/go/global-configuration.md @@ -4,7 +4,7 @@ linktitle: "Global configuration" description: "Configuring Chainguard Libraries for Go in your organization" type: "article" date: 2026-09-25T00:00:00+00:00 -lastmod: 2026-09-29T19:14:43+00:00 +lastmod: 2026-10-14T16:30:14+00:00 draft: false tags: ["Chainguard Libraries", "Go"] images: [] @@ -121,3 +121,9 @@ If validation fails, review the following settings: Use the URL of the `go-all` virtual repository in Go configuration. In Artifactory, select the `go-all` repository and use **Set Me Up** or **Generate Settings** to obtain the URL and authentication instructions for your Artifactory version. The URL commonly has the following form: `https://exampleorg.jfrog.io/artifactory/go-all`. See [Configuring your build tool](/chainguard/libraries/go/build-configuration/#repository-manager) for more information. + +## Serve remediated Go versions + +Chainguard-remediated Go versions use the `-cgr.N` prerelease suffix, such as `v1.2.5-cgr.1`, and are served through the same `https://libraries.cgr.dev/go/` endpoint as every other module. Unlike Chainguard Libraries for Python and Java, which publish remediated artifacts in a separate repository, Go remediated versions need no additional repository in your repository manager. The `go-chainguard` remote and `go-all` virtual repository already serve them. + +Remediated versions reach developers through the same `go-all` endpoint you configured earlier. Because Go does not resolve `-cgr.N` prereleases automatically, developers select a remediated version explicitly with a `replace` directive in `go.mod` or with `go get`. See [Use remediated Go versions](/chainguard/libraries/go/build-configuration/#use-remediated-go-versions) for the selection workflow. diff --git a/content/chainguard/libraries/go/migration.md b/content/chainguard/libraries/go/migration.md index d804630a4e..ae79aec987 100644 --- a/content/chainguard/libraries/go/migration.md +++ b/content/chainguard/libraries/go/migration.md @@ -4,7 +4,7 @@ type: "article" linktitle: "Migrate to Chainguard" description: "How to migrate an existing Go project to pull dependencies from Chainguard Libraries" date: 2026-09-25T00:00:00+00:00 -lastmod: 2026-10-14T15:52:37+00:00 +lastmod: 2026-10-14T16:30:14+00:00 draft: false tags: ["Chainguard Libraries", "Go"] menu: @@ -181,3 +181,23 @@ go mod verify ``` After the build succeeds, inspect `go env GOPROXY` and your build logs to confirm that module requests are going through Chainguard. Keep the generated `go.sum` file with the project if it is part of your existing dependency-management workflow. + +## Step 5: Adopt remediated versions explicitly + +Chainguard-remediated Go versions use the `-cgr.N` prerelease suffix. Go does not select these versions through `@latest` or `go get -u`, so you must request the version explicitly. + +For example: + +```bash +go get example.com/module@v1.2.5-cgr.1 +go mod tidy +go mod verify +``` + +You can also update the `require` directive in `go.mod` directly: + +```bash +require example.com/module v1.2.5-cgr.1 +``` + +Use the module version listed by Chainguard for the CVE remediation you want to adopt. A remediated version is a distinct source archive; it does not replace the upstream bytes for another version. diff --git a/content/chainguard/libraries/go/overview.md b/content/chainguard/libraries/go/overview.md index f7674b52e0..7269647541 100644 --- a/content/chainguard/libraries/go/overview.md +++ b/content/chainguard/libraries/go/overview.md @@ -4,7 +4,7 @@ linktitle: "Go overview" description: "Go modules for your application development" type: "article" date: 2026-09-25T00:00:00+00:00 -lastmod: 2026-10-14T18:18:18+00:00 +lastmod: 2026-10-14T16:30:14+00:00 draft: false tags: ["Chainguard Libraries", "Go", "Overview"] menu: @@ -38,6 +38,42 @@ When a Go command requests a module, Chainguard resolves the request through the The `/go` endpoint is the endpoint you configure in `GOPROXY`. It uses the standard Go module proxy paths for version lists, metadata, `go.mod` files, and module source archives. Go builds from source on the customer side. Unlike ecosystems that distribute prebuilt language artifacts, Chainguard Libraries for Go distributes module source archives. A CVE-remediated module is published as a distinct Go version rather than replacing the upstream bytes for the same version. +## CVE remediation + +Chainguard Libraries for Go can provide backported fixes for high and critical CVEs in older module versions when upgrading to a newer upstream release is not practical. + +Remediated Go versions use the `-cgr.N` prerelease suffix. For example, a remediated build of upstream `v1.2.5` is `v1.2.5-cgr.1`. + +The `-cgr.N` suffix identifies a Chainguard-remediated source archive, while the incremented prerelease ensures that vulnerability scanners recognize the remediated version as a fix for upstream `v1.2.5`. A remediated version is a distinct module source archive; it does not replace the upstream bytes for another version. + +Because `-cgr.N` versions are prereleases, Go’s minimal version selection and `@latest` do not select them automatically. Use a [`replace` directive](https://go.dev/ref/mod#go-mod-file-replace) in `go.mod` to pin a dependency to its remediated version: + +```bash +require example.com/module v1.2.5 +replace example.com/module v1.2.5 => example.com/module v1.2.5-cgr.1 +``` + +This version-specific form replaces upstream v1.2.5 wherever it is selected, including as a transitive dependency. To force the remediated version regardless of the selected upstream version, omit the old version from the directive: + +```bash +replace example.com/module => example.com/module v1.2.5-cgr.1 +``` + +Replace the module path and versions with the remediated version available for your dependency. After adding or updating a replace directive, run: + +```bash +go mod tidy +go mod verify +``` + +You can also select the remediated version directly with `go get`, but use `replace` when you need a stable project-level pin: + +```bash +go get example.com/module@v1.2.5-cgr.1 +go mod tidy +go mod verify +``` + ## Go checksum verification Chainguard-remediated versions are not recorded in the public Go checksum database because they are not available from public upstream origins. Configure Go to skip public checksum verification for modules retrieved through Chainguard: diff --git a/content/chainguard/libraries/policies-and-security/cve-remediation.md b/content/chainguard/libraries/policies-and-security/cve-remediation.md index a65ecad680..31a92562fa 100644 --- a/content/chainguard/libraries/policies-and-security/cve-remediation.md +++ b/content/chainguard/libraries/policies-and-security/cve-remediation.md @@ -4,7 +4,7 @@ linktitle: "CVE remediation" description: "An overview of the CVE remediation feature for Chainguard Libraries" type: "article" date: 2025-09-11 -lastmod: 2026-10-02T16:25:03+00:00 +lastmod: 2026-10-14T16:30:14+00:00 draft: false tags: ["Chainguard Libraries", "CVE"] menu: @@ -28,7 +28,7 @@ quickly, especially when moving to a newer version would introduce disruptive changes. Remediated artifacts are published as incremental patch versions, allowing teams to take a targeted fix for a CVE without taking on a broader upgrade at the same time. CVE remediation is available for a subset of [Chainguard Libraries for -Python](/chainguard/libraries/python/overview/), [Chainguard Libraries for Java](/chainguard/libraries/java/overview/) (available in private preview), and [Chainguard Libraries for JavaScript](/chainguard/libraries/javascript/overview/). If you want to request CVE +Python](/chainguard/libraries/python/overview/), [Chainguard Libraries for Java](/chainguard/libraries/java/overview/) (available in private preview), [Chainguard Libraries for JavaScript](/chainguard/libraries/javascript/overview/), and [Chainguard Libraries for Go](/chainguard/libraries/go/overview/) (available in beta). If you want to request CVE remediation for additional libraries, reach out to your account team. ## About CVE remediation @@ -66,6 +66,12 @@ For JavaScript, remediated artifacts use a `-cgr.N` suffix appended to the base Because `-cgr.N` is an npm prerelease identifier, it must not be treated as a newer ordinary release by npm semver resolution. The JavaScript build integration selects the remediated artifact while preserving the dependency version requested by the application. +#### Go version naming + +For Go, remediated versions use a `-cgr.N` prerelease suffix appended to the base version. For example, a remediated build of `v1.2.5` is published as `v1.2.5-cgr.1`. + +Because `-cgr.N` is a Go prerelease identifier, Go's minimal version selection and `@latest` don't select it automatically. You select a remediated version explicitly with a `replace` directive in `go.mod` or with `go get`. A remediated version is a distinct module source archive; it doesn't replace the upstream bytes for another version. + ### Remediation and transitive dependencies **Python** @@ -113,6 +119,25 @@ Re-run `chainctl libraries remediate` after every install or dependency update s Unlike Python, JavaScript remediation does not rely on a remediated index selecting a higher-precedence version. Unlike Java, it does not depend on BOM updates to propagate remediation through the dependency tree. +**Go** + +Go remediation propagates through explicit version selection in `go.mod` rather than through index precedence, BOM updates, or metadata rewrites. Because `-cgr.N` versions are prereleases, you choose them deliberately. + +A version-specific `replace` directive substitutes the remediated version wherever the upstream version is selected, including as a transitive dependency: + +```bash +require example.com/module v1.2.5 +replace example.com/module v1.2.5 => example.com/module v1.2.5-cgr.1 +``` + +To force the remediated version regardless of the upstream version selected, omit the old version from the directive: + +```bash +replace example.com/module => example.com/module v1.2.5-cgr.1 +``` + +After adding or updating a replace directive, run `go mod tidy` and `go mod verify`. Because Chainguard-remediated versions are not recorded in the public Go checksum database, you must also configure Go to skip public checksum verification for modules retrieved through Chainguard. For the full configuration, see the [Go overview](/chainguard/libraries/go/overview/#cve-remediation). + ### CVE remediation for vendored dependencies Some Python packages bundle compiled code written in other languages (such as Go, Rust, or C/C++) directly into their wheel. When a CVE exists in a dependency of that @@ -133,6 +158,7 @@ Remediated libraries are published in dedicated repositories: - Python: In a PyPI-compatible index at `https://libraries.cgr.dev/python-remediated/` - the simple index is at `https://libraries.cgr.dev/python-remediated/simple/` - Java: In a repository at `https://libraries.cgr.dev/java-remediated/` - a companion to the standard Chainguard Libraries for Java repository at `https://libraries.cgr.dev/java/` - JavaScript: Consume remediated artifacts through the standard JavaScript endpoint: `https://libraries.cgr.dev/javascript/`. +- Go: Consume remediated versions through the standard Go module proxy endpoint: `https://libraries.cgr.dev/go/`. You can: diff --git a/content/chainguard/libraries/troubleshooting/faq.md b/content/chainguard/libraries/troubleshooting/faq.md index c4439767d0..4951a91b8c 100644 --- a/content/chainguard/libraries/troubleshooting/faq.md +++ b/content/chainguard/libraries/troubleshooting/faq.md @@ -4,7 +4,7 @@ linktitle: "FAQ" description: "Frequently asked questions about Chainguard Libraries, including security benefits, supported ecosystems, and how automated patching protects against supply chain attacks" type: "article" date: 2025-03-25T08:04:00+00:00 -lastmod: 2026-10-08T13:25:53+00:00 +lastmod: 2026-10-14T16:30:14+00:00 draft: false tags: ["Chainguard Libraries", "Overview"] aliases: @@ -197,6 +197,11 @@ SLSA‑aligned build environment, and publishes them to hardened registries for customers to consume. This closes off most supply chain malware vectors compared to pulling directly from public registries like Maven Central, npm, and PyPI. +For Go, Chainguard serves module source archives through an authenticated proxy +with the same malware and greyware scanning and policy controls, rather than +rebuilding prebuilt artifacts, because Go modules are distributed as source and +compiled on the customer side. + [CVE remediation](/chainguard/libraries/policies-and-security/cve-remediation/) is an additional feature where Chainguard backports High and Critical vulnerability fixes from newer upstream releases to older versions that customers are still using, @@ -220,6 +225,11 @@ builds from non‑remediated upstream versions, but how you select them differs: Rather than relying on version precedence, the command sets the exact `-cgr.N` version for direct dependencies and adds override or resolution rules for transitive ones, then updates the lockfile. +* **Go**: A `-cgr.N` prerelease suffix (for example, `v1.2.5-cgr.1`), served + through the standard endpoint at `https://libraries.cgr.dev/go/`. Because Go + treats `-cgr.N` as a prerelease, minimal version selection and `@latest` do + not select it automatically. You select a remediated version explicitly with a + `replace` directive in `go.mod` or with `go get`. ## Why might I still see errors with the upstream fallback enabled through the Chainguard Repository? @@ -254,7 +264,7 @@ Chibbies](https://www.youtube.com/watch?v=adfU9LJg3I0&t=2843s). ## JFrog Artifactory troubleshooting -The following questions apply to repo manager configurations for Chainguard Libraries, using JFrog Artifactory. Learn more about using a repo manager in the global configuration pages for each ecosystem: [Java](/chainguard/libraries/java/global-configuration/), [JavaScript](/chainguard/libraries/javascript/global-configuration/), [Python](/chainguard/libraries/python/global-configuration/). +The following questions apply to repo manager configurations for Chainguard Libraries, using JFrog Artifactory. Learn more about using a repo manager in the global configuration pages for each ecosystem: [Go](/chainguard/libraries/go/global-configuration/), [Java](/chainguard/libraries/java/global-configuration/), [JavaScript](/chainguard/libraries/javascript/global-configuration/), [Python](/chainguard/libraries/python/global-configuration/). ### What are the most common setup mistakes when using Artifactory with Chainguard Libraries?