Concepts
Repository types
Section titled “Repository types”FerroBox has three kinds of repository, and a given package format can use any of them:
- Forge — a repository you host directly: you push artifacts to it, FerroBox stores and serves them.
- Mirror — a pull-through cache in front of an upstream registry (e.g. crates.io, npmjs.org). The first request for an artifact fetches and caches it; later requests are served locally. Since 0.2.3, a Mirror can store an upstream username and secret, the upstream URL can be changed after create, and Test connection reports only an HTTP status. The secret is never returned. Prefetch without a version lists the indexed versions before the file is downloaded.
- Alloy — a virtual repository that aggregates several Forge and/or Mirror repos behind one endpoint, so clients only need to point at one URL instead of juggling several.
The directory added in 0.2.4 is where bytes live for the whole instance.
It is an S3 bucket or that directory, not a fourth repository kind.
Settings shows Directory /var/lib/ferrobox/blobs or
S3 bucket ferrobox. Switching storage backends does not copy objects.
Supply-chain checks
Section titled “Supply-chain checks”- Assays — every published package version is assayed. The assay carries a CycloneDX SBOM, declared-license findings, and known vulnerabilities. Vulnerability results come from the instance feed when one is loaded, and from api.osv.dev otherwise. The assay does not itself block a download or a publish.
- Vulnerability feed — one index for the instance. Details below.
- Signing — a repository policy can check a
Cosign signature on OCI images
and Helm charts. That public key is the one you paste under Policies.
It is a different key from
osv-sync.pub.pem, which signs the vulnerability index.
Vulnerability feed
Section titled “Vulnerability feed”Until an administrator loads an index, assays keep calling api.osv.dev.
The index is one ferrobox-osv-index file (v1, JSON or gzip) for the
whole instance. It is not a FerroBox repository, it is not a Docker
image, and it is not a GitHub Release. It covers npm, PyPI, crates.io,
Maven, NuGet, and Go. OCI images, Helm charts, Conan, and generic files
are not part of it.
An administrator configures that index on the Vulnerability feed
page. The reference includes the date. The tag published with 0.2.0 is
ghcr.io/ferrobox/osv-db:2026-10-03. A later day publishes a later tag;
use the tag that exists. Paste
osv-sync.pub.pem
from the product repository into Cosign public key and press
Save. The page reports “Sync settings saved”. Sync now downloads
the artifact and checks the saved reference. While that runs, the button
reads “Syncing…”. A successful import reports “Imported dataset” and that
date. Dataset shows the date, Imported shows when this instance
stored it, and Mode shows sync. Remove clears the loaded feed.
Deleting a repository does not.
A repository’s Packages tab shows the same dataset, import date, and mode, and links to Manage. It does not hold the reference or the key.
A rejected signature does not replace the index already in use. Last
result stays rejected, and Dataset, Imported, and Mode stay as they
were. The console has no control for uploading the file.
An air-gapped machine can still pull that index and check the checksum,
then import the gzip with POST /api/security/osv-feed. The
X-FerroBox-Sha256 header is the hex digest without a sha256: prefix.
That import leaves Mode as file. Sync now pulls from the
registry, so it stays unused on the offline machine. Deleting a
repository does not delete the feed.
0.2.5 introduced a directory built on a connected machine with
infra/offline-bundle.sh. It carries the FerroBox image,
postgres:18-alpine, the Helm chart, one vulnerability index,
osv-sync.pub.pem, and SHA256SUMS. Garage is not in it, and a
container scanner is not in it. The index is still npm, PyPI, crates.io,
Maven, NuGet, and Go. It is not an OCI image. OCI images, Helm charts,
Conan, and generic files stay outside that index. 0.2.6 keeps the
directory and adds linux/arm64. --platform linux/arm64 applies to
0.2.6 and does not apply to 0.2.5. The 0.2.5 digest stays
sha256:609afb8c1ec94acc72a2c6142c9f5e983d88fa5c957d3185d37da2047eb2524a.
The 0.2.6 steps are in the
Quickstart.
oras pull ghcr.io/ferrobox/osv-db:2026-10-03sha256sum -c ferrobox-osv-index.json.gz.sha256Do not use docker save, and do not look for an osv-db-* GitHub
Release.
Before any index is loaded, the page reads “No vulnerability feed has
been imported.” The package list does not show a zero in the severity
column for a version that has not been assayed. When the assay is Ready,
the version shows a count such as [0 Crit | 2 High]. Opening that
count shows Assay · name version. Against the 2026-10-03 index, the
Ready assay for lodash 4.17.20 includes GHSA-35jh-r3h4-6jhm.
Importing an index with a new checksum re-runs the stored assays.
Repeating the same checksum does not. A later Sync now of an index
this instance already has reports “The index is already current”, and
Last result is unchanged.
Paste the public key that ships in the product repository. Generating a key pair, and storing a signing secret in GitHub, is the publish workflow’s job. It is not part of installing FerroBox.




Admission policies
Section titled “Admission policies”Admission policies block a client pull or a promotion when an artifact fails a rule: a known vulnerability at or above a threshold, a denied license, or a missing Cosign signature on an OCI image or Helm chart.
Known vulnerability is Off, ≥ Medium, ≥ High, or ≥ Critical. Off does
not block. At any other setting, a missing feed or an assay that is not
Ready denies the pull and the promote. A missing feed is reported as
feed missing. On the Policies tab the hint under that control reads: if
it is not Off, a missing vulnerability feed or an assay that is not ready
denies the pull. The rule’s When line is “When installing, pulling, or
promoting in”.
The Download button in the console does not apply admission policies. A client pull and a promote do.
Client protocols are unchanged in 0.2.0. If a repository already has this rule on, load a feed before expecting those pulls to succeed. Leave the rule Off to keep the previous behavior.

Access control
Section titled “Access control”- SSO (OIDC) — single sign-on for people. See the Configuration reference for the exact switch and claim mapping.
- RBAC — fine-grained roles per repository.
- Robot tokens — scoped credentials for CI, so pipelines don’t need a shared admin login.
Data lifecycle
Section titled “Data lifecycle”- WORM lock — makes a release immutable once it’s written.
- Quotas — caps how much storage a given repository can use.
- Retention — garbage collection cleans up what your retention rules no longer need.
Replication
Section titled “Replication”Multiple FerroBox instances can be kept in sync across sites or regions, for redundancy or to keep artifacts closer to where they’re used.
Auditability
Section titled “Auditability”Webhooks and a full audit trail cover what happens in the registry, for integrating with your own alerting or compliance tooling.