Reference architecture

Four topologies, one binary, identical policy.

An install-path firewall between your developers, CI and clusters and the sixteen registries they pull from.

Book a 30-min architect review

Dataflow

Client → proxy → verdict

Cache key: (registry, package, version, bundle-digest).

01 · Client
npm, pip, docker, kubelet
resolves the registry host to the proxy
02 · chainsaw-proxy
- authenticate, identify workspace
- 25 signals beyond CVE
- Rego bundle
- Trivy on OCI layers
cache miss: upstream fetch, then evaluate · hit: verdict from memory
Structured refusal

signed audit row written

Bytes streamed

signed audit row written

K8s admission runs the same bundle against the pod spec and returns admit, warn or deny.

Component map · HA

What runs, and what breaks if it dies

One binary; topology decides where each piece sits.

Component	Owns	If it dies
chainsaw-proxy	Evaluates the Rego bundle; forwards, serves from cache or refuses	Stateless; restart costs the cache warm-up
Billy, approval queue	Exception approvals, written as signed rows	Read-only; pending requests never auto-approve
Postgres	Audit rows, exceptions, policy versions, RBAC	Replica failover; block mode refuses rather than emit unrecorded decisions
Blob store	SBOMs, scan artefacts, bundle payloads	SBOM browsing degrades; enforcement continues
NATS policy-bus	Optional cache invalidation between replicas	Falls back to a 15s cache TTL; verdicts unchanged
K8s admission webhook	Same bundle against pod and image specs	failurePolicy Ignore in warn, Fail in block
Intel-bundle store	Digest-verified intel bundle, loaded from CHAINSAW_INTEL_BUNDLE_PATH at start	Failed verification: previous bundle stays

Topologies

SaaS, VPC, on-premises, air-gapped

Same binary, Rego bundle and audit-row schema across all four.

SaaS, Chainsaw-hosted

Figure 1 · SaaS

Chainsaw runs the control and data plane.
VPC-peered

Figure 2 · VPC-peered (dashed: out-of-band control plane)

Data plane in your cloud; no inbound vendor connection.
On-prem, one proxy per BU

Figure 3 · On-prem, one proxy per BU

A deployment pattern you run: each proxy verifies the same signed Rego bundle, which you distribute.
Air-gapped

Figure 4 · Air-gapped

Zero outbound: CHAINSAW_OFFLINE=1.

Identity flow

Okta / Entra → SCIM → Rego input

Policies predicate on the directory without re-querying the IdP at evaluation time.

01 · Identity provider

Okta or Entra
02 · SCIM push

Users and groups into Postgres
03 · Rego input
input.actor.groups

Latency budget

Targets on the hot path

Targets, not measurements. Deployments publish observed p50 / p95 to your Prometheus.

Path	Target	Note
Cache hit, policy unchanged	p50 target < 8 ms	No network egress on the hot path
Cache miss, upstream fetch + 25 signals + Rego eval	p95 target < 450 ms	Dominated by upstream registry latency
K8s admission decision	p99 target < 250 ms	Ledger write is async

Air-gapped operational lifecycle

Sideload, verify, restart

A failed verify loads nothing; the previous bundle stays.

# manifest, hashes and digest binding (--strict adds Sigstore authenticity)
chainsaw bundle verify ./chainsaw-intel-bundle-2026-05-25.tar.gz
# point the proxy at it and restart; providers pick it up on the next refresh tick
CHAINSAW_INTEL_BUNDLE_PATH=./chainsaw-intel-bundle-2026-05-25.tar.gz
# which registries the loaded bundle can adjudicate
chainsaw doctor --offline

CHAINSAW_OFFLINE_FAIL_MODE is advisory: it refuses nothing on its own, and each policy condition applies its own outage fall-back.

Telemetry surfaces

Scrape, trace, ship to SIEM

OpenTelemetry (OTLP)	traces and metrics
Prometheus	latency by verdict, cache hit ratio, bundle age
Golden-signal alerts	5xx rate, p99, burn rate, bundle age, NATS lag
Audit-row schema	stable JSON for Splunk, Sentinel and QRadar

Security baseline

Defaults you don't negotiate

Container identity	uid 10001, non-root, read-only root filesystem, distroless
Verified binary	published SHA-256 checksum; Sigstore signing and SLSA provenance on the roadmap, not yet live
Signed policy bundle	Sigstore-verified at load; disabling it needs an explicit, audited workspace flag
HTTP security headers	CSP, X-Frame-Options, Referrer-Policy on every admin response

Scope boundary

What Chainsaw is not

It refuses on the install path and composes with the categories below.

Architect review

Walk an engineer through your topology

30 minutes with a Chainsaw engineer. Bring your network diagram; leave with a placement plan.

Book the review Talk to sales