Skip to content
Get started

Getting started

Socair is one binary that runs offline. There is no account, and no network call unless you ask for one: pulling a model (socair airlock pull) is the one operation that reaches the network.

Install a release

With Homebrew, on macOS or Linux:

brew install defilantech/tap/socair

The formula installs the release's own socair binary for your platform, checked against the release's SHA256SUMS, so the binary's attestation verifies the installed copy:

gh attestation verify "$(brew --prefix socair)/bin/socair" \
  --repo defilantech/socair \
  --signer-workflow defilantech/socair/.github/workflows/release.yml

Or download a release yourself. Releases are GitHub pre-releases for now. Each holds socair and the optional socair-sigstore helper for linux and darwin on amd64 and arm64, a SHA256SUMS file, a build-provenance attestation for every binary, and an SBOM of the Go modules linked into them. Check the binary before you run it:

V=0.1.0-rc.6
curl -LO https://github.com/defilantech/socair/releases/download/v$V/socair_${V}_linux_amd64
curl -LO https://github.com/defilantech/socair/releases/download/v$V/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
gh attestation verify socair_${V}_linux_amd64 --repo defilantech/socair \
  --signer-workflow defilantech/socair/.github/workflows/release.yml
chmod +x socair_${V}_linux_amd64 && mv socair_${V}_linux_amd64 socair
  • Use darwin or arm64 in the file name for the other platforms. Where sha256sum is missing, use shasum -a 256 --check --ignore-missing SHA256SUMS.
  • The checksums come from the same release page as the binary, so they catch a damaged download, not a tampered release. The attestation and a rebuild from source do that: the attestation records the repository, workflow, commit, and run that built the binary, signed through Sigstore.
  • gh attestation verify fetches the attestation and the Sigstore trust root over the network. To verify on a machine without network access, fetch both on a connected machine first and carry them in; verifying a release shows how.
  • The macOS builds are not notarized. A binary downloaded with a browser is quarantined, so after verifying it, clear that with xattr -d com.apple.quarantine socair. A download with curl is not quarantined.
  • The release binaries do not include the wizard or the airlock console. Build that static web app from a checkout (see the console), or run the container image, which carries it.

On Kubernetes

The Helm chart runs the airlock and the console in one pod, from the release’s container image, ghcr.io/defilantech/socair, which carries the same release binaries and the console’s build. The chart and the image carry build-provenance attestations too. Fetch the chart and check both before installing:

V=0.1.0-rc.6
helm repo add socair https://defilantech.github.io/socair
helm pull socair/socair --version $V
gh attestation verify socair-$V.tgz --repo defilantech/socair \
  --signer-workflow defilantech/socair/.github/workflows/release.yml
gh attestation verify oci://ghcr.io/defilantech/socair:$V \
  --repo defilantech/socair \
  --signer-workflow defilantech/socair/.github/workflows/release.yml

Name the version: Helm lists a pre-release only with --devel. The install, the trust keys, and who can reach the console are in running Socair on Kubernetes.

Your first scan

Point it at a GGUF file, safetensors, a pickle checkpoint, an ONNX, OpenVINO IR, or Keras model, or a whole Hugging Face model directory. The scan runs offline.

./socair scan model.gguf > report.json                  # the report (JSON)
./socair render model.gguf > report.html                # HTML
./socair render model.gguf --pdf report.pdf             # or --sarif report.sarif, --cyclonedx bom.json
./socair scan ~/.cache/huggingface/hub/models--org--name/snapshots/<commit>   # a whole model directory

When it comes back withheld

A file scanned on its own comes back withheld: nothing says where it came from, so the provenance row is NOT_TESTED, and for a single file so is the file inventory, which needs the repository’s file listing. Socair did not look, so it says so. Pull the model through the airlock instead, which records where it came from, and a model whose every row passes comes back authorized with nothing else supplied.

A check that needs data only you hold does not run without it: Known-bad hash match needs your known-bad list, and until you supply one the report names it under Out of scope, where it withholds nothing. Each input moves one row:

SOCAIR_PROVENANCE, which socair airlock pull writes, or an OMS signature from a trusted publisher
Hash, provenance, lineage
SOCAIR_REPO_MIRROR
File inventory and payloads, for a single file
SOCAIR_DENYLIST, or a denylist in your organization’s signed feed
Runs Known-bad hash match, which does not run without one
socair accept, a signed acceptance
The promotion state, for the rows it names

The shapes of those inputs are in the provenance bundle. To see a complete report without a model, ./socair demo > sample.html writes a fabricated sample report, marked SAMPLE on every page.

Sign and verify

key gen writes a private key (mode 0600) and its public half. The report is signed as an in-toto statement in a DSSE envelope, with Ed25519, and anyone with the public key can verify it offline.

./socair key gen --out operator --issuer "Acme ML Platform"
./socair sign --key operator.key --report report.json   # report.dsse.json
./socair verify report.dsse.json --trusted operator.pub --artifact model.gguf
./socair render --attestation report.dsse.json --trusted operator.pub --artifact model.gguf --pdf report.pdf   # the signed attestation, to file

The issuer is whoever signs. --issuer records a name with the key, and sign writes it into the report under the signature; a verifier confirms it against the name its own trust list gives that key. With --artifact, verify also checks the file itself against the report’s hash. render --attestation verifies the envelope the same way and renders what was signed; socair render on a model scans again and marks its draft UNSIGNED.

To try it on a report someone else signed, verify one of the reports on this site. To bring a model into a clean store with its signed report as the ticket, take it through the airlock, step by step.

Hand the report to your other tools

A signed report is the record. These carry it, or what it found, into the systems you already run:

  • Code scanning socair render --sarif writes a SARIF log; each finding carries a fingerprint computed from it, so a rescan of the same bytes reports the same alerts.
  • Your inventory of AI components A CycloneDX ML-BOM of the model, made from the signed report and signed with your key (the first command below).
  • The registry socair attach binds the attestation to an OCI model artifact’s manifest digest, for raw-file layers and for KServe ModelCar images, and socair verify checks it there.
  • The cluster Kyverno policies refuse a pod that names a model artifact without a binding from your key in a promotion state you accept. The doc says which pod fields they read and what they do not check.
  • Your control framework Which rows and features are evidence for which controls (MITRE ATLAS, OWASP LLM, NIST, AI supply-chain guidance), full or partial, and why.

A signed BOM, from the signed report:

./socair sign --key operator.key --bom --attestation report.dsse.json   # report.cdx.dsse.json, a signed CycloneDX BOM

The attestation bound to an OCI model artifact, and checked in the registry:

./socair attach registry.example/models/tiny:q4 --attestation report.dsse.json --key operator.key --trusted operator.pub
./socair verify registry.example/models/tiny:q4 --trusted operator.pub

Or build from source

Go 1.27 or later. Dependencies are vendored, so this builds air-gapped.

git clone https://github.com/defilantech/socair && cd socair
go build -o socair ./cmd/socair

Rebuild a release and compare

Releases are reproducible: the same commit, built with the same Go version, gives byte-identical binaries. Use the exact Go version the release used, which go version -m reports, and build from a clean checkout of the tag. This compares against the release binary under its release name, so it fetches one.

V=0.1.0-rc.6
curl -LO https://github.com/defilantech/socair/releases/download/v$V/socair_${V}_linux_amd64
git clone https://github.com/defilantech/socair socair-src && cd socair-src
git checkout v$V
go version -m ../socair_${V}_linux_amd64 | head -1    # e.g. go1.27.2: the Go version to use
GOTOOLCHAIN=go1.27.2 go version                       # online, once: downloads that toolchain
GOTOOLCHAIN=go1.27.2 scripts/build-release.sh $V dist # needs no network: modules are vendored
sha256sum dist/socair_${V}_linux_amd64 ../socair_${V}_linux_amd64   # the two must match

scripts/build-release.sh sets GOPROXY=off, so it cannot download a toolchain: fetch that toolchain once while online. Details are in verifying a release.

Read further

All the docs