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.0 also adds 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.

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 .