spidercob 0.1.0__tar.gz

spidercob-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+
+.env*
+

spidercob-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: spidercob
+Version: 0.1.0
+Summary: Python SDK for the Spidercob DLP API — scan, detect, and remediate sensitive data at scale
+Project-URL: Homepage, https://spidercob.com
+Project-URL: Repository, https://github.com/SpiderCob/spidercob-python
+Project-URL: Bug Tracker, https://github.com/SpiderCob/spidercob-python/issues
+License: Apache-2.0
+Keywords: compliance,data-loss-prevention,dlp,gdpr,hipaa,pci-dss,pii,privacy,secrets,security,spidercob
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# spidercob
+
+Python SDK for the [Spidercob](https://spidercob.com) DLP API.
+
+Scan text, files, and data pipelines for PII, secrets, and sensitive data. Get AI-powered analysis, compliance alerts, and remediation guidance — all from a single API call.
+
+```python
+from spidercob import Client
+
+client = Client(api_key="your-api-key")
+result = client.scan("postgresql://admin:s3cr3t@prod-db:5432/mydb")
+
+print(result.highest_severity)       # CRITICAL
+print(result.critical[0].type)       # db_connection_string
+print(result.ai_insight)             # CISO-grade analysis
+print(result.compliance_alerts)      # ["PCI-DSS", "SOC2"]
+```
+
+## Install
+
+```bash
+pip install spidercob
+```
+
+Zero dependencies. Python 3.9+.
+
+Get your API key at [spidercob.com/settings](https://spidercob.com/settings).
+
+## Authentication
+
+```python
+# Pass directly
+client = Client(api_key="your-api-key")
+
+# Or set environment variable
+export SPIDERCOB_API_KEY=your-api-key
+client = Client()
+```
+
+## Scan text
+
+```python
+result = client.scan("My SSN is 432-78-9012 and AWS key AKIAIOSFODNN7EXAMPLE")
+
+result.has_findings          # True
+result.highest_severity      # "CRITICAL"
+result.critical              # list[Finding]
+result.high
+result.medium
+result.low
+
+# Each Finding:
+f = result.critical[0]
+f.type                       # "aws_access_key"
+f.description                # "AWS Access Key ID"
+f.value                      # masked value
+f.severity                   # "CRITICAL"
+f.position                   # "char 10-30"
+f.remediation                # "Rotate this key immediately in AWS IAM"
+
+# AI analysis
+result.ai_insight            # CISO-grade explanation
+result.compliance_alerts     # ["PCI-DSS 3.2", "SOC 2 CC6"]
+result.threat_score          # 0-100
+```
+
+## Scan a file
+
+```python
+result = client.scan_file("src/config.py")
+if result.has_findings:
+    print(result.to_dict())
+```
+
+## Retrieve past scans
+
+```python
+# Get a scan by ID
+result = client.get_scan(scan_id=1234)
+
+# List recent scans
+scans = client.list_scans(limit=20)
+```
+
+## Use in CI
+
+```python
+import sys
+from spidercob import Client
+
+client = Client()
+result = client.scan_file("config.py")
+
+if result.critical:
+    for f in result.critical:
+        print(f"CRITICAL: {f.type} at {f.position}")
+        print(f"  Remediation: {f.remediation}")
+    sys.exit(1)
+```
+
+## Error handling
+
+```python
+from spidercob import Client, AuthenticationError, RateLimitError, SpidercobError
+
+try:
+    result = client.scan(text)
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Rate limit hit — slow down or upgrade plan")
+except SpidercobError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Free tier — no API key needed
+
+Want to scan locally without an API key? Use [dlp-patterns](https://github.com/SpiderCob/dlp-patterns) — the open source pattern engine this SDK is built on:
+
+```bash
+pip install dlp-patterns
+```
+
+The SDK adds: AI-powered CISO analysis, compliance mapping (GDPR/HIPAA/PCI-DSS/SOC2), audit logs, dashboard, team management, and policy enforcement.
+
+## License
+
+Apache 2.0

spidercob-0.1.0/README.md

@@ -0,0 +1,128 @@
+# spidercob
+
+Python SDK for the [Spidercob](https://spidercob.com) DLP API.
+
+Scan text, files, and data pipelines for PII, secrets, and sensitive data. Get AI-powered analysis, compliance alerts, and remediation guidance — all from a single API call.
+
+```python
+from spidercob import Client
+
+client = Client(api_key="your-api-key")
+result = client.scan("postgresql://admin:s3cr3t@prod-db:5432/mydb")
+
+print(result.highest_severity)       # CRITICAL
+print(result.critical[0].type)       # db_connection_string
+print(result.ai_insight)             # CISO-grade analysis
+print(result.compliance_alerts)      # ["PCI-DSS", "SOC2"]
+```
+
+## Install
+
+```bash
+pip install spidercob
+```
+
+Zero dependencies. Python 3.9+.
+
+Get your API key at [spidercob.com/settings](https://spidercob.com/settings).
+
+## Authentication
+
+```python
+# Pass directly
+client = Client(api_key="your-api-key")
+
+# Or set environment variable
+export SPIDERCOB_API_KEY=your-api-key
+client = Client()
+```
+
+## Scan text
+
+```python
+result = client.scan("My SSN is 432-78-9012 and AWS key AKIAIOSFODNN7EXAMPLE")
+
+result.has_findings          # True
+result.highest_severity      # "CRITICAL"
+result.critical              # list[Finding]
+result.high
+result.medium
+result.low
+
+# Each Finding:
+f = result.critical[0]
+f.type                       # "aws_access_key"
+f.description                # "AWS Access Key ID"
+f.value                      # masked value
+f.severity                   # "CRITICAL"
+f.position                   # "char 10-30"
+f.remediation                # "Rotate this key immediately in AWS IAM"
+
+# AI analysis
+result.ai_insight            # CISO-grade explanation
+result.compliance_alerts     # ["PCI-DSS 3.2", "SOC 2 CC6"]
+result.threat_score          # 0-100
+```
+
+## Scan a file
+
+```python
+result = client.scan_file("src/config.py")
+if result.has_findings:
+    print(result.to_dict())
+```
+
+## Retrieve past scans
+
+```python
+# Get a scan by ID
+result = client.get_scan(scan_id=1234)
+
+# List recent scans
+scans = client.list_scans(limit=20)
+```
+
+## Use in CI
+
+```python
+import sys
+from spidercob import Client
+
+client = Client()
+result = client.scan_file("config.py")
+
+if result.critical:
+    for f in result.critical:
+        print(f"CRITICAL: {f.type} at {f.position}")
+        print(f"  Remediation: {f.remediation}")
+    sys.exit(1)
+```
+
+## Error handling
+
+```python
+from spidercob import Client, AuthenticationError, RateLimitError, SpidercobError
+
+try:
+    result = client.scan(text)
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Rate limit hit — slow down or upgrade plan")
+except SpidercobError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Free tier — no API key needed
+
+Want to scan locally without an API key? Use [dlp-patterns](https://github.com/SpiderCob/dlp-patterns) — the open source pattern engine this SDK is built on:
+
+```bash
+pip install dlp-patterns
+```
+
+The SDK adds: AI-powered CISO analysis, compliance mapping (GDPR/HIPAA/PCI-DSS/SOC2), audit logs, dashboard, team management, and policy enforcement.
+
+## License
+
+Apache 2.0

spidercob-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spidercob"
+version = "0.1.0"
+description = "Python SDK for the Spidercob DLP API — scan, detect, and remediate sensitive data at scale"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.9"
+dependencies = []
+keywords = [
+    "dlp", "data-loss-prevention", "pii", "secrets", "security",
+    "privacy", "compliance", "gdpr", "hipaa", "pci-dss", "spidercob",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage    = "https://spidercob.com"
+Repository  = "https://github.com/SpiderCob/spidercob-python"
+"Bug Tracker" = "https://github.com/SpiderCob/spidercob-python/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "responses>=0.25"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spidercob"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

spidercob-0.1.0/src/spidercob/__init__.py

@@ -0,0 +1,37 @@
+"""
+spidercob — Python SDK for the Spidercob DLP API.
+
+Quick start::
+
+    from spidercob import Client
+
+    client = Client(api_key="your-api-key")
+    result = client.scan("My AWS key is AKIAIOSFODNN7EXAMPLE")
+
+    print(result.highest_severity)       # CRITICAL
+    print(result.critical[0].type)       # aws_access_key
+    print(result.ai_insight)             # CISO-grade analysis
+    print(result.compliance_alerts)      # ["PCI-DSS", "SOC2"]
+
+Full docs: https://github.com/SpiderCob/spidercob-python
+"""
+
+from spidercob._client import (
+    Client,
+    ScanResult,
+    Finding,
+    SpidercobError,
+    AuthenticationError,
+    RateLimitError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client",
+    "ScanResult",
+    "Finding",
+    "SpidercobError",
+    "AuthenticationError",
+    "RateLimitError",
+    "__version__",
+]

spidercob-0.1.0/src/spidercob/_client.py

@@ -0,0 +1,255 @@
+"""Spidercob API client."""
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+import json
+
+
+BASE_URL = "https://spidercob.com"
+
+
+@dataclass
+class Finding:
+    type: str
+    description: str
+    value: str
+    severity: str
+    position: str
+    context: str = ""
+    remediation: str = ""
+    context_score: float = 0.0
+
+    @classmethod
+    def _from_dict(cls, d: Dict[str, Any]) -> "Finding":
+        return cls(
+            type=d.get("type", ""),
+            description=d.get("description", ""),
+            value=d.get("value", ""),
+            severity=d.get("severity", ""),
+            position=d.get("position", ""),
+            context=d.get("context", ""),
+            remediation=d.get("remediation", ""),
+            context_score=d.get("context_score", 0.0),
+        )
+
+
+@dataclass
+class ScanResult:
+    id: int
+    status: str
+    risk_level: Optional[str]
+    verdict: Optional[str]
+    threat_score: int
+    findings: List[Finding]
+    scan_duration_ms: int
+    ai_insight: Optional[str]
+    compliance_alerts: List[str]
+    remediations: List[str]
+    created_at: str
+
+    @property
+    def has_findings(self) -> bool:
+        return len(self.findings) > 0
+
+    @property
+    def critical(self) -> List[Finding]:
+        return [f for f in self.findings if f.severity.upper() == "CRITICAL"]
+
+    @property
+    def high(self) -> List[Finding]:
+        return [f for f in self.findings if f.severity.upper() == "HIGH"]
+
+    @property
+    def medium(self) -> List[Finding]:
+        return [f for f in self.findings if f.severity.upper() == "MEDIUM"]
+
+    @property
+    def low(self) -> List[Finding]:
+        return [f for f in self.findings if f.severity.upper() == "LOW"]
+
+    @property
+    def highest_severity(self) -> Optional[str]:
+        for sev in ("CRITICAL", "HIGH", "MEDIUM", "LOW"):
+            if any(f.severity.upper() == sev for f in self.findings):
+                return sev
+        return None
+
+    def to_dict(self) -> Dict[str, Any]:
+        result: Dict[str, Any] = {}
+        for sev in ("CRITICAL", "HIGH", "MEDIUM", "LOW"):
+            items = [f for f in self.findings if f.severity.upper() == sev]
+            if items:
+                result[sev] = [
+                    {
+                        "type": f.type,
+                        "description": f.description,
+                        "value": f.value,
+                        "position": f.position,
+                        "remediation": f.remediation,
+                    }
+                    for f in items
+                ]
+        return result
+
+    @classmethod
+    def _from_dict(cls, d: Dict[str, Any]) -> "ScanResult":
+        findings = [Finding._from_dict(f) for f in (d.get("findings") or [])]
+        return cls(
+            id=d.get("id", 0),
+            status=d.get("status", ""),
+            risk_level=d.get("risk_level"),
+            verdict=d.get("verdict"),
+            threat_score=d.get("threat_score", 0),
+            findings=findings,
+            scan_duration_ms=d.get("scan_duration_ms") or d.get("duration", 0),
+            ai_insight=d.get("aiInsight"),
+            compliance_alerts=d.get("compliance_alerts", []),
+            remediations=d.get("remediations", []),
+            created_at=d.get("created_at", ""),
+        )
+
+
+class SpidercobError(Exception):
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthenticationError(SpidercobError):
+    pass
+
+
+class RateLimitError(SpidercobError):
+    pass
+
+
+class Client:
+    """
+    Spidercob API client.
+
+    Parameters
+    ----------
+    api_key:
+        Your Spidercob API key. Falls back to the ``SPIDERCOB_API_KEY``
+        environment variable if not provided.
+    base_url:
+        Override the default API base URL. Useful for self-hosted deployments.
+    timeout:
+        Request timeout in seconds (default: 30).
+
+    Examples
+    --------
+    >>> from spidercob import Client
+    >>> client = Client(api_key="your-api-key")
+    >>> result = client.scan("My AWS key is AKIAIOSFODNN7EXAMPLE")
+    >>> print(result.highest_severity)
+    CRITICAL
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = BASE_URL,
+        timeout: int = 30,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("SPIDERCOB_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "No API key provided. Pass api_key= or set the SPIDERCOB_API_KEY environment variable. "
+                "Get your key at https://spidercob.com/settings"
+            )
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(self, method: str, path: str, body: Optional[Dict] = None) -> Dict:
+        url = f"{self.base_url}{path}"
+        data = json.dumps(body).encode() if body else None
+        req = Request(
+            url,
+            data=data,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": "spidercob-python/0.1.0",
+            },
+        )
+        try:
+            with urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode())
+        except HTTPError as exc:
+            body_text = exc.read().decode(errors="replace")
+            if exc.code == 401:
+                raise AuthenticationError("Invalid API key. Check your key at https://spidercob.com/settings") from exc
+            if exc.code == 429:
+                raise RateLimitError("Rate limit exceeded. Slow down requests or upgrade your plan.") from exc
+            try:
+                detail = json.loads(body_text).get("detail", body_text)
+            except Exception:
+                detail = body_text
+            raise SpidercobError(f"API error {exc.code}: {detail}", status_code=exc.code) from exc
+
+    def scan(
+        self,
+        text: str,
+        source: str = "SDK",
+    ) -> ScanResult:
+        """
+        Scan text for PII, secrets, and sensitive data.
+
+        Parameters
+        ----------
+        text:
+            The content to scan — plain text, source code, log output, etc.
+        source:
+            Label for the scan source shown in the Spidercob dashboard.
+
+        Returns
+        -------
+        ScanResult
+            Findings grouped by severity with AI analysis and compliance alerts.
+
+        Examples
+        --------
+        >>> result = client.scan("postgresql://admin:s3cr3t@prod-db:5432/mydb")
+        >>> result.highest_severity
+        'CRITICAL'
+        >>> result.critical[0].type
+        'db_connection_string'
+        """
+        payload = {"content": text, "source": source}
+        data = self._request("POST", "/api/scans/", payload)
+        return ScanResult._from_dict(data)
+
+    def scan_file(self, path: str, source: str = "SDK") -> ScanResult:
+        """
+        Scan a file for PII, secrets, and sensitive data.
+
+        Parameters
+        ----------
+        path:
+            Path to the file to scan.
+        source:
+            Label for the scan source shown in the Spidercob dashboard.
+        """
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            text = fh.read()
+        return self.scan(text, source=source or path)
+
+    def get_scan(self, scan_id: int) -> ScanResult:
+        """Retrieve a previously run scan by ID."""
+        data = self._request("GET", f"/api/scans/{scan_id}")
+        return ScanResult._from_dict(data)
+
+    def list_scans(self, limit: int = 20) -> List[ScanResult]:
+        """List recent scans from your account."""
+        data = self._request("GET", f"/api/scans/?limit={limit}")
+        if isinstance(data, list):
+            return [ScanResult._from_dict(d) for d in data]
+        return []