malloryapi 0.1.0__py3-none-any.whl

malloryapi/__init__.py

@@ -0,0 +1,27 @@
+"""malloryapi - Official Python client for the Mallory API."""
+
+from malloryapi._pagination import paginate_async, paginate_sync
+from malloryapi._types import PaginatedResponse
+from malloryapi.client import AsyncMalloryApi, MalloryApi
+from malloryapi.exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+__all__ = [
+    "MalloryApi",
+    "AsyncMalloryApi",
+    "PaginatedResponse",
+    "paginate_sync",
+    "paginate_async",
+    "APIError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+]
+
+__version__ = "0.1.0"

malloryapi/_http.py

@@ -0,0 +1,202 @@
+"""HTTP client wrapper for sync and async requests."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from malloryapi.exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+DEFAULT_BASE_URL = "https://api.mallory.ai/v1"
+DEFAULT_TIMEOUT = 30.0
+
+
+def _resolve_api_key(api_key: str | None) -> str:
+    key = api_key or os.environ.get("MALLORY_API_KEY")
+    if not key:
+        raise AuthenticationError(
+            "No API key provided. Pass api_key= or set the "
+            "MALLORY_API_KEY environment variable."
+        )
+    return key
+
+
+def _build_headers(api_key: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+
+
+def _handle_error_response(response: httpx.Response) -> None:
+    """Raise the appropriate exception for non-2xx responses."""
+    status = response.status_code
+    try:
+        body = response.json()
+    except Exception:
+        body = response.text
+
+    if status in (401, 403):
+        raise AuthenticationError(
+            f"Authentication failed ({status})",
+            status_code=status,
+            response_body=body,
+        )
+    if status == 404:
+        raise NotFoundError(
+            "Resource not found",
+            status_code=status,
+            response_body=body,
+        )
+    if status == 422:
+        raise ValidationError(
+            f"Validation error: {body}",
+            status_code=status,
+            response_body=body,
+        )
+    if status == 429:
+        raise RateLimitError(
+            "Rate limit exceeded",
+            status_code=status,
+            response_body=body,
+        )
+    raise APIError(
+        f"API request failed ({status})",
+        status_code=status,
+        response_body=body,
+    )
+
+
+class SyncHttpClient:
+    """Synchronous HTTP client backed by httpx."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = _resolve_api_key(api_key)
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=_build_headers(resolved_key),
+            timeout=timeout,
+        )
+
+    def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        response = self._client.get(path, params=params)
+        if response.status_code >= 400:
+            _handle_error_response(response)
+        return response.json()
+
+    def post(
+        self,
+        path: str,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        response = self._client.post(path, json=json, params=params)
+        if response.status_code >= 400:
+            _handle_error_response(response)
+        return response.json()
+
+    def patch(
+        self,
+        path: str,
+        json: Any = None,
+    ) -> Any:
+        response = self._client.patch(path, json=json)
+        if response.status_code >= 400:
+            _handle_error_response(response)
+        return response.json()
+
+    def delete(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        response = self._client.delete(path, params=params)
+        if response.status_code >= 400:
+            _handle_error_response(response)
+        return response.json()
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP client backed by httpx."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = _resolve_api_key(api_key)
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=_build_headers(resolved_key),
+            timeout=timeout,
+        )
+
+    async def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        response = await self._client.get(path, params=params)
+        if response.status_code >= 400:
+            _handle_error_response(response)
+        return response.json()
+
+    async def post(
+        self,
+        path: str,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        response = await self._client.post(
+            path, json=json, params=params
+        )
+        if response.status_code >= 400:
+            _handle_error_response(response)
+        return response.json()
+
+    async def patch(
+        self,
+        path: str,
+        json: Any = None,
+    ) -> Any:
+        response = await self._client.patch(path, json=json)
+        if response.status_code >= 400:
+            _handle_error_response(response)
+        return response.json()
+
+    async def delete(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        response = await self._client.delete(path, params=params)
+        if response.status_code >= 400:
+            _handle_error_response(response)
+        return response.json()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

malloryapi/_pagination.py

@@ -0,0 +1,56 @@
+"""Auto-pagination iterators for sync and async usage."""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Callable, Iterator
+
+
+def paginate_sync(
+    fetch: Callable[..., Any],
+    limit: int = 100,
+    **kwargs: Any,
+) -> Iterator[dict[str, Any]]:
+    """Yield all items across pages synchronously.
+
+    Usage::
+
+        for vuln in paginate_sync(client.vulnerabilities.list, limit=50):
+            print(vuln["cve_id"])
+    """
+    offset = 0
+    while True:
+        page = fetch(offset=offset, limit=limit, **kwargs)
+        items = page.items if hasattr(page, "items") else page
+        if not items:
+            break
+        yield from items
+        offset += limit
+        if not page.has_more:
+            break
+
+
+async def paginate_async(
+    fetch: Callable[..., Any],
+    limit: int = 100,
+    **kwargs: Any,
+) -> AsyncIterator[dict[str, Any]]:
+    """Yield all items across pages asynchronously.
+
+    Usage::
+
+        async for vuln in paginate_async(
+            client.vulnerabilities.list, limit=50
+        ):
+            print(vuln["cve_id"])
+    """
+    offset = 0
+    while True:
+        page = await fetch(offset=offset, limit=limit, **kwargs)
+        items = page.items if hasattr(page, "items") else page
+        if not items:
+            break
+        for item in items:
+            yield item
+        offset += limit
+        if not page.has_more:
+            break

malloryapi/_types.py

@@ -0,0 +1,30 @@
+"""Shared types for the Mallory API client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class PaginatedResponse:
+    """Response from a paginated list endpoint."""
+
+    items: list[dict[str, Any]] = field(default_factory=list)
+    total: int = 0
+    offset: int = 0
+    limit: int = 100
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __iter__(self):
+        return iter(self.items)
+
+    def __getitem__(self, index):
+        return self.items[index]
+
+    @property
+    def has_more(self) -> bool:
+        """Whether there are more pages available."""
+        return self.offset + self.limit < self.total

malloryapi/client.py

@@ -0,0 +1,176 @@
+"""Main client classes for the Mallory API."""
+
+from __future__ import annotations
+
+from malloryapi._http import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    AsyncHttpClient,
+    SyncHttpClient,
+)
+from malloryapi.resources.attack_patterns import (
+    AsyncAttackPatterns,
+    AttackPatterns,
+)
+from malloryapi.resources.breaches import AsyncBreaches, Breaches
+from malloryapi.resources.content_chunks import (
+    AsyncContentChunks,
+    ContentChunks,
+)
+from malloryapi.resources.detection_signatures import (
+    AsyncDetectionSignatures,
+    DetectionSignatures,
+)
+from malloryapi.resources.exploitations import (
+    AsyncExploitations,
+    Exploitations,
+)
+from malloryapi.resources.exploits import AsyncExploits, Exploits
+from malloryapi.resources.malware import AsyncMalware, Malware
+from malloryapi.resources.mentions import AsyncMentions, Mentions
+from malloryapi.resources.organizations import (
+    AsyncOrganizations,
+    Organizations,
+)
+from malloryapi.resources.products import AsyncProducts, Products
+from malloryapi.resources.references import (
+    AsyncReferences,
+    References,
+)
+from malloryapi.resources.search import AsyncSearch, Search
+from malloryapi.resources.sources import AsyncSources, Sources
+from malloryapi.resources.stories import AsyncStories, Stories
+from malloryapi.resources.technology_product_advisories import (
+    AsyncTechnologyProductAdvisories,
+    TechnologyProductAdvisories,
+)
+from malloryapi.resources.threat_actors import (
+    AsyncThreatActors,
+    ThreatActors,
+)
+from malloryapi.resources.vulnerabilities import (
+    AsyncVulnerabilities,
+    Vulnerabilities,
+)
+from malloryapi.resources.weaknesses import (
+    AsyncWeaknesses,
+    Weaknesses,
+)
+
+
+class MalloryApi:
+    """Synchronous client for the Mallory threat intelligence API.
+
+    Usage::
+
+        from malloryapi import MalloryApi
+
+        client = MalloryApi(api_key="sk-...")
+        vulns = client.vulnerabilities.list(limit=10)
+        actor = client.threat_actors.get("apt28-uuid")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._http = SyncHttpClient(
+            api_key=api_key, base_url=base_url, timeout=timeout
+        )
+
+        # Entities
+        self.vulnerabilities = Vulnerabilities(self._http)
+        self.threat_actors = ThreatActors(self._http)
+        self.malware = Malware(self._http)
+        self.exploits = Exploits(self._http)
+        self.exploitations = Exploitations(self._http)
+        self.organizations = Organizations(self._http)
+        self.products = Products(self._http)
+        self.attack_patterns = AttackPatterns(self._http)
+        self.breaches = Breaches(self._http)
+        self.detection_signatures = DetectionSignatures(self._http)
+        self.advisories = TechnologyProductAdvisories(self._http)
+        self.weaknesses = Weaknesses(self._http)
+
+        # Content
+        self.stories = Stories(self._http)
+        self.references = References(self._http)
+        self.sources = Sources(self._http)
+        self.content_chunks = ContentChunks(self._http)
+
+        # Analytics
+        self.mentions = Mentions(self._http)
+        self.search = Search(self._http)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection."""
+        self._http.close()
+
+    def __enter__(self) -> MalloryApi:
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+
+class AsyncMalloryApi:
+    """Asynchronous client for the Mallory threat intelligence API.
+
+    Usage::
+
+        from malloryapi import AsyncMalloryApi
+
+        async with AsyncMalloryApi(api_key="sk-...") as client:
+            vulns = await client.vulnerabilities.list(limit=10)
+            actor = await client.threat_actors.get("apt28-uuid")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._http = AsyncHttpClient(
+            api_key=api_key, base_url=base_url, timeout=timeout
+        )
+
+        # Entities
+        self.vulnerabilities = AsyncVulnerabilities(self._http)
+        self.threat_actors = AsyncThreatActors(self._http)
+        self.malware = AsyncMalware(self._http)
+        self.exploits = AsyncExploits(self._http)
+        self.exploitations = AsyncExploitations(self._http)
+        self.organizations = AsyncOrganizations(self._http)
+        self.products = AsyncProducts(self._http)
+        self.attack_patterns = AsyncAttackPatterns(self._http)
+        self.breaches = AsyncBreaches(self._http)
+        self.detection_signatures = AsyncDetectionSignatures(
+            self._http
+        )
+        self.advisories = AsyncTechnologyProductAdvisories(
+            self._http
+        )
+        self.weaknesses = AsyncWeaknesses(self._http)
+
+        # Content
+        self.stories = AsyncStories(self._http)
+        self.references = AsyncReferences(self._http)
+        self.sources = AsyncSources(self._http)
+        self.content_chunks = AsyncContentChunks(self._http)
+
+        # Analytics
+        self.mentions = AsyncMentions(self._http)
+        self.search = AsyncSearch(self._http)
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncMalloryApi:
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.aclose()

malloryapi/exceptions.py

@@ -0,0 +1,35 @@
+"""Exceptions raised by the Mallory API client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class APIError(Exception):
+    """Base exception for all Mallory API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response_body: Any = None,
+    ) -> None:
+        self.status_code = status_code
+        self.response_body = response_body
+        super().__init__(message)
+
+
+class AuthenticationError(APIError):
+    """Raised on 401 or 403 responses."""
+
+
+class NotFoundError(APIError):
+    """Raised on 404 responses."""
+
+
+class ValidationError(APIError):
+    """Raised on 422 responses."""
+
+
+class RateLimitError(APIError):
+    """Raised on 429 responses."""

malloryapi/resources/_base.py

@@ -0,0 +1,133 @@
+"""Base resource classes for sync and async API access."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from malloryapi._http import AsyncHttpClient, SyncHttpClient
+from malloryapi._types import PaginatedResponse
+
+TrendingPeriod = Literal["1d", "7d", "30d"]
+
+
+class SyncResource:
+    """Base class for synchronous resource clients."""
+
+    _path: str  # e.g. "/vulnerabilities"
+
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    # -- common helpers ------------------------------------------------
+
+    def _list(
+        self,
+        params: dict[str, Any] | None = None,
+        **extra: Any,
+    ) -> PaginatedResponse:
+        merged = {**(params or {}), **extra}
+        merged = {k: v for k, v in merged.items() if v is not None}
+        data = self._http.get(self._path, params=merged)
+        return _parse_paginated(data)
+
+    def _get(self, identifier: str) -> dict[str, Any]:
+        return self._http.get(f"{self._path}/{identifier}")
+
+    def _sub(
+        self,
+        identifier: str,
+        sub: str,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        return self._http.get(
+            f"{self._path}/{identifier}/{sub}", params=params
+        )
+
+    def _post(
+        self,
+        path: str | None = None,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        return self._http.post(
+            path or self._path, json=json, params=params
+        )
+
+    def _patch(
+        self,
+        identifier: str,
+        json: Any = None,
+    ) -> Any:
+        return self._http.patch(
+            f"{self._path}/{identifier}", json=json
+        )
+
+
+class AsyncResource:
+    """Base class for asynchronous resource clients."""
+
+    _path: str
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def _list(
+        self,
+        params: dict[str, Any] | None = None,
+        **extra: Any,
+    ) -> PaginatedResponse:
+        merged = {**(params or {}), **extra}
+        merged = {k: v for k, v in merged.items() if v is not None}
+        data = await self._http.get(self._path, params=merged)
+        return _parse_paginated(data)
+
+    async def _get(self, identifier: str) -> dict[str, Any]:
+        return await self._http.get(f"{self._path}/{identifier}")
+
+    async def _sub(
+        self,
+        identifier: str,
+        sub: str,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        return await self._http.get(
+            f"{self._path}/{identifier}/{sub}", params=params
+        )
+
+    async def _post(
+        self,
+        path: str | None = None,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        return await self._http.post(
+            path or self._path, json=json, params=params
+        )
+
+    async def _patch(
+        self,
+        identifier: str,
+        json: Any = None,
+    ) -> Any:
+        return await self._http.patch(
+            f"{self._path}/{identifier}", json=json
+        )
+
+
+# -- helpers -----------------------------------------------------------
+
+
+def _parse_paginated(data: Any) -> PaginatedResponse:
+    """Parse a paginated API response into a PaginatedResponse."""
+    if isinstance(data, dict):
+        return PaginatedResponse(
+            items=data.get("items", data.get("data", [])),
+            total=data.get("total", 0),
+            offset=data.get("offset", 0),
+            limit=data.get("limit", 100),
+        )
+    if isinstance(data, list):
+        return PaginatedResponse(
+            items=data, total=len(data), offset=0, limit=len(data)
+        )
+    return PaginatedResponse()