Skip to content

Supply chain

How SourceOrrery is built and published: one release workflow, locked dependencies, trusted publishing and provenance, how to check what you installed, and what is not done yet.

12 min read

SourceOrrery runs inside every application that reads a secret with it, so a tampered package would be as dangerous as a tampered vault. This page describes how the source becomes the packages you install, what stops someone altering them on the way, how to check what you installed, and what is not done yet. The threat model covers the vault itself.

  • Checks matched to the change. Code changes trigger formatting, Clippy with warnings as errors, tests on Ubuntu, Windows and macOS, SDK tests and the cross-language conformance harness against a real vault, and an audit of every dependency graph (below). The CI gate aggregates those jobs. Documentation-only changes may skip the native builds; the documentation workflow builds and link-checks the site.

  • One workflow, one commit, every package. A release is cut by dispatching .github/workflows/release.yml by hand, never by pushing a tag. One run builds the CLI and the C ABI for six targets and every SDK package from a single commit, creates the GitHub Release with SHA256SUMS, and publishes to each registry. No package is uploaded from a developer’s machine. The procedure is in Releasing.

  • Locked dependencies. CI and the release build with cargo --locked against the committed Cargo.lock (the Python and Node extensions have lock files of their own) and with npm ci against package-lock.json. A dependency changes only in a commit that changes a lock file.

  • Every dependency graph audited. The dependency audit CI job runs scripts/ci/dependency-audit.py over each graph resolved on its own, and fails on a known vulnerability, on a scanner or advisory service that fails (an unavailable scan is never a pass), and on a lock file or package manifest under version control that its inventory does not cover:

    Graph Checked with
    Cargo.lock, bindings/python/Cargo.lock, bindings/node/Cargo.lock cargo audit (RustSec)
    package-lock.json of site/, bindings/node/, scripts/coverage/, scripts/ci/lstk/ npm audit --package-lock-only (no install; the site’s private icon registry is not needed)
    bindings/python/ci-requirements.txt, scripts/coverage/requirements.txt (hash-pinned) the OSV.dev API, every pin
    bindings/python/pyproject.toml no runtime dependencies; its build requirement is pinned above
    bindings/java/pom.xml the OSV.dev API, direct dependencies and plugins (the transitive graph needs Maven; Dependabot follows it)
    the .csproj files the OSV.dev API, direct package references (the transitive graph needs the .NET SDK; Dependabot follows it)
    bindings/go/go.mod, composer.json, bindings/cpp/CMakeLists.txt, the npm platform packages no third-party dependency; the audit fails if one appears

    A maintenance notice (RustSec’s “unmaintained”) is not a vulnerability and is not fixed by calling it one. Each one is reviewed in the script’s REVIEWED table with an owner by role, the upstream issue, the upgrade that removes it and what makes it due again; an unreviewed notice is a warning in CI and fails a release (--strict). Reviewed now:

    Advisories Through Owner Upstream Removed by Revisit
    RUSTSEC-2026-0370 (zvariant), -0371 (zbus_names), -0372 (zvariant_derive) sourceorrery-storage → zbus-secret-service-keyring-store 1.0.1 → secret-service 5.2.0 → zbus 5.19 (the Linux credential store) maintainer of the storage keystore z-galaxy/zbus#2043 (opens in a new tab): merged into zbus 6 secret-service and the keyring store on zbus 6 their release on zbus 6 (a Dependabot cargo update); the upgrade gets the Linux keyring smoke test and the MSRV build
  • Pinned actions, automated updates. Every third-party GitHub Action the workflows use is referenced by the full commit SHA of a release, with the version as a comment, so a moved or compromised tag cannot change what runs in CI or in a release build. Dependabot (.github/dependabot.yml) opens a weekly grouped pull request per ecosystem for the actions and for the Rust, npm, Python, NuGet and Maven dependencies (Rust lock files only; a range change is a deliberate commit), and the workflows CI job runs zizmor over .github/ so an unpinned action or a shell step that expands an input fails the gate.

  • Bills of materials and auditable binaries. Every release carries a CycloneDX document per shipped binary and target, and the CLI and the C ABI library are built with cargo auditable, which embeds their dependency list in the binary (below).

  • Immutable versions. The workflow refuses a tag that already exists. A version is never rebuilt or replaced; a mistake is fixed by the next patch version.

  • No cryptography of our own. Every primitive comes from the RustCrypto crates (architecture).

With trusted publishing, a registry is told once which repository and which workflow file may publish a package. At release time the publishing job presents an identity token that GitHub signs for that one workflow run (OpenID Connect), and the registry exchanges it for a short-lived publishing credential under the configured trust policy. The workflow does not need a stored long-lived token for those registries. npm and PyPI also record a provenance statement, signed through Sigstore, that ties each published file to the commit and the workflow run that built it.

The npm, PyPI, crates.io and NuGet packages have trusted publishers configured for release.yml and ReleasePackages.yaml in Netizine/sourceorrery. Normal 0.3.1 releases use those policies, including the Azure provider and OS helper crate; no first-publication bootstrap is required. Other distribution channels use their mechanisms listed below.

Registry Package Published with What you can check
npm @sourceorreryai/sdk and its six platform packages Trusted publishing Provenance and registry signatures
PyPI sourceorrery Trusted publishing An attestation for every file, and its SHA-256 against the release
crates.io the eleven publishable sourceorrery* crates Trusted publishing (a token that lives 30 minutes) The checksums in Cargo.lock
NuGet SourceOrrery Trusted publishing (a key that lives one hour) nuget.org’s repository signature
Maven Central ai.sourceorrery:sourceorrery The workflow uses a Central publishing token and signs each file with the release key The .asc signature next to each file
Go module proxy github.com/netizine/sourceorrery/bindings/go Nothing uploaded: the tag bindings/go/vX.Y.Z The Go checksum database
Packagist sourceorrery/sourceorrery Nothing uploaded: the tag vX.Y.Z The commit recorded in composer.lock
GitHub Release CLI and C ABI archives, wheels, jar, .nupkg, npm tarballs, SHA256SUMS The release workflow A build provenance attestation per file (gh attestation verify), SHA256SUMS, and the workflow run linked from the release
Homebrew tap sourceorrery in Netizine/homebrew-sourceorrery Nothing uploaded: the release workflow commits a formula naming the release archive for each platform and its SHA-256 Homebrew checks the hash before installing; the formula is a readable file in the tap
Scoop bucket sourceorrery in Netizine/scoop-sourceorrery Nothing uploaded: the release workflow commits a manifest naming the release archives and their SHA-256 Scoop checks the hash before installing
WinGet Netizine.SourceOrrery A pull request on microsoft/winget-pkgs with manifests naming the release archives and their SHA-256, validated there WinGet checks InstallerSha256 before installing

The wheels and sdist on PyPI, the npm tarballs and the jar on Maven Central are byte for byte the files attached to the GitHub Release, so their SHA-256 hashes appear in its SHA256SUMS. Comparing the copies can detect a mismatch between the registry and release, but both originate in the same build workflow: a compromised workflow could publish matching malicious files to both. Check provenance as well as hashes. The .nupkg on nuget.org differs from the release’s only by the repository signature nuget.org adds.

In a project that depends on @sourceorreryai/sdk:

Terminal window
npm audit signatures

It checks the registry signature of every installed package and the provenance of those that carry one; the SourceOrrery packages count among the verified attestations. The package page on npmjs.com shows the same provenance, with links to the commit and the workflow run.

Terminal window
dotnet nuget verify --all ~/.nuget/packages/sourceorrery/0.3.1/sourceorrery.0.3.1.nupkg

Expect Signature type: Repository with the subject NuGet.org Repository by Microsoft.

Every file is signed with the SourceOrrery release key:

F14C 928F CC55 C651 7F1A E1E7 DAFA E59A 4372 DBC2
Terminal window
gpg --keyserver keyserver.ubuntu.com --recv-keys F14C928FCC55C6517F1AE1E7DAFAE59A4372DBC2
curl -LO https://repo1.maven.org/maven2/ai/sourceorrery/sourceorrery/0.3.1/sourceorrery-0.3.1.jar
curl -LO https://repo1.maven.org/maven2/ai/sourceorrery/sourceorrery/0.3.1/sourceorrery-0.3.1.jar.asc
gpg --verify sourceorrery-0.3.1.jar.asc sourceorrery-0.3.1.jar # Good signature from "SourceOrrery Releases ..."

Each file published by trusted publishing carries an attestation, shown under Provenance on the file’s page on pypi.org with the repository, workflow and commit that built it. To check one yourself:

Terminal window
pip install pypi-attestations
pypi-attestations verify pypi --repository https://github.com/Netizine/sourceorrery \
pypi:sourceorrery-<version>-cp311-abi3-manylinux_2_28_x86_64.whl

To make sure every install gets exactly those files, pin the hashes. Each file’s SHA-256 is on its PyPI page and in the release’s SHA256SUMS; check that the two agree, then require them:

requirements.txt
sourceorrery==0.3.1 \
--hash=sha256:<hash of the wheel for each platform you deploy to>
Terminal window
pip install --require-hashes -r requirements.txt

pip-compile --generate-hashes (pip-tools) and uv pip compile --generate-hashes write those lines for you from PyPI.

Cargo.lock records the checksum of every crate, and Cargo verifies it on every build. Install the CLI with --locked:

Terminal window
cargo install --locked sourceorrery-cli --version 0.3.1

The crate ships the lock file the release was built and tested with; without --locked, Cargo resolves the newest compatible version of every dependency at install time instead.

Nothing to do. The go command checks every module version against the checksum database at sum.golang.org and records it in go.sum; a published version can never change.

Packagist serves the repository at the release tag, and composer.lock records the commit it installed. Compare it with the tag:

Terminal window
git ls-remote https://github.com/Netizine/sourceorrery refs/tags/v0.3.1

Every file on a GitHub Release, SHA256SUMS included, carries a build provenance attestation: a statement signed through Sigstore in the release workflow run, stored with the repository, naming the file’s SHA-256, the commit and the workflow that built it. Check a download against it with the GitHub CLI (signed in, or --owner for a public repository without signing in):

Terminal window
gh attestation verify sourceorrery-0.3.1-x86_64-unknown-linux-gnu.tar.gz --repo Netizine/sourceorrery

The command fails for a file that was altered after the build or that did not come out of release.yml in Netizine/sourceorrery. It proves origin on a GitHub-hosted runner; it does not make the code safe, and no reproducible-build claim is made. The attestations are listed under Attestations on the repository’s Actions tab as well.

SHA256SUMS next to the archives proves a download is intact without the GitHub CLI, as Getting started shows; for the files that are also on a registry, compare with the registry’s hash as above.

Every GitHub Release carries one CycloneDX (opens in a new tab) 1.5 document (*.cdx.json) per shipped binary and target, listed in SHA256SUMS and covered by the provenance attestation like every other file:

File Describes
sourceorrery-X.Y.Z-<target>.cdx.json the sourceorrery CLI binary in the archive of the same name
sourceorrery-ffi-X.Y.Z-<target>.cdx.json the C ABI library (libsourceorrery_ffi.*, sourceorrery_ffi.dll) in the sourceorrery-ffi archive, and the same library as embedded in the Java jar, the .NET package and the Go, C, C++ and PHP SDKs
sourceorrery-python-X.Y.Z-<target>.cdx.json the extension module inside the Python wheel for that platform
sourceorrery-node-X.Y.Z-<target>.cdx.json the addon inside the @sourceorreryai/sdk-<platform> package

Each lists every Rust crate compiled into that binary for that target, with name, version, licence and package URL (opens in a new tab) (pkg:cargo/…), and the dependency graph between them; build-time-only dependencies are left out. The documents are rendered from the lock files by cargo cyclonedx in the release workflow, so they describe exactly what cargo --locked built. The language-level wrappers around the C ABI (the jar, the NuGet package, the npm main package, the Go module, the PHP package) have no third-party runtime dependencies of their own, so no separate document is published for them.

Terminal window
jq -r '.components[] | "\(.name) \(.version) \(.licenses[0].license.id // "")"' sourceorrery-0.3.1-x86_64-unknown-linux-gnu.cdx.json

The CLI and the C ABI library are also built with cargo auditable (opens in a new tab), which embeds the same dependency list in the binary itself, so a binary on disk can be checked against the RustSec advisory database without its SBOM:

Terminal window
cargo install cargo-audit --locked
cargo audit bin ./sourceorrery

What SourceOrrery changes in your own supply chain

Section titled “What SourceOrrery changes in your own supply chain”

A malicious dependency, a poisoned install script or a misled coding agent may look for credentials in plain files: .env, configuration files or shell history. Replacing plaintext configuration with vault references reduces that exposure after the original files and copies are removed. It does not change these limits:

  • Code running as you can open the vault as you. An install script or an agent runs with your user’s rights, so it can run the CLI and open any vault you can open without typing anything: this machine’s key opens it silently, and run never asks the view check. Elsewhere a vault opens only where its recovery key is available. Keep production secrets in vaults that development machines cannot open, and keep SOURCEORRERY_RECOVERY_KEY out of shells that install packages. The authenticated broker (milestone 3) is what will change this (threat model).
  • Code inside your application reads what your application reads. A compromised dependency can read every secret the application can. What it cannot do through an SDK is write: no SDK can set, disable, delete or purge a secret, change the vault’s keys, checks or connections, or manage the audit log (ADR 0005), so it cannot plant a value for the next deployment through the library. Every read is recorded in the vault’s audit log, which sourceorrery audit shows.
  • sourceorrery run hands values to every dependency in the child. It puts them in the environment of the process it starts. An SDK keeps each value in the process that asked for it, in a guarded buffer, until it is closed.
  • Maven Central’s checked-in upload uses a stored publishing token and GPG signatures. Registry trust does not replace that workflow mechanism.
  • macOS binaries are not signed or notarised; Windows binaries are not Authenticode-signed.
  • No claim of reproducible builds is made: an SBOM and an attestation say what was built from which commit, not that a second build would be byte-for-byte the same.

These are on the roadmap. To report a package you suspect was tampered with, follow the security policy (opens in a new tab): email security@sourceorrery.ai, not a public issue.