CyberVault Python SDK

Installation

Install the SDK using pip. The package supports Python 3.8 and above.

Terminal

pip install cybervault-sdk

Optional: Install with async support and development tools

Terminal

pip install "cybervault-sdk[async,dev]"

Quick Start

Initialize the client and run your first threat scan in under 10 lines.

quick_start.py
from cybervault import CyberVaultClient

# Initialize client with API key
client = CyberVaultClient(api_key="cv_live_sk_...")

# Run a real-time threat scan on a target
result = client.threats.scan("example.com")

if result.status == "clean":
    print("✅ No threats detected.")
else:
    print(f"⚠️ {result.risk_level} risk found. Details: {result.summary}")

Authentication

The SDK supports multiple authentication methods. API keys are recommended for server-side applications.

Method	Usage	Security Level
API Key	`api_key="cv_live_sk_..."`	High (Recommended)
Environment	`os.environ["CYBERVAULT_API_KEY"]`	High
OAuth2	`oauth_token="..."`	Medium

💡 Tip: Never hardcode API keys in production. Use environment variables or a secrets manager.

Core Client

The CyberVaultClient is your entry point to all SDK features. It handles connection pooling, retries, and request signing automatically.

client_init.py
from cybervault import CyberVaultClient
import os

client = CyberVaultClient(
    api_key=os.environ["CYBERVAULT_API_KEY"],
    environment="production",  # or "sandbox"
    timeout=30,
    max_retries=3
)

Threat Detection

Query the threat intelligence engine for real-time analysis of IPs, domains, hashes, and URLs.

Method	Description	Returns
`client.threats.scan(target)`	Scan any asset or identifier	ScanResult
`client.threats.lookup_hash(hash)`	Check file/hash against malware DB	ThreatReport
`client.threats.stream()`	Real-time threat feed (WebSocket)	AsyncIterator

threat_analysis.py
# Analyze a suspicious IP address
ip_report = client.threats.lookup("198.51.100.23")

print(ip_report.reputation)  # 'malicious'
print(ip_report.categories)   # ['botnet', 'proxy']
print(ip_report.last_seen)    # datetime object

Asset Scanning

Discover and classify assets across your network. Supports ports, services, certificates, and exposed endpoints.

scan_assets.py
# Initiate a network asset discovery
scan = client.assets.discover(
    cidr="10.0.0.0/24",
    deep_scan=True,
    include_certificates=True
)

# Poll until complete
for event in client.assets.stream(scan.id):
    print(f"Found: {event.asset_type} at {event.ip}")

# Get final report
report = client.assets.get_report(scan.id)
print(f"Scanned {report.total_assets} assets. Critical: {report.critical_count}")

Configuration

Fine-tune SDK behavior using the config module or environment variables.

config.py
from cybervault import config

config.log_level = "DEBUG"
config.connection_pool_size = 10
config.enable_metrics = True
config.retry_strategy = "exponential"  # 'none', 'constant', 'exponential'

⚠️ Note: Changing configuration after client initialization requires creating a new client instance.

Error Handling

The SDK raises descriptive exceptions for all failures. Catch them gracefully in production code.

errors.py
from cybervault import (
    CyberVaultError, AuthenticationError, RateLimitError, NotFoundError
)

try:
    client.threats.scan("invalid_target")
except AuthenticationError as e:
    print("❌ Invalid API key: " + e.message)
except RateLimitError as e:
    print("⏳ Retry after " + str(e.retry_after) + "s")
except CyberVaultError as e:
    print("💥 SDK Error: " + str(e))

Async Support

Full async/await support for non-blocking operations. Ideal for high-throughput security pipelines.

async_example.py
import asyncio
from cybervault import AsyncCyberVaultClient

async def monitor_threats():
    client = AsyncCyberVaultClient(api_key="cv_live_sk_...")
    
    # Async stream for real-time events
    async for event in client.threats.subscribe(category="apt"):
        print(f"🚨 Alert: {event.severity} - {event.indicator}")
        await client.incidents.create(source="python_sdk", data=event)

asyncio.run(monitor_threats())