Migration of Cortex Analyzers and Responders Docker images to GHCR: What it means for you

Effective April 1, 2025, DockerHub will enforce stricter pull rate limits for Docker images, affecting unauthenticated users and free-tier accounts. These changes may impact customers using Cortex Analyzers and Responders, as Cortex currently does not support authentication with Docker registries.

To mitigate this and ensure uninterrupted access to our Docker images, we are migrating the hosting of Cortex Analyzers and Responders images to GitHub Container Registry (GHCR).

In this article, we will explain the reasons behind this change, its potential impact on your applications, and the necessary steps to ensure a smooth transition.

DockerHub’s new pull rate limits, detailed here, include:

• Unauthenticated users: 10 pulls per hour
• Authenticated users with a free account: 100 pulls per hour
• Authenticated users with a paid account: Unlimited pulls subject to fair use

Since Cortex does not currently support authentication with Docker registries, all image pulls are considered unauthenticated, potentially leading to rate limit errors. While many users may not experience issues due to Docker’s image caching mechanism—where images are downloaded once and reused—certain scenarios could still be problematic. For instance, if you have restricted Docker cache settings or multiple instances sharing the same source IP, you might exceed the unauthenticated pull limits.

By migrating to GHCR, we ensure that our Docker images remain accessible without authentication and without pull rate restrictions, providing a more reliable experience for all users.

To understand the impact and the necessary actions, it’s important to know how Cortex manages Analyzer and Responder images.

Cortex relies on official catalogs hosted online. These catalogs are essentially lists of available Analyzers and Responders, and critically, they contain the specific URLs indicating where Cortex should pull the corresponding Docker image from.

With the migration of images to the GitHub Container Registry (GHCR), we are simultaneously updating these official catalogs. The URLs listed for our Analyzers and Responders within these catalogs will be changed to point to their new locations on GHCR instead of DockerHub.

For this change to be effective in practice, the following needs to happen on your Cortex instance:

Your Cortex instance needs to download these updated catalogs to become aware of the new GHCR image locations. This happens automatically upon restarting the Cortex application or when hitting the “refresh” button in the Cortex UI Analyzers or Responders management tab.

Even after downloading the new catalogs, Cortex might continue using locally cached images pulled previously from DockerHub.

To ensure Cortex actively uses the new GHCR URLs specified in the updated catalogs (necessary for future updates or if images need re-pulling) and to avoid potential attempts to pull from DockerHub using outdated references (which could trigger rate limits), the specific disable/enable steps outlined below are required to update the configuration of each active Analyzer/Responder.

While Docker’s image caching might allow already downloaded images to function for a time without immediate action, this is not a reliable long-term state. Relying on cached images means your instance will not receive any new versions or security updates for Analyzers and Responders, as these will only be published to GHCR and referenced in the updated catalogs. Furthermore, any event triggering a re-pull (e.g., cache clearing, specific errors) could still lead to failures if Cortex attempts to use the old DockerHub URLs and encounters rate limits.

Therefore, to ensure uninterrupted operation, access to the latest updates, and avoidance of potential disruptions related to DockerHub’s rate limits, we strongly recommend all on-premises users follow the migration steps detailed in the next section promptly after April 1, 2025.

No action is required on your part. We will manage the migration and ensure that your Cortex Analyzers and Responders continue to function seamlessly.

To adapt to this change, please follow these steps as soon as possible, starting April 1, 2025:

1. Restart the Cortex application: This is necessary to download the updated catalogs that reference the new image locations on GHCR.
2. Update Analyzer and Responder configurations: For each active Analyzer and Responder, disable and then re-enable them in the Cortex Administration console. This ensures the new image references are applied. Note: Your custom Analyzers and Responders are not affected and do not require this action.
3. Verify network access: If your infrastructure restricts outgoing traffic, ensure that Cortex can access ghcr.io to download the required images.

If you need assistance during this transition, please contact our support team.

Yes, we are actively developing support for Docker registry authentication in Cortex. This will allow users to authenticate with registries like DockerHub, benefiting from higher pull rate limits. We will provide updates on this feature as development progresses.

If you restart Cortex after April 1, 2025, without updating the catalogs, it will still reference DockerHub. Since existing images will remain on DockerHub, you can continue to use them. However, the DockerHub repository will no longer receive updates for new or modified Analyzers and Responders. To access the latest versions, follow the migration steps promptly.

Yes, existing images will stay on DockerHub, but no new updates will be published there. All future updates will be available exclusively on GHCR.

No, the Docker images for TheHive and Cortex will continue to be published on DockerHub. Additionally, they will also be available on GHCR for your convenience.

This migration is a proactive measure to ensure that our customers can continue to access and use Cortex Analyzers and Responders without interruption. We understand that changes like this can be challenging, and we are committed to supporting you through this transition. If you have any questions or need further assistance, please do not hesitate to reach out to our support team.

Thank you for your understanding and cooperation.