An offline fallback bundle holds everything a clean build needs from outside your repository: lockfiles, package files, base images, build tools and the vulnerability data your scanner uses. Keep it in storage you control, refresh it on a schedule, and prove it works with a regular offline build drill.
What the bundle is for
When the public registry is down, rate limited or unreachable from your network, a normal build fails at the first download. A bundle lets you build and ship a hotfix anyway. It is not a daily workflow. It is insurance, and like all insurance it only counts if it pays out when you need it.
The checklist
| Item | Why it is needed | How to keep it |
|---|---|---|
| Lockfiles | Fix exact versions | Committed in each repository |
| Package files | Source of the bytes | Vendor directory, wheelhouse, or a mirror cache |
| Base container images | Builds often start with a pull by tag | Copy to your own registry, pin by digest |
| Build tools and compilers | Fetched on the fly by many pipelines | Bake into a pinned build image |
| Plugins and extensions | Resolved at build time | Include in the cache or vendor set |
| Scanner and its data | A gate that cannot run is a decision, not a check | Store a copy of the scanner and its database |
| Signing keys access | Releases still need signing | Document the path, never copy keys into the bundle |
| A written runbook | People under stress forget steps | One page, tested |
Per language notes
The official documentation for each tool describes an offline route.
- Go. In vendor mode the go command does not use the network or the module cache. See go mod vendor to keep building offline.
- Python. pip can ignore the package index and look only at locations you give it. A local wheelhouse fits that mode. See pip wheelhouse for offline Python installs.
- Rust. Cargo has a net.offline setting that avoids the network and proceeds with locally cached data. See cargo locked, frozen and offline.
- JavaScript. npm has an offline mode that makes no network requests during install, so the cache must already hold every package. See npm ci and cache during a registry outage.
Do not forget the scanner
Teams remember packages and forget the security gate. If the scanner needs the network to fetch its database, your offline build either skips the check or fails. Decide in advance which, and write it down. The choices are in scanner outage: fail open or fail closed in CI, and the caching side is in how to cache a vulnerability database across scan workers. Also read can a security scanner run offline.
Keeping it fresh and safe
- Refresh on a schedule. A bundle six months old holds known vulnerable versions. Rebuild it when lockfiles change and at least monthly.
- Scan the bundle. It is a copy of your dependencies, so it carries their issues.
- Verify integrity. Record hashes of the bundle files and check them before use. See does a cached package need re-verifying.
- Restrict who can change it. An editable bundle is an attack path.
- Store it away from the failing region. A bundle in the same place as your CI fails with it.
- Drill. Follow the monthly offline build drill.
Where Safeguard fits
Safeguard's SBOM and dependency scanning lists what is in your bundle and which findings matter, using reachability analysis to rank them. Refresh the bundle when that list shows something you should not ship.
Quick check
Is vendoring the same as an offline bundle?
Vendoring keeps packages inside the repository. A bundle is wider: it also covers images, tools and scanner data.
How big does a bundle get?
It depends on your dependencies and images. Start with the services you would hotfix first, not everything.
Sources
Last reviewed: 19 October 2026.
