BlackShield Python SDK

Official Python SDK for the BlackShield Security Platform.

Installation

pip install blackshield-sdk

Quick Start

import blackshield

client = blackshield.BlackShield(api_key="bsk_live_...")

# List critical findings
page = client.findings.list(severity=["critical", "high"], page_size=10)
for f in page.items:
    print(f"{f.severity.value} | {f.title}")

# Get a specific finding
finding = client.findings.get("550e8400-e29b-41d4-a716-446655440000")

# Update finding status
client.findings.update_status(finding.id, status="in_progress", reason="Investigating")

Async Usage

import asyncio
from blackshield import AsyncBlackShield

async def main():
    async with AsyncBlackShield(api_key="bsk_live_...") as client:
        page = await client.findings.list(severity=["critical"])
        for f in page.items:
            print(f.title)

asyncio.run(main())

Available Resources

Version 0.2.1 preserves the 0.2.0 surface and adds durable EASM verification outcomes, explicit challenge rotation, and synchronous/asynchronous AI provider configuration deletion. Version 0.2.0 added EASM asset-verification operations, AI Gateway client updates/deactivation, OAuth token exchange and governed chat completions. Reports v2 and Threat Intelligence v2 are part of the supported public surface. All new resources have matching synchronous and asynchronous implementations.

Official packages are released only by the Jenkins Publish SDK stage after the Python 3.10–3.13 matrix and repository security gates pass. The stage publishes an immutable PyPI version and fingerprints its wheel checksum; it does not depend on a GitHub workflow, release, or tag.

Ingestion

from blackshield.types.ingestion import UnifiedFinding, AffectedResource, SourceMeta

finding = UnifiedFinding(
    finding_type="vulnerability",
    title="CVE-2024-1234 in openssl 3.0.8",
    severity="critical",
    cve_id="CVE-2024-1234",
    affected_resource=AffectedResource(
        resource_type="container_image",
        resource_id="sha256:abc123",
        resource_name="myapp:latest",
    ),
    source=SourceMeta(scanner="trivy", scanner_version="0.50.0"),
    dedup_key="vuln:CVE-2024-1234:sha256:abc123",
)

result = client.ingestion.ingest_findings([finding])
print(f"Job ID: {result.job_id}, Status: {result.status}")

# Poll for completion
job = client.ingestion.get_job(result.job_id)
print(f"Created: {job.created}, Updated: {job.updated}")

Error Handling

import blackshield

try:
    finding = client.findings.get("nonexistent-id")
except blackshield.NotFoundError:
    print("Finding not found")
except blackshield.RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except blackshield.AuthenticationError:
    print("Invalid API key")
except blackshield.BlackShieldError as e:
    print(f"API error: {e}")

Configuration

client = blackshield.BlackShield(
    api_key="bsk_live_...",
    base_url="https://api.blackshield.chaplau.com",  # or self-hosted URL
    timeout=60.0,       # request timeout in seconds
    max_retries=3,       # automatic retries on 429/5xx
)

Development

cd sdk
pip install -e ".[dev]"
pytest -v --cov=blackshield
ruff check .
mypy .