Skip to main content

Patched upstream images

This feature is available once it is released. The changelog records the date.

Some upstream images have known vulnerabilities and no fixed release yet. If you build from such a base and patch the vulnerable packages in your own layers, your organisation’s image pull gate still refuses the unpatched base when your build pulls it through the dependency proxy, because that base, on its own, has the findings.

A patched-bases list in your repository lets that one build pull that one base. Only the known-vulnerability (CVE) verdict on the base is deferred, and the image your build produces from it is judged instead by the same gate, on its own findings. What you ship still has to be clean.

When to use it

Use a patched-bases list when all of these are true:

  • your organisation’s image block action is block_pull, so a pull of an image with findings at or above your block threshold is refused;
  • a build of yours pulls an upstream base image through the dependency proxy, and that base has such findings;
  • there is no newer upstream tag or rebuild that fixes them (the finding says Upstream image, no newer fixed tag; see Newer tags for upstream images);
  • your build fixes the findings in its own layers, and the same run pushes the result to your organisation’s container registry on frem.sh.

If a newer upstream tag fixes the findings, move to it instead. If you accept a risk without patching it, that is an exception, not a patched base.

Under warn or none nothing is refused, so there is nothing to defer and the list has no effect.

The threat model

A list that lets an image past a security gate is itself a target. Each rule below closes one way of abusing it.

  • Read from the default branch only. fremforge reads .fremforge/patched-bases.json at the head of the repository’s default branch, never from the branch or commit the job runs on. A pull request that adds or widens an entry changes nothing until it has passed your own branch protection and review and merged. Protect the default branch, and require review of .fremforge/, as you would for workflow files.
  • Exact digests, never tags. An entry names manifest digests, not a tag. A tag can be moved upstream to different content; a digest is the content. Only a pull whose served manifest hashes to a listed digest matches.
  • Named jobs of this repository. An entry names the workflow file and the job that may pull the base, and only jobs of the repository the list is in. fremforge identifies the job from its own records of the running job, not from anything the workflow or the client says. A pull by a person, a registry robot, a personal access token or another repository’s job is judged as before.
  • No pull requests, no forks. Only push, schedule and workflow_dispatch runs on an allowed branch can defer. A pull-request run, a merge-group run or a run from a fork never does, so code that has not been reviewed cannot pull the unpatched base.
  • Your organisation only. The list defers pulls in its own organisation’s dependency proxy, by its own jobs. It cannot defer anything for another organisation, whatever digest or name that organisation uses.
  • The output is judged. The entry names the image your build produces. That image is in your own registry, where the same image gates judge it on every pull: with block_pull, an output that still has findings at or above your threshold is refused like any other image.
  • The output must arrive. Every deferred pull must be followed within 6 hours by a push of the entry’s output image, from the same run, to your organisation’s registry on frem.sh. A job that succeeds without that push suspends the entry for the repository at once, and three failed or unfinished jobs in a row do too: see The output push is checked.
  • Fails closed. An unknown key, or one invalid entry, invalidates the whole list. A list that does not validate defers nothing; it is never half applied.
  • No dates. An entry has no expiry, because it is not an exception: it moves the verdict from the input to the output. When upstream publishes a fixed base, pin the new digest. The old entry then no longer matches anything you pull, and you can remove it.

Example

.fremforge/patched-bases.json in the repository acme/base-images:

{
  "version": 1,
  "bases": [
    {
      "id": "nginx-1-27-patched",
      "image": "docker.io/library/nginx",
      "digests": [
        "sha256:847ed4ff646e27c4141ccda2134c861d71c53d97c8e17c4717aeb0a97371eba6",
        "sha256:416c19e2f2f06ad4ea5fac5768a4ef9ecef4a56f1457a6cd0cb4e4ce1e03f32f"
      ],
      "pullers": [
        { "repo": "acme/base-images", "workflow": "build.yaml", "job": "build" },
        { "repo": "acme/base-images", "workflow": "nightly.yaml", "job": "rebuild (amd64)" }
      ],
      "refs": ["refs/heads/main"],
      "events": ["push", "schedule", "workflow_dispatch"],
      "output": { "image": "nginx-patched" },
      "reason": "Upstream has no release with the fixed OpenSSL yet; our Dockerfile upgrades the affected packages in its own layer.",
      "approved_by": "Platform security team, change review",
      "confirmed": "2026-11-12, platform security team"
    }
  ]
}

The build pins the base by digest, through the dependency proxy, and logs in with the job’s own token:

FROM frem.sh/acme/dependency-proxy/docker.io/library/nginx@sha256:847ed4ff646e27c4141ccda2134c861d71c53d97c8e17c4717aeb0a97371eba6
RUN apt-get update && apt-get install -y --only-upgrade openssl libssl3 && rm -rf /var/lib/apt/lists/*
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "$GITHUB_TOKEN" | docker login frem.sh -u x --password-stdin
      - run: docker build -t frem.sh/acme/nginx-patched:1.27 . && docker push frem.sh/acme/nginx-patched:1.27

Field reference

The top level holds version (must be 1) and bases, and may hold $schema. Any other key invalidates the file.

FieldRequiredMeaning
idyesA short lower-case name for the entry, unique in the file: letters, digits, ., _ and -, 2 to 64 characters, starting with a letter or digit. It is recorded in the audit event.
imageyesThe upstream image as the dependency proxy names it: registry host and path, such as docker.io/library/nginx or ghcr.io/example/server. No tag, no digest, and not the frem.sh/<org>/dependency-proxy/... path. A Docker Hub image needs its full name (docker.io/library/nginx, not nginx).
digestsyes1 to 32 manifest digests, sha256: followed by 64 lower-case hex characters. List the multi-architecture index and the platform manifests your build pulls.
pullersyes1 to 20 jobs that may pull the base, each { "repo", "workflow", "job" }. repo must be this repository, <owner>/<repo>. workflow is the workflow file name under .forgejo/workflows/, such as build.yaml, without the directory. job is the job’s name as Forgejo shows it in the run: its name: if it sets one, otherwise its key; a matrix job with its suffix, such as rebuild (amd64). Matched exactly.
refsno1 to 10 branches the job may run on, as full refs: refs/heads/main. No tags and no wildcards. Default: the repository’s default branch.
eventsnoThe events the run may have: any of push, schedule and workflow_dispatch. Default: all three.
output.imageyesThe image your build produces, in your organisation’s own registry, as the name under your organisation: nginx-patched for frem.sh/acme/nginx-patched. No host, no tag, no digest, and not a dependency-proxy image.
reasonyesWhy the base is patched rather than replaced, 20 to 2,000 characters.
approved_byyesWho reviewed the entry, up to 200 characters.
confirmednoA note that re-confirms the entry, 1 to 200 characters, such as a date and who checked it. It changes nothing about what the entry matches. Setting or changing it is how you lift a suspension.

Limits: the file is at most 64 KiB and holds at most 50 entries.

What is deferred, and what is not

Deferred: only the known-vulnerability (CVE) verdict of the image pull gate, and only for a pull that matches every one of these:

  • a listed digest of the listed image;
  • pulled through your organisation’s dependency proxy;
  • by a listed job of the same repository, in the same organisation, authenticated with that job’s own token;
  • in a run on an allowed branch, for an allowed event.

Such a pull is served. The output image named in the entry is judged by the normal registry CVE gate instead.

Not deferred:

  • the malware checks: infected layers, malicious packages inside the image, and layers that could not be scanned are refused as before;
  • the image signature check and your package policy;
  • pull-request runs, merge-group runs and runs from forks;
  • other repositories, other jobs and other organisations, and pulls that are not made by a job;
  • a digest that is not listed, including the same tag after it has moved upstream.

Your existing CVE exceptions, your block threshold and your block action (block_pull, warn or none) are unchanged.

The output push is checked

A deferral is a promise: the run that pulled the unpatched base builds the patched image and pushes it. fremforge checks that promise for every deferred pull.

  • The clock starts at the pull. The first deferred pull of an entry in a run starts a window of 6 hours. Later pulls of the same entry in the same run do not restart it.
  • The same run. A job of the run that pulled the base must push the output, logged in with its own token. Any job of that run counts. A push by another run, including a later run of the same workflow, or by a person, a personal access token or a registry robot does not.
  • The entry’s output image, in your registry. The push must be an accepted push of frem.sh/<org>/<output.image> to your organisation’s own registry, with any tag. A push to another registry, to another organisation or under another image name does not count.
  • Within 6 hours. fremforge checks every few minutes, so a missing push is found shortly after the 6 hours are over.

If the push did not arrive, the outcome of the job that pulled the base decides, as Forgejo records it at the 6-hour mark. It is the job’s outcome, not the run’s; if several jobs of the run pulled the base for the entry, it counts as a success if any of them succeeded.

  • The job succeeded. The entry is suspended for the repository at once. A job that finished well without delivering its output is what this check exists to catch.
  • The job failed, was cancelled or skipped, or had not finished. The entry is not suspended. The miss is recorded as the audit event image_cve.patched_base_output_skipped and counted. A job that is still running at the 6-hour mark, or that Forgejo no longer knows, counts as not finished.
  • Three in a row. The third such miss for the same entry in the same repository, with no verified push in between, suspends the entry.
  • A verified push resets the count, and so does lifting a suspension.

If an entry is suspended

What happens. The entry defers nothing more for that repository. A pull that the entry would otherwise defer is refused with 403 DENIED and its own reason, patched_base_suspended, so you can tell it from an ordinary CVE refusal:

  • the response carries the header X-Fremforge-Refusal-Reason: patched_base_suspended;
  • the body names the entry, when it was suspended and how to re-confirm it (below);
  • the registry access log records the pull as blocked with the decision_reason image_cve:patched_base_suspended, which the console shows as Blocked: declared patched base suspended (its output image was not pushed).
HTTP/1.1 403 Forbidden
Content-Type: application/json
X-Fremforge-Refusal-Reason: patched_base_suspended
{
  "errors": [
    {
      "code": "DENIED",
      "message": "Pull blocked: patched base \"nginx-1-27-patched\" in .fremforge/patched-bases.json is suspended for this repository (an earlier run that pulled it did not push its output image), so its 3 high/critical finding(s) are judged as usual. To re-confirm it, change the entry on the default branch, e.g. its `confirmed` note.",
      "detail": {
        "reason": "patched_base_suspended",
        "entry": "nginx-1-27-patched",
        "suspended_at": "2026-11-12T16:05:12.000Z",
        "reconfirm": "change the entry on the default branch, e.g. its `confirmed` note",
        "finding_count": 3,
        "block_severity": "high",
        "admin_url": "https://frem.sh/acme/_admin/code-security/images"
      }
    }
  ]
}

detail.finding_count and detail.block_severity are the base’s findings and your block threshold; admin_url is your organisation’s image findings page. The other entries in the list keep working. A suspension does not expire, and a later push does not lift it.

How you are told. fremforge writes the audit event image_cve.patched_base_suspended, which also reaches your SIEM stream, and sends the security event security.policy.violation, with "policy": "patched_base" in details, to every webhook destination subscribed to it. There is no email. To hear about a suspension, subscribe a security alert webhook destination to security.policy.violation, or watch the audit log.

{
  "event": "security.policy.violation",
  "event_id": "9a1e5c7b3d2f4a6c8e0b1d3f5a7c9e2b",
  "occurred_at": "2026-11-12T16:05:12.000Z",
  "org": "acme",
  "severity": "high",
  "title": "Patched base nginx-1-27-patched suspended: run 48213 did not push acme/nginx-patched within 6 h",
  "repository": "acme/base-images",
  "source": "registry",
  "correlation_key": "patched-base:acme/base-images:nginx-1-27-patched",
  "console_url": "https://frem.sh/acme/_admin/code-security/images",
  "details": {
    "policy": "patched_base",
    "audit_event_id": "1f3b5d7f-2a4c-4e6a-8c0e-2b4d6f8a0c1e",
    "org": "acme",
    "repo": "acme/base-images",
    "run_id": 48213,
    "run_number": 112,
    "entry": "nginx-1-27-patched",
    "output_image": "acme/nginx-patched",
    "deferred_at": "2026-11-12T10:01:37.000Z",
    "deferral_event_id": "7c9e1a3b-5d7f-4b2d-9f1a-3c5e7a9b1d3f",
    "window_hours": 6,
    "cause": "success_without_push",
    "outcome": "success"
  }
}

title names the run by its run_id; details.run_number gives its page, /<owner>/<repo>/actions/runs/<run_number>. correlation_key is the same for every suspension of the same entry in the same repository.

How to lift it.

  1. Find out why the push did not arrive (see Mistakes that suspend an entry), and fix the workflow.
  2. Change the entry on the default branch, through your normal review. To change it without changing what it matches, set or change its confirmed note, such as "confirmed": "2026-11-12, push fixed in build.yaml".
  3. Run the build again. At its first pull of the base, fremforge reads the entry at the head of the default branch, sees that it differs from the entry that was suspended, lifts the suspension and writes the audit event image_cve.patched_base_reconfirmed. That pull is deferred again, and its output push is checked like any other.

Only a change to what the entry says counts: any of its fields, confirmed included. Reformatting the file, reordering keys, entries, digests or pullers, and commits to other entries or other files leave the entry as it was, so it stays suspended. A change on another branch or in an open pull request does not count until it has merged.

Verify that it worked

Every deferred pull leaves two records.

In the registry access log, the pull is allowed, and its decision_reason contains image_cve:deferred_patch_input:

curl -sS -H "Authorization: Bearer $FFP_TOKEN" \
  "https://frem.sh/_app/api/v1/orgs/acme/access-log?decision=allowed&since=2026-11-01" \
  | jq '.. | objects | select((.decision_reason? // "") | test("image_cve:deferred_patch_input"))'

In the audit log, and from there on your SIEM stream, each deferred pull is the event image_cve.deferred_patch_input. Its fields:

FieldMeaning
org, repoYour organisation and the repository whose job pulled the base
run_id, run_number, job_idThe run and job; run_number is the run’s page, /<owner>/<repo>/actions/runs/<run_number>
workflow, jobThe workflow file and job name that matched the entry
image, digestThe proxied image and the digest that was served
output_imageThe output image the verdict was deferred to, <org>/<name>
entryThe id of the entry that matched
list_path, list_commit.fremforge/patched-bases.json and the default-branch commit it was read at
entry_hashA hash of the entry as it was read. A suspension is lifted only when it changes
curl -sS -H "Authorization: Bearer $FFP_TOKEN" \
  "https://frem.sh/_app/api/v1/orgs/acme/audit?since=2026-11-01T00:00:00Z" \
  | jq '.. | objects | select(.action? == "image_cve.deferred_patch_input")'

Both need a token with audit:read. If the pull was refused with 403 DENIED and neither record exists, the pull was not deferred: see the mistakes below.

When the output check fails

A miss that does not suspend the entry, a suspension, and the change that lifts it each leave an audit event. The miss that suspends an entry after two earlier ones leaves both its image_cve.patched_base_output_skipped event and the suspension.

image_cve.patched_base_output_skipped, written when a job that did not succeed also did not push:

FieldMeaning
org, repoYour organisation and the repository whose job pulled the base
entryThe id of the entry
run_id, run_numberThe run that pulled the base and did not push the output
output_imageThe output image that was not pushed, <org>/<name>
outcomeThe job’s outcome: failure, cancelled, skipped, unfinished or unknown
consecutive_non_success, suspends_atHow many such misses in a row this is for the entry, and the count that suspends it, 3
deferral_event_idThe id of the image_cve.deferred_patch_input event that started the clock

image_cve.patched_base_suspended, written when the entry is suspended:

FieldMeaning
org, repoYour organisation and the repository the entry is suspended for
entryThe id of the suspended entry
run_id, run_numberThe run that pulled the base and did not push the output
output_imageThe output image that was not pushed, <org>/<name>
deferred_at, deferral_event_idWhen the deferred pull that started the clock happened, and the id of its image_cve.deferred_patch_input event
window_hoursThe window, 6
causesuccess_without_push (the job succeeded without pushing) or non_success_x3 (the third miss in a row)
outcomeThe job’s outcome, as above, or success
consecutive_non_successWith non_success_x3 only: the count, 3

image_cve.patched_base_reconfirmed, written at the first pull after the entry changed:

FieldMeaning
org, repoYour organisation and the repository the suspension is lifted for
entryThe id of the entry
list_commitThe default-branch commit the changed entry was read at
suspended_at, suspended_run_idWhen the entry was suspended, and the run_id of the run that caused it
entry_hashThe hash of the entry as it reads now
curl -sS -H "Authorization: Bearer $FFP_TOKEN" \
  "https://frem.sh/_app/api/v1/orgs/acme/audit?since=2026-11-01T00:00:00Z" \
  | jq '.. | objects | select(.action? | IN("image_cve.patched_base_output_skipped", "image_cve.patched_base_suspended", "image_cve.patched_base_reconfirmed"))'

The security.policy.violation deliveries are in each destination’s delivery log, GET /orgs/{org}/webhooks/deliveries?destination_id={id}.

Common mistakes

A pull that is not deferred is refused exactly as it was before; there is no separate error for it. The exception is a pull of a suspended entry, which carries the reason patched_base_suspended. Check these first:

  • The list is not on the default branch yet. The pull-request run that adds it cannot use it, and neither can any run until the change has merged.
  • The run is a pull request. A pull-request run or a merge-group run never defers, even after the list has merged. Build the image on push, schedule or workflow_dispatch.
  • A tag instead of a digest. "image": "docker.io/library/nginx:1.27" or a tag in digests invalidates the whole list. Put the digests in digests, and pin the base by digest in your Dockerfile, so that an upstream re-push of the tag cannot change what you pull.
  • A digest that is not the one served. A multi-architecture tag is served as an index first, then a platform manifest. List both digests, or the pull of the one you left out is refused.
  • An unknown key, or one bad entry. A misspelt field ("digest" instead of "digests"), an extra field such as "expires", or one entry that does not validate invalidates the whole list, and nothing is deferred for any entry.
  • The wrong job name. job is the name Forgejo shows for the job in the run: its name: if it has one, not its key; a matrix job includes its suffix.
  • A path in workflow. Write build.yaml, not .forgejo/workflows/build.yaml.
  • A short branch name in refs. Write refs/heads/main, not main.
  • Another repository in pullers. A list covers only the jobs of its own repository. To let another repository pull the same base, put a list in that repository.
  • The wrong credential. The job must log in to frem.sh with its own token (GITHUB_TOKEN). A personal access token or a registry robot is not a job, so its pulls are not deferred.
  • The base pulled directly from upstream. Only pulls through frem.sh/<org>/dependency-proxy/... are deferred.

Mistakes that suspend an entry

If a pull is refused with patched_base_suspended, find the image_cve.patched_base_suspended event in the audit log: its cause and run_number say which rule applied and which run caused it. These make the output check fail:

  • The output pushed from another run. Building in one workflow and pushing from another, or pushing the image by hand afterwards, does not count. Push from the run that pulled the base.
  • The output pushed to another registry. A push to Docker Hub, to another registry or to another organisation on frem.sh does not count. Push to frem.sh/<org>/<output.image>.
  • Another image name. For "output": { "image": "nginx-patched" }, a push of nginx-patched-amd64 does not count. The tag does not matter; the name does.
  • The push made with another credential. A personal access token or a registry robot in the push step does not carry the run. Log in with the job’s own token (GITHUB_TOKEN) for the push too.
  • A job that succeeds without pushing. A push step that is skipped by an if: condition, or that fails under continue-on-error, leaves the job successful and the output not pushed. That suspends the entry at once.
  • A listed workflow that never pushes. A scheduled scan or test workflow in pullers whose job pulls the base, succeeds and does not push the output suspends the entry on its first run. List only workflows whose runs push the output.
  • A build that keeps failing after the pull. One failed, cancelled or unfinished job is recorded, not suspended; the third in a row for the same entry, with no verified push in between, suspends it. Fix the build before it fails a third time.
  • A push later than 6 hours. A long build that pushes more than 6 hours after its first pull of the base is too late; a job still running at that point counts as not finished. Pull the base close to the push.
  • Only confirmed changed. Re-confirming without fixing the cause lifts the suspension, but the same mistake suspends the entry again.

See also

  • Image scanning: the findings, the block threshold and the image pull gate.
  • Dependency proxy: pulling upstream images through your organisation.
  • Exceptions: accepting a risk you do not patch, with an expiry and a second approver.
  • Branch protection: the review a change to the list goes through.