hush-am-sdk 0.1.0

Python SDK for Hush secret access via SPIFFE mTLS

hush-am-sdk-python

Python SDK for fetching secrets from the Hush access-manager via SPIFFE mTLS.

Installation

pip install hush-am-sdk

Configuration

The client reads the following environment variables (all populated by the mufasa injector at runtime — there are no constructor overrides):

Variable	Default	Description
_HUSH_INJECTOR_SERVER_ADDRESS	hush-am-access-manager.hush-security.svc:8743	Access-manager address (https:// is added if no scheme is present)
_HUSH_INJECTOR_SPIRE_AGENT_SOCKET_PATH	unix:///tmp/spire-agent/public/api.sock	SPIRE agent socket
_HUSH_INJECTOR_TRUST_DOMAIN	(required)	SPIFFE trust domain. Used to validate the server's identity as spiffe://<trust-domain>/hush/simba/server
_HUSH_INJECTOR_POLICY_SNAPSHOT	(required to call get_secret)	Base64 policy snapshot

Usage

from hush import HushClient

with HushClient() as hush:
    # Fetch a secret's full key-value map
    creds = hush.get_secret("user-a-postgres")
    print(creds["username"], creds["password"])

    # Fetch a single field
    password = hush.get_secret_field("user-a-postgres", "password")

Module-level convenience helpers backed by a singleton client are also available:

from hush import get_secret, get_secret_field

creds = get_secret("user-a-postgres")
password = get_secret_field("user-a-postgres", "password")

Pass an optional bearer token for user-claims filtering:

hush.get_secret("user-a-postgres", token=user_jwt)

Error handling

All SDK errors derive from HushError. Catch the base class for a generic fallback, or the specific subclasses where the caller can do something useful:

Exception	Raised when
HushConfigError	A required _HUSH_INJECTOR_* env var is missing
HushSpiffeError	SPIRE Workload API unreachable or no SVID issued
HushAuthError	mTLS handshake failed or server SPIFFE ID mismatch
HushNetworkError	Connection / timeout reaching the access-manager
HushSecretNotFoundError	Secret missing, or caller's SPIFFE ID has no policy granting access (simba returns 404 for both)
HushFieldNotFoundError	Secret exists but the requested field does not
HushBadRequestError	Server returned 400 — deployment misconfiguration, not caller-recoverable
HushServerError	Server returned 5xx; .status_code and .message available

from hush import HushClient, HushSecretNotFoundError, HushError

try:
    with HushClient() as hush:
        creds = hush.get_secret("user-a-postgres")
except HushSecretNotFoundError:
    ...  # secret missing or no access
except HushError as e:
    ...  # any other SDK failure

Running the example

examples/get_postgres_creds.py shows a minimal end-to-end use of the SDK. It needs a Hush-instrumented runtime to actually fetch a secret — it cannot run from your laptop because there is no local SPIRE agent.

Required runtime conditions:

1. A SPIRE agent reachable at $_HUSH_INJECTOR_SPIRE_AGENT_SOCKET_PATH (provided by your cluster's SPIRE deployment).
2. The mufasa admission controller has injected $_HUSH_INJECTOR_POLICY_SNAPSHOT into the pod — you do not set this manually.
3. $_HUSH_INJECTOR_TRUST_DOMAIN set to your deployment's trust domain.
4. A Hush policy named postgres_creds attached to your workload's SPIFFE ID, with username, password, and host fields.

Steps inside such a pod:

# 1. Install the SDK
pip install -e /path/to/hush-am-sdk-python

# 2. Confirm the runtime env is populated (the injector usually does this)
echo $_HUSH_INJECTOR_TRUST_DOMAIN
echo $_HUSH_INJECTOR_SPIRE_AGENT_SOCKET_PATH
echo $_HUSH_INJECTOR_POLICY_SNAPSHOT

# 3. Run
python examples/get_postgres_creds.py

To try it out without standing up your own infrastructure, deploy as a workload modeled on goat-apps/apps/hush-agent-demo/k8s/deployment.yaml — the same admission-controller annotations, with the container running this script.

Build & publish

The build and publish Makefile targets produce a wheel and upload it to public PyPI:

# Build sdist + wheel into dist/
make build

# Build, then publish to PyPI (requires PyPI credentials in ~/.pypirc
# or TWINE_USERNAME / TWINE_PASSWORD env vars)
make publish

CI publishes automatically on v* tags via PyPI trusted publishing — see .github/workflows/publish.yml.