Skip to main content

Offline & Air-Gapped Operation

Stave runtime commands are designed for offline execution against local files.

Runtime Behavior is Offline​

The runtime CLI (stave) operates on local inputs and does not require cloud credentials or network access.

Typical offline flow:

  1. Prepare local observation and control files.
  2. Run stave validate, stave apply, stave apply --profile aws-s3, or stave diagnose.
  3. Consume local JSON/text output.

Runtime Guarantees​

The stave binary:

  • No network access — contains zero networking code; makes no HTTP requests, DNS lookups, or socket connections.
  • No subprocess execution — never calls os/exec or shells out to external tools.
  • No credential access — does not read AWS credentials, environment variables for cloud APIs, or key stores.
  • Local files only — reads observation JSON and invariant YAML from disk, writes evaluation results to stdout.
  • Embedded schemas — JSON Schemas are compiled into the binary via //go:embed; no download step at runtime.

You can verify this yourself:

# Confirm no net or os/exec imports in the runtime binary
go list -deps ./cmd/stave | grep -E '^net$|^net/http$|^os/exec$'
# Expected: no output

What is in Scope for Air-Gapped Use​

  • Running the released stave binary
  • Validating observations/controls
  • Evaluating findings from local snapshots
  • Diagnosing previous output with local inputs
  • Logic trace audit trail (--trace writes a local JSON file, no network calls)

What is Not Offline​

These activities are outside runtime execution and may require network:

  • downloading dependencies while building from source
  • CI workflows
  • release signing and attestation publication
  • uploading release artifacts

Build-Time Network Dependencies​

Building Stave from source requires network access for the following:

DependencyPurposeWhen
Go module proxy (proxy.golang.org)Download Go dependenciesgo mod download
GitHub Actions runnersCI pipeline executionOn push/PR
govulncheck DB (vuln.go.dev)Known-vulnerability scanningCI lint step
OpenSSF ScorecardSupply-chain security scoringScheduled CI
Docker Hub / GHCRBase images for demo containerdocker build
Sigstore (rekor.sigstore.dev)Keyless release signingRelease workflow
GitHub Releases APIUpload release archivesRelease workflow

For fully air-gapped builds, vendor dependencies first on a connected machine:

go mod vendor
# Then copy the repository (with vendor/) to the air-gapped host
GOFLAGS=-mod=vendor make build

Test-Time Notes​

  • Unit tests (make test) — fully local, no network required.
  • E2E tests (scripts/e2e.sh, scripts/e2e-counterfactual.sh) — fully local, but require jq, diff, and bash to be installed.
  • No test downloads fixtures or contacts external services.

Release-Time Notes​

Release signing and attestation require network access:

  • Sigstore cosign — keyless signing via Fulcio CA and Rekor transparency log
  • SBOM generation — Syft produces SPDX SBOMs (runs locally, but the release workflow uploads them)
  • Build provenance — GitHub-native SLSA attestation on release archives
  • Artifact upload — release archives, checksums, and SBOMs are uploaded to GitHub Releases

Operational Guidance​

  • Treat observation and output files as sensitive.
  • Use --sanitize for shared outputs.
  • Prefer deterministic runs in CI with --now.

FAQ​

Why do the ACL constants contain http:// URLs?​

The constants AllUsersGranteeURI and AuthenticatedUsersGranteeURI in internal/adapters/input/extract/s3/acl.go contain URIs like http://acs.amazonaws.com/groups/global/AllUsers. These are opaque identifiers defined by the AWS S3 ACL specification — they are string comparisons, not HTTP endpoints. Stave never fetches these URLs.

See: AWS ACL grantee documentation

What are the urn:stave:schema:... identifiers?​

The JSON Schema specification requires $id to be a URI. Stave uses URN-scheme identifiers (e.g. urn:stave:schema:obs.v0.1) as in-memory identifiers for the schema compiler. Schemas are loaded from embedded files (//go:embed), never fetched over the network. The URN scheme was chosen specifically to avoid false positives from security scanners looking for HTTP endpoints.

Does genrecordings make network calls?​

No. cmd/genrecordings is a developer-only build tool (not part of the shipped binary) that uses os/exec to run the local stave binary and capture terminal recordings. It makes no network connections.