Blacksands Bursar Python SDK

Python client for the Blacksands Bursar API -- zero-trust network security provisioning, certificate management, compliance, and posture verification.

Installation

pip install blacksands-shield

For development:

pip install -e ".[dev]"

Quickstart

from blacksands_shield import ShieldClient

client = ShieldClient(
    client_cert="/path/to/client.crt",
    client_key="/path/to/client.key",
    ca_cert="/path/to/blacksands-ca.crt",  # optional
)

# Create an organisation
org = client.orgs.create("Acme Corp", "admin@acme.com", tier="professional")
org_id = org["data"]["id"]

# Register an application
app = client.apps.register(org_id, "web-frontend", framework="react")
app_id = app["data"]["id"]

# Generate a certificate
cert = client.certs.generate(app_id)

# Provision an endpoint
ep = client.endpoints.provision(app_id, "ingress", "api.acme.com", 443)

# Run a verification scan and wait for results
scan = client.verify.scan(app_id)
result = client.operations.poll_until_complete(scan["data"]["operationId"])

Authentication

The Shield SDK uses mTLS client certificates exclusively. API-key authentication is not supported. An mTLS certificate bundle is issued by a Blacksands administrator through Overwatch or SysAdmin and delivered to the caller out-of-band.

client = ShieldClient(
    client_cert="/path/to/client.crt",
    client_key="/path/to/client.key",
)

The cert and key are attached to the underlying requests session via session.cert.

Configuration

client = ShieldClient(
    client_cert="/path/to/client.crt",
    client_key="/path/to/client.key",
    ca_cert="/path/to/blacksands-ca.crt",       # optional: pin the server cert
    base_url="https://shield.blacksands.io/v1",  # default
    timeout=30,       # seconds, default
    max_retries=3,    # retries on 5xx / connection errors, default
)

API Reference

Organisations -- client.orgs

Applications -- client.apps

Certificates -- client.certs

Endpoints -- client.endpoints

Policies -- client.policies

DNS -- client.dns

Manifests -- client.manifests

Verify -- client.verify

Compliance -- client.compliance

Operations -- client.operations

Sessions -- client.sessions

Error Handling

from blacksands_shield.exceptions import (
    ShieldAPIError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
)

try:
    client.orgs.get("nonexistent")
except NotFoundError as e:
    print(f"Not found: {e} (HTTP {e.status_code})")
except AuthenticationError:
    print("Check your API key")
except RateLimitError:
    print("Slow down -- rate limit hit")
except ShieldAPIError as e:
    print(f"API error: {e}")

All exceptions carry status_code and response attributes.

License

MIT