{"id":14155235,"url":"https://github.com/salesforce/dockerfile-image-update","last_synced_at":"2025-04-04T05:08:28.985Z","repository":{"id":25872228,"uuid":"104787715","full_name":"salesforce/dockerfile-image-update","owner":"salesforce","description":"A tool that helps you get security patches for Docker images into production as quickly as possible without breaking things","archived":false,"fork":false,"pushed_at":"2024-10-03T22:26:49.000Z","size":1505,"stargazers_count":140,"open_issues_count":44,"forks_count":48,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-28T04:15:47.420Z","etag":null,"topics":["docker","dockerfile","github","hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/salesforce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-25T18:38:13.000Z","updated_at":"2025-03-06T01:49:22.000Z","dependencies_parsed_at":"2024-09-13T20:08:20.503Z","dependency_job_id":"ee09e086-f8d9-4efa-b0d0-f03213fa7066","html_url":"https://github.com/salesforce/dockerfile-image-update","commit_stats":{"total_commits":589,"total_committers":25,"mean_commits":23.56,"dds":0.6570458404074703,"last_synced_commit":"53f63406152e4d04543b0d8465181665dd189df7"},"previous_names":[],"tags_count":415,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salesforce%2Fdockerfile-image-update","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salesforce%2Fdockerfile-image-update/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salesforce%2Fdockerfile-image-update/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salesforce%2Fdockerfile-image-update/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/salesforce","download_url":"https://codeload.github.com/salesforce/dockerfile-image-update/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247123107,"owners_count":20887261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","dockerfile","github","hacktoberfest"],"created_at":"2024-08-17T08:02:34.272Z","updated_at":"2025-04-04T05:08:28.965Z","avatar_url":"https://github.com/salesforce.png","language":"Java","readme":"[![codecov](https://codecov.io/gh/salesforce/dockerfile-image-update/branch/main/graph/badge.svg)](https://codecov.io/gh/salesforce/dockerfile-image-update)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.salesforce.dockerfile-image-update/dockerfile-image-update/badge.svg?maxAge=3600)](https://maven-badges.herokuapp.com/maven-central/com.salesforce.dockerfile-image-update/dockerfile-image-update)\n[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/salesforce/dockerfile-image-update?label=Docker%20version\u0026sort=semver)](https://hub.docker.com/r/salesforce/dockerfile-image-update/tags)\n[![Project Map](https://sourcespy.com/shield.svg)](https://sourcespy.com/github/salesforcedockerfileimageupdate/)\n\n# Dockerfile Image Updater\n\nThis tool provides a mechanism to make security updates to docker images at\nscale. The tool searches github for declared docker images and sends pull\nrequests to projects that are not using the desired version of the requested\ndocker image.\n\nDocker builds images using a declared Dockerfile. Within the Dockerfile,\nthere is a `FROM` declaration that specifies the base image and a tag that\nwill be used as the starting layers for the new image. If the base image that\n`FROM` depends on is rebuilt, the Docker images that depend on it will never\nbe updated with the newer layers. This becomes a major problem if the reason\nthe base image was updated was to fix a security vulnerability. All Docker\nimages are often based on operating system libraries and these get patched\nfor security updates quite frequently. This tool, the Dockerfile Image Updater\nwas created to automatically make sure that child images are updated when the\nimages they depend on get updated.\n\n## Table of contents\n\n* [User Guide](#user-guide)\n  * [What It Does](#what-it-does)\n  * [Prerequisites](#prerequisites)\n  * [Precautions](#precautions)\n  * [How To Use It](#how-to-use-it)\n  * [Skip An Image](#additional-notes)\n* [Developer Guide](#developer-guide)\n  * [Building](#building)\n  * [Running locally](#running-locally)\n  * [Creating a New Feature](#creating-a-new-feature)\n  * [Running Unit Tests](#running-unit-tests)\n  * [Running Integration Tests](#running-integration-tests)\n  * [Release Process](#release-process)\n* [Blogs / Slides](#blogs--slides)\n\n## User Guide\n\n### What it does\n\nThe tool has three modes\n\n1. `all` - Reads store that declares the docker images and versions that you\n   intend others to use.\n\n   Example:\n\n   ```commandline\n   export git_api_url=https://api.github.com\n   export git_api_token=my_github_token\n   docker run --rm -e git_api_token -e git_api_url \\\n     salesforce/dockerfile-image-update all image-to-tag-store\n   ```\n\n1. `parent` - Searches github for images that use a specified image name and\n   sends pull requests if the image tag doesn't match intended tag. The\n   intended image with tag is passed in the command line parameters. The\n   intended image-to-tag mapping is persisted in a store in a specified git\n   repository under the token owner.\n\n   Example:\n\n   ```commandline\n   export git_api_url=https://api.github.com\n   export git_api_token=my_github_token\n   docker run --rm -e git_api_token -e git_api_url \\\n     salesforce/dockerfile-image-update parent my_org/my_image v1.0.1 \\\n     image-to-tag-store\n   ```\n\n1. `child` - Given a specific git repo, sends a pull request to update the\n   image to a given version. You can optionally persist the image version\n   combination in the image-to-tag store.\n\n   Example:\n\n   ```commandline\n   export git_api_url=https://api.github.com\n   export git_api_token=my_github_token\n   docker run --rm -e git_api_token -e git_api_url \\\n     salesforce/dockerfile-image-update child my_gh_org/my_gh_repo \\\n     my_image_name v1.0.1\n   ```\n\n### Prerequisites\n\nIn environment variables, please provide:\n\n* `git_api_token` : This is your GitHub token to your account. Set these\n  privileges by: going to your GitHub account --\u003e settings --\u003e\n  Personal access tokens --\u003e check `repo` and `delete_repo`.\n* `git_api_url` : This is the Endpoint URL of the GitHub API. In general\n  GitHub, this is `https://api.github.com/`; for Enterprise, this should\n  be `https://hostname/api/v3`. (this variable is optional; you can provide it\n  through the command line.)\n\n### Precautions\n\n1. This tool may create a LOT of forks in your account. All pull requests\n   created are through a fork on your own account.\n1. We currently do not operate on forked repositories due to limitations in\n   forking a fork on GitHub. We should invest some time in doing this right.\n   See [issue #21](https://github.com/salesforce/dockerfile-image-update/issues/22)\n1. Submodules are separate repositories and get their own pull requests.\n\n### How to use it\n\nOur recommendation is to run it as a docker container:\n\n```commandline\nexport git_api_url=https://api.github.com\nexport git_api_token=my_github_token\ndocker run --rm -e git_api_token -e git_api_url \\\n  salesforce/dockerfile-image-update \u003cCOMMAND\u003e \u003cPARAMETERS\u003e\n```\n\n```commandline\nusage: dockerfile-image-update [-h] [-l GHAPISEARCHLIMIT] [-o ORG] [-b BRANCH] [-g GHAPI] [-f] [-m M] [-c C] [-e EXCLUDES] [-B B] [-s {true,false}] [-x X] COMMAND ...\n\nImage Updates through Pull Request Automator\n\nnamed arguments:\n  -h, --help             show this help message and exit\n  -l GHAPISEARCHLIMIT, --ghapisearchlimit GHAPISEARCHLIMIT\n                         limit the search results for github api (default: 1000)\n  -o ORG, --org ORG      search within specific organization (default: all of github)\n  -b BRANCH, --branch BRANCH\n                         make pull requests for given branch name (default: main)\n  -g GHAPI, --ghapi GHAPI\n                         link to github api; overrides environment variable\n  -f, --auto-merge       NOT IMPLEMENTED / set to automatically merge pull requests if available\n  -m M                   message to provide for pull requests\n  -c C                   additional commit message for the commits in pull requests\n  -e EXCLUDES, --excludes EXCLUDES\n                         regex of repository names to exclude from pull request generation\n  -B B                   additional body text to include in pull requests\n  -s {true,false}, --skipprcreation {true,false}\n                         Only update image tag store. Skip creating PRs\n  -x X                   comment snippet mentioned in line just before FROM instruction for ignoring a child image. Defaults to 'no-dfiu'\n  -r, --rate_limit_pr_creations \n                         Enable rateLimiting for throttling the number of PRs DFIU will cut over a period of time. \n                         The argument value should be in format \"\u003cpositive_integer\u003e-\u003cISO-8601_formatted_time\u003e\". For example \"--rate_limit_pr_creations 60-PT1H\" to create 60 PRs per hour.\n                         Default is not set, this means no ratelimiting is imposed.\n                         \nsubcommands:\n  Specify which feature to perform\n\n  COMMAND                FEATURE\n    parent               updates all repositories' Dockerfiles with given base image\n    all                  updates all repositories' Dockerfiles\n    child                updates one specific repository with given tag\n```\n\n#### The `all` command\n\nSpecify an image-to-tag store (a repository name on GitHub that contains a\nfile called store.json); looks through the JSON file and checks/updates all\nthe base images in GitHub to the tag in the store.\n\n```commandline\nusage: dockerfile-image-update all [-h] \u003cIMG_TAG_STORE\u003e\n\npositional arguments:\n  \u003cIMG_TAG_STORE\u003e        REQUIRED\n\noptional arguments:\n  -h, --help             show this help message and exit\n```\n\n#### The `child` command\n\nForcefully updates a repository's Dockerfile(s) to given tag. If specified a\nstore, it will also forcefully update the store.\n\n```commandline\nusage: dockerfile-image-update child [-h] [-s \u003cIMG_TAG_STORE\u003e] \u003cGIT_REPO\u003e \u003cIMG\u003e \u003cFORCE_TAG\u003e\n\npositional arguments:\n  \u003cGIT_REPO\u003e             REQUIRED\n  \u003cIMG\u003e                  REQUIRED\n  \u003cFORCE_TAG\u003e            REQUIRED\n\noptional arguments:\n  -h, --help             show this help message and exit\n  -s \u003cIMG_TAG_STORE\u003e     OPTIONAL\n```\n\n#### The `parent` command\n\nGiven an image, tag, and store, it will create pull requests for any\nDockerfiles that has the image as a base image and an outdated tag. It also\nupdates the store.\n\n```commandline\nusage: dockerfile-image-update parent [-h] \u003cIMG\u003e \u003cTAG\u003e \u003cIMG_TAG_STORE\u003e\n\npositional arguments:\n  \u003cIMG\u003e                  REQUIRED\n  \u003cTAG\u003e                  REQUIRED\n  \u003cIMG_TAG_STORE\u003e        REQUIRED\n\noptional arguments:\n  -h, --help             show this help message and exit\n```\n\n### Skip An Image\n\nIn case you want the tool to skip updating a particular image tag then add a comment `no-dfiu` after the `FROM` declaration in the Dockerfile. The tool will process the comment following `FROM` declaration and if `no-dfiu` is mentioned, pull request for that image tag will be ignored. You can use an alternate comment string by passing an additional command line parameter `-x IGNORE_IMAGE_STRING`. In that case string mentioned with the parameter, will be used for skipping PR creation.\n\nExample:\n\n```\nFROM imagename:imagetag # no-dfiu\n```\n\n### PR throttling\n\nIn case you want to throttle the number of PRs cut by DFIU over a period of time,\nset --rate_limit_pr_creations with appropriate value. \n\n##### Default case:\n\nBy default, this feature is disabled. This will be enabled when argument ``--rate_limit_pr_creations`` will be passed\nwith appropriate value.\n\n```\nexample: dockerfile-image-update all image-tag-store-repo-falcon //throttling will be disabled by default\n```\n\n##### Configuring the rate limit:\n\nBelow are some examples that will throttle the number of PRs cut based on values passed to the\nargument ``--rate_limit_pr_creations``\nThe argument value should be in format ``\u003cpositive_integer\u003e-\u003cISO-8601_formatted_time\u003e``.\nFor example ``--rate_limit_pr_creations 60-PT1H`` would mean the tool will cut 60 PRs every hour and the rate of adding\na new PR will be (PT1H/60) i.e. one minute.\nThis will distribute the load uniformly and avoid sudden spikes, The process will go in waiting state until next PR\ncould be sent.\n\nBelow are some more examples:\n\n```\nUsage: \n    dockerfile-image-update --rate_limit_pr_creations 60-PT1H all image-tag-store-repo-falcon //DFIU can send up to 60 PRs per hour.\n    dockerfile-image-update --rate_limit_pr_creations 500-PT1H all image-tag-store-repo-falcon //DFIU can send up to 500 PRs per hour.\n    dockerfile-image-update --rate_limit_pr_creations 86400-PT24H all image-tag-store-repo-falcon //DFIU can send up to 1 PRs per second.\n    dockerfile-image-update --rate_limit_pr_creations 1-PT1S all image-tag-store-repo-falcon //Same as above. DFIU can send up to 1 PRs per second.\n    dockerfile-image-update --rate_limit_pr_creations 5000 all image-tag-store-repo-falcon //rate limiting will be disabled because argument is not in correct format.\n```\n\n## Developer Guide\n\n### Building\n\n```commandline\ngit clone https://github.com/salesforce/dockerfile-image-update.git\ncd dockerfile-image-update\nmvn clean install\n```\n\n### Running locally\n\n```commandline\ncd dockerfile-image-update/target\njava -jar dockerfile-image-update-1.0-SNAPSHOT.jar \u003cCOMMAND\u003e \u003cPARAMETERS\u003e\n```\n\n### Creating a new feature\n\nUnder [dockerfile-image-update/src/main/java/com/salesforce/dva/dockerfileimageupdate/subcommands/impl](https://github.com/salesforce/dockerfile-image-update/tree/main/dockerfile-image-update/src/main/java/com/salesforce/dockerfileimageupdate/subcommands/impl),\ncreate a new class `YOUR_FEATURE.java`.\nMake sure it implements `ExecutableWithNamespace` and has the `SubCommand`\nannotation with a `help`, `requiredParams`, and `optionalParams`.\nThen, under the `execute` method, code what you want this tool to do.\n\n### Running unit tests\n\nRun unit tests by running `mvn test`.\n\n### Running integration tests\n\nBefore you run the integration tests (locally):\n\n1. Make sure that you have access to the github orgs specified in\n   [TestCommon.ORGS](https://github.com/salesforce/dockerfile-image-update/blob/main/dockerfile-image-update-itest/src/main/java/com/salesforce/dockerfileimageupdate/itest/tests/TestCommon.java#L33).\n   You likely will need to change it to three orgs where you have permissions\n   to create repositories.\n1. Make sure you have `git_api_url=https://api.github.com` in `/dockerfile-image-update-itest/itest.env`,\n   or set it to your internal GitHub Enterprise.\n1. Make sure you have a secret file which contains the `git_api_token`.\n   The token needs to have `delete_repo, repo` permissions.\n   You can generate your token by going to [personal access tokens](https://github.com/settings/tokens/new)\n   in GitHub. Once you have your token place it in a file:\n\n   ```\n   echo git_api_token=[copy personal access token here] \u003e ${HOME}/.dfiu-itest-token\n   ```\n\n1. Export the following environment variable to point to the file:\n\n   ```\n   export user_itest_secrets_file_secret=${HOME}/.dfiu-itest-token\n   ```\n\n1. Run integration tests by running\n\n   ```\n   make integration-test\n   ```\n\n### Release Process\n\nWe currently use GitHub Actions and Releases. In order to collect dependency\nupdates from dependabot and any other minor changes, we've switched to a process\nto manually trigger the release process. For now, that looks like the following:\n\n#### 1. Versioned Git Tag\n\n* Decide what version you desire to have. If you want to bump the major or minor\n  version then you need to bump the `MVN_SNAPSHOT_VERSION` in the [Makefile](https://github.com/salesforce/dockerfile-image-update/blob/main/Makefile#L5)\n  and in the\n  [Dockerfile](https://github.com/salesforce/dockerfile-image-update/blob/main/Dockerfile#L4)\n  before proceeding to the next steps. For example\n  `MVN_SNAPSHOT_VERSION=1.0-SNAPSHOT` to\n  `MVN_SNAPSHOT_VERSION=2.0-SNAPSHOT`.\n* After PRs have been merged to the primary branch, go to the Actions tab\n  and trigger the `Release new version` Workflow. This will build,\n  integration test, deploy the latest version to Docker Hub and Maven\n  Central, and tag that commit hash with the next semantic version.\n\n#### 2. Cut Release with Release Notes\n\n* PRs continually get updated with labels by [Pull Request Labeler](https://github.com/actions/labeler)\n  and that helps set us up for nice release notes by [Release Drafter](https://github.com/release-drafter/release-drafter).\n* Once that release has been tagged you can go to the draft release which\n  is continually updated by [Release Drafter](https://github.com/release-drafter/release-drafter)\n  and select the latest tag to associate with that release. Change the\n  version to reflect the same version as the tag (`1.0.${NEW_VERSION}`).\n  Take a look at the release notes to make sure that PRs are categorized\n  correctly. The categorization is based on the labels of the PRs. You can\n  either fix the labels on the PRs, which will trigger the\n  [release drafter action](https://github.com/salesforce/dockerfile-image-update/actions/workflows/release-drafter.yml),\n  or simply modify the release notes before publishing. Ideally we'll automate\n  this to run at the end of the triggered workflow with something like\n  [svu](https://github.com/caarlos0/svu).\n\n### Checking Code Climate Locally\n\nIf you'd like to check [Code Climate](https://codeclimate.com/quality/)\nresults locally you can run the following:\n\n```\ndocker run --interactive --tty --rm \\\n --env CODECLIMATE_CODE=\"$(pwd)\" \\\n --volume \"$(pwd)\":/code \\\n --volume /var/run/docker.sock:/var/run/docker.sock \\\n --volume /tmp/cc:/tmp/cc \\\n codeclimate/codeclimate analyze README.md\n```\n\n# Blogs / Slides\n\n* [2018-03-13 Salesforce Engineering Blog - Open Sourcing Dockerfile Image Update](https://engineering.salesforce.com/open-sourcing-dockerfile-image-update-6400121c1a75)\n* [2018 SRECon 18 - Auto-Cascading Security Updates Through Docker Images](https://www.slideshare.net/AndreyFalko1/srecon18americas-lightning-talk-autocascading-security-updates-through-docker-images?qid=c659b92a-aa60-4ef1-942a-de7b4fb66ad2\u0026v=\u0026b=\u0026from_search=1)\n* [2018-10-22 - Lyft Engineering Blog -\n  The Challenges Behind Rolling Out Security Updates To Your Docker Images](https://eng.lyft.com/the-challenges-behind-rolling-out-security-updates-to-your-docker-images-86106de47ece)\n","funding_links":[],"categories":["hacktoberfest"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsalesforce%2Fdockerfile-image-update","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsalesforce%2Fdockerfile-image-update","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsalesforce%2Fdockerfile-image-update/lists"}