aisoc-sdk 4.0.0__py3-none-any.whl

aisoc_sdk/__init__.py

@@ -0,0 +1,52 @@
+"""aisoc-sdk — Python client for AiSOC.
+
+Usage::
+
+    from aisoc_sdk import AiSOCClient
+
+    async with AiSOCClient(base_url="https://soc.example.com", token="aisoc_...") as client:
+        alerts = await client.alerts.list(severity="critical")
+"""
+
+from .client import AiSOCClient, AiSOCError
+from .models import (
+    Alert,
+    AlertFilters,
+    AlertSeverity,
+    AlertStatus,
+    ApiKey,
+    ApiKeyCreateRequest,
+    ApiKeyCreateResponse,
+    Case,
+    CaseFilters,
+    CasePriority,
+    CaseStatus,
+    Connector,
+    DetectionRule,
+    Page,
+    Playbook,
+    PlaybookRun,
+)
+
+__all__ = [
+    "AiSOCClient",
+    "AiSOCError",
+    "Alert",
+    "AlertFilters",
+    "AlertSeverity",
+    "AlertStatus",
+    "ApiKey",
+    "ApiKeyCreateRequest",
+    "ApiKeyCreateResponse",
+    "Case",
+    "CaseFilters",
+    "CasePriority",
+    "CaseStatus",
+    "Connector",
+    "DetectionRule",
+    "Page",
+    "Playbook",
+    "PlaybookRun",
+]
+
+__version__ = "4.0.0"

aisoc_sdk/client.py

@@ -0,0 +1,292 @@
+"""AiSOCClient — async httpx-based client for the AiSOC REST API.
+
+Usage::
+
+    async with AiSOCClient(base_url="https://soc.example.com", token="aisoc_...") as c:
+        page = await c.alerts.list(severity="critical")
+        case = await c.cases.create(title="Incident", priority="high")
+        run  = await c.playbooks.run("isolate-host", trigger_data={"host": "srv-42"})
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type, TypeVar
+
+import httpx
+from pydantic import TypeAdapter
+
+from .models import (
+    Alert,
+    AlertFilters,
+    ApiKey,
+    ApiKeyCreateRequest,
+    ApiKeyCreateResponse,
+    Case,
+    CaseFilters,
+    Connector,
+    DetectionRule,
+    Page,
+    Playbook,
+    PlaybookRun,
+)
+
+T = TypeVar("T")
+
+
+# ─── Error ────────────────────────────────────────────────────────────────────
+
+
+class AiSOCError(Exception):
+    """Raised when the AiSOC API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"AiSOC API {status_code}: {detail}")
+
+
+# ─── Base resource client ─────────────────────────────────────────────────────
+
+
+class _ResourceClient:
+    def __init__(self, http: httpx.AsyncClient) -> None:
+        self._http = http
+
+    async def _get(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+        model: Optional[Type[T]] = None,
+    ) -> Any:
+        r = await self._http.get(path, params=self._clean(params))
+        self._raise(r)
+        if model is not None:
+            return TypeAdapter(model).validate_python(r.json())
+        return r.json()
+
+    async def _post(self, path: str, body: Any, model: Optional[Type[T]] = None) -> Any:
+        r = await self._http.post(path, json=body)
+        self._raise(r)
+        if model is not None:
+            return TypeAdapter(model).validate_python(r.json())
+        return r.json()
+
+    async def _patch(self, path: str, body: Any, model: Optional[Type[T]] = None) -> Any:
+        r = await self._http.patch(path, json=body)
+        self._raise(r)
+        if model is not None:
+            return TypeAdapter(model).validate_python(r.json())
+        return r.json()
+
+    async def _put(self, path: str, body: Any, model: Optional[Type[T]] = None) -> Any:
+        r = await self._http.put(path, json=body)
+        self._raise(r)
+        if model is not None:
+            return TypeAdapter(model).validate_python(r.json())
+        return r.json()
+
+    async def _delete(self, path: str) -> None:
+        r = await self._http.delete(path)
+        self._raise(r)
+
+    @staticmethod
+    def _clean(params: Optional[dict[str, Any]]) -> dict[str, Any]:
+        if params is None:
+            return {}
+        return {k: v for k, v in params.items() if v is not None}
+
+    @staticmethod
+    def _raise(r: httpx.Response) -> None:
+        if not r.is_success:
+            try:
+                detail = r.json().get("detail", r.text)
+            except Exception:
+                detail = r.text
+            raise AiSOCError(r.status_code, detail)
+
+
+# ─── Resource sub-clients ─────────────────────────────────────────────────────
+
+
+class AlertsClient(_ResourceClient):
+    async def list(self, filters: Optional[AlertFilters] = None, **kwargs: Any) -> Page[Alert]:
+        params = filters.model_dump(exclude_none=True) if filters else self._clean(kwargs)
+        return await self._get("/api/v1/alerts", params, Page[Alert])
+
+    async def get(self, alert_id: str) -> Alert:
+        return await self._get(f"/api/v1/alerts/{alert_id}", model=Alert)
+
+    async def update(self, alert_id: str, **data: Any) -> Alert:
+        return await self._patch(f"/api/v1/alerts/{alert_id}", data, Alert)
+
+
+class CasesClient(_ResourceClient):
+    async def list(self, filters: Optional[CaseFilters] = None, **kwargs: Any) -> Page[Case]:
+        params = filters.model_dump(exclude_none=True) if filters else self._clean(kwargs)
+        return await self._get("/api/v1/cases", params, Page[Case])
+
+    async def get(self, case_id: str) -> Case:
+        return await self._get(f"/api/v1/cases/{case_id}", model=Case)
+
+    async def create(self, **data: Any) -> Case:
+        return await self._post("/api/v1/cases", data, Case)
+
+    async def update(self, case_id: str, **data: Any) -> Case:
+        return await self._patch(f"/api/v1/cases/{case_id}", data, Case)
+
+    # There is no `delete`. The API serves no DELETE on a case — a case is
+    # closed by patching its status, and the method that used to be here
+    # called a route `services/api` has never declared.
+
+
+class DetectionsClient(_ResourceClient):
+    # The route is `/detection/rules`, singular, and this client asked for
+    # `/detections` — so every method here answered 404 against a real
+    # deployment while its mocked test passed.
+    async def list(self, page: int = 1, page_size: int = 20) -> Page[DetectionRule]:
+        return await self._get(
+            "/api/v1/detection/rules", {"page": page, "page_size": page_size}, Page[DetectionRule]
+        )
+
+    async def get(self, rule_id: str) -> DetectionRule:
+        return await self._get(f"/api/v1/detection/rules/{rule_id}", model=DetectionRule)
+
+
+class ConnectorsClient(_ResourceClient):
+    async def list(self, page: int = 1, page_size: int = 20) -> Page[Connector]:
+        return await self._get(
+            "/api/v1/connectors", {"page": page, "page_size": page_size}, Page[Connector]
+        )
+
+    async def get(self, connector_id: str) -> Connector:
+        return await self._get(f"/api/v1/connectors/{connector_id}", model=Connector)
+
+
+class PlaybooksClient(_ResourceClient):
+    async def list(self, page: int = 1, page_size: int = 20) -> Page[Playbook]:
+        return await self._get(
+            "/api/v1/playbooks", {"page": page, "page_size": page_size}, Page[Playbook]
+        )
+
+    async def get(self, playbook_id: str) -> Playbook:
+        return await self._get(f"/api/v1/playbooks/{playbook_id}", model=Playbook)
+
+    async def create(self, **data: Any) -> Playbook:
+        return await self._post("/api/v1/playbooks", data, Playbook)
+
+    # PUT, not PATCH: `playbooks.py` declares `@router.put("/{playbook_id}")`
+    # and no patch route, so the previous verb returned 405.
+    async def update(self, playbook_id: str, **data: Any) -> Playbook:
+        return await self._put(f"/api/v1/playbooks/{playbook_id}", data, Playbook)
+
+    async def delete(self, playbook_id: str) -> None:
+        return await self._delete(f"/api/v1/playbooks/{playbook_id}")
+
+    async def run(
+        self,
+        playbook_id: str,
+        trigger_data: Optional[dict[str, Any]] = None,
+    ) -> PlaybookRun:
+        return await self._post(
+            f"/api/v1/playbooks/{playbook_id}/run",
+            {"trigger_data": trigger_data or {}},
+            PlaybookRun,
+        )
+
+    async def get_run(self, run_id: str) -> PlaybookRun:
+        return await self._get(f"/api/v1/playbooks/runs/{run_id}", model=PlaybookRun)
+
+
+class ApiKeysClient(_ResourceClient):
+    async def list(self) -> Page[ApiKey]:
+        return await self._get("/api/v1/api-keys", model=Page[ApiKey])
+
+    async def create(self, req: ApiKeyCreateRequest) -> ApiKeyCreateResponse:
+        return await self._post(
+            "/api/v1/api-keys",
+            req.model_dump(exclude_none=True),
+            ApiKeyCreateResponse,
+        )
+
+    async def revoke(self, key_id: str) -> None:
+        return await self._delete(f"/api/v1/api-keys/{key_id}")
+
+
+# ─── Main client ─────────────────────────────────────────────────────────────
+
+
+class AiSOCClient:
+    """Async Python client for the AiSOC REST API.
+
+    Must be used as an async context manager::
+
+        async with AiSOCClient(base_url="...", token="...") as client:
+            alerts = await client.alerts.list()
+
+    Or manage the lifecycle manually::
+
+        client = AiSOCClient(base_url="...", token="...")
+        await client.__aenter__()
+        try:
+            ...
+        finally:
+            await client.__aexit__(None, None, None)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        timeout: float = 30.0,
+        headers: Optional[dict[str, str]] = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._timeout = timeout
+        self._extra_headers = headers or {}
+        self._http: Optional[httpx.AsyncClient] = None
+
+        # Placeholders — initialised in __aenter__
+        self.alerts: AlertsClient
+        self.cases: CasesClient
+        self.detections: DetectionsClient
+        self.connectors: ConnectorsClient
+        self.playbooks: PlaybooksClient
+        self.api_keys: ApiKeysClient
+
+    async def __aenter__(self) -> "AiSOCClient":
+        self._http = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {self._token}",
+                "Content-Type": "application/json",
+                **self._extra_headers,
+            },
+            timeout=self._timeout,
+        )
+        self.alerts = AlertsClient(self._http)
+        self.cases = CasesClient(self._http)
+        self.detections = DetectionsClient(self._http)
+        self.connectors = ConnectorsClient(self._http)
+        self.playbooks = PlaybooksClient(self._http)
+        self.api_keys = ApiKeysClient(self._http)
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        if self._http is not None:
+            await self._http.aclose()
+            self._http = None
+
+    async def graphql(
+        self,
+        query: str,
+        variables: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Execute a GraphQL query against the /graphql endpoint."""
+        if self._http is None:
+            raise RuntimeError("Use AiSOCClient as an async context manager")
+        r = await self._http.post("/graphql", json={"query": query, "variables": variables})
+        if not r.is_success:
+            raise AiSOCError(r.status_code, r.text)
+        return r.json()  # type: ignore[return-value]

aisoc_sdk/models.py

@@ -0,0 +1,208 @@
+"""Pydantic models mirroring the AiSOC OpenAPI schema."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Generic, List, Optional, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+
+
+# ── Enums ─────────────────────────────────────────────────────────────────────
+
+
+class AlertSeverity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+class AlertStatus(str, Enum):
+    OPEN = "open"
+    IN_PROGRESS = "in_progress"
+    CLOSED = "closed"
+    FALSE_POSITIVE = "false_positive"
+
+
+class CasePriority(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class CaseStatus(str, Enum):
+    OPEN = "open"
+    INVESTIGATING = "investigating"
+    RESOLVED = "resolved"
+    CLOSED = "closed"
+
+
+# ── Core models ───────────────────────────────────────────────────────────────
+
+_M = ConfigDict(populate_by_name=True, from_attributes=True)
+
+
+class Alert(BaseModel):
+    model_config = _M
+
+    id: str
+    tenant_id: str
+    title: str
+    severity: AlertSeverity
+    status: AlertStatus
+    source: str
+    source_ref: Optional[str] = None
+    mitre_tactics: List[str] = []
+    ai_score: Optional[float] = None
+    case_id: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class Case(BaseModel):
+    model_config = _M
+
+    id: str
+    tenant_id: str
+    case_number: str
+    title: str
+    status: CaseStatus
+    priority: CasePriority
+    assignee: Optional[str] = None
+    mitre_tactics: List[str] = []
+    alert_ids: List[str] = []
+    created_at: datetime
+    updated_at: datetime
+
+
+class DetectionRule(BaseModel):
+    model_config = _M
+
+    id: str
+    tenant_id: str
+    name: str
+    description: Optional[str] = None
+    rule_language: str
+    severity: AlertSeverity
+    enabled: bool
+    created_at: datetime
+    updated_at: datetime
+
+
+class Connector(BaseModel):
+    model_config = _M
+
+    id: str
+    tenant_id: str
+    name: str
+    connector_type: str
+    is_enabled: bool
+    health_status: str
+    events_ingested: int = 0
+    created_at: datetime
+    updated_at: datetime
+
+
+class PlaybookStep(BaseModel):
+    model_config = _M
+
+    id: str
+    name: str
+    type: str
+    action: Optional[str] = None
+    parameters: Optional[dict[str, Any]] = None
+    next_steps: List[str] = []
+
+
+class Playbook(BaseModel):
+    model_config = _M
+
+    id: str
+    name: str
+    description: Optional[str] = None
+    version: str
+    steps: List[PlaybookStep] = []
+    trigger_conditions: Optional[dict[str, Any]] = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class PlaybookRun(BaseModel):
+    model_config = _M
+
+    run_id: str
+    playbook_id: str
+    status: str
+    started_at: datetime
+    completed_at: Optional[datetime] = None
+    trigger_data: Optional[dict[str, Any]] = None
+    step_results: Optional[dict[str, Any]] = None
+
+
+class ApiKey(BaseModel):
+    model_config = _M
+
+    id: str
+    name: str
+    prefix: str
+    scopes: List[str]
+    expires_at: Optional[datetime] = None
+    last_used_at: Optional[datetime] = None
+    created_at: datetime
+
+
+# ── Pagination ────────────────────────────────────────────────────────────────
+
+T = TypeVar("T")
+
+
+class Page(BaseModel, Generic[T]):
+    model_config = _M
+
+    items: List[T]
+    total: int
+    page: int
+    page_size: int
+
+
+# ── Request / response helpers ────────────────────────────────────────────────
+
+
+class AlertFilters(BaseModel):
+    model_config = _M
+
+    severity: Optional[AlertSeverity] = None
+    status: Optional[AlertStatus] = None
+    case_id: Optional[str] = None
+    search: Optional[str] = None
+    page: int = 1
+    page_size: int = 20
+
+
+class CaseFilters(BaseModel):
+    model_config = _M
+
+    status: Optional[CaseStatus] = None
+    priority: Optional[CasePriority] = None
+    assignee: Optional[str] = None
+    page: int = 1
+    page_size: int = 20
+
+
+class ApiKeyCreateRequest(BaseModel):
+    model_config = _M
+
+    name: str
+    scopes: List[str]
+    expires_at: Optional[datetime] = None
+
+
+class ApiKeyCreateResponse(BaseModel):
+    model_config = _M
+
+    key: ApiKey
+    raw_key: str

aisoc_sdk-4.0.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: aisoc-sdk
+Version: 4.0.0
+Summary: Python client SDK for AiSOC — typed httpx client
+Project-URL: Homepage, https://github.com/beenuar/AiSOC
+Project-URL: Documentation, https://beenuar.github.io/AiSOC
+Project-URL: Repository, https://github.com/beenuar/AiSOC
+Project-URL: Issues, https://github.com/beenuar/AiSOC/issues
+Author-email: AiSOC Contributors <oss@aisoc.io>
+License: MIT
+Keywords: aisoc,client,sdk,security,soc
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy<3,>=2.3.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aisoc-sdk
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+[![PyPI release](https://img.shields.io/badge/pypi-not%20yet%20published-f59e0b)](https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md)
+
+Async Python client SDK for [AiSOC](https://github.com/beenuar/AiSOC).
+
+> **Status — monorepo today, not yet on PyPI.** `pip install aisoc-sdk` does not resolve; install from the monorepo source path below. The import path (`aisoc_sdk`) and API surface stay identical once it ships.
+
+## Installation
+
+```bash
+# Today (from this monorepo):
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC && pip install -e packages/sdk-py
+
+# Not yet on PyPI — the upload is blocked on registry credentials,
+# which is an account action rather than a code change. Until then, install
+# from source with the command above.
+#   pip install aisoc-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+from aisoc_sdk import AiSOCClient
+
+
+async def main():
+    async with AiSOCClient(
+        base_url="https://your-aisoc.example.com",
+        token="aisoc_...",
+    ) as client:
+        # List critical open alerts
+        alerts = await client.alerts.list(severity="critical", status="open")
+        print(f"Found {alerts.total} critical alerts")
+
+        # Create a case
+        case = await client.cases.create(
+            title="Suspicious lateral movement",
+            priority="high",
+        )
+
+        # Trigger a playbook
+        run = await client.playbooks.run(
+            "isolate-host",
+            trigger_data={"host_id": "srv-prod-42", "case_id": case.id},
+        )
+        print("Playbook run:", run.run_id)
+
+
+asyncio.run(main())
+```
+
+## GraphQL
+
+```python
+async with AiSOCClient(base_url="...", token="...") as client:
+    result = await client.graphql("""
+        query {
+            alerts(pageSize: 10, status: "open") {
+                items { id title severity }
+            }
+        }
+    """)
+```
+
+## API reference
+
+All resource methods are `async` and return typed Pydantic models.
+
+| Attribute | Methods |
+|---|---|
+| `client.alerts` | `list(filters?)`, `get(id)`, `update(id, **data)` |
+| `client.cases` | `list(filters?)`, `get(id)`, `create(**data)`, `update(id, **data)`, `delete(id)` |
+| `client.detections` | `list(page, page_size)`, `get(id)` |
+| `client.connectors` | `list(page, page_size)`, `get(id)` |
+| `client.playbooks` | `list(page, page_size)`, `get(id)`, `create(**data)`, `update(id, **data)`, `delete(id)`, `run(id, trigger_data?)`, `get_run(run_id)` |
+| `client.api_keys` | `list()`, `create(req)`, `revoke(id)` |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

aisoc_sdk-4.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+aisoc_sdk/__init__.py,sha256=cF4BWhjS-orfVyWEXsKUQRBjdoo6MrDXXcaURQoINWQ,955
+aisoc_sdk/client.py,sha256=VBp10g4i6qKOa_zMXqrBbvhcR9TEkuPfYG_ckGwaCoU,10630
+aisoc_sdk/models.py,sha256=iWCoAr3ZRL3HuZ2NPxbxwcvYbSSUyTz-rLybpl-94G0,4677
+aisoc_sdk-4.0.0.dist-info/METADATA,sha256=h0pX-Pou7jm_ZhajJ52-mltlu0RGe4dSfn1br_mSubI,3485
+aisoc_sdk-4.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+aisoc_sdk-4.0.0.dist-info/RECORD,,

aisoc_sdk-4.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any