fix(security): APPS_JSON_BASE64 build-arg leaks private repo tokens in image layer metadata

[OmarElaraby26]

Labels

security, bug, docker, docs

---

Description of the issue

When building custom images with private apps, apps.json contains GitHub PATs embedded in repository URLs. The current Containerfiles (images/custom/Containerfile and images/layered/Containerfile) pass this as a Docker build argument (--build-arg=APPS_JSON_BASE64). Docker build arguments are permanently recorded in image layer metadata, meaning anyone with access to the image can trivially extract private repo tokens.

This is a known Docker anti-pattern documented by Docker themselves: SecretsUsedInArgOrEnv.

Impact: Any image built with private apps using the documented workflow has credentials permanently embedded. Images pushed to registries (even private ones) expose PATs to all users with pull access.

Affected files:

• images/custom/Containerfile
• images/layered/Containerfile
• docs/02-setup/02-build-setup.md
• docs/02-setup/08-single-server-nginxproxy-example.md

Context information (for bug reports)

• frappe_docker: main branch (latest as of 2026-04-05)
• Docker Engine: any version with BuildKit support
• Host OS: any (issue is in Containerfile / docs, not host-specific)

Steps to reproduce the issue

1. Create apps.json with a private repo URL containing a PAT:

   [
     {
       "url": "https://USER:ghp_XXXX@github.com/org/private-app.git",
       "branch": "main"
     }
   ]

2. Build the custom image following the current docs:

   docker build \
     --build-arg=APPS_JSON_BASE64=$(base64 -w 0 apps.json) \
     --build-arg=FRAPPE_PATH=https://github.com/frappe/frappe \
     --build-arg=FRAPPE_BRANCH=version-16 \
     --tag=custom:latest \
     --file=images/custom/Containerfile .

3. Inspect the image:

   docker image history --no-trunc custom:latest

Observed result

The full base64-encoded apps.json (including PATs) is visible in the ARG layer metadata. Decoding it reveals the plain-text GitHub PAT:

echo "<base64_from_history>" | base64 -d
# {"url": "https://USER:ghp_XXXX@github.com/org/private-app.git", ...}

Expected result

Private repository tokens should never be persisted in image layers or metadata. The image should be safe to push to registries or share with team members without leaking credentials.

Suggested fix

Replace ARG / --build-arg with a Docker BuildKit secret mount. I have a PR ready for this.

Containerfile (remove ARG APPS_JSON_BASE64 and the decode RUN, replace with):

RUN --mount=type=secret,id=apps_json,target=/opt/frappe/apps.json,uid=1000,gid=1000 \
  export APP_INSTALL_ARGS="" && \
  if [ -f /opt/frappe/apps.json ] && [ -s /opt/frappe/apps.json ]; then \
    export APP_INSTALL_ARGS="--apps_path=/opt/frappe/apps.json"; \
  fi && \
  bench init ${APP_INSTALL_ARGS} ...

Build command:

DOCKER_BUILDKIT=1 docker build \
  --secret=id=apps_json,src=apps.json \
  --build-arg=FRAPPE_BRANCH=version-16 \
  --tag=custom:latest \
  --file=images/custom/Containerfile .

Key points:

• --mount=type=secret makes the file available only during that RUN step -- it is never committed to any layer
• uid=1000,gid=1000 ensures the frappe user can read the secret
• The -f and -s checks handle the case where no apps.json is provided (backward compatible)
• Requires DOCKER_BUILDKIT=1 or docker buildx build

References

• Docker: SecretsUsedInArgOrEnv build check
• Docker: Build Secrets
• Don't leak your Docker image's build secrets (pythonspeed.com)

[OmarElaraby26]

I have a PR ready with the fix for this. I will also submit a follow-up PR to the frappe/bench repo to update easy-install.py for compatibility with these changes

[asieftejani]

@OmarElaraby26 - your suggestion looks very reasonable
However I would be a little cautious about easy-install.py which is held at the frappe bench repo. Previous attempts to update it (frappe/bench#1701) are still open and I dont see any follow-ups so yours will probably have the same fate
Best of luck

[OmarElaraby26]

Thanks @asieftejani I've opened the PR for frappe_docker: #1861

Regarding easy-install.py in frappe/bench — I appreciate the warning about the stalled PR history there. I'll open the follow-up PR anyway once this PR is accepted. Worst case it serves as a reference for anyone hitting this issue.

[DanielRadlAMR]

While we should avoid breaking changes for others, we can’t indefinitely wait for frappe/bench to address the easy-install.py issue.

We’ve already opened PRs, but without feedback or progress, there’s little we can do on that front.

@Rocket-Quack, you might also want to take a look at this, as it could be relevant for your TUI.

[Rocket-Quack]

Its also excellent PR especially for reinforcing images.

Since this is a very major update with breaking changes, I’d like to address a few things.
How do we handle legacy pipelines or users who are still using the old system with Base64-encoded apps?
A short doic explaining the migration process would be helpful here and why these changes are made.
Additionally regarding existing pipelines, are we planning a hybrid approach where the current setup continues to function for a certain period of time, or do we prefer to make a clean break? Because in that case, we would need to verify that existing builds continue to work (at least for a short while).

@DanielRadlAMR I think this kind of change will likely require a new major release. But I’ll update the TUI scripts then :) it’s mostly just a matter of removing the intermediate step for Base64 encoding since it’s then no longer needed.

[DanielRadlAMR]

@Rocket-Quack Yeah, this will definitely require a new major release. I’ve been thinking about it, but I haven’t landed on a final approach yet. This PR is going to break things for quite a few users.

One option could be a two-step approach, similar to how we handled the Traefik version bump. First, we introduce the new feature in a fully backward-compatible way. During that phase, pipelines can be updated and migration guides prepared. After that, we can deprecate the old approach entirely. Maintaining two parallel solutions for the same problem doesn’t seem worthwhile, especially since the new approach has clear advantages.

That said, since releases were only introduced relatively recently, a lot of users are probably still relying on the main branch anyway. So breakage is somewhat inevitable—we might just accept that and move forward without the intermediate step.

---

@asieftejani Since you’re quite active in the community, do you know if the easy-install.py script is still in use? This PR could completely break it, which wouldn’t be great if people still depend on it. If I remember correctly, we may have already broken it in a previous major release and it hasn’t been fixed since—does that sound right?

[asieftejani]

@DanielRadlAMR I think it is mostly used for open source repos so I was not able to figure out if this change will effect all repos or only private ones?

@OmarElaraby26 - please can you enlighten me

[Rocket-Quack]

@asieftejani what @DanielRadlAMR meant was if you happen to know whether many people still rely heavily on the easy-install.py. Maybe some questions about this have also come up from people in the forum, etc. that you know of.

The changes would affect any repository that uses easy-install although we have already introduced breaking changes with the Traefik update.

In that case, I might as well address the README right away and update the cloning instructions accordingly—specifying that users should clone the latest version from the relevant tag rather than from the main branch.

[asieftejani]

Not that I have seen