blackshield-sdk 0.1.0__tar.gz

blackshield_sdk-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+.venv/
+venv/
+
+# Node
+node_modules/
+frontend/dist/
+frontend/.next/
+frontend/.serverless-frontend/
+frontend/.amplify-hosting/
+frontend/tsconfig.tsbuildinfo
+
+# Environment
+.env
+.env.local
+*.env
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+docker-compose.override.yml
+
+# CDK
+iac/cdk.out/
+
+# Coverage
+htmlcov/
+.coverage
+coverage.xml
+
+# Terraform (legacy)
+.terraform/
+*.tfstate*
+
+.tools
+.next
+
+.mipy
+
+# Local agent worktrees
+.claude/worktrees/

blackshield_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: blackshield-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the BlackShield Security Platform
+Project-URL: Homepage, https://blackshield.security
+Project-URL: Documentation, https://docs.blackshield.security/sdk/python
+Project-URL: Repository, https://github.com/blackshield-security/blackshield-python
+Author-email: BlackShield Security <contact@chaplau.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# BlackShield Python SDK
+
+Official Python SDK for the [BlackShield Security Platform](https://blackshield.security).
+
+## Installation
+
+```bash
+pip install blackshield-sdk
+```
+
+## Quick Start
+
+```python
+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
+
+```python
+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
+
+| Resource | Description | Example |
+|----------|-------------|---------|
+| `client.findings` | List, get, update findings | `client.findings.list(severity=["critical"])` |
+| `client.ingestion` | Ingest findings & assets | `client.ingestion.ingest_findings([...])` |
+| `client.dashboard` | Stats, trends, usage | `client.dashboard.stats()` |
+| `client.compliance` | Compliance overview & controls | `client.compliance.overview(framework="SOC2")` |
+| `client.reports` | Summaries & CSV/PDF exports | `client.reports.export_findings_csv()` |
+| `client.easm` | External attack surface | `client.easm.overview()` |
+| `client.threat_intel` | Blocklist & indicator lookup | `client.threat_intel.lookup(indicator="1.2.3.4")` |
+| `client.connectors` | Connector health monitoring | `client.connectors.freshness()` |
+| `client.api_keys` | API key management | `client.api_keys.create(label="CI")` |
+
+## Ingestion
+
+```python
+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
+
+```python
+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
+
+```python
+client = blackshield.BlackShield(
+    api_key="bsk_live_...",
+    base_url="https://api.blackshield.security",  # or self-hosted URL
+    timeout=60.0,       # request timeout in seconds
+    max_retries=3,       # automatic retries on 429/5xx
+)
+```
+
+## Development
+
+```bash
+cd sdk
+pip install -e ".[dev]"
+pytest -v --cov=blackshield
+ruff check .
+mypy .
+```

blackshield_sdk-0.1.0/README.md

@@ -0,0 +1,122 @@
+# BlackShield Python SDK
+
+Official Python SDK for the [BlackShield Security Platform](https://blackshield.security).
+
+## Installation
+
+```bash
+pip install blackshield-sdk
+```
+
+## Quick Start
+
+```python
+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
+
+```python
+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
+
+| Resource | Description | Example |
+|----------|-------------|---------|
+| `client.findings` | List, get, update findings | `client.findings.list(severity=["critical"])` |
+| `client.ingestion` | Ingest findings & assets | `client.ingestion.ingest_findings([...])` |
+| `client.dashboard` | Stats, trends, usage | `client.dashboard.stats()` |
+| `client.compliance` | Compliance overview & controls | `client.compliance.overview(framework="SOC2")` |
+| `client.reports` | Summaries & CSV/PDF exports | `client.reports.export_findings_csv()` |
+| `client.easm` | External attack surface | `client.easm.overview()` |
+| `client.threat_intel` | Blocklist & indicator lookup | `client.threat_intel.lookup(indicator="1.2.3.4")` |
+| `client.connectors` | Connector health monitoring | `client.connectors.freshness()` |
+| `client.api_keys` | API key management | `client.api_keys.create(label="CI")` |
+
+## Ingestion
+
+```python
+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
+
+```python
+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
+
+```python
+client = blackshield.BlackShield(
+    api_key="bsk_live_...",
+    base_url="https://api.blackshield.security",  # or self-hosted URL
+    timeout=60.0,       # request timeout in seconds
+    max_retries=3,       # automatic retries on 429/5xx
+)
+```
+
+## Development
+
+```bash
+cd sdk
+pip install -e ".[dev]"
+pytest -v --cov=blackshield
+ruff check .
+mypy .
+```

blackshield_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "blackshield-sdk"
+dynamic = ["version"]
+description = "Official Python SDK for the BlackShield Security Platform"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "BlackShield Security", email = "contact@chaplau.com" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27,<1",
+    "pydantic>=2.0,<3",
+]
+
+[project.urls]
+Homepage = "https://blackshield.security"
+Documentation = "https://docs.blackshield.security/sdk/python"
+Repository = "https://github.com/blackshield-security/blackshield-python"
+
+[tool.hatch.version]
+path = "src/blackshield/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/blackshield"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "respx>=0.22",
+    "ruff>=0.8",
+    "mypy>=1.13",
+    "pytest-cov>=6.0",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

blackshield_sdk-0.1.0/src/blackshield/__init__.py

@@ -0,0 +1,47 @@
+"""BlackShield Python SDK — Official client for the BlackShield Security Platform.
+
+Quick start::
+
+    import blackshield
+
+    client = blackshield.BlackShield(api_key="bsk_live_...")
+    page = client.findings.list(severity=["critical", "high"])
+    for finding in page.items:
+        print(f"{finding.severity.value} | {finding.title}")
+
+For async usage::
+
+    from blackshield import AsyncBlackShield
+
+    async with AsyncBlackShield(api_key="bsk_live_...") as client:
+        page = await client.findings.list()
+"""
+
+from blackshield._async_client import AsyncBlackShield
+from blackshield._client import BlackShield
+from blackshield._exceptions import (
+    APIError,
+    AuthenticationError,
+    BlackShieldError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ValidationError,
+)
+from blackshield._version import __version__
+
+__all__ = [
+    "APIError",
+    "AsyncBlackShield",
+    "AuthenticationError",
+    "BlackShield",
+    # Exceptions
+    "BlackShieldError",
+    "ConflictError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ValidationError",
+    "__version__",
+]

blackshield_sdk-0.1.0/src/blackshield/_async_client.py

@@ -0,0 +1,130 @@
+"""Asynchronous BlackShield client — async/await variant."""
+
+from __future__ import annotations
+
+from blackshield._base_client import AsyncHTTPClient
+from blackshield.resources.ai_gateway import AsyncAiGatewayResource
+from blackshield.resources.alerts import AsyncAlertsResource
+from blackshield.resources.api_keys import AsyncApiKeysResource
+from blackshield.resources.audit import AsyncAuditResource
+from blackshield.resources.compliance import AsyncComplianceResource
+from blackshield.resources.connectors import AsyncConnectorsResource
+from blackshield.resources.dashboard import AsyncDashboardResource
+from blackshield.resources.easm import AsyncEasmResource
+from blackshield.resources.findings import AsyncFindingsResource
+from blackshield.resources.identity import AsyncIdentityResource
+from blackshield.resources.ingestion import AsyncIngestionResource
+from blackshield.resources.policies import AsyncPoliciesResource
+from blackshield.resources.remediation import AsyncRemediationResource
+from blackshield.resources.reports import AsyncReportsResource
+from blackshield.resources.security_reviews import AsyncSecurityReviewsResource
+from blackshield.resources.threat_intel import AsyncThreatIntelResource
+
+
+class AsyncBlackShield:
+    """Asynchronous client for the BlackShield Security Platform API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.blackshield.security",
+        timeout: float = 60.0,
+        max_retries: int = 3,
+    ) -> None:
+        self._http = AsyncHTTPClient(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._findings = AsyncFindingsResource(self._http)
+        self._ingestion = AsyncIngestionResource(self._http)
+        self._dashboard = AsyncDashboardResource(self._http)
+        self._compliance = AsyncComplianceResource(self._http)
+        self._reports = AsyncReportsResource(self._http)
+        self._easm = AsyncEasmResource(self._http)
+        self._threat_intel = AsyncThreatIntelResource(self._http)
+        self._connectors = AsyncConnectorsResource(self._http)
+        self._api_keys = AsyncApiKeysResource(self._http)
+        self._policies = AsyncPoliciesResource(self._http)
+        self._security_reviews = AsyncSecurityReviewsResource(self._http)
+        self._audit = AsyncAuditResource(self._http)
+        self._alerts = AsyncAlertsResource(self._http)
+        self._identity = AsyncIdentityResource(self._http)
+        self._remediation = AsyncRemediationResource(self._http)
+        self._ai_gateway = AsyncAiGatewayResource(self._http)
+
+    @property
+    def findings(self) -> AsyncFindingsResource:
+        return self._findings
+
+    @property
+    def ingestion(self) -> AsyncIngestionResource:
+        return self._ingestion
+
+    @property
+    def dashboard(self) -> AsyncDashboardResource:
+        return self._dashboard
+
+    @property
+    def compliance(self) -> AsyncComplianceResource:
+        return self._compliance
+
+    @property
+    def reports(self) -> AsyncReportsResource:
+        return self._reports
+
+    @property
+    def easm(self) -> AsyncEasmResource:
+        return self._easm
+
+    @property
+    def threat_intel(self) -> AsyncThreatIntelResource:
+        return self._threat_intel
+
+    @property
+    def connectors(self) -> AsyncConnectorsResource:
+        return self._connectors
+
+    @property
+    def api_keys(self) -> AsyncApiKeysResource:
+        return self._api_keys
+
+    @property
+    def policies(self) -> AsyncPoliciesResource:
+        return self._policies
+
+    @property
+    def security_reviews(self) -> AsyncSecurityReviewsResource:
+        return self._security_reviews
+
+    @property
+    def audit(self) -> AsyncAuditResource:
+        return self._audit
+
+    @property
+    def alerts(self) -> AsyncAlertsResource:
+        return self._alerts
+
+    @property
+    def identity(self) -> AsyncIdentityResource:
+        return self._identity
+
+    @property
+    def remediation(self) -> AsyncRemediationResource:
+        return self._remediation
+
+    @property
+    def ai_gateway(self) -> AsyncAiGatewayResource:
+        return self._ai_gateway
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncBlackShield:
+        return self
+
+    async def __aexit__(self, *_args: object) -> None:
+        await self.close()