validin-sdk 0.1.0__py3-none-any.whl

validin/__init__.py

@@ -0,0 +1,47 @@
+"""Minimal Validin SDK surface for DNS history, host responses, and enrichment."""
+
+from .annotation_record import AnnotationRecord
+from .certificate_record import CertificateObservation, CertificateRecord
+from .client import Client, ValidinClient
+from .enriched_indicator import EnrichedIndicator
+from .content import Content, ContentIndicator, ContentResource
+from .dns_record import DNSRecord
+from .errors import ApiError, ValidinError
+from .host_response_record import HostResponse, HostResponseRecord
+from .indicator import Indicator, IndicatorType
+from .lookalike_record import LookalikeRecord
+from .registration import Registration
+from .registration_record import RegistrationRecord
+from .result_set import ResultSet
+from .scan import ScanJob
+from .scan_record import ScanRecord, ScanResponse
+from .yara_match_record import YaraMatchRecord
+
+__all__ = [
+    "AnnotationRecord",
+    "ApiError",
+    "CertificateObservation",
+    "CertificateRecord",
+    "Client",
+    "Content",
+    "ContentIndicator",
+    "ContentResource",
+    "DNSRecord",
+    "EnrichedIndicator",
+    "HostResponse",
+    "HostResponseRecord",
+    "Indicator",
+    "IndicatorType",
+    "LookalikeRecord",
+    "Registration",
+    "RegistrationRecord",
+    "ResultSet",
+    "ScanJob",
+    "ScanRecord",
+    "ScanResponse",
+    "ValidinClient",
+    "ValidinError",
+    "YaraMatchRecord",
+]
+
+__version__ = "0.1.0"

validin/annotation_record.py

@@ -0,0 +1,92 @@
+"""Quick reputation annotation record model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional
+
+from .indicator import Indicator, IndicatorType
+
+
+@dataclass(frozen=True)
+class AnnotationRecord:
+    """Flattened annotation row returned by quick reputation endpoints."""
+
+    description: Optional[str]
+    key: Optional[Indicator]
+    value: Any
+    value_type: Optional[str]
+    category: Optional[str]
+    risk_cat: Optional[str]
+    title: Optional[str]
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_api(
+        cls,
+        payload: Mapping[str, Any],
+        *,
+        query_indicator_type: IndicatorType,
+    ) -> "AnnotationRecord":
+        key_value = payload.get("key")
+        key = None
+        if key_value not in (None, ""):
+            key = Indicator(str(key_value), query_indicator_type)
+
+        value = payload.get("value")
+        if value is None and "values" in payload:
+            values = payload.get("values")
+            value = list(values) if isinstance(values, list) else values
+
+        value_type = payload.get("value_type")
+        if value_type in (None, "") and isinstance(value, list):
+            value_type = "list"
+
+        return cls(
+            description=str(payload.get("description")) if payload.get("description") is not None else None,
+            key=key,
+            value=value,
+            value_type=str(value_type) if value_type is not None else None,
+            category=str(payload.get("category")) if payload.get("category") is not None else None,
+            risk_cat=str(payload.get("risk_cat")) if payload.get("risk_cat") is not None else None,
+            title=str(payload.get("title")) if payload.get("title") is not None else None,
+            raw=dict(payload),
+        )
+
+    @property
+    def result_key(self) -> Optional[Indicator]:
+        return self.key
+
+    def dedupe_key(self) -> tuple:
+        return (
+            self.description,
+            self.key.value if self.key else None,
+            self.key.type.value if self.key else None,
+            self._make_hashable(self.value),
+            self.value_type,
+            self.category,
+            self.risk_cat,
+            self.title,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "description": self.description,
+            "key": self.key.value if self.key else None,
+            "key_type": self.key.type.value if self.key else None,
+            "value": self.value,
+            "value_type": self.value_type,
+            "category": self.category,
+            "risk_cat": self.risk_cat,
+            "title": self.title,
+        }
+
+    @staticmethod
+    def _make_hashable(value: Any) -> Any:
+        if isinstance(value, list):
+            return tuple(AnnotationRecord._make_hashable(item) for item in value)
+        if isinstance(value, dict):
+            return tuple(
+                sorted((key, AnnotationRecord._make_hashable(item)) for key, item in value.items())
+            )
+        return value

validin/certificate_record.py

@@ -0,0 +1,217 @@
+"""Certificate transparency record models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Mapping, Optional
+
+from .indicator import Indicator, IndicatorType
+
+
+def _coerce_str(value: Any) -> Optional[str]:
+    if value in (None, ""):
+        return None
+    return str(value)
+
+
+def _parse_timestamp(value: Any) -> Optional[datetime]:
+    if value in (None, ""):
+        return None
+
+    if isinstance(value, datetime):
+        return value
+
+    if isinstance(value, (int, float)):
+        return datetime.fromtimestamp(value, tz=timezone.utc)
+
+    if isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            return None
+        if stripped.endswith("Z"):
+            stripped = stripped[:-1] + "+00:00"
+        try:
+            return datetime.fromisoformat(stripped)
+        except ValueError:
+            try:
+                return datetime.fromtimestamp(float(stripped), tz=timezone.utc)
+            except ValueError:
+                return None
+
+    return None
+
+
+@dataclass(frozen=True)
+class CertificateObservation:
+    """Normalized certificate transparency observation."""
+
+    timestamp: Optional[datetime] = None
+    update_type: Optional[str] = None
+    common_name: Optional[str] = None
+    cert_issuer: Optional[str] = None
+    issuer: Mapping[str, Any] = field(default_factory=dict)
+    not_before: Optional[datetime] = None
+    not_after: Optional[datetime] = None
+    fingerprint: Optional[str] = None
+    fingerprint_sha256: Optional[str] = None
+    domains: tuple[str, ...] = field(default_factory=tuple)
+    links: tuple[str, ...] = field(default_factory=tuple)
+    type: Optional[str] = None
+    time: Optional[datetime] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> "CertificateObservation":
+        if not isinstance(payload, Mapping):
+            raise TypeError("payload must be a mapping")
+
+        details = payload.get("details")
+        if isinstance(details, Mapping):
+            details_payload = details
+        else:
+            details_payload = {}
+
+        issuer = payload.get("issuer")
+        if isinstance(issuer, Mapping):
+            issuer_payload = dict(issuer)
+        else:
+            issuer_payload = {}
+
+        domains = tuple(
+            str(item).strip()
+            for item in (details_payload.get("domains") or [])
+            if str(item).strip()
+        )
+        links = tuple(
+            str(item).strip()
+            for item in (payload.get("links") or [])
+            if str(item).strip()
+        )
+
+        return cls(
+            timestamp=_parse_timestamp(payload.get("timestamp")),
+            update_type=_coerce_str(payload.get("update_type")),
+            common_name=_coerce_str(payload.get("common_name")),
+            cert_issuer=_coerce_str(payload.get("cert_issuer")),
+            issuer=issuer_payload,
+            not_before=_parse_timestamp(payload.get("not_before")),
+            not_after=_parse_timestamp(payload.get("not_after")),
+            fingerprint=_coerce_str(details_payload.get("fingerprint")),
+            fingerprint_sha256=_coerce_str(details_payload.get("fingerprint_sha256")),
+            domains=domains,
+            links=links,
+            type=_coerce_str(payload.get("type")),
+            time=_parse_timestamp(payload.get("time")),
+            raw=dict(payload),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "timestamp": self.timestamp.isoformat() if self.timestamp else None,
+            "update_type": self.update_type,
+            "common_name": self.common_name,
+            "cert_issuer": self.cert_issuer,
+            "issuer": dict(self.issuer),
+            "not_before": self.not_before.isoformat() if self.not_before else None,
+            "not_after": self.not_after.isoformat() if self.not_after else None,
+            "fingerprint": self.fingerprint,
+            "fingerprint_sha256": self.fingerprint_sha256,
+            "domains": list(self.domains),
+            "links": list(self.links),
+            "type": self.type,
+            "time": self.time.isoformat() if self.time else None,
+        }
+
+
+@dataclass(frozen=True)
+class CertificateRecord:
+    """Normalized certificate history row."""
+
+    key: Optional[Indicator]
+    type: str
+    value: Optional[CertificateObservation]
+    value_type: Optional[str]
+    first_seen: Optional[datetime]
+    last_seen: Optional[datetime]
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_api(
+        cls,
+        record_type: str,
+        payload: Mapping[str, Any],
+        *,
+        query_indicator_type: IndicatorType,
+    ) -> "CertificateRecord":
+        key = None
+        key_value = payload.get("key")
+        if key_value not in (None, ""):
+            key = Indicator.from_api(
+                str(key_value),
+                str(payload.get("key_type") or query_indicator_type.value),
+            )
+
+        value = None
+        value_payload = payload.get("value")
+        if isinstance(value_payload, Mapping):
+            value = CertificateObservation.from_payload(value_payload)
+
+        return cls(
+            key=key,
+            type=str(record_type),
+            value=value,
+            value_type=_coerce_str(payload.get("value_type")),
+            first_seen=_parse_timestamp(payload.get("first_seen")),
+            last_seen=_parse_timestamp(payload.get("last_seen")),
+            raw=dict(payload),
+        )
+
+    @property
+    def result_key(self) -> Optional[Indicator]:
+        return self.key
+
+    @property
+    def common_name(self) -> Optional[str]:
+        return self.value.common_name if self.value else None
+
+    @property
+    def fingerprint(self) -> Optional[str]:
+        return self.value.fingerprint if self.value else None
+
+    @property
+    def fingerprint_sha256(self) -> Optional[str]:
+        return self.value.fingerprint_sha256 if self.value else None
+
+    @property
+    def domains(self) -> tuple[str, ...]:
+        return self.value.domains if self.value else ()
+
+    @property
+    def timestamp(self) -> Optional[datetime]:
+        return self.value.timestamp if self.value else None
+
+    def dedupe_key(self) -> tuple:
+        return (
+            self.key.value if self.key else None,
+            self.key.type.value if self.key else None,
+            self.type,
+            self.value_type,
+            self.common_name,
+            self.fingerprint,
+            self.fingerprint_sha256,
+            self.domains,
+            self.first_seen.isoformat() if self.first_seen else None,
+            self.last_seen.isoformat() if self.last_seen else None,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "key": self.key.value if self.key else None,
+            "key_type": self.key.type.value if self.key else None,
+            "type": self.type,
+            "value_type": self.value_type,
+            "first_seen": self.first_seen.isoformat() if self.first_seen else None,
+            "last_seen": self.last_seen.isoformat() if self.last_seen else None,
+            "certificate": self.value.to_dict() if self.value else None,
+        }