Skip to content

Concepts

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.

  • 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.

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.

Terminal window
oras pull ghcr.io/ferrobox/osv-db:2026-10-03
sha256sum -c ferrobox-osv-index.json.gz.sha256

Do 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.

Vulnerability feed page. Dataset 2026-10-03, Mode sync, reference ghcr.io/ferrobox/osv-db, Last result unchanged

Packages tab for npm-mirror. The feed card shows the same dataset and a Manage link. lodash 4.17.20 shows 0 critical and 2 high

Create repository dialog for an npm Mirror named npm-mirror, with the public npm registry as upstream

Assay dialog for lodash 4.17.20 in the light theme: status Ready, 2 high, 3 medium, license MIT

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.

Policies tab with Known vulnerability set to at least High and the rule enabled

  • 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.
  • 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.

Multiple FerroBox instances can be kept in sync across sites or regions, for redundancy or to keep artifacts closer to where they’re used.

Webhooks and a full audit trail cover what happens in the registry, for integrating with your own alerting or compliance tooling.