Docs

runbook
self-hosted

The runbook. Webhook payload schemas, sandbox config, self-hosting, compliance, install, quickstart.

The deep technical reference a platform team and a tightening reviewer read end to end — four webhook source payloads with their signature-verification notes, the sandbox configuration knob table mapped to the audit-trail and SBOM output, the self-host deployment guide from prerequisites to upgrade workflow, the four-section compliance record a security reviewer reads on audit day, the platform-team install evaluator checklist (prerequisites, env-var surface, worked local-dev Docker compose, upgrade / rollback path), and the quickstart walkthrough that combines five day-one onboarding sections (connect GitHub · trigger entry point · scan cadence · read PR with SBOM delta · rollback) with the seven-step overnight scenario — CVE → draft → sandbox → sign → SBOM → PR.

Schemas

Webhook payload schemas

Four sources — GitHub, CI, dependency, on-call — with minimum JSON payloads and signature-verification notes for every event the watcher ingests.

Knobs

Sandbox configuration

Each knob maps to its audit-trail column and to the SBOM output a runner emits — one tightening reviewer reads end to end.

Self-host

Self-host deployment guide

Prerequisites, install steps, upgrade workflow — every step names the platform team, the artefact, and the verification command the reviewer runs.

Compliance

Compliance record

RBAC matrix, merge audit trail, SBOM emission, and cryptographic signing — the four sections the security reviewer reads first.

Quickstart

Overnight PR walkthrough

Five onboarding sections (connect GitHub · trigger entry · scan cadence · read PR with SBOM delta · rollback), then the seven-step overnight scenario — alert id → audit row in one click.

byte-stable · replayable · KMS-resident

Webhook payload schemas

Four sources, four minimum payloads, four signature-verification notes.

Every webhook that arrives at the in-VPC receiver lands in one of four record sets inside the watcher. The cards below capture the minimum JSON each source emits, the events the watcher subscribes to, and the algorithm + header + secret custody story the verifier checks before the record lands.

Webhook source

GitHub

The Driftlock GitHub App subscribes to push, pull_request, branch_protection_rule, dependabot_alert, and check_run. The watcher correlates every event against an alert id, an advisory GUID, or a failing CI job URL.

  • push · head SHA + sender identity
  • pull_request · open/synchronize/close + review state
  • branch_protection_rule · reviewer + required-checks drift
  • dependabot_alert · advisory GUID + ecosystem
  • check_run · CI failure + log URL

Minimum payload

{
  "id": "12345678901",
  "event": "push",
  "repository": { "full_name": "acme/checkout-svc" },
  "sender": { "login": "ren-bot[bot]" },
  "ref": "refs/heads/main",
  "after": "8f6c1d5b9c2f6c1d5b9c2f6c1d5b9c2f6c1d5b9c",
  "head_commit": { "id": "8f6c1d5b9c2f" }
}

Signature verification

algorithm
HMAC-SHA256
header
X-Hub-Signature-256

A per-install webhook secret minted by your platform team at GitHub App install and rotated on the schedule you set. The watcher compares the header against the HMAC of the raw request body — never the parsed JSON.

Webhook source

CI

A generic job-completion envelope the watcher accepts from any CI runner under your control. Carries the failing-test paths, the log URL, and an OIDC token claim so the replay runs same-identity in the sandbox.

  • job · id + run attempt + pipeline
  • repo · source repo slug under watch
  • head_sha · the commit the job ran against
  • status · success | failure | cancelled
  • failing_tests · paths the sandbox will replay first
  • log_url · internal URL for reviewer drill-down
  • oidc_claim · signed by your CI IdP, audience=driftlock

Minimum payload

{
  "job": { "id": "ci-7421", "run_attempt": 2 },
  "repo": "acme/checkout-svc",
  "head_sha": "8f6c1d5b9c2f",
  "status": "failure",
  "failing_tests": [
    "test/checkout/refund.rs: refund_id_round_trip"
  ],
  "log_url": "https://ci.internal/acme/checkout-svc/7421",
  "oidc_claim": {
    "iss": "https://ci.internal",
    "sub": "ci-runner-7421",
    "aud": "driftlock"
  }
}

Signature verification

algorithm
HMAC-SHA256
header
X-Driftlock-Signature

An HMAC key the platform team stores in your KMS (or as a Kubernetes sealed-secret in air-gap mode). The CI runner writes the header over the raw body; the watcher rejects mismatches before the payload lands.

Webhook source

Dependency

A normalized wrapper around NVD, GHSA, and OSV feeds. Each advisory is enriched with a call-graph path so the watcher only drafts a fix when the affected package is reachable from your review surface.

  • advisory_id · NVD CVE / GHSA id / OSV id
  • source · originating feed (NVD | GHSA | OSV)
  • cve · id + CVSS v3 score
  • affected · PURL list of vulnerable versions
  • call_graph · repo files that import the package
  • ingested_at · ISO-8601 watcher ingest timestamp

Minimum payload

{
  "advisory_id": "GHSA-xxxx-yyyy-zzzz",
  "source": "GHSA",
  "cve": {
    "id": "CVE-2026-9999",
    "cvss_v3": 7.5
  },
  "affected": [
    { "purl": "pkg:npm/lodash@4.17.20" }
  ],
  "call_graph": [
    "api/users",
    "middleware/audit",
    "utils/dep"
  ],
  "ingested_at": "2026-08-08T11:23:14Z"
}

Signature verification

algorithm
GPG / cosign attestation
header
X-Driftlock-Advisory-Signature

Air-gap mode signs each adapter payload with a cosign keypair held on an offline KMS mirror; online mode uses HMAC-SHA256 over the raw body, secret in your KMS. Adapters shipped as signed OCI artifacts so the watcher fails closed on a tampered feed.

Webhook source

On-call

An on-call and SLO-burn envelope the watcher correlates against open incidents. PagerDuty, Opsgenie, and SLO burn-rate alerts all land in the same record so the drafted PR links back to the incident that triggered it.

  • incident · id + originating service + severity
  • title · short label surfaced in the PR body
  • runbook_url · internal runbook for the service
  • fired_at · ISO-8601 trigger timestamp
  • slo · SLO name + burn rate at ingest time

Minimum payload

{
  "incident": {
    "id": "PD-INC-31415",
    "service": "checkout-svc",
    "severity": "SEV-2"
  },
  "title": "5xx surge on /checkout/confirm",
  "runbook_url": "https://runbooks.acme/checkout-5xx",
  "fired_at": "2026-08-08T11:31:02Z",
  "slo": {
    "name": "checkout-availability",
    "burn_rate": 4.8
  }
}

Signature verification

algorithm
HMAC-SHA256
header
X-Driftlock-Signature

Secret stored in your KMS; each vendor adapter rotates the per-vendor key on the schedule your platform team sets. The watcher discards on any mismatch and surfaces a `triage.egressVerdict` reject line so the audit trail captures the attempt.

For Driftlock's outbound event payloads (triage.issue.created, pr.signed, sandbox.failed, dependency.advisory.detected) with field-by-field definitions and HMAC replay, see Webhook payload schema reference.

Verification appendix

Three commands a reviewer runs against any webhook delivery.

Re-listed from the signing identity the governed commits use — same cosign / Sigstore surface, same KMS-resident keypair, same Rekor transparency-log entry.

  • Cosign · verify-blob on the SBOM

    cosign verify-blob --bundle sbom.bundle --certificate-identity-regexp ".*" sbom.json

  • GitHub CLI · verify the PR attestation

    gh attestation verify --owner <org> <sha>

  • Cosign · verify the commit signature

    cosign verify --certificate-identity-regexp ".*" <sha>

Sandbox configuration

Every knob, mapped to its audit-trail column and SBOM output.

The platform team owns one values.yaml. Each row below is a key the platform team sets, the per-PR column it writes to, and the SBOM emission it stamps onto the run. Knob names mirror the audit-trail vocabulary from /governance so the same column name appears in the run record and on this page.

Knob

Audit column · SBOM output

sandbox.toolchain

sandbox toolchain

Hermetic Nix / Bazel build identity. Pins the toolchain so the same diff reproduces byte-for-byte across reruns.

audit column
sandboxed-test
sbom output
toolchainIdentity · hermeticBuildHash on every bumped SBOM

sandbox.cacheMode

sandbox cache mode

Topology-aware test cache. Keeps warmth on out-of-scope paths so only the trigger path reruns.

audit column
sandboxed-test
sbom output
cacheHash field on the sandboxed-test record (no SBOM line)

sandbox.replayFirst

sandbox replay first

Boolean — replay the exact failing test before applying the proposed diff. Keeps the regression reproducible.

audit column
sandboxed-test
sbom output
failingTest + replay enum on the run record

egress.allowed

sandbox egress

Egress allow-list. Default-deny; every outbound call reviewed and versioned by the platform team.

audit column
triage
sbom output
egressVerdict + sandboxed-test.egressAudit line on the record

sbom.format

sandbox sbom format

CycloneDX 1.5 — JSON and XML. Byte-identical output across reruns so the lockfile and the SBOM hash diff together.

audit column
sbom
sbom output
sbom.hash (SHA-256 of the CycloneDX document)

sbom.signingKey

sandbox sbom signing

Cosign / KMS-resident / HSM. The signing key never leaves the signer — Enterprise tier swaps to your HSM.

audit column
sbom
sbom output
sbom.hash + cosign signature recorded on every emission

signing.commitKey

sandbox signing commit

Cosign commit key — KMS-resident, Sigstore OIDC federated to your IdP. Rekor claim binds the run id.

audit column
signed-commit
sbom output
No SBOM line (commit-only signature); Rekor claim carries the SBOM hash

retention.hot / retention.cold

sandbox retention

Tier the audit-trail retention on hot vs cold storage. Defaults align with the AuditField vocabulary.

audit column
approver-chain
sbom output
No SBOM line; retention row applied to the per-PR record

signing.rotation

sandbox signing rotation

KMS-managed rotation on the schedule the platform team sets. Re-key events land a new signerKid in Rekor.

audit column
signed-commit
sbom output
signerKid + Rekor claim refreshed on each rotated commit

nine knobs · audit + SBOM vocabulary shared with /governance

For the runtime knobs platform teams actually set — five supported base images (Node, Python, Go, JVM, Rust), per-step resource limits (CPU, memory, disk, timeout, parallel tests, cache mode) with defaults + ceilings, five secret-mount patterns (envFile, fileMount, oidcToken, k8sSecret, hsmToken) with custody story, the network-isolation toggle set (default-deny egress, TLS pinning), PR-test command templates per language, and the compliance-control mapping a staff-plus engineer reads end to end, see Sandbox configuration reference.

Self-hosting

The deployment guide a platform team owns from prerequisites to upgrade.

Three subsections in order: the prerequisites the platform team holds before install, the install path (Helm once, Terraform when you BYOC), and the upgrade workflow that keeps every chart bump audit-linked and reversible.

Prerequisites the platform team holds before install.

Driftlock installs as one Helm + (optional) Terraform deployment into the VPC your platform team already runs. The list below is the minimum your team supplies — every item maps to a Helm value or a Terraform resource you can audit by name.

  • VPC layoutOne private subnet per environment, outbound deny-by-default, a delegated KMS / HSM role, and a /16 prefix reserved for the watcher / sandbox / signing workloads.
  • KMS / HSM targetAWS KMS · GCP KMS · Azure Key Vault, or on-prem HSM via PKCS#11. The signing keypair and the SBOM key never leave this target — Enterprise tier wires them straight to your HSM.
  • GitHub org + App scopeA GitHub org with a Driftlock App installed on the two-to-ten repos your trial covers. Permissions scoped at install from the App manifest — least-privilege, revocable per repo.
  • Container registryAny OCI-compatible registry with cosign-pinned pulls. A mirror is configurable for dual-region installs so the watcher pulls from the closest warm registry.
  • OIDC IdPOkta · Entra · Google, or your existing internal IdP. Issues the OIDC claims the verifier checks — no long-lived shared secrets in the watcher or sandbox.
  • Hosted PostgreSQLPostgreSQL 15+ · 8 vCPU · 32 GiB · gp3 storage · automated base backup. The project ships Prisma against Postgres; no schema migrations outside the install job.
  • Binary-allowlisted egressDefault-deny network policy on the sandbox namespace. Every outbound host is enumerated in .driftlock/config.yaml and reviewed at deploy time.

Install — Helm once, Terraform when you BYOC.

The install path is one `helm install` plus (optionally) one `terraform apply` for the VPC, IAM, and Postgres resources when your team brings its own cloud. The values.yaml the platform team owns is the only file that needs editing.

  • helm install driftlockhelm install driftlock oci://registry.internal/driftlock --version <semver> -f values.yaml. The chart pins the watcher, sandbox runner, SBOM emitter, webhook receiver, and signing controller to one replica each with bounded egress.
  • terraform apply (BYOC only)terraform apply for VPC + IAM + Postgres when you BYOC. The modules ship with the chart; the state file lives in your Terraform backend, encrypted with the same KMS key as the signing private key.
  • attach KMS keysWire your KMS to the signing workload — KMS-resident cosign keypair for the commit, a second KMS-resident key for SBOMs. Enterprise tier wires both to your HSM.
  • install GitHub AppInstall the Driftlock App on the watched repos. The App opens its webhook to the in-VPC receiver and reads Dependabot, CI, and on-call surfaces through the grants you scoped at install.
  • .driftlock/config.yamlConfigure signal sources + approver group + SBOM ingest targets. The file is sealed-secret encrypted, reviewed by your platform team, and re-applied on every helm upgrade.
  • first smoke PRA signed pull request lands in your queue within minutes — linked to the alert, log, or CVE GUID that produced it. Reviewers traverse from the PR to the trigger in one click.

Upgrade — rolling, reversible, audit-linked.

Upgrades are designed-for-SRE. One workload rolls at a time, a helm rollback fires on any failed pre-flight, an audit-trail entry lands per upgrade, and a green-field install is reproducible from the same values.yaml.

  • helm repo updatehelm repo update driftlock && helm upgrade driftlock driftlock/driftlock --version <semver> -f values.yaml. The chart pulls the next semver, applies the workload in the order signed off in the rollout plan.
  • rolling one workload at a timeWatchdog pre-flight on each workload before the next one starts. A failed pre-flight halts the upgrade and surfaces the failure code in the audit-trail `drafted-fix` slot for that run id.
  • audit-trail entry per upgradeEvery upgrade lands a `signed-commit` row with the new chart version, the new signerKid, and the new Rekor claim. The same row also lands in SBOM output so the SBOM hash diff flags the upgrade in your registry.
  • helm rollback on failed pre-flightHelm rollback fires automatically on any failed pre-flight — the previous revision stays live while the platform team triages. No manual intervention, no silent half-upgrade.
  • green-field install from the same values.yamlWhen your team replatforms or moves regions, the same values.yaml is the only input. The new install lands with the same audit-trail vocabulary, the same SBOM format, and the same signing identity — no manual reseed.

prerequisites · install · upgrade · rolling, reversible, audit-linked

For the platform engineer who reads in front of a security reviewer — nine prerequisites with verification rows (Docker · Postgres · S3-compatible object storage · VPC · KMS · OIDC · registry · GitHub · egress allow-list), seven compose services + a starter docker-compose.yml the platform team commits to their chart repo, twelve Helm values + seven templates + install / upgrade / rollback commands, the full env-var reference cross-checked against .env.example and the env.ts schema, nginx / Caddy / Envoy + mTLS reverse-proxy snippets, a one-page upgrade runbook the team prints and pins, the Helm-managed DB migration step with pg_verifybackup + a PITR + a rollback tactic, three overnight cron schedules (02:14 UTC scan · 03:00 UTC sbom-reaper · 04:00 UTC Sun rekor-prune), and a .driftlock/config.yaml RBAC bootstrap snippet mapped to the six roles × eleven actions grant table this page enumerates under rbac-matrix — see Self-host deployment guide.

Compliance record

Four sections a security reviewer reads on audit day.

The compliance reference a regulated-enterprise security reviewer reads end to end on the day an audit lands — RBAC matrix, merge audit trail, SBOM emission per merged PR, and cryptographic PR-signing. The deep-dive page expands each card below into the row level (matrix rows, audit-trail column schema, SPDX JSON example, cosign verifier commands a reviewer runs verbatim).

RBAC matrix

Six roles × eleven actions

Role × action grant matrix in .driftlock/config.yaml — admin, security reviewer, operator, watcher-bot, sandbox-runner, signing-controller. Every DENY is a hard deny; approval-required cells surface a + sign-off marker so the runtime enforces a dual sign-off gate.

Merge audit trail

Seven columns, append-only, Rekor-anchored

Every merged PR produces one audit row — alert · triage · drafted-fix · sandboxed-test · approver-chain · signed-commit · sbom. 7y hot / 10y cold retention plus an indefinite Rekor-logged pin on the signature + SBOM rows. Rewriting a row invalidates the line HMAC and breaks the Rekor inclusion.

SBOM emission

SPDX 2.3 · content-addressed · cosign-signed

SPDX 2.3 (preferred over CycloneDX 1.5 fallback) emitted per merged PR. The SBOM lands at a content-addressed registry path lookup-by-sha256, signed by the KMS-resident SBOM key — Rekor claim ties the emission back to the run id alongside the commit claim.

Cryptographic signing

cosign ECDSA P-256 · KMS-resident · HSM on Enterprise

Cosign keyful ECDSA P-256 signing identity; private half lives in your KMS by default, on your HSM via PKCS#11 when the platform team is on Enterprise tier. KMS-managed 90-day rotation, Rekor transparency-log claim with run_id + sbom_sha256 + approver_chain_root payload.

rbac · audit trail · sbom (SPDX) · cosign ECDSA P-256 · KMS-resident · HSM on Enterprise

For the security reviewer who reads in front of an audit — six roles × eleven actions grant matrix with explicit DENY overrides, the seven-column per-PR row schema with immutability + retention trio and a sample row, the SPDX 2.3 registry path with a sample SPDX JSON document, the signing .driftlock/config.yaml block with key custody + rotation + Rekor claim payload, and four commands a reviewer runs verbatim (cosign verify, cosign verify-blob, rekor search, gh attestation verify) — see Compliance reference.

Install reference

The install evaluator checklist a platform team reads before sign-off.

For the platform team evaluating Driftlock before sign-off — three prerequisites (Node runtime · Postgres · object storage for SBOM artifacts), the env-var surface grouped by data-handling / signing-key / audit-log, a worked local-dev Docker compose path a platform engineer runs on a laptop, and a three-step evaluator- scoped upgrade / rollback path that links back to /architecture for the pipeline vocabulary.

Evaluator checklist

three prerequisites
laptop-shaped install

The deep-dive page expands each item below into the row-level schema a platform engineer reads end to end. Anchor ids mirror the sibling deep-dives (prereq- · env- · up-) so a reviewer pivots between pages without translating any term.

node ≥ 20.18.1 · postgres 16+ · object storage · data-handling toggles · KMS-resident · audit-log sink · docker compose · upgrade / rollback

For the platform engineer who reads in front of a sign-off — three prerequisites with verification commands (node runtime ≥ 20.18.1 · Postgres 16+ · object storage for SBOM artifacts at the content-addressed registry path), the env-var surface grouped into data-handling toggles (NODE_ENV · SEO_INDEXABLE) · signing-key mount (BETTER_AUTH_SECRET + DRIFTLOCK_KMS_KEY_ALIAS) · audit-log sink (DATABASE_URL + REKOR_URL), every key cross-referenced against .env.example and env.ts, a worked four-service docker-compose the platform team drops into a scratch dir and runs docker compose up against on a laptop, plus four verification commands a platform engineer walks top-to-bottom, and a three-step evaluator-scoped upgrade / rollback path (pre- flight · apply · rollback) that links to /architecture for the pipeline vocabulary — see Install reference.

Quickstart

One overnight PR pass — walkthrough the runbook ties together.

The six-section signpost a platform team and a tightening reviewer read end to end. A transitive dependency CVE surfaces at 02:14 UTC; Driftlock pins the advisory GUID + the affected PURL list to an alert id, drafts a byte-stable fix on a branch, replays the full monorepo test matrix in the sandbox under the pinned hermetic toolchain, signs the commit with cosign ECDSA P-256 over SBOM sha256 + approver-chain root SHA, attaches the SPDX 2.3 SBOM delta, and opens the PR ready for morning merge — the reviewer traces alert id → audit row in one click.

Overnight walkthrough

seven steps
byte-stable · replayable

The deep-dive page expands each step below with anchor ids, icon, body prose, and the matching audit-trail row it pins. Each step in the walkthrough maps to a field already documented on /docs/compliance and to a row on the /architecture audit-trail band.

ingest · triage · draft · sandbox-test · sign · sbom-delta · open-pr · byte-stable · KMS-resident · Rekor-anchored

For the reader who wants one scenario a reviewer follows end to end at 08:00 — the seven ordered step cards (with anchor ids, Lucide icons, and body prose against each step), the example dependency.advisory.detected notification payload, and the Driftlock-stamped PR description Markdown template — see Quickstart reference.

Need a deeper walkthrough?

The runbook grows with each cohort — pace the roll-out to your audit cycle.

The three sections above answer the questions every platform team raises in the first evaluation week. Anything deeper — a key rotation drill, an air-gap runbook, or a defender questionnaire — is best walked through live. Drop your buyer email below and we'll set up a call.

Back to get-started
Architecture — pipeline diagram + audit-trail row schema
See pricing first

Request a deeper-docs walkthrough

We'll reply with a calendar link and the air-gap or key-handling runbook relevant to your scope.