Java CVE remediation docs

content/chainguard/libraries/cve-remediation.md

@@ -14,22 +14,19 @@ weight: 006
 toc: true
 ---
 
-CVE remediation is a feature in Chainguard Libraries that provides security
-protection against critical and high CVEs, while medium or low CVEs are not
-considered. Applications often rely on older versions of libraries, but upstream
-maintainers may not apply and release patches for those versions. CVE
-remediation addresses this gap by applying vulnerability fixes from newer
-releases to older releases, particularly in cases where maintainers are no
-longer able to support and provide fixes.
+CVE remediation for Chainguard Libraries provides protection against
+critical and high CVEs. Applications often rely on older versions of libraries,
+but upstream maintainers may not apply and release patches for those versions.
+Chainguard addresses this gap by backporting vulnerability fixes
+from newer releases to older releases, particularly in cases where maintainers
+are no longer able to support and provide fixes.
 
 CVE remediation helps reduce risk for organizations that cannot always upgrade
-quickly, especially when a larger upgrade to newer versions forces often disruptive
-changes. CVE remediation makes multiple incremental patch versions of affected
-older versions available, allowing a very minor upgrade that only
-addresses the CVE, but does not introduce other changes.
+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/). If you want to request CVE
+Python](/chainguard/libraries/python/overview/) and [Chainguard Libraries for Java](/chainguard/libraries/java/overview/) (available in private preview). If you want to request CVE
 remediation for additional libraries, reach out to your account team.
 
 ## About CVE remediation
@@ -49,6 +46,14 @@ provides the option to make remediated versions available for your development
 or opt out of using these versions completely and continue to use upstream
 versions only.
 
+### Remediated version naming
+
+Chainguard publishes remediated versions using ecosystem-specific version suffixes.
+
+For Python, remediated packages use a `+cgr.N` local version suffix. For example, if `flask==1.1.2` has a remediated build, Chainguard publishes it as `flask==1.1.2+cgr.1`. Python package managers treat this as a higher-precedence local version of the base release, so remediated versions can be selected automatically during dependency resolution when the remediated index is configured.
+
+For Java, remediated artifacts use a `-0.cgr.N` suffix appended to the base version. For example, if `org.apache.commons:commons-lang3:3.18.0` has a remediated build, that build is published as org.apache.`commons:commons-lang3:3.18.0-0.cgr.1`. If Chainguard publishes another remediated iteration for the same base version, the trailing number increases, such as `-0.cgr.2` or `-0.cgr.3`.
+
 ### 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
@@ -65,24 +70,23 @@ in their results.
 
 ## Browse libraries with CVE remediation
 
-Remediated libraries are published in a dedicated PyPI-compatible index: `https://libraries.cgr.dev/python-remediated/` (simple index at `https://libraries.cgr.dev/python-remediated/simple/`). 
+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/`
 
 You can:
 - Browse them in the Chainguard Console
 - Use the public VEX feed to understand what has been remediated
-    - This feed only covers backported Python-level CVEs, but does not include [vendored dependencies](#cve-remediation-for-vendored-dependencies).
+    - This feed does not include [vendored dependencies](#cve-remediation-for-vendored-dependencies).
 - View them in a browser at the simple index URL
-    - Learn more in [Python Overview > Manual access](/chainguard/libraries/python/overview/#manual-access).
+    - Learn more in [Python Overview > Manual access](/chainguard/libraries/python/overview/#manual-access) and in [Java Overview > Manual access](/chainguard/libraries/java/overview/#manual-access).
 - Expose them to your developers via a repo manager 
-    - Learn more in the Python global configuration docs:
-        - [JFrog Artifactory](/chainguard/libraries/python/global-configuration/#jfrog-artifactory)
-        - [Cloudsmith](/chainguard/libraries/python/global-configuration/#cloudsmith)
-        - [Sonatype Nexus](/chainguard/libraries/python/global-configuration/#sonatype-nexus-repository)
+    - Learn more in the global configuration docs for [Python](/chainguard/libraries/python/global-configuration/) and [Java](/chainguard/libraries/java/global-configuration/).
 
 
 ### Browse remediated libraries in the Chainguard Console
 
-In the Chainguard Console, navigate to the Python libraries, then click the **Remediated** tab. Click into a library to see which versions have remediated CVEs.
+In the Chainguard Console, navigate to the Python or Java libraries, then click the **Remediated** tab. Click into a library to see which versions have remediated CVEs.
 
 Learn more in [Browsing Chainguard libraries](/chainguard/libraries/browse/).
 

content/chainguard/libraries/java/build-configuration.md

@@ -34,7 +34,11 @@ other engineers running relevant application builds. They must also be performed
 on any build server such as Jenkins, TeamCity, GitHub or other infrastructure
 that builds the applications or otherwise downloads and uses relevant libraries.
 
-## Cloudsmith
+## Library access approaches 
+
+### Repo manager
+
+#### Cloudsmith
 
 Build configuration to retrieve artifacts from Cloudsmith requires you to
 authenticate. Use your username and password for Cloudsmith in your build tool
@@ -44,7 +48,7 @@ Follow the steps from the [global
 configuration](/chainguard/libraries/java/global-configuration/#cloudsmith) to
 determine URL and authentication details.
 
-## JFrog Artifactory
+#### JFrog Artifactory
 
 Build configuration to retrieve artifacts from Artifactory typically requires
 you to authenticate and use the identity token in the configuration of your
@@ -54,7 +58,7 @@ Follow the steps from the [global
 configuration](/chainguard/libraries/java/global-configuration/#jfrog-artifactory)
 to determine URL and authentication details.
 
-## Sonatype Nexus Repository
+#### Sonatype Nexus Repository
 
 Build configuration to retrieve artifacts from Nexus may require authentication.
 Use your username and password for Nexus in your build tool configuration.
@@ -63,14 +67,73 @@ Follow the steps from the [global
 configuration](/chainguard/libraries/java/global-configuration/#sonatype-nexus-repository)
 to determine URL and authentication details.
 
-## Direct access
+### Direct access
 
 Build configuration to retrieve artifacts **directly** from the Chainguard
 Libraries
-for Java repository at `https://libraries.cgr.dev/java/` requires authentication
+for Java repository requires authentication
 with username and password from a pull token as detailed in
 [access documentation](/chainguard/libraries/access/#pull-token).
 
+If using Chainguard's [CVE remediation](/chainguard/libraries/cve-remediation/) for Java libraries (available in beta), set it as the top repository. The recommended ordering for repositories is:
+1. `https://libraries.cgr.dev/javascript/remediated/` for remediated Spring Boot libraries; this is available in beta as part of the [CVE Remediation](/chainguard/libraries/cve-remediation/) feature.
+1. `https://libraries.cgr.dev/javascript/`
+1. `https://repo1.maven.org/maven2/` or your Maven Central proxy
+
+
+
+## Selecting remediated library versions
+
+When using the [CVE remediation feature](/chainguard/libraries/cve-remediation/), available in beta to Chainguard Libraries for Java, your build will not receive a remediated Java artifact automatically with the overlay repository configured. To use the remediated build, you must opt in to the suffixed version directly, or route resolution to it through dependency management, Gradle constraints, or version ranges.
+
+### Update dependency version directly
+
+For Maven, you can set the suffixed version as a dependency in your `pom.xml`. For example:
+
+```xml
+<dependency>
+  <groupId>org.apache.commons</groupId>
+  <artifactId>commons-lang3</artifactId>
+  <version>3.18.0-0.cgr.1</version>
+</dependency>
+```
+
+For Gradle, you can set the suffixed version in the dependencies block in `build.gradle`:
+
+```build.gradle
+implementation 'org.apache.commons:commons-lang3:3.18.0-0.cgr.1'
+```
+
+### Override the version centrally
+
+When you use this option, the remediated version will apply to both direct and transitive dependencies.
+
+For Maven, update the `dependencyManagement` in a parent POM or the project POM:
+
+```xml
+<dependencyManagement>
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.commons</groupId>
+      <artifactId>commons-lang3</artifactId>
+      <version>3.18.0-0.cgr.1</version>
+    </dependency>
+  </dependencies>
+</dependencyManagement>
+```
+
+For Gradle, update the `constraints` block in `build.gradle`:
+
+```build.gradle
+dependencies {
+  constraints {
+    implementation('org.apache.commons:commons-lang3:3.18.0-0.cgr.1') {
+      because 'CVE remediation via Chainguard Libraries overlay'
+    }
+  }
+}
+```
+
 ## Apache Maven
 
 [Apache Maven](https://maven.apache.org/) is the most widely used build tool in
@@ -222,10 +285,10 @@ Java.
 If you are not using a repository manager at your organization, you can
 configure access to the Chainguard Libraries for Java repository directly.
 Ensure that the Chainguard repository is located above the necessary override
-for the built-in `central` repository and any other repositories.
+for the built-in `central` repository and any other repositories. If you are participating in the beta for CVE remediation, include the `https://libraries.cgr.dev/java-remediated/` repository first.
 
-The following `~/.m2/settings.xml` configures direct access with Chainguard as
-the primary repository and Maven Central as a fallback for transitive
+The following `~/.m2/settings.xml` configures direct access with Chainguard's remediated Java repository as
+the primary repository, falling back to the standard Chainguard Libraries repository when a remediated version is not available, and then to Maven Central as a fallback for transitive
 dependencies not available from Chainguard. It uses placeholder values
 `CG_PULLTOKEN_USERNAME` and `CG_PULLTOKEN_PASSWORD` or [environment
 variables](/chainguard/libraries/access/#env) for the pull token detailed in
@@ -240,6 +303,12 @@ variables](/chainguard/libraries/access/#env) for the pull token detailed in
     <profile>
       <id>no-repo-manager</id>
       <repositories>
+        <repository>
+          <id>chainguard-remediated</id>
+          <url>https://libraries.cgr.dev/java-remediated/</url>
+          <releases><enabled>true</enabled></releases>
+          <snapshots><enabled>false</enabled></snapshots>
+        </repository>
         <repository>
           <id>chainguard</id>
           <url>https://libraries.cgr.dev/java/</url>
@@ -414,6 +483,8 @@ cat > ~/.m2/settings.xml << EOF
 EOF
 ```
 
+If you are using Chainguard's remediated repository for Java libraries, make sure to add `https://libraries.cgr.dev/java-remediated/` first, as shown in the [direct access example](#direct-access) earlier on this page.
+
 **5. Build the project**
 
 Then build the project:
@@ -554,10 +625,18 @@ for your pull token credentials.
 
 Open `app/build.gradle` and update the `repositories` block to include the
 Chainguard repository. Ensure it is located above the `mavenCentral` repository
-and any other repositories:
+and any other repositories. If you are using Chainguard's [remediated library repository](/chainguard/libraries/cve-remediation/), set it as the top repository:
 
 ```groovy
 repositories {
+      maven {
+    url = uri("https://libraries.cgr.dev/java-remediated/")
+    credentials {
+      username = providers.environmentVariable("CHAINGUARD_JAVA_IDENTITY_ID").orNull
+      password = providers.environmentVariable("CHAINGUARD_JAVA_TOKEN").orNull
+    }
+  }
+
     maven {
         url = uri("https://libraries.cgr.dev/java/")
         credentials {
@@ -644,6 +723,8 @@ repositories {
 }
 ```
 
+If you are using Chainguard's remediated repository for Java libraries, make sure to add `https://libraries.cgr.dev/java-remediated/` first, as shown in the [direct access example](#direct-access-to-chainguard-libraries) earlier in the Gradle section on this page.
+
 **4. Build the project**
 
 Run the following command: