Get Started with the Python SDK

# 1. (Optional) Create and activate a Python virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 2. Install the official BlackShield SDK from PyPI
# This will automatically resolve dependencies like httpx and pydantic
pip install blackshield-sdk

# 3. Verify the installation
python -c "import blackshield; print('SDK Version:', blackshield.__version__)"

import os
from blackshield import BlackShield

# 1. Initialize client
# The SDK automatically uses BLACKSHIELD_API_KEY and BLACKSHIELD_API_URL env vars
# if not passed explicitly.
client = BlackShield(
    api_key=os.environ.get("BLACKSHIELD_API_KEY", "sp_your_api_key"),
    base_url=os.environ.get("BLACKSHIELD_API_URL", "https://api.blackshield.chaplau.com")
)

# 2. Retrieve findings
try:
    page = client.findings.list(page_size=20)
    print(f"Retrieved {len(page.items)} findings.")
    for f in page.items:
        print(f"[{f.severity.upper()}] {f.title} - Status: {f.status}")
except Exception as e:
    print(f"Error querying findings: {e}")

import asyncio
import os
from datetime import datetime, timezone
from blackshield import AsyncBlackShield

async def main():
    # 1. Initialize asynchronous client
    client = AsyncBlackShield(
        api_key=os.environ.get("BLACKSHIELD_API_KEY", "sp_your_api_key"),
        base_url=os.environ.get("BLACKSHIELD_API_URL", "https://api.blackshield.chaplau.com")
    )

    # 2. Construct mock finding payload
    new_finding = {
        "finding_type": "vulnerability",
        "title": "Outdated Frontend Library dependency",
        "description": "React-DOM package has known cross-site scripting vulnerabilities.",
        "severity": "high",
        "affected_resource": {
            "resource_type": "repository",
            "resource_id": "github:blackshield-security/frontend",
            "resource_name": "frontend"
        },
        "source": {
            "scanner": "manual-sdk-script",
            "scanner_version": "1.0.0",
            "scan_started_at": datetime.now(timezone.utc).isoformat()
        },
        "dedup_key": "github:frontend:vuln:react-dom"
    }

    # 3. Submit finding
    try:
        async with client:
            job = await client.ingestion.ingest_findings(findings=[new_finding])
            print(f"Ingestion job accepted: {job.job_id} (Status: {job.status})")
    except Exception as e:
        print(f"Failed to ingest finding: {e}")

if __name__ == "__main__":
    asyncio.run(main())