Lockstep

Compare, inspect and sync KV secrets across HashiCorp Vault clusters.

Website: getlockstep.cloud · Try it: demo.getlockstep.cloud, a public demo with two throwaway Vaults (sign in as alice / password; data resets every hour).

Compare KV v2 secrets engines across HashiCorp Vault clusters, or across two mounts in the same Vault. See exactly which values differ, without displaying them. Copy selected keys between the two sides safely, with a reviewed changeset.

Features

• Compare anything to anything. Two Vaults, two mounts, or two path prefixes. Each side has its own connection, mount and prefix.
• Values are compared on the server and never shown unless you ask. The browser receives only a status per key (equal / different / left only / right only / no access). Show values reveals them, only for the secrets you open.
• Only values count. Versions, timestamps and the order of keys inside JSON are ignored. 5432 vs "5432" is flagged as a type difference.
• Comparison profiles. Pair paths that differ between environments (services/*/prod/** ⇄ services/*/staging/**), and ignore keys or paths that are meant to differ. Copies follow the mapping. Profiles can be shared by the team (server) or personal (browser, export/import).
• Honest about permissions. Secrets you can't list or read show as No access, never as "only on the other side", so nobody overwrites what they couldn't see.
• Copy with ← / → per key or per secret. A review shows exactly what each target gets. Writes use KV v2 check-and-set: a target changed by someone else since you compared becomes a conflict, not an overwrite. Nothing is ever deleted. Every write is audit-logged (without values).
• Sync plans. Save a reviewed set of copies as a signed file (paths, keys and versions, never values) that doubles as a report of what needs updating from where. Someone with write access opens it, checks it and applies it. If anything in it changed since it was made, nothing is written and the plan has to be made again. Read-only users can prepare plans.
• Command line too. lockstep compare writes a YAML report of the differences (no values), with each secret's Vault UI link and vault kv get command. Set an action on the keys to change, and lockstep apply makes the copies, asking before each key is written. Logs in like the vault CLI, and works as a drift check in CI (exit code 1 on differences). See Command line.
• Export and import a secret engine. Export a mount with its values to a file, encrypted with a one-time key, leaving out what you choose. Compare a Vault against an export, copy from it, or import it into another Vault with rules and transforms (application-dev-env → application-test-env), previewed and written with check-and-set. In the UI and the CLI (lockstep export, lockstep import).
• Certificate expiry dashboard. Scan one or both sides' mounts for every certificate (PEM, DER, base64, PKCS#12, JKS/JCEKS; keystores opened with the password stored beside them) and see what expires when. Only certificate details come back, never values.
• Value tools. Each value is identified by its content: base64, PEM, DER, X.509 certificates and chains (validated link by link), PKCS#12, JKS / JCEKS keystores, keys, CSRs, images, ZIP/JAR, PDF… Inspect one or both sides, compare certificates field by field, preview images, download files.
• Last-updated metadata. When each secret was written and when each key last changed (worked out from KV v2 versions), never part of the comparison.
• Sign in your way. Token, userpass, LDAP, OIDC redirect (the same flow as the Vault UI), JWT, or the pod's Kubernetes service account with a mount and role you choose.
• Built to run on Kubernetes. Stateless (sessions live in an encrypted cookie), configured only through environment variables, runs on Red Hat Hardened Images (distroless, non-root), scanned in CI.

Screenshots

Connect. Each side discovers the login methods its Vault offers (OIDC preselected).	Key detail and copying. Values shown on request, per-key last change, a staged copy (→) with the target value outlined.
Review before writing. Per target secret: keys added or updated, version change, permission and conflict checks.	What each value is, even while masked: keystores, certificates, expiry.
Comparison profiles. Map prod paths to staging paths, ignore keys meant to differ (here host); copies follow the mapping.	Profile editor. Mappings with wildcards, ignored keys and paths. Shared profiles come from the server; personal ones live in your browser and export as JSON.
Inspect both sides. A PKCS#12 opened with its sibling password key; certificates compared field by field.	Certificate chains, validated link by link against the trust anchors you choose.
Certificate expiry dashboard. Every certificate in both mounts, including inside keystores, by time to expiry; filter, inspect, export CSV.	Sync plans. A saved plan, opened and checked against both Vaults before anyone applies it.
Export and import. An encrypted export with its one-time key, shown once.	Import with rules. Rewrite paths and values (prod → staging), preview, then write with check-and-set.
Pick what to ignore. Click Ignore on secrets, folders and keys, check the effect, save it as a profile.	Override values. Type new values for one side or both; reviewed and written like a copy.
Keystore password finder. The password lives in another folder: candidates are tried on the server, never shown.

Quick start (local, with two demo Vaults)

Requires Podman (or Docker) with Compose.

make up          # = podman compose up --build -d
open http://localhost:8080

This starts two dev-mode Vaults filled with demo data, Dex as an OIDC provider, and the tool. Sign in with OIDC as alice@example.com / password, or with Username alice / password, on both sides. Pick app-config on each side and press Compare. The development guide lists every demo user, mount and fixture.

make up-k8s also starts a small k3s cluster, so you can try Kubernetes auth locally.

Deploy

helm upgrade --install lockstep oci://ghcr.io/welshstew/charts/lockstep --version 0.3.0 \
  -n lockstep --create-namespace -f my-values.yaml

Or run the container anywhere: ghcr.io/welshstew/lockstep:0.3.0 (amd64 and arm64, signed with cosign, with an SBOM and build provenance; see releases).

For the command line, install from GitHub (it isn't on PyPI yet) or use the same image with --entrypoint lockstep. See Command line: install:

pipx install "git+https://github.com/welshstew/lockstep@v0.3.0#subdirectory=backend"

A hardened chart: non-root, read-only filesystem, a session key kept across upgrades, optional Ingress, NetworkPolicy and Kubernetes auth. See Deploying on Kubernetes and the chart README.

Documentation

Guide	Contents
Using the tool	Comparing, statuses and permissions, copying values, value tools, timestamps
Command line	lockstep compare reports and lockstep apply: install, logging in, the report format, exit codes
Authentication	Token, userpass/LDAP, OIDC redirect, JWT, Kubernetes service account: app settings and the Vault-side setup for each
Configuration	Every LOCKSTEP_* setting
Deploying on Kubernetes	The Helm chart, a deployment checklist, OIDC callback and Kubernetes auth in a cluster (chart values)
Public demo	Run the self-contained demo stack on a Docker host with Caddy and automatic HTTPS
Security model	What the tool sees, stores, logs and writes; hardening and supply chain
Development	Project layout, demo data, tests, k3s profile, screenshots, security scanning, CI
API	HTTP endpoints

Status and roadmap

Working: comparison, copying, a command-line interface (reports and apply), value tools, last-updated metadata, comparison profiles (path mapping and ignore rules), a certificate expiry dashboard, all sign-in methods (token, userpass/LDAP, OIDC redirect, Kubernetes), a Helm chart tested in a real cluster, and in CI security scanning, chart checks and browser end-to-end tests.

Possible next steps:

1. Four-eyes rule for sync plans: optionally require the person applying a plan to be someone other than its creator (plans already record who made them)

Licence

MIT. Third-party components keep their own licences; see NOTICE.

Contributions are welcome (CONTRIBUTING.md). Please report security issues privately (SECURITY.md).

---

Lockstep is an independent project. It is not affiliated with, endorsed by or sponsored by HashiCorp. HashiCorp and Vault are trademarks of HashiCorp, Inc.