From e971c2aba998f49cec9b186fde4399c2e46c1fa0 Mon Sep 17 00:00:00 2001 From: dash14 Date: Tue, 18 Aug 2026 22:50:19 +0900 Subject: [PATCH] Document the allowlist's structural limit and what to consider within it --- README.md | 11 +++++++++++ docs/security.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) diff --git a/README.md b/README.md index 0330112..b45db00 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ workflow `run:` step rather than a Docker build, use - [Proxy engines](#proxy-engines) - [Report action](#report-action) - [Scope](#scope) +- [Hardening](#hardening) - [Documentation](#documentation) ## Usage @@ -253,6 +254,16 @@ delivered through an allowed domain still runs. Use it as one layer in a defense a last line of defense so that if something slips through your other measures, at least it can't call home. See [Security Details](./docs/security.md) for the full threat model. +## Hardening + +An allowlist works on domain names, so it cannot stop anything leaving through a service you had to +allow anyway. That is a structural limit. What it does stop is traffic to a command-and-control +server or any other host an attacker picked, which is the case an investigation afterwards has the +least to work with. + +Buildcage runs against your Dockerfile as it is, and the generated allowlist already covers that. If +you want to go further within the same limit, see [Hardening](./docs/security.md#hardening). + ## Documentation | Doc | What's in it | diff --git a/docs/security.md b/docs/security.md index 0456a4c..e96e6c2 100644 --- a/docs/security.md +++ b/docs/security.md @@ -136,6 +136,56 @@ Given these implementation costs versus the strict preconditions for the attack - **Major CDN countermeasures** — Major CDN providers like CloudFront and Cloudflare have already introduced measures to restrict domain fronting. Consult your CDN provider's documentation for current details. - **Regular audits** — Periodically run in [audit mode](../README.md#operation-modes) to detect anomalies in connection patterns. +## Hardening + +An allowlist decides which destinations a build can reach. It works on domain names, so it cannot +tell a legitimate use of an allowed destination from an abusive one. Anything leaving through a +service you had to allow anyway still leaves. That is a structural limit rather than something a +better rule set fixes. + +What can be said with confidence is narrower. Traffic to a command-and-control server, or to any +other host an attacker chose, is not on the list and does not go through. That is the case an +investigation afterwards has the least to work with, so closing it is worth something even though +the rest stays open. + +The sections below are for working within that limit. None of them are required. Buildcage runs +against your Dockerfile as it is, and the allowlist an audit run generates already covers the case +above. These are things to consider if you want to go further. + +### Review what the audit produced + +A generated allowlist is tuned for one thing: the build completing. Every entry in it is a +destination you are now permitting, so it is worth a second pass. + +- Can a wildcard become an exact host? `*.githubusercontent.com` covers considerably more than the + one host a build usually needs. +- Is a general-purpose place to put things on the list, such as a gist host, object storage, or an + API that can create repositories? Those double as somewhere to send data to. Check whether the + build genuinely needs it or merely touched it in passing. +- If an entry cannot be dropped, the build itself may be able to change. Pinning a download to a + fixed URL is often enough to replace a broad rule with a narrow one. + +### Reduce what the build has to reach + +Dependency fetching is usually what forces a package registry onto the list. Moving it out of the +main build, into an earlier stage or a step that runs before it, can leave the build proper needing +very little. + +If you already run a registry mirror or proxy, pointing the build at it removes the public registry +from the allowlist. Standing one up purely for this is a large undertaking and not something to do +on Buildcage's account. + +### Read the report when dependencies change + +A destination that was not there before is the thing worth looking into, and a dependency update is +when it tends to appear. The report is the only place a change like that surfaces, so it is worth a +look when the dependency set moves. + +### Keep the rest of your supply chain practice + +Pinning versions, lockfiles, and review still do work an allowlist cannot. Buildcage is one layer +among them rather than a replacement for any of them. + ## Explicit Proxy Engine > [!WARNING]