Python SDK

pip install compliancelayer

from compliancelayer import ComplianceLayer

client = ComplianceLayer("cl_your_api_key_here")

report = client.scan("example.com")

print(report.domain, report.grade, report.score)
print(f"{report.total_issues} issues ({report.critical_issues} critical)")

for issue in report.issues[:5]:
    print(f"[{issue.severity}] {issue.finding}")

client.close()

from compliancelayer import ComplianceLayer

client = ComplianceLayer(
    "cl_your_api_key_here",
    timeout=60.0,
    poll_interval=5.0,
    poll_timeout=300.0,
    max_retries=5,
)

report = client.scan("example.com", poll_interval=2.0, poll_timeout=180.0)

print(report.score)          # 82
print(report.grade)          # "B"
print(report.risk_level)     # "low"
print(report.total_issues)   # 7

# Per-module breakdown
for name, module in report.modules.items():
    print(f"{name}: {module.grade} ({module.score})")

import time

job = client.scan_async("example.com")
print(job.job_id, job.status)

while not job.is_complete:
    time.sleep(3)
    job.refresh()

if job.is_failed:
    print("Scan failed:", job.failure_reason)
else:
    report = job.get_report()
    print(report.grade, report.score)

job = client.get_scan_job(12345)
print(job.status)

# Raises ScanError (HTTP 409) if the scan has not finished yet
report = client.get_scan_report(12345)
print(report.grade)

# limit accepts 1-100, defaults to 50
for entry in client.scan_history(limit=20):
    print(entry.scanned_at, entry.domain, entry.grade, entry.total_issues)

result = client.free_scan("example.com")

print(result.grade, result.score, result.risk_level)
for issue in result.top_issues:
    print(f"[{issue.severity}] {issue.finding}")

# sort_by is "risk" (default) or "domain"
batch = client.batch_scan(
    ["example.com", "example.org", "example.net"],
    sort_by="risk",
)

print(f"{batch.total} domains scanned")
print(batch.summary)   # aggregate counts returned by the API

for result in batch.results:
    if result.error:
        print(f"{result.domain}: failed -- {result.error}")
    else:
        print(result.domain, result.overall_grade, result.overall_score)

domain = client.domains.add(
    "example.com",
    scan_interval="daily",       # "hourly" | "daily" | "weekly"
    alert_on_score_drop=True,
    alert_threshold=5,           # alert on a drop of 5+ points
)

print(domain.id, domain.domain, domain.scan_frequency)

endpoint = client.webhooks.create(
    url="https://example.com/hooks/compliancelayer",
    enabled_events=["scan.completed", "alert.triggered"],
    description="Production listener",
)

# The signing secret is only returned on creation -- store it now.
print(endpoint.id, endpoint.secret)

# endpoint_id is the numeric ID
result = client.webhooks.test(endpoint.id)
print(result.success, result.status_code, result.response_time_ms)

for delivery in client.webhooks.deliveries(endpoint.id, limit=10):
    print(delivery.created_at, delivery.event_type, delivery.status)
    print("  HTTP", delivery.http_status_code, "retries:", delivery.retry_count)
    if not delivery.success:
        print("  error:", delivery.error_message)

client.webhooks.update(endpoint.id, is_active=False)

url = client.badge_url("example.com")
print(url)  # embed this in your README

svg = client.badge_svg("example.com")
with open("badge.svg", "w") as f:
    f.write(svg)

usage = client.usage()

print(usage.plan)              # "professional"
print(usage.email)
print(usage.scans_used)        # scans consumed this month
print(usage.scans_limit)       # monthly scan allowance
print(usage.scans_remaining)   # reported by the API, not computed
print(usage.domains_limit)     # maximum monitored domains
print(usage.subscription_status)

from compliancelayer import ComplianceLayer
from compliancelayer.exceptions import (
    APIError,
    AuthenticationError,
    QuotaExceededError,
    RateLimitError,
    ScanError,
    ScanTimeoutError,
    ValidationError,
)

client = ComplianceLayer("cl_your_api_key_here")

try:
    report = client.scan("example.com")
except AuthenticationError:
    print("Check your API key.")
except QuotaExceededError as exc:
    print("Monthly scan quota exhausted:", exc)
except RateLimitError as exc:
    print(f"Rate limited; retry after {exc.retry_after}s")
except ValidationError as exc:
    print("Invalid request:", exc)
except ScanTimeoutError:
    print("Scan did not finish in time -- poll the job later.")
except ScanError as exc:
    print("Scan failed:", exc)
except APIError as exc:
    # Catch-all for anything else the API returned
    print(f"API error {exc.status_code}: {exc}")

import asyncio
from compliancelayer import AsyncComplianceLayer

async def main():
    async with AsyncComplianceLayer("cl_your_api_key_here") as client:
        report = await client.scan("example.com")
        print(report.grade, report.score)

        usage = await client.usage()
        print(usage.scans_used, "/", usage.scans_limit)

asyncio.run(main())