blacksands-bursar 0.2.0__tar.gz

blacksands_bursar-0.2.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: blacksands-bursar
+Version: 0.2.0
+Summary: Python SDK for the Blacksands Bursar API
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+
+# Blacksands Bursar Python SDK
+
+Python client for the Blacksands Bursar API -- zero-trust network security provisioning, certificate management, compliance, and posture verification.
+
+## Installation
+
+```bash
+pip install blacksands-shield
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+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.
+
+```python
+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
+
+```python
+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`
+
+| Method | Description |
+|--------|-------------|
+| `create(name, contact_email, tier="essentials")` | Create a new organisation |
+| `get(org_id)` | Get organisation by ID |
+| `list(limit=20, offset=0)` | List organisations |
+| `update(org_id, **kwargs)` | Update organisation fields |
+
+### Applications -- `client.apps`
+
+| Method | Description |
+|--------|-------------|
+| `register(org_id, name, version=None, framework=None, runtime=None)` | Register a new app |
+| `get(app_id)` | Get application by ID |
+| `list(org_id, limit=20, offset=0)` | List apps for an org |
+| `decommission(app_id)` | Decommission an app |
+
+### Certificates -- `client.certs`
+
+| Method | Description |
+|--------|-------------|
+| `generate(app_id, algorithm="RSA-2048")` | Generate a new certificate |
+| `rotate(app_id, cert_id)` | Rotate a certificate |
+| `revoke(app_id, cert_id)` | Revoke a certificate |
+| `list(app_id, limit=20, offset=0)` | List certificates for an app |
+
+### Endpoints -- `client.endpoints`
+
+| Method | Description |
+|--------|-------------|
+| `provision(app_id, type, hostname, port, protocol="https")` | Provision an endpoint |
+| `list(app_id, limit=20, offset=0)` | List endpoints |
+| `verify(app_id, endpoint_id)` | Verify an endpoint |
+| `deprovision(app_id, endpoint_id)` | Deprovision an endpoint |
+
+### Policies -- `client.policies`
+
+| Method | Description |
+|--------|-------------|
+| `create(app_id, type, name, rules, priority=1)` | Create a policy |
+| `update(app_id, policy_id, **kwargs)` | Update a policy |
+| `apply(app_id)` | Apply all policies for an app |
+| `list(app_id, limit=20, offset=0)` | List policies |
+
+### DNS -- `client.dns`
+
+| Method | Description |
+|--------|-------------|
+| `allow(app_id, domain, reason=None)` | Allow a domain |
+| `block(app_id, domain, reason=None)` | Block a domain |
+| `scan(app_id)` | Trigger a DNS scan |
+| `report(app_id)` | Get DNS report |
+
+### Manifests -- `client.manifests`
+
+| Method | Description |
+|--------|-------------|
+| `submit(org_id, manifest)` | Submit a deployment manifest |
+| `get(manifest_id)` | Get manifest by ID |
+| `provision(manifest_id)` | Provision from manifest |
+| `diff(manifest_id, compare_version)` | Diff against a version |
+
+### Verify -- `client.verify`
+
+| Method | Description |
+|--------|-------------|
+| `scan(app_id)` | Trigger a posture scan |
+| `get_result(operation_id)` | Get scan result |
+| `get_latest(app_id)` | Get latest posture |
+
+### Compliance -- `client.compliance`
+
+| Method | Description |
+|--------|-------------|
+| `get_status(app_id)` | Get compliance status |
+| `generate_report(app_id, framework="SOC2")` | Generate a report |
+| `get_controls(framework)` | List controls for a framework |
+| `get_history(app_id)` | Get compliance history |
+
+### Operations -- `client.operations`
+
+| Method | Description |
+|--------|-------------|
+| `get_status(operation_id)` | Get operation status |
+| `poll_until_complete(operation_id, timeout=120, interval=3)` | Block until done |
+
+### Sessions -- `client.sessions`
+
+| Method | Description |
+|--------|-------------|
+| `list(app_id)` | List active sessions |
+| `get(session_id)` | Get session details |
+| `terminate(session_id)` | Terminate a session |
+
+## Error Handling
+
+```python
+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

blacksands_bursar-0.2.0/README.md

@@ -0,0 +1,197 @@
+# Blacksands Bursar Python SDK
+
+Python client for the Blacksands Bursar API -- zero-trust network security provisioning, certificate management, compliance, and posture verification.
+
+## Installation
+
+```bash
+pip install blacksands-shield
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+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.
+
+```python
+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
+
+```python
+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`
+
+| Method | Description |
+|--------|-------------|
+| `create(name, contact_email, tier="essentials")` | Create a new organisation |
+| `get(org_id)` | Get organisation by ID |
+| `list(limit=20, offset=0)` | List organisations |
+| `update(org_id, **kwargs)` | Update organisation fields |
+
+### Applications -- `client.apps`
+
+| Method | Description |
+|--------|-------------|
+| `register(org_id, name, version=None, framework=None, runtime=None)` | Register a new app |
+| `get(app_id)` | Get application by ID |
+| `list(org_id, limit=20, offset=0)` | List apps for an org |
+| `decommission(app_id)` | Decommission an app |
+
+### Certificates -- `client.certs`
+
+| Method | Description |
+|--------|-------------|
+| `generate(app_id, algorithm="RSA-2048")` | Generate a new certificate |
+| `rotate(app_id, cert_id)` | Rotate a certificate |
+| `revoke(app_id, cert_id)` | Revoke a certificate |
+| `list(app_id, limit=20, offset=0)` | List certificates for an app |
+
+### Endpoints -- `client.endpoints`
+
+| Method | Description |
+|--------|-------------|
+| `provision(app_id, type, hostname, port, protocol="https")` | Provision an endpoint |
+| `list(app_id, limit=20, offset=0)` | List endpoints |
+| `verify(app_id, endpoint_id)` | Verify an endpoint |
+| `deprovision(app_id, endpoint_id)` | Deprovision an endpoint |
+
+### Policies -- `client.policies`
+
+| Method | Description |
+|--------|-------------|
+| `create(app_id, type, name, rules, priority=1)` | Create a policy |
+| `update(app_id, policy_id, **kwargs)` | Update a policy |
+| `apply(app_id)` | Apply all policies for an app |
+| `list(app_id, limit=20, offset=0)` | List policies |
+
+### DNS -- `client.dns`
+
+| Method | Description |
+|--------|-------------|
+| `allow(app_id, domain, reason=None)` | Allow a domain |
+| `block(app_id, domain, reason=None)` | Block a domain |
+| `scan(app_id)` | Trigger a DNS scan |
+| `report(app_id)` | Get DNS report |
+
+### Manifests -- `client.manifests`
+
+| Method | Description |
+|--------|-------------|
+| `submit(org_id, manifest)` | Submit a deployment manifest |
+| `get(manifest_id)` | Get manifest by ID |
+| `provision(manifest_id)` | Provision from manifest |
+| `diff(manifest_id, compare_version)` | Diff against a version |
+
+### Verify -- `client.verify`
+
+| Method | Description |
+|--------|-------------|
+| `scan(app_id)` | Trigger a posture scan |
+| `get_result(operation_id)` | Get scan result |
+| `get_latest(app_id)` | Get latest posture |
+
+### Compliance -- `client.compliance`
+
+| Method | Description |
+|--------|-------------|
+| `get_status(app_id)` | Get compliance status |
+| `generate_report(app_id, framework="SOC2")` | Generate a report |
+| `get_controls(framework)` | List controls for a framework |
+| `get_history(app_id)` | Get compliance history |
+
+### Operations -- `client.operations`
+
+| Method | Description |
+|--------|-------------|
+| `get_status(operation_id)` | Get operation status |
+| `poll_until_complete(operation_id, timeout=120, interval=3)` | Block until done |
+
+### Sessions -- `client.sessions`
+
+| Method | Description |
+|--------|-------------|
+| `list(app_id)` | List active sessions |
+| `get(session_id)` | Get session details |
+| `terminate(session_id)` | Terminate a session |
+
+## Error Handling
+
+```python
+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

blacksands_bursar-0.2.0/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blacksands-bursar"
+version = "0.2.0"
+description = "Python SDK for the Blacksands Bursar API"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+dependencies = ["requests>=2.28.0"]
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-mock", "responses>=0.23"]

blacksands_bursar-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

blacksands_bursar-0.2.0/src/blacksands_bursar/__init__.py

@@ -0,0 +1,21 @@
+"""Blacksands Bursar Python SDK."""
+
+from blacksands_bursar.client import BursarClient
+from blacksands_bursar.exceptions import (
+    BursarAPIError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "BursarClient",
+    "BursarAPIError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "__version__",
+]

blacksands_bursar-0.2.0/src/blacksands_bursar/client.py

@@ -0,0 +1,212 @@
+"""Main Bursar API client, ported from shieldApiClient.js."""
+
+import time
+
+import requests
+
+from blacksands_bursar.exceptions import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    BursarAPIError,
+    ValidationError,
+)
+from blacksands_bursar.resources.apps import AppResource
+from blacksands_bursar.resources.certs import CertResource
+from blacksands_bursar.resources.compliance import ComplianceResource
+from blacksands_bursar.resources.dns import DnsResource
+from blacksands_bursar.resources.endpoints import EndpointResource
+from blacksands_bursar.resources.manifests import ManifestResource
+from blacksands_bursar.resources.operations import OperationResource
+from blacksands_bursar.resources.orgs import OrgResource
+from blacksands_bursar.resources.policies import PolicyResource
+from blacksands_bursar.resources.sessions import SessionResource
+from blacksands_bursar.resources.verify import VerifyResource
+
+_ERROR_MAP = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: AuthenticationError,
+    404: NotFoundError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+DEFAULT_BASE_URL = "https://shield.blacksands.io/v1"
+DEFAULT_TIMEOUT = 30
+DEFAULT_MAX_RETRIES = 3
+
+
+class BursarClient:
+    """Python client for the Blacksands Bursar API.
+
+    Authentication is mTLS only. API keys are not supported.
+
+    Args:
+        client_cert: Path to the PEM client certificate file.
+        client_key: Path to the PEM client private key file.
+        ca_cert: Optional path to a PEM CA bundle to pin the server cert.
+        base_url: Override the default API base URL.
+        timeout: Request timeout in seconds.
+        max_retries: Number of retries for transient (5xx) failures.
+    """
+
+    def __init__(
+        self,
+        client_cert: str,
+        client_key: str,
+        ca_cert: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        if not client_cert or not client_key:
+            raise ValueError(
+                "BursarClient requires client_cert and client_key. "
+                "mTLS is the only supported authentication method."
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        self.session = requests.Session()
+        self.session.headers.update({"Content-Type": "application/json"})
+        self.session.cert = (client_cert, client_key)
+        if ca_cert:
+            self.session.verify = ca_cert
+
+        # Lazy-initialised resource singletons
+        self._orgs = None
+        self._apps = None
+        self._certs = None
+        self._endpoints = None
+        self._policies = None
+        self._dns = None
+        self._manifests = None
+        self._verify = None
+        self._compliance = None
+        self._operations = None
+        self._sessions = None
+
+    # -- resource properties --------------------------------------------------
+
+    @property
+    def orgs(self) -> OrgResource:
+        if self._orgs is None:
+            self._orgs = OrgResource(self)
+        return self._orgs
+
+    @property
+    def apps(self) -> AppResource:
+        if self._apps is None:
+            self._apps = AppResource(self)
+        return self._apps
+
+    @property
+    def certs(self) -> CertResource:
+        if self._certs is None:
+            self._certs = CertResource(self)
+        return self._certs
+
+    @property
+    def endpoints(self) -> EndpointResource:
+        if self._endpoints is None:
+            self._endpoints = EndpointResource(self)
+        return self._endpoints
+
+    @property
+    def policies(self) -> PolicyResource:
+        if self._policies is None:
+            self._policies = PolicyResource(self)
+        return self._policies
+
+    @property
+    def dns(self) -> DnsResource:
+        if self._dns is None:
+            self._dns = DnsResource(self)
+        return self._dns
+
+    @property
+    def manifests(self) -> ManifestResource:
+        if self._manifests is None:
+            self._manifests = ManifestResource(self)
+        return self._manifests
+
+    @property
+    def verify(self) -> VerifyResource:
+        if self._verify is None:
+            self._verify = VerifyResource(self)
+        return self._verify
+
+    @property
+    def compliance(self) -> ComplianceResource:
+        if self._compliance is None:
+            self._compliance = ComplianceResource(self)
+        return self._compliance
+
+    @property
+    def operations(self) -> OperationResource:
+        if self._operations is None:
+            self._operations = OperationResource(self)
+        return self._operations
+
+    @property
+    def sessions(self) -> SessionResource:
+        if self._sessions is None:
+            self._sessions = SessionResource(self)
+        return self._sessions
+
+    # -- core request plumbing ------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs):
+        """Send an HTTP request with retry + exponential back-off.
+
+        Mirrors the JS ``_request(method, path, data, retries)`` pattern:
+        - Retries up to ``max_retries`` on 5xx / connection errors.
+        - Maps 4xx status codes to typed exceptions immediately (no retry).
+        """
+        url = f"{self.base_url}{path}"
+        kwargs.setdefault("timeout", self.timeout)
+
+        last_exc = None
+        for attempt in range(1, self.max_retries + 1):
+            try:
+                resp = self.session.request(method, url, **kwargs)
+
+                if resp.status_code >= 400:
+                    error_body = {}
+                    try:
+                        error_body = resp.json()
+                    except ValueError:
+                        pass
+                    message = error_body.get("error", resp.text or "Unknown error")
+
+                    exc_cls = _ERROR_MAP.get(resp.status_code, BursarAPIError)
+
+                    # Do not retry client errors (4xx) except 429
+                    if resp.status_code < 500 and resp.status_code != 429:
+                        raise exc_cls(message, status_code=resp.status_code, response=resp)
+
+                    # 429 and 5xx are retryable
+                    last_exc = exc_cls(message, status_code=resp.status_code, response=resp)
+                    if attempt == self.max_retries:
+                        raise last_exc
+
+                    time.sleep(2**attempt)
+                    continue
+
+                # Success
+                try:
+                    return resp.json()
+                except ValueError:
+                    return resp.text
+
+            except (requests.ConnectionError, requests.Timeout) as exc:
+                last_exc = BursarAPIError(str(exc))
+                if attempt == self.max_retries:
+                    raise last_exc from exc
+                time.sleep(2**attempt)
+
+        # Should not reach here, but just in case
+        raise last_exc  # pragma: no cover

blacksands_bursar-0.2.0/src/blacksands_bursar/exceptions.py

@@ -0,0 +1,30 @@
+"""Exception classes for the Blacksands Bursar SDK."""
+
+
+class BursarAPIError(Exception):
+    """Base exception for Bursar API errors."""
+
+    def __init__(self, message, status_code=None, response=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+
+class AuthenticationError(BursarAPIError):
+    """Raised when API authentication fails (401)."""
+    pass
+
+
+class RateLimitError(BursarAPIError):
+    """Raised when the API rate limit is exceeded (429)."""
+    pass
+
+
+class NotFoundError(BursarAPIError):
+    """Raised when a requested resource is not found (404)."""
+    pass
+
+
+class ValidationError(BursarAPIError):
+    """Raised when request validation fails (400/422)."""
+    pass