Burrow SDK for Python

Read secrets from a self-hosted RatelKey Burrow with a machine identity.

• Single and structured secrets, and individual fields of a structured secret.
• The machine's own access map (list_projects, list_secrets).
• Certificate pinning, or standard CA trust (TlsMode).
• An OIDC token instead of a key (Burrow.oidc).

Requirements

• Python 3.9+.
• One dependency: cryptography (Ed25519 signing and the certificate pin).

Install

pip install ratelkey-burrow-sdk

Bootstrap a machine

From the Burrow dashboard, Machines → Add machine, and run the install it gives you on the target host. The identity lands at ~/.burrow/burrows/<slug>/identity.json.

Quick start

from ratelkey_burrow import Burrow

# The single machine identity on this host (under ~/.burrow, or $BURROW_HOME).
burrow = Burrow()

# A single-value secret:
api_key = burrow.get_secret("payments/prod/API_KEY").value

# A structured secret — one read, projected locally (no re-fetch):
db = burrow.get_secret("payments/prod/DATABASE")
everything = db.to_dict()                                  # every field as name -> value
host = db.get_field("host")                                # one field
user, password = db.get_fields("username", "password")     # in order

# What this machine can read:
for p in burrow.list_projects():
    print(p.project, p.categories)

Point it at a specific identity by selector or path:

Burrow("burrow-a1b2c3d4e5f60718")                            # slug / name / machine id / URL
Burrow("/home/you/.burrow/burrows/burrow-a1b2c3d4e5f60718")  # path (a burrow dir or identity.json)

Without ~/.burrow

For an app that manages its own key material:

import os
from ratelkey_burrow import Burrow

burrow = Burrow.connect(
    burrow_url="https://burrow.internal:12010",
    machine_id="...",
    private_key_pem=os.environ["BURROW_MACHINE_KEY"],  # PKCS#8 PEM
)

OIDC

import os
from ratelkey_burrow import Burrow

burrow = Burrow.oidc(
    burrow_url="https://burrow.example.com",
    fingerprint=os.environ.get("BURROW_FINGERPRINT"),  # omit for a publicly-trusted certificate
)

api_key = burrow.get_secret("payments/prod/API_KEY").value

audience defaults to burrow_url. GitHub Actions currently requires permissions: id-token: write.

Certificate trust

from ratelkey_burrow import Burrow, TlsMode

burrow = Burrow(tls=TlsMode.SystemTrust)

Without an explicit tls, the SDK uses the trust chosen when the machine was added: encrypted by default (works everywhere), or verified against the Burrow's own key or a CA if that was selected.

• TlsMode.Pinned — trust-on-first-use, stored at ~/.burrow/burrows/<slug>/known_cert.
• TlsMode.PinnedTo("aa:bb:...") — a fixed fingerprint (from the Burrow's network settings).
• TlsMode.SystemTrust — CA + hostname verification, for a Burrow on a custom domain or Let's Encrypt.
• TlsMode.Insecure — no verification; accepts any certificate. Opt-in only, for a network you already trust. Shortcut: Burrow().insecure_tls(True).

Webhooks

Verify a delivery from a Burrow's Signed webhook. Needs only the webhook's signing secret, not a machine identity.

import os
from flask import Flask, request
from ratelkey_burrow import verify_webhook

app = Flask(__name__)

@app.post("/hooks/burrow")
def burrow_hook():
    event = verify_webhook(request.get_data(), request.headers, os.environ["BURROW_WEBHOOK_SECRET"])
    print(event.event, event.data.summary)
    return "", 204

Pass the raw body, before JSON parsing (request.body in Django). A retry of the same event carries the same event.id, so keep the ids you've handled to ignore repeats.

Errors

Every failure is a BurrowError: BurrowAuthError (401), BurrowForbiddenError (403, no grant), BurrowNotFoundError (404), BurrowServerError (5xx), BurrowCertificateError (pin mismatch), BurrowTransportError (unreachable / unparsable), BurrowIdentityError (no/ambiguous/invalid identity), plus two projection errors on the result handle — SecretShapeError (e.g. .value on a structured secret) and FieldNotFoundError. The message carries the Burrow's own reason. verify_webhook raises BurrowWebhookError for a missing or wrong signature.

Build

python -m build