hush-am-sdk 0.3.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.

Requirements

• Hush-am access-manager deployed in the cluster.
• A SPIRE agent reachable in the pod (provides the SPIFFE SVID for mTLS).
• The pod's workload identity is bound to a Hush policy granting access to the requested secrets.

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:

from husham import HushClient, HushSecretNotFoundError, HushError

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

End-to-end example

The snippet below needs a Hush-am-instrumented runtime to actually fetch a secret — it cannot run from your laptop because there is no local SPIRE agent.

1. Create a Hush-am policy that:

   • Includes an SDK delivery config that maps a secret to <secret_name> and maps the fields you intend to read (e.g. username, password, host).
   • Adds an attestation rule for the pod that will run the SDK, so its workload identity is bound to the policy.

2. Install the SDK in the pod image:

   pip install hush-am-sdk
   

3. Run this snippet inside the pod:

import sys
from husham import HushClient, HushError


def main() -> int:
    try:
        with HushClient() as hush:
            secret = hush.get_secret("<secret_name>")
            print(f"username: {secret['username']}")
            print(f"password: {secret['password']}")

            # Or fetch a single field directly:
            host = hush.get_secret_field("<secret_name>", "host")
            print(f"host: {host}")
    except HushError as exc:
        print(f"{type(exc).__name__}: {exc}", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())

Additional features

Bearer token for user-claims filtering

Pass an optional bearer token to scope the request to a specific user's claims:

hush.get_secret("secret_name", token=user_jwt)
hush.get_secret_field("secret_name", "password", token=user_jwt)

Module-level helpers

Module-level convenience helpers backed by a singleton client are also available, so you don't need to manage a HushClient instance yourself:

from husham import get_secret, get_secret_field

creds = get_secret("secret_name")
password = get_secret_field("secret_name", "password")