Python SDK Reference

import attestd

client = attestd.Client(api_key="YOUR_API_KEY")

result = client.check("nginx", "1.20.0")
print(result.risk_state)         # "high"
print(result.actively_exploited) # False
print(result.cve_ids)            # ["CVE-2021-23017"]

client.close()

import attestd
import asyncio

async def check_deps():
    async with attestd.AsyncClient(api_key="YOUR_API_KEY") as client:
        result = await client.check("redis", "6.0.9")
        return result

result = asyncio.run(check_deps())

import attestd
import asyncio

async def fanout(deps):
    async with attestd.AsyncClient(
        api_key="YOUR_API_KEY",
        batch_window_ms=5,  # coalesce concurrent check() into one batch
    ) as client:
        return await asyncio.gather(*(client.check(p, v) for p, v in deps))

import attestd
import asyncio

async def check_sbom(deps):
    async with attestd.AsyncClient(api_key="YOUR_API_KEY") as client:
        return await client.batch_check(deps)

deps = [("nginx", "1.20.0"), ("redis", "6.0.9")]
results = asyncio.run(check_sbom(deps))

import attestd

with attestd.Client(api_key="YOUR_API_KEY") as client:
    catalog = client.products()
    print(catalog.total)
    print(catalog.cve_products[0].slug)

import attestd
from attestd import AttestdAPIError

with attestd.Client(api_key="YOUR_API_KEY") as client:
    try:
        detail = client.cve("CVE-2021-44228")
        print(detail.cvss_score, detail.epss_score)
    except AttestdAPIError as e:
        if e.status_code == 404:
            print("CVE not in database")

import attestd

with attestd.Client(api_key="YOUR_API_KEY") as client:
    usage = client.usage()
    print(usage.tier)
    print(usage.key_calls_this_month, "/", usage.included_calls)
    print(usage.billing_period_end)

@dataclass(frozen=True, slots=True)
class RiskResult:
    product: str
    version: str
    risk_state: RiskState        # "critical" | "high" | "elevated" | "low" | "none"
    risk_factors: list[str]
    actively_exploited: bool
    remote_exploitable: bool
    authentication_required: bool
    patch_available: bool
    fixed_version: str | None
    confidence: float
    cve_ids: list[str]
    max_epss: float | None = None
    cves: list[CveSummary] = field(default_factory=list)
    supply_chain: SupplyChainSignal | None   # None for CVE-only products
    typosquat: TyposquatSignal | None        # None when no resemblance detected
    last_updated: datetime

import attestd

client = attestd.Client(api_key="YOUR_API_KEY")

# Check a monitored PyPI package
result = client.check("langchain", "0.1.0")

if result.supply_chain and result.supply_chain.compromised:
    print(f"WARNING: {result.product} {result.version} is compromised")
    print(f"Detected by: {', '.join(result.supply_chain.sources)}")
    raise SystemExit("Do not deploy")

# CVE-only products have supply_chain = None
result = client.check("nginx", "1.20.0")
assert result.supply_chain is None  # Not in supply chain monitoring

client.close()

@dataclass(frozen=True, slots=True)
class TyposquatSignal:
    detected: bool
    resembles: str | None
    confidence: float        # 0.0–1.0
    ecosystem: str           # "pypi" | "npm"
    kind: Literal["typosquat", "hallucination"] = "typosquat"
    likely_intended: tuple[str, ...] = ()

@dataclass(frozen=True, slots=True)
class CveSummary:
    cve_id: str
    cvss_score: float | None
    actively_exploited: bool
    remote_exploitable: bool
    epss_score: float | None      # EPSS probability (0.0–1.0)
    epss_percentile: float | None # EPSS percentile rank (0.0–1.0)

import attestd

client = attestd.Client(api_key="YOUR_API_KEY")

try:
    result = client.check("nginx", "1.20.0")
except attestd.AttestdAuthError:
    print("Invalid API key")
except attestd.AttestdRateLimitError as e:
    print(f"Rate limited. Retry in {e.retry_after}s")
except attestd.AttestdUnsupportedProductError as e:
    # Product is outside coverage. Not a safety clearance.
    # Check typosquat first: the name itself may be the risk.
    if e.typosquat and e.typosquat.detected:
        print(
            f"{e.product} fails name integrity "
            f"(kind={e.typosquat.kind}). Prefer {e.typosquat.resembles}."
        )
    else:
        print(f"{e.product} is outside attestd coverage")
    raise  # or handle according to your policy
except attestd.AttestdAPIError as e:
    print(f"API error: {e}")

from attestd.testing import (
    NGINX_SAFE,       # risk_state: "none"
    NGINX_VULNERABLE, # risk_state: "high"
    LOG4J_CRITICAL,   # risk_state: "critical", actively_exploited: true
    UNSUPPORTED,      # supported: false
)

# Override individual fields
transport = MockTransport(200, NGINX_VULNERABLE | {"risk_state": "critical"})