spidercob

Python SDK for the Spidercob 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.

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

pip install spidercob

Zero dependencies. Python 3.9+.

Get your API key at spidercob.com/settings.

Authentication

# Pass directly
client = Client(api_key="your-api-key")

# Or set environment variable
export SPIDERCOB_API_KEY=your-api-key
client = Client()

Scan text

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

result = client.scan_file("src/config.py")
if result.has_findings:
    print(result.to_dict())

Scan for real vulnerabilities, not just secrets

scan_file() above only looks for secrets/PII in a file's text. scan_code_file() runs the Spidercob API's static analysis engine — real AST/dataflow analysis via Semgrep, not lexical regex — to catch SQL injection, SSRF, command injection, and more, in addition to secrets.

result = client.scan_code_file("app.py")

for v in result.vulnerabilities:
    print(f"{v.type} (line {v.line}): {v.description}")
    print(f"  Remediation: {v.remediation}")

for s in result.secrets:
    print(f"{s.type}: {s.description}")

# Everything the AI risk classifier marked as a real, actionable issue
# (as opposed to a test fixture or unreachable/dead code)
if result.blocking:
    print(f"{len(result.blocking)} blocking issue(s) found")

Scan a whole repo, not just one file

scan_repo() runs the same secrets + Semgrep vulnerability detection as scan_code_file() across every supported file in a directory or .zip — useful for scanning an entire project instead of one file at a time.

result = client.scan_repo("./my-project")  # a directory, zipped automatically
# or: client.scan_repo("codebase.zip")

print(result.status)  # COMPLETED / PARTIAL / FAILED
for v in result.vulnerabilities:
    print(f"{v.type}: {v.description}")
for s in result.secrets:
    print(f"{s.type}: {s.description}")

This always runs as a background job server-side (each file costs a few seconds), so scan_repo() blocks and polls until it finishes by default. For a non-blocking version — e.g. in a web request handler — pass poll=False to get the job back immediately and poll it yourself:

job = client.scan_repo("./my-project", poll=False)
# ... later ...
result = client.get_repo_scan(job.batch_id)
if result.is_done:
    print(result.status)

Directories are zipped in-memory, skipping .git, node_modules, __pycache__, venv, and other common noise directories. Capped server-side at 100 files / 25MB compressed.

Supported extensions: .py .js .ts .java .c .cpp .h .go .rb .php. Actual vulnerability detection (as opposed to secrets-only) currently covers .py/.js/.ts/.java/.go/.php.

Retrieve past scans

# Get a scan by ID
result = client.get_scan(scan_id=1234)

# List recent scans
scans = client.list_scans(limit=20)

Use in CI

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

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 — the open source pattern engine this SDK is built on:

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