Skip to content

Enabling remediation

This page explains how to enable remediation plans and fix pull requests and confirm that the settings have taken effect. For an overview, see Remediation plans and pull requests.

For supported environments and inputs, see Scope and requirements; for connection destinations, see Outbound connections.

Enabling remediation plans

Merge the following examples into the relevant sections of your existing config.yml. Do not add duplicate remediation sections to the same file.

Preparing GitHub access

  1. Choose the GitHub repository to map and the branch to use as the source and PR target
  2. Check GitHub access for the permissions needed to read source files and create PRs
  3. For uses that require a token, prepare one restricted to the target repositories and set it in remediation.github.token
  4. Keep the configuration file containing the token readable only by its owner and exclude it from repository commits

Identifying the workload

  1. Inspect the target running container with docker inspect
  2. Note the values of the com.docker.compose.project and com.docker.compose.service labels
  3. Use those values to construct the workload key for the mapping in the format compose/<project>/<service>

If the project is example and the service is web, the workload key is compose/example/web. For format details, see Source mappings.

Compose project name

Check the Compose project name used in the actual deployment. It may differ from the repository or directory name.

Mapping source files

  1. Choose the mapping kind for the update target from Source mappings
  2. Replace the workload, repository, base branch, and target file locations with your actual values
  3. Enable remediation plans with PR creation initially disabled

This minimal example maps a distributed image reference to a Compose file.

remediation:
  enabled: true
  pull_requests:
    enabled: false
  mappings:
    - workload: compose/example/web
      repository: example/deployment
      base_branch: main
      compose:
        path: compose.yml
        service: web

For dependency file and Dockerfile settings and restrictions on multiple mappings, see Source mappings. For details on the enablement keys, see Enablement settings.

Authenticating to private image registries

This configuration is unnecessary if you use only public images.

  1. Prepare credentials with read access to the target images
  2. Add the target host and credentials as described in Image registry authentication
  3. If the registry uses a token service on another host, check where credentials will be sent and configure token_hosts
remediation:
  registries:
    - host: registry.example.com
      username: example-puller
      password: "REPLACE_WITH_REGISTRY_READ_TOKEN"

For key formats and configuration requirements, see Image registry authentication. For the destinations that receive credentials, see Credential destinations.

Record storage

The supplied Compose configuration stores records in the state volume. If you change remediation.storage_dir, choose a location that persists when the container is recreated. For details, see Storage location.

Verifying remediation plan startup

  1. With the supplied Compose configuration, run docker compose up -d --force-recreate kestrelynx in the KestreLynx deployment directory
  2. Use docker compose logs -f kestrelynx to confirm that the configuration loaded and remediation plans are enabled
  3. Check the target image scan and remediation plan results during the scan after startup or at the next scheduled time
  4. Confirm that the workload, source, and update targets shown in the notification are as intended

For the meaning of each field, see Displayed fields. If startup fails, see Startup validation; if no plan appears, see Checking for a missing plan.

Enabling fix pull requests

Complete Verifying remediation plan startup before enabling PR creation.

Docker API

For language package updates, KestreLynx creates, starts, and removes work containers through the Docker API. Mounting the Docker socket with :ro does not restrict API operations, so the supplied Compose configuration does not need to change to :rw. If you use a Docker API proxy, allow these operations.

Enabling PR creation

  1. Confirm that the token configured in Preparing GitHub access has the access needed to create PRs
  2. Enable PR creation while keeping the existing mappings, credentials, and storage location
  3. Recreate the KestreLynx container and confirm in the logs that PR creation is enabled
remediation:
  enabled: true
  pull_requests:
    enabled: true

For key details, see Enablement settings. To adjust PR counts or dependency update processing limits, see Processing limits.

Repository workflows

Creating a PR may start workflows triggered by pull_request in the target repository.

HTML comments in the PR body contain identification markers used for record reconciliation and recovery, so preserve them when editing the body. If no PR is created, see Checking for a missing PR.