Endor Magic Patches

• 1: Connect to the Endor Labs Patch Factory
• 2: Automatic patching
• 3: Patch transparency

1 - Connect to the Endor Labs Patch Factory

You can start using Endor Magic patches with 3 simple steps:

1. Configure an API Key to connect to the Endor Labs Patch Factory
2. Configure your package manager to use Endor Magic Patch.
   • Configure Gradle
   • Configure Maven
   • Configure a Maven virtual repository with JFrog’s Artifactory
3. Specify the Endor Magic Patch you want to use.

Create an API key

To gain Rest API access to Endor Labs Patch Factory, you have to generate API credentials to authenticate to the repository.

1. From Manage, navigate to API Keys.
2. Select Generate API Key.
3. Enter a name to identify the API key, such as “Endor Patch Factory”.
4. Select the permissions to apply to the API Key, you’ll need at least Read Only.
5. Select the expiration date of the API key. This may be either 30, 60, or 90 days.

Using these credentials, you can configure Endor Labs your package manager or Artifact Repository proxy to authenticate to the Endor Patch Factory.

Configure Gradle

1. Open the build.gradle file of the package you’d like to configure to use patches.
2. Include a repositories section in the build.gradle file to establish a repository connection to the Endor Labs Patch Factory. Make sure to replace with the name of your Endor Labs namespace.
3. Include a reference to the Endor Magic Patch version in the build.gradle file.

Example repositories section:

repositories {
    mavenCentral()
    maven {
        url "https://factory.endorlabs.com/v1/namespaces/<namespace>/maven2"
        credentials {
            username "$ENDOR_API_CREDENTIALS_KEY"
            password "$ENDOR_API_CREDENTIALS_SECRET"
    }
}

Finally, include the Endor Labs patch version you’d like to use. For example, to use the latest patched version from Endor Labs add -endor-latest to the version of your dependency.

dependencies {
    implementation("com.fasterxml.jackson.core:jackson-databind:2.9.10.3-endor-latest")
}

See configuring a Maven virtual repository for more details on connecting with Endor Labs Patch factory using Artifactory.

Configure Maven

1. Open the pom.xml file of the package you’d like to configure to use patches.
2. If there is no section in the pom.xml, then create one.
3. Include a repositories section in the pom.xml file to establish a repository connection to the Endor Labs Patch Factory. Make sure to replace with the name of your Endor Labs namespace.

<repositories>
  <repository>
    <id>endorlabs</id>
    <url>https://factory.endorlabs.com/v1/namespaces/<namespace>/maven2</url>
  </repository>
</repositories>

4. Next, open the Maven settings.xml file located at $HOME/.m2/settings.xml and add a section to the settings file with your Endor Labs credentials.
   • The value must be your API key.
   • The must be your API key secret.
   • The value must be same as the value provided in the pom.xml.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>endorlabs</id>
            <username>${env.ENDOR_API_CREDENTIALS_KEY}</username>
            <password>${env.ENDOR_API_CREDENTIALS_SECRET}</password>
        </server>
    </servers>
</settings>

5. Finally, include the Endor Labs patch version you’d like to use in to your manifest. For example, to use the latest patched version from Endor Labs include -endor-latest to the version of your dependency.

<dependency>
   <groupId>com.fasterxml.jackson.core</groupId>
   <artifactId>jackson-databind</artifactId>
   <version>2.9.10.3-endor-latest</version>
</dependency>

Configure a Maven virtual repository with JFrog’s Artifactory

If your organization uses Artifactory as its primary package repository you’ll need to configure the Artifactory to pull packages from Endor Labs.

1. Login to Artifactory as an administrator.
2. From the Admin view go to Repositories.
3. Configure a new remote repository by selecting Create a Repository.
4. Ensure you configure a repository of type Maven.
5. Enter a Repository Key to uniquely identify the repository, such as endorlabs.
6. Enter the URL https://factory.endorlabs.com/v1/namespaces//maven2. Make sure to replace with the namespace of your Endor Labs tenant.
7. For the Username field use your Endor Labs API Key.
8. For the Password field use your API Key Secret.
9. Make sure to test your configuration.
10. Finally, create a virtual repository and set it as the first priority remote repository in the virtual repository. You can now use this virtual repository to pull Endor Labs patches.

2 - Automatic patching

Requiring development teams to upgrade software is often very difficult. With Endor Magic Patches, security risks can be fixed seamlessly during the next software build.

Auto patching with an Endor Magic Patch for each build allows you to automatically patch vulnerabilities in both direct and transitive dependencies so that you don’t have to go through the hard work of having a constant vulnerability backlog.

Opt into automated patching

To opt into auto patching with Endor Magic Patches you must configure Endor Labs Patch factory as the top priority package repository in your package manager or Artifactory virtual repository. See Connect to the Endor Labs Patch Factory for more details.

To enable Endor Magic Patch Streaming.

1. Navigate to Manage > Settings in your Endor Labs tenant.
2. Click Enable Auto Patching.
3. Click Save Patch Settings and acknowledge the warning about reproducible builds.

Tradeoffs with automated patching

When you automatically patch your software, you also give up build reproducibility as the patches might introduce changes that affect the build process or the resulting binaries in ways that are not fully controlled or predictable.

Endor Labs works hard to ensure that you get the minimum viable security patch for your software. With auto patching enabled, when a new patch is available it will automatically be applied to your software.

3 - Patch transparency

In security, trust is crucial. Therefore, the patch details of an Endor Magic Patch are fully transparent. You can audit the exact code changes, builds, build steps, and logs. The builds are reproducible and hermetic.

Review patch transparency information

To review patches, build, test and deploy proccess used to create an Endor Magic Patch, use the AssuredPackageVersion API.

The commands and logs used to test, deploy and build this package are stored for each version of a package as an attestation.

Review security attestations

To see the exact changes used for a given security patch, Endor Labs provides a security attestation which shows:

1. Fixed vulnerabilities
2. Exact code changes for each package
3. Exact commits used and if they are upstream commits or commits applied by Endor Labs directly

To see a security attestation use the following command with the name of the package version you’d like to inspect. For this example we’ll use com.fasterxml.jackson.core:jackson-databind@2.9.10.3:

endorctl api list -r AssuredPackageVersion -n oss --filter="meta.name==mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3" | jq '.list.objects[].spec.security_attestation'

Review attestations

To see all information about the patch, build, test and deploy proccess for this Endor Magic Patch use the command:

endorctl api list -r AssuredPackageVersion -n oss --filter="meta.name==mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3"

Review build attestations

To see the build steps and build logs for an Endor Magic Patch, you can see that patch build attestation.

To see a build attestation use the following command with the name of the package version you’d like to inspect. For this example we’ll use com.fasterxml.jackson.core:jackson-databind@2.9.10.3

endorctl api list -r AssuredPackageVersion -n oss --filter="meta.name==mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3" | jq '.list.objects[].spec.build_attestation'

Reviewing Test Attestations

To see the test steps and test logs for an Endor Magic Patch, you can see that patch test attestation.

To see a deployment attestation use the following command with the name of the package version you’d like to inspect. For this example we’ll use com.fasterxml.jackson.core:jackson-databind@2.9.10.3

endorctl api list -r AssuredPackageVersion -n oss --filter="meta.name==mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3" | jq '.list.objects[].spec.test_attestation'

Review deploy attestations

To review the deployment steps and logs for an Endor Magic Patch, check the patch deployment attestation.

To see a deployment attestation, use the following command with the name of the package version you’d like to inspect. For this example, we’ll use com.fasterxml.jackson.core:jackson-databind@2.9.10.3.

endorctl api list -r AssuredPackageVersion -n oss --filter="meta.name==mvn://com.fasterxml.jackson.core:jackson-databind@2.9.10.3" | jq '.list.objects[].spec.deploy_attestation'