kobil-agent-audit 1.2.0__tar.gz

kobil_agent_audit-1.2.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

kobil_agent_audit-1.2.0/LICENSE

@@ -0,0 +1,128 @@
+KOBIL Agent Trust SDK License
+Version 1.0
+
+Copyright (c) 2026 KOBIL GmbH. All rights reserved.
+The Software is developed by the KOBIL AI Team.
+
+In short: you may install and use the Software free of charge, also in
+commercial products, and ship it inside your own application. You may not
+change it, copy it into other software, or pass it on or sell it on its
+own. The numbered terms below are the license; this summary is not.
+
+1. Definitions
+
+   "The Software" is the code and documentation in this package.
+
+   "You" is the person or organization that accepts these terms.
+
+   "Your company" is the organization you work for, and the organizations
+   that control it, that it controls, or that are under common control
+   with it.
+
+   "Your application" is software or a service that you build and that
+   does more than give access to the Software. Your application is not a
+   work based on the Software just because it uses the Software.
+
+2. Acceptance
+
+   By installing, copying or using the Software you accept these terms.
+   If you do not accept them, do not use the Software.
+
+3. What you may do
+
+   KOBIL grants you and your company a non-exclusive, worldwide,
+   non-transferable license, free of charge, to:
+
+   a. install and use the Software, unchanged, to build, test and run your
+      applications, including commercial ones that you charge for;
+   b. make the copies of the Software that this needs, for example on
+      developer machines, on build servers and in your application's
+      environments;
+   c. ship the Software, unchanged, as part of your application, for
+      example inside its container image, package or bundle.
+
+   Your company's employees and contractors may do the same on your
+   company's behalf.
+
+   Building your application with tools such as bundlers, minifiers,
+   transpilers or compilers is not a change to the Software. Using AI
+   coding tools to write applications that use the Software is allowed.
+
+4. Shipping the Software inside your application
+
+   When you ship the Software as part of your application:
+
+   a. the Software must be needed for your application to work, and must
+      not be offered as a library, SDK or tool of its own;
+   b. the people who receive your application get no right to use the
+      Software apart from your application;
+   c. keep this license and the copyright notice with the Software, or in
+      your application's third-party notices.
+
+5. What you may not do
+
+   You may not:
+
+   a. change, adapt or translate the Software, or make works based on it;
+   b. copy the Software's code, or substantial parts of it, into other
+      software, whether by hand or with automated or AI tools, or use the
+      Software to train AI models;
+   c. publish, share, sublicense, sell, rent or lease the Software on its
+      own, or as part of another SDK, library, framework or developer
+      tool;
+   d. remove or change this license or any copyright notice in the
+      Software;
+   e. use the Software to break the law, or to suggest that KOBIL endorses
+      your application.
+
+   These limits apply to the Software itself. You may sell and
+   commercially distribute your application.
+
+6. KOBIL services
+
+   The Software can connect to KOBIL services. Using those services is
+   governed by their own terms, not by this license. This license does not
+   give you access to any KOBIL service.
+
+7. Ownership
+
+   KOBIL keeps all rights in the Software that this license does not
+   expressly grant. This license gives you no right to KOBIL's names,
+   logos or trademarks, except to say truthfully that your application
+   uses the Software.
+
+8. Other software
+
+   The Software uses third-party open-source packages. Each of them is
+   covered by its own license, not by this one.
+
+9. New versions
+
+   KOBIL may release new versions of the Software under a new version of
+   this license. Each copy of the Software is covered by the license that
+   came with it.
+
+10. Violations
+
+   If you break these terms, KOBIL may tell you so in writing. The first
+   time this happens, your license continues if, within 30 days of that
+   notice, you fully comply again and take practical steps to correct past
+   violations. Otherwise, and after any later violation, your license
+   ends. You must then stop using and shipping the Software.
+
+11. No warranty
+
+   As far as the law allows, the Software comes "as is", without any
+   warranty or condition, express or implied, including fitness for a
+   particular purpose and non-infringement.
+
+12. Limitation of liability
+
+   As far as the law allows, KOBIL is not liable for any damages that come
+   from these terms or from using, or not being able to use, the Software,
+   under any kind of legal claim.
+
+13. Other permissions
+
+   For any use these terms do not allow, ask KOBIL for written permission
+   at www.kobil.com.

kobil_agent_audit-1.2.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: kobil-agent-audit
+Version: 1.2.0
+Summary: Audit, Observability & Human-in-the-Loop for the KOBIL AI Trust Platform
+License-Expression: LicenseRef-KOBIL-Agent-Trust-SDK-1.0
+License-File: LICENSE
+Keywords: agent,ai-security,audit,ciba,compliance,human-in-the-loop,kobil,observability,siem,token-tracking
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kobil-agent-audit (Python)
+
+Python mirror of the `@uveysservetoglu/kobil-agent-audit` TypeScript SDK — audit,
+observability, and human-in-the-loop for the KOBIL AI Trust Platform.
+
+Behavioral 1:1 port of the TypeScript package in `../src`. The TypeScript
+source is the reference specification; the Python code reproduces its logic,
+HTTP wire format, and error semantics. `AuditConfig` is a snake_case dataclass
+(developer surface); the entity types (AuditEvent, TokenTrackingEntry, …) are
+camelCase dicts because they are the literal JSON exchanged with the platform.
+
+## Install (dev)
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Test
+
+```bash
+pytest
+```
+
+## Usage
+
+```python
+import asyncio
+from kobil_agent_audit import KobilAgentAudit
+
+audit = KobilAgentAudit(
+    platform_url="https://platform.kobil.com",
+    agent_id="my-agent",
+    api_token="tok",
+)
+
+audit.log_action("call_tool", "weather-api", "success", {"temp": 72})
+
+async def main():
+    await audit.destroy()  # flushes remaining events
+
+asyncio.run(main())
+```

kobil_agent_audit-1.2.0/README.md

@@ -0,0 +1,43 @@
+# kobil-agent-audit (Python)
+
+Python mirror of the `@uveysservetoglu/kobil-agent-audit` TypeScript SDK — audit,
+observability, and human-in-the-loop for the KOBIL AI Trust Platform.
+
+Behavioral 1:1 port of the TypeScript package in `../src`. The TypeScript
+source is the reference specification; the Python code reproduces its logic,
+HTTP wire format, and error semantics. `AuditConfig` is a snake_case dataclass
+(developer surface); the entity types (AuditEvent, TokenTrackingEntry, …) are
+camelCase dicts because they are the literal JSON exchanged with the platform.
+
+## Install (dev)
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Test
+
+```bash
+pytest
+```
+
+## Usage
+
+```python
+import asyncio
+from kobil_agent_audit import KobilAgentAudit
+
+audit = KobilAgentAudit(
+    platform_url="https://platform.kobil.com",
+    agent_id="my-agent",
+    api_token="tok",
+)
+
+audit.log_action("call_tool", "weather-api", "success", {"temp": 72})
+
+async def main():
+    await audit.destroy()  # flushes remaining events
+
+asyncio.run(main())
+```

kobil_agent_audit-1.2.0/kobil_agent_audit/__init__.py

@@ -0,0 +1,211 @@
+"""kobil-agent-audit — Audit, Observability & Human-in-the-Loop (Python).
+
+Python mirror of the ``@uveysservetoglu/kobil-agent-audit`` TypeScript package.
+
+Provides:
+ - Batched audit event logging with platform / SIEM / webhook sinks
+ - Full token lifecycle tracking with anomaly detection
+ - CIBA push notifications for human approval
+ - Async authorization gates for tool execution
+ - Compliance report generation, export, and scheduling
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .async_auth import AsyncAuthError, AsyncAuthorization
+from .ciba_notification import CIBANotificationError, CIBANotificationService
+from .compliance import ComplianceError, ComplianceReporter
+from .logger import AuditLogger, AuditLoggerError, AuditQueryFilter, AuditQueryResult
+from .token_tracker import TokenTracker, TokenTrackerError
+from .types import (
+    ALL_EVENT_TYPES,
+    AnomalyDetection,
+    AnomalySeverity,
+    AnomalyType,
+    ApprovalStats,
+    AsyncAuthRequest,
+    AsyncAuthResponse,
+    AsyncAuthStatus,
+    AuditConfig,
+    AuditEvent,
+    AuditEventInput,
+    AuditOutcome,
+    CIBANotification,
+    CIBAStatus,
+    ComplianceReport,
+    EventType,
+    SinkType,
+    TokenStats,
+    TokenStatus,
+    TokenTrackingEntry,
+    Urgency,
+)
+
+# The release pipeline stamps the version into pyproject.toml only, so read it back from the installed metadata.
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("kobil-agent-audit")
+except _PackageNotFoundError:  # running from a source checkout that is not installed
+    __version__ = "0.0.0"
+
+
+class AuditError(Exception):
+    """Base error class for the audit package."""
+
+    def __init__(self, message: str, code: str, cause: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.cause = cause
+        self.name = "AuditError"
+
+
+class KobilAgentAudit:
+    """Top-level entry point — instantiates and exposes all sub-systems."""
+
+    def __init__(
+        self,
+        platform_url: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        api_token: str = "",
+        sink_type: SinkType = "platform",
+        sink_url: Optional[str] = None,
+        batch_size: int = 50,
+        flush_interval_ms: int = 10_000,
+        cert_path: Optional[str] = None,
+        key_path: Optional[str] = None,
+        timeout_ms: int = 30_000,
+    ) -> None:
+        if not platform_url:
+            raise AuditError("AuditConfig.platformUrl is required", "CONFIG_MISSING")
+        if not agent_id:
+            raise AuditError("AuditConfig.agentId is required", "CONFIG_MISSING")
+
+        self.config = AuditConfig(
+            platform_url=platform_url,
+            agent_id=agent_id,
+            api_token=api_token,
+            sink_type=sink_type,
+            sink_url=sink_url,
+            batch_size=batch_size,
+            flush_interval_ms=flush_interval_ms,
+            cert_path=cert_path,
+            key_path=key_path,
+            timeout_ms=timeout_ms,
+        )
+        self.logger = AuditLogger(self.config)
+        self.token_tracker = TokenTracker(self.config)
+        self.notifications = CIBANotificationService(self.config)
+        self.async_auth = AsyncAuthorization(self.config)
+        self.compliance = ComplianceReporter(self.config)
+
+    def log_action(
+        self,
+        action: str,
+        resource: str,
+        outcome: AuditOutcome,
+        metadata: Optional[dict] = None,
+    ) -> None:
+        """Convenience helper to log a single tool_call action event."""
+        event: dict = {
+            "agentId": self.config.agent_id,
+            "eventType": "tool_call",
+            "action": action,
+            "resource": resource,
+            "outcome": outcome,
+        }
+        if metadata is not None:
+            event["metadata"] = metadata
+        self.logger.log(event)
+
+    async def log_event(self, input: "AuditEventInput") -> None:
+        """Log a single arbitrary audit event and flush immediately.
+
+        Mirrors the TS ``KobilAgentAudit.logEvent`` facade added in 0.2.16 —
+        callers use this instead of hand-rolling ``POST /v1/events`` so the
+        SDK owns transport (incl. mTLS) and endpoint resolution. The immediate
+        flush gives fire-and-forget parity with pre-batched inline emit paths.
+        """
+        event: dict = {
+            "agentId": input.get("agentId") or self.config.agent_id,
+            "eventType": input.get("eventType"),
+            "action": input.get("action"),
+            "resource": input.get("resource") or input.get("resourceType") or "",
+            "outcome": input.get("outcome", "success"),
+        }
+        # Top-level optional fields — mirror TS widening.
+        for key in ("resourceType", "resourceId", "correlationId", "actorId", "userId", "details"):
+            if input.get(key) is not None:
+                event[key] = input[key]
+        # ``metadata`` falls back to ``details`` when the caller only provided the latter.
+        metadata = input.get("metadata")
+        if metadata is None:
+            metadata = input.get("details")
+        if metadata is not None:
+            event["metadata"] = metadata
+        self.logger.log(event)
+        await self.logger.flush()
+
+    async def destroy(self) -> None:
+        """Gracefully tear down all sub-systems."""
+        errors: list[Exception] = []
+        for fn in (
+            self.logger.destroy,
+            self.token_tracker.destroy,
+            self.notifications.destroy,
+            self.async_auth.destroy,
+            self.compliance.destroy,
+        ):
+            try:
+                result = fn()
+                if hasattr(result, "__await__"):
+                    await result
+            except Exception as e:  # noqa: BLE001
+                errors.append(e if isinstance(e, Exception) else Exception(str(e)))
+        if errors:
+            msg = "; ".join(str(e) for e in errors)
+            raise AuditError(
+                f"Audit destroy encountered {len(errors)} error(s): {msg}", "DESTROY_ERROR"
+            )
+
+
+__all__ = [
+    "AuditError",
+    "KobilAgentAudit",
+    "AuditLogger",
+    "AuditLoggerError",
+    "AuditQueryFilter",
+    "AuditQueryResult",
+    "TokenTracker",
+    "TokenTrackerError",
+    "CIBANotificationService",
+    "CIBANotificationError",
+    "AsyncAuthorization",
+    "AsyncAuthError",
+    "ComplianceReporter",
+    "ComplianceError",
+    "AuditConfig",
+    "AuditEvent",
+    "AuditEventInput",
+    "AuditOutcome",
+    "EventType",
+    "SinkType",
+    "TokenStatus",
+    "TokenTrackingEntry",
+    "CIBAStatus",
+    "CIBANotification",
+    "Urgency",
+    "AsyncAuthRequest",
+    "AsyncAuthResponse",
+    "AsyncAuthStatus",
+    "TokenStats",
+    "ApprovalStats",
+    "AnomalyType",
+    "AnomalySeverity",
+    "AnomalyDetection",
+    "ComplianceReport",
+    "ALL_EVENT_TYPES",
+]

kobil_agent_audit-1.2.0/kobil_agent_audit/_common.py

@@ -0,0 +1,38 @@
+"""Shared helpers for the kobil-agent-audit Python package."""
+
+from __future__ import annotations
+
+import uuid as _uuid
+from datetime import datetime, timezone
+
+
+def uuid() -> str:
+    """Mirror of crypto.randomUUID()."""
+    return str(_uuid.uuid4())
+
+
+def iso_now() -> str:
+    """Mirror of ``new Date().toISOString()`` — always millisecond + 'Z'."""
+    dt = datetime.now(timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"
+
+
+def iso_from_dt(dt: datetime) -> str:
+    """Mirror of ``date.toISOString()`` for an arbitrary datetime."""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    dt = dt.astimezone(timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"
+
+
+def parse_iso_ms(value: str) -> int:
+    """Parse an ISO-8601 string to epoch milliseconds (mirror Date.parse)."""
+    normalized = value.replace("Z", "+00:00")
+    dt = datetime.fromisoformat(normalized)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return int(dt.timestamp() * 1000)
+
+
+def now_ms() -> int:
+    return int(datetime.now(timezone.utc).timestamp() * 1000)

kobil_agent_audit-1.2.0/kobil_agent_audit/async_auth.py

@@ -0,0 +1,163 @@
+"""AsyncAuthorization — human-in-the-loop approval gates (Python mirror).
+
+Mirror of ``kobil-agent-audit/src/async-auth.ts``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Awaitable, Callable
+from urllib.parse import quote
+
+import httpx
+
+from ._common import iso_now, now_ms, uuid
+from .types import AsyncAuthRequest, AsyncAuthResponse, AuditConfig
+
+
+class AsyncAuthError(Exception):
+    def __init__(self, message: str, code: str, cause: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.cause = cause
+        self.name = "AsyncAuthError"
+
+
+class AsyncAuthorization:
+    def __init__(self, config: AuditConfig) -> None:
+        self.config = config
+        self._requests: dict[str, AsyncAuthResponse] = {}
+
+    def destroy(self) -> None:
+        self._requests.clear()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def request_approval(self, request: AsyncAuthRequest) -> AsyncAuthResponse:
+        request_id = uuid()
+        full: AsyncAuthRequest = {**request, "requestId": request_id}
+        response = await self._submit_remote(full)
+        self._requests[request_id] = response
+        return response
+
+    async def check_approval(self, request_id: str) -> AsyncAuthResponse:
+        try:
+            remote = await self._fetch_remote_status(request_id)
+            self._requests[request_id] = remote
+            return remote
+        except AsyncAuthError:
+            raise
+        except Exception:
+            local = self._requests.get(request_id)
+            if not local:
+                raise AsyncAuthError(
+                    f"Approval request not found: {request_id}", "REQUEST_NOT_FOUND"
+                )
+            return dict(local)  # type: ignore[return-value]
+
+    async def wait_for_approval(
+        self, request_id: str, timeout_ms: int = 300_000
+    ) -> AsyncAuthResponse:
+        deadline = now_ms() + timeout_ms
+        poll_interval_ms = 2000
+
+        while now_ms() < deadline:
+            response = await self.check_approval(request_id)
+            if response.get("status") != "pending":
+                return response
+            await asyncio.sleep(min(poll_interval_ms, deadline - now_ms()) / 1000)
+
+        expired: AsyncAuthResponse = {
+            "requestId": request_id,
+            "status": "expired",
+            "respondedAt": iso_now(),
+        }
+        self._requests[request_id] = expired
+        return expired
+
+    async def cancel_request(self, request_id: str) -> None:
+        url = f"{self.config.platform_url}/v1/async-auth/requests/{quote(request_id, safe='')}"
+        async with httpx.AsyncClient() as http:
+            res = await http.request(
+                "DELETE",
+                url,
+                headers={
+                    "Authorization": f"Bearer {self.config.api_token}",
+                    "X-Agent-Id": self.config.agent_id,
+                },
+            )
+        if not res.is_success:
+            raise AsyncAuthError(
+                f"Failed to cancel request: {res.status_code} — {res.text}", "CANCEL_ERROR"
+            )
+        self._requests.pop(request_id, None)
+
+    def wrap_with_approval(
+        self,
+        action: str,
+        tool_fn: Callable[..., Awaitable[Any]],
+    ) -> Callable[..., Awaitable[Any]]:
+        async def wrapped(*args: Any, **kwargs: Any) -> Any:
+            response = await self.request_approval(
+                {
+                    "agentId": self.config.agent_id,
+                    "userId": "system",
+                    "action": action,
+                    "reason": f"Agent {self.config.agent_id} wants to execute: {action}",
+                    "urgency": "normal",
+                    "timeout": 300,
+                }
+            )
+            resolved = await self.wait_for_approval(response["requestId"], 300_000)
+            if resolved.get("status") != "approved":
+                raise AsyncAuthError(
+                    f'Approval {resolved.get("status")} for action "{action}" '
+                    f'(request {resolved.get("requestId")})',
+                    "APPROVAL_DENIED",
+                )
+            return await tool_fn(*args, **kwargs)
+
+        return wrapped
+
+    # ------------------------------------------------------------------
+    # Remote helpers
+    # ------------------------------------------------------------------
+
+    async def _submit_remote(self, request: AsyncAuthRequest) -> AsyncAuthResponse:
+        url = f"{self.config.platform_url}/v1/async-auth/requests"
+        async with httpx.AsyncClient() as http:
+            res = await http.post(
+                url,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {self.config.api_token}",
+                    "X-Agent-Id": self.config.agent_id,
+                },
+                content=json.dumps(request, separators=(",", ":")),
+            )
+        if not res.is_success:
+            raise AsyncAuthError(
+                f"Failed to submit approval request: {res.status_code} — {res.text}", "SUBMIT_ERROR"
+            )
+        return res.json()
+
+    async def _fetch_remote_status(self, request_id: str) -> AsyncAuthResponse:
+        url = f"{self.config.platform_url}/v1/async-auth/requests/{quote(request_id, safe='')}"
+        async with httpx.AsyncClient() as http:
+            res = await http.get(
+                url,
+                headers={
+                    "Authorization": f"Bearer {self.config.api_token}",
+                    "X-Agent-Id": self.config.agent_id,
+                },
+            )
+        if not res.is_success:
+            raise AsyncAuthError(f"Remote status check failed: {res.status_code}", "STATUS_FETCH_ERROR")
+        return res.json()
+
+
+__all__ = ["AsyncAuthorization", "AsyncAuthError"]