auditail 0.2.0__py3-none-any.whl

auditail/__init__.py

@@ -0,0 +1,14 @@
+"""
+Auditail Python SDK
+The security layer for autonomous AI agents.
+Guardrails that block risky actions, plus a tamper-evident audit trail.
+
+https://auditail.io/docs
+"""
+
+from .client import Auditail
+from .types import GuardOptions, GuardResult, GuardrailRule, AuditEvent
+from . import rules
+
+__version__ = "0.2.0"
+__all__ = ["Auditail", "GuardOptions", "GuardResult", "GuardrailRule", "AuditEvent", "rules"]

auditail/client.py

@@ -0,0 +1,339 @@
+"""
+Auditail Python SDK — Client
+"""
+
+import asyncio
+import atexit
+import concurrent.futures
+import inspect
+import json
+import random
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from collections import deque
+from dataclasses import asdict
+from datetime import datetime, timezone
+from typing import Any, Callable, Deque, Iterable, List, Optional
+
+from .types import AuditEvent, GuardOptions, GuardResult, GuardrailRule
+
+SDK_VERSION = "0.2.0"
+MAX_QUEUE = 10_000
+MAX_BATCH = 50
+MAX_DELIVERY_ATTEMPTS = 5
+DEFAULT_REDACT = {
+    "password", "passwd", "secret", "token", "apikey", "api_key", "authorization", "auth",
+    "ssn", "creditcard", "credit_card", "cardnumber", "card_number", "cvv", "privatekey", "private_key",
+}
+
+
+def _redact(value: Any, keys: set, depth: int = 0) -> Any:
+    if depth > 10:
+        return "[TRUNCATED]"
+    if isinstance(value, dict):
+        return {k: ("[REDACTED]" if str(k).lower() in keys else _redact(v, keys, depth + 1)) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_redact(v, keys, depth + 1) for v in value]
+    return value
+
+
+def _to_wire(e: AuditEvent) -> dict:
+    """AuditEvent -> the camelCase JSON the API expects."""
+    return {
+        "auditId": e.audit_id, "agentId": e.agent_id, "userId": e.user_id, "action": e.action,
+        "payload": e.payload, "approved": e.approved, "reason": e.reason, "matchedRule": e.matched_rule,
+        "tags": e.tags, "timestamp": e.timestamp, "environment": e.environment, "sdkVersion": e.sdk_version,
+    }
+WAITLIST_URL = "https://auditail.io/waitlist"
+
+
+class Auditail:
+    """
+    Auditail client. Instantiate once at app startup and reuse.
+
+    Example::
+
+        from auditail import Auditail, rules
+
+        aegis = Auditail(api_key="your_key")
+        aegis.add_rule(rules.no_external_email())
+        aegis.add_rule(rules.no_data_deletion())
+
+        result = aegis.guard(
+            action="send_email",
+            payload={"to": "client@example.com", "body": "Report attached."},
+            agent_id="financial-bot-01",
+        )
+
+        if result.approved:
+            send_email(...)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        environment: str = "production",
+        log_level: str = "info",
+        base_url: str = "https://api.auditail.io",
+        redact_keys: Optional[Iterable[str]] = None,
+        ship: bool = True,
+        flush_interval: float = 1.0,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ):
+        if not api_key:
+            raise ValueError(
+                f"[Auditail] No API key provided.\nGet your free API key at: {WAITLIST_URL}"
+            )
+
+        self.api_key = api_key
+        self.environment = environment
+        self.log_level = log_level
+        self.base_url = base_url.rstrip("/")
+        self.ship = ship
+        self.flush_interval = flush_interval
+        self._redact = DEFAULT_REDACT | {k.lower() for k in (redact_keys or [])}
+        self._on_error = on_error or (lambda e: self._log("error", str(e)))
+
+        self._rules: List[GuardrailRule] = []
+        self._audit_log: List[AuditEvent] = []
+
+        self._queue: Deque[AuditEvent] = deque()
+        self._qlock = threading.Lock()
+        self._flush_lock = threading.Lock()
+        self._wake = threading.Event()
+        self._stop = threading.Event()
+        self._worker: Optional[threading.Thread] = None
+        if ship:
+            atexit.register(self.flush)
+
+    def add_rule(self, rule: GuardrailRule) -> "Auditail":
+        """Register a guardrail rule. Rules are evaluated in registration order."""
+        self._rules.append(rule)
+        self._log("debug", f'Guardrail rule added: "{rule.name}"')
+        return self
+
+    def add_rules(self, rules: List[GuardrailRule]) -> "Auditail":
+        """Register multiple guardrail rules at once."""
+        for rule in rules:
+            self.add_rule(rule)
+        return self
+
+    def guard(
+        self,
+        action: str,
+        payload: dict,
+        agent_id: str,
+        user_id: Optional[str] = None,
+        tags: Optional[dict] = None,
+    ) -> GuardResult:
+        """
+        Synchronous guard evaluation.
+        Evaluates the action against all registered rules and logs an audit event.
+        """
+        opts = GuardOptions(
+            action=action,
+            payload=payload,
+            agent_id=agent_id,
+            user_id=user_id,
+            tags=tags,
+        )
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(self._evaluate(opts))
+        # Already inside a running event loop (FastAPI, async LangChain):
+        # run the evaluation on a worker thread so we don't crash or block the loop's state.
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(asyncio.run, self._evaluate(opts)).result()
+
+    async def guard_async(
+        self,
+        action: str,
+        payload: dict,
+        agent_id: str,
+        user_id: Optional[str] = None,
+        tags: Optional[dict] = None,
+    ) -> GuardResult:
+        """
+        Async guard evaluation for use in async codebases (FastAPI, etc.).
+        """
+        opts = GuardOptions(
+            action=action,
+            payload=payload,
+            agent_id=agent_id,
+            user_id=user_id,
+            tags=tags,
+        )
+        return await self._evaluate(opts)
+
+    def get_audit_log(self) -> List[AuditEvent]:
+        """
+        Returns all audit events from this session.
+        In the full SDK, use the dashboard at https://app.auditail.io for persistent logs.
+        """
+        return list(self._audit_log)
+
+    # ---------------------------------------------------------------------------
+    # Private
+    # ---------------------------------------------------------------------------
+
+    async def _evaluate(self, opts: GuardOptions) -> GuardResult:
+        start = time.monotonic()
+        audit_id = self._generate_id()
+
+        self._log("debug", f'Evaluating action "{opts.action}" for agent "{opts.agent_id}"')
+
+        approved = True
+        reason: Optional[str] = None
+        matched_rule: Optional[str] = None
+
+        for rule in self._rules:
+            try:
+                result = rule.condition(opts)
+                triggered = await result if inspect.isawaitable(result) else result
+            except Exception as exc:  # fail closed: a broken rule must not approve the action
+                self._log("error", f'Rule "{rule.name}" raised {exc!r}. Failing closed (blocking action).')
+                triggered = True
+
+            if triggered:
+                matched_rule = rule.name
+                if rule.action in ("block", "require_approval"):
+                    approved = False
+                    reason = rule.description
+                    self._log("warn", f'Action BLOCKED by rule "{rule.name}": {rule.description}')
+                    break
+                elif rule.action == "alert":
+                    self._log("warn", f'ALERT fired by rule "{rule.name}": {rule.description}')
+
+        latency_ms = int((time.monotonic() - start) * 1000)
+        timestamp = datetime.now(timezone.utc).isoformat()
+
+        event = AuditEvent(
+            audit_id=audit_id,
+            agent_id=opts.agent_id,
+            user_id=opts.user_id,
+            action=opts.action,
+            payload=_redact(opts.payload, self._redact),
+            approved=approved,
+            reason=reason,
+            matched_rule=matched_rule,
+            tags=opts.tags,
+            timestamp=timestamp,
+            environment=self.environment,
+            sdk_version=SDK_VERSION,
+        )
+
+        self._audit_log.append(event)
+        status = "APPROVED" if approved else "BLOCKED"
+        self._log("info", f"[{status}] {opts.action} | auditId: {audit_id} | {latency_ms}ms")
+
+        self._ship_to_api(event)
+
+        return GuardResult(
+            approved=approved,
+            audit_id=audit_id,
+            reason=reason,
+            matched_rule=matched_rule,
+            timestamp=timestamp,
+            latency_ms=latency_ms,
+        )
+
+    def _generate_id(self) -> str:
+        return f"aeg_{uuid.uuid4().hex[:16]}"
+
+    def _log(self, level: str, message: str) -> None:
+        levels = ["debug", "info", "warn", "error", "silent"]
+        if level not in levels:
+            return
+        if levels.index(level) < levels.index(self.log_level):
+            return
+        prefix = "[Auditail]"
+        if level == "warn":
+            print(f"{prefix} ⚠️  {message}")
+        elif level == "error":
+            print(f"{prefix} ❌  {message}")
+        else:
+            print(f"{prefix} {message}")
+
+    # ---------------------------------------------------------------------------
+    # Delivery: non-blocking queue + background worker. Never raises into the caller.
+    # ---------------------------------------------------------------------------
+
+    def _ship_to_api(self, event: AuditEvent) -> None:
+        if not self.ship:
+            return
+        with self._qlock:
+            if len(self._queue) >= MAX_QUEUE:
+                self._queue.popleft()
+                self._on_error(RuntimeError(f"Auditail queue full ({MAX_QUEUE}); dropped oldest event"))
+            self._queue.append(event)
+        self._ensure_worker()
+        self._wake.set()
+
+    def _ensure_worker(self) -> None:
+        if self._worker and self._worker.is_alive():
+            return
+        self._stop.clear()
+        self._worker = threading.Thread(target=self._run, name="auditail-shipper", daemon=True)
+        self._worker.start()
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            self._wake.wait(timeout=self.flush_interval)
+            self._wake.clear()
+            self._drain()
+
+    def flush(self) -> None:
+        """Deliver all queued events now. Never raises. Call before a serverless handler returns."""
+        self._drain()
+
+    def shutdown(self) -> None:
+        """Flush and stop the background worker."""
+        self._stop.set()
+        self._wake.set()
+        self.flush()
+
+    def _drain(self) -> None:
+        with self._flush_lock:
+            while True:
+                with self._qlock:
+                    batch = list(self._queue)[:MAX_BATCH]
+                if not batch:
+                    return
+                if not self._deliver(batch):
+                    return  # keep events queued; the next flush retries
+                done = {id(e) for e in batch}
+                with self._qlock:
+                    self._queue = deque(e for e in self._queue if id(e) not in done)
+
+    def _deliver(self, batch: List[AuditEvent]) -> bool:
+        body = json.dumps({"events": [_to_wire(e) for e in batch]}).encode()
+        req = urllib.request.Request(
+            f"{self.base_url}/v1/events",
+            data=body,
+            method="POST",
+            headers={
+                "content-type": "application/json",
+                "authorization": f"Bearer {self.api_key}",
+                # Explicit UA: Cloudflare blocks the default "Python-urllib" signature (error 1010).
+                "user-agent": f"auditail-python/{SDK_VERSION}",
+            },
+        )
+        for attempt in range(1, MAX_DELIVERY_ATTEMPTS + 1):
+            try:
+                with urllib.request.urlopen(req, timeout=10):
+                    return True
+            except urllib.error.HTTPError as exc:
+                if 400 <= exc.code < 500 and exc.code != 429:
+                    detail = exc.read(200).decode(errors="replace")
+                    self._on_error(RuntimeError(f"Auditail rejected {len(batch)} event(s): HTTP {exc.code} {detail}"))
+                    return True  # permanent: drop, don't retry forever
+            except Exception:
+                pass  # network error: retry
+            if attempt < MAX_DELIVERY_ATTEMPTS:
+                time.sleep(random.random() * min(0.25 * 2**attempt, 4.0))
+        self._on_error(RuntimeError(f"Auditail could not deliver {len(batch)} event(s); will retry on next flush"))
+        return False

auditail/rules.py

@@ -0,0 +1,79 @@
+"""
+Pre-built guardrail rules for common AI agent security scenarios.
+"""
+
+from .types import GuardrailRule, GuardOptions
+
+
+def no_external_email(internal_domains: list[str] | None = None) -> GuardrailRule:
+    """
+    Block any email action targeting an external domain.
+
+    Args:
+        internal_domains: Trusted domains (e.g. ['acme.com']). Emails to any other
+                          domain are blocked. If empty, the rule is inactive.
+    """
+    domains = internal_domains or []
+
+    def condition(opts: GuardOptions) -> bool:
+        if not domains:
+            return False  # not configured, skip rule
+        to = opts.payload.get("to", "")
+        if not to:
+            return False
+        return not any(to.endswith(f"@{d}") for d in domains)
+
+    return GuardrailRule(
+        name="no-external-email",
+        description="Blocked: sending email to an external domain requires human approval.",
+        condition=condition,
+        action="block",
+    )
+
+
+def no_data_deletion() -> GuardrailRule:
+    """Block destructive SQL operations (DELETE, DROP, TRUNCATE)."""
+
+    def condition(opts: GuardOptions) -> bool:
+        query = str(opts.payload.get("query", "")).upper()
+        return any(kw in query for kw in ["DELETE", "DROP TABLE", "TRUNCATE"])
+
+    return GuardrailRule(
+        name="no-data-deletion",
+        description="Blocked: destructive data operations are not permitted.",
+        condition=condition,
+        action="block",
+    )
+
+
+def no_external_api_calls() -> GuardrailRule:
+    """Alert when an agent makes an outbound HTTP request."""
+
+    def condition(opts: GuardOptions) -> bool:
+        return opts.action == "http_request"
+
+    return GuardrailRule(
+        name="no-external-api-calls",
+        description="Alert: agent is making a call to an external API.",
+        condition=condition,
+        action="alert",
+    )
+
+
+def no_pii_in_logs() -> GuardrailRule:
+    """Block actions that appear to include PII (email addresses, phone numbers) in payloads."""
+    import re
+
+    EMAIL_RE = re.compile(r"[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}")
+    PHONE_RE = re.compile(r"\b(\+?\d[\d\s\-().]{7,}\d)\b")
+
+    def condition(opts: GuardOptions) -> bool:
+        payload_str = str(opts.payload)
+        return bool(EMAIL_RE.search(payload_str) or PHONE_RE.search(payload_str))
+
+    return GuardrailRule(
+        name="no-pii-in-logs",
+        description="Alert: payload appears to contain PII (email or phone number).",
+        condition=condition,
+        action="alert",
+    )

auditail/types.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass, field
+from typing import Any, Callable, Awaitable, Dict, Optional, Union
+
+
+@dataclass
+class GuardOptions:
+    """Options for a single guard evaluation."""
+    action: str
+    payload: Dict[str, Any]
+    agent_id: str
+    user_id: Optional[str] = None
+    tags: Optional[Dict[str, str]] = None
+
+
+@dataclass
+class GuardResult:
+    """Result of a guard evaluation."""
+    approved: bool
+    audit_id: str
+    timestamp: str
+    latency_ms: int
+    reason: Optional[str] = None
+    matched_rule: Optional[str] = None
+
+
+@dataclass
+class GuardrailRule:
+    """
+    A single guardrail rule.
+
+    condition: callable that receives GuardOptions and returns True to BLOCK.
+    action: 'block' | 'require_approval' | 'alert'
+    """
+    name: str
+    description: str
+    condition: Callable[[GuardOptions], Union[bool, Awaitable[bool]]]
+    action: str = "block"  # 'block' | 'require_approval' | 'alert'
+
+
+@dataclass
+class AuditEvent:
+    """A record of a single agent action evaluation."""
+    audit_id: str
+    agent_id: str
+    action: str
+    payload: Dict[str, Any]
+    approved: bool
+    timestamp: str
+    environment: str
+    sdk_version: str
+    user_id: Optional[str] = None
+    reason: Optional[str] = None
+    matched_rule: Optional[str] = None
+    tags: Optional[Dict[str, str]] = None

auditail-0.2.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: auditail
+Version: 0.2.0
+Summary: Guardrails that block risky actions, plus a tamper-evident audit trail for autonomous AI agents.
+Author: Auditail
+License-Expression: MIT
+Project-URL: Homepage, https://auditail.io
+Project-URL: Documentation, https://auditail.io/docs
+Project-URL: Repository, https://github.com/auditailhq/auditail
+Project-URL: Request an API key, https://auditail.io/waitlist
+Keywords: ai,agents,security,guardrails,audit,compliance,soc2,langchain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# auditail (Python SDK)
+
+> The security layer for autonomous AI agents. Guardrails that block risky actions, and a tamper-evident audit trail of everything your agents do.
+
+**[📖 Full Documentation](https://auditail.io/docs)** · **[🚀 Join the Private Beta](https://auditail.io/waitlist)**
+
+---
+
+## Install
+
+```bash
+pip install auditail
+```
+
+## Quickstart
+
+```python
+from auditail import Auditail, rules
+
+aegis = Auditail(api_key="your_key")
+
+aegis.add_rules([
+    rules.no_external_email(internal_domains=["acme.com"]),
+    rules.no_data_deletion(),
+])
+
+result = aegis.guard(
+    action="send_email",
+    payload={"to": "client@example.com", "body": "Report attached."},
+    agent_id="financial-bot-01",
+)
+
+if result.approved:
+    send_email(...)
+else:
+    print(f"Blocked: {result.reason}")
+```
+
+## LangChain Integration
+
+```python
+from langchain.agents import tool
+from auditail import Auditail, rules
+
+aegis = Auditail(api_key="your_key")
+aegis.add_rule(rules.no_external_email(internal_domains=["acme.com"]))
+
+@tool
+def send_email(to: str, body: str) -> str:
+    """Send an email to a recipient."""
+    result = aegis.guard(
+        action="send_email",
+        payload={"to": to, "body": body},
+        agent_id="langchain-agent",
+    )
+    if not result.approved:
+        return f"Action blocked by Auditail: {result.reason}"
+    # ... actual send logic
+    return "Email sent."
+```
+
+## Private beta
+
+The SDK, API and dashboard are live. Guardrail rules run locally in your process; every decision is delivered in the background to a **hash-chained audit log** you can browse and verify at [app.auditail.io](https://app.auditail.io).
+
+- Batched, retried, idempotent delivery. `guard()` never waits on the network, and a delivery failure never reaches your agent.
+- Secrets are redacted before an event leaves your process (`password`, `token`, `apiKey`, ... plus your own `redact_keys`).
+- Call `aegis.flush()` before a serverless function returns or the process exits.
+
+**[Request an API key](https://auditail.io/waitlist)**: keys are issued to design partners personally.
+
+**Roadmap** (not available yet): Slack/PagerDuty alerts, human-in-the-loop approval (`require_approval` currently behaves like `block`), compliance export, private-cloud deployment.
+
+## License
+
+MIT

auditail-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+auditail/__init__.py,sha256=VXlpxXRpTZzUWEoaWTmGgdfF0ISl7X-ll3JBWlr56tk,410
+auditail/client.py,sha256=W6HAB0p6IuDvobu28KR7A1Bp_07U_YkQayMcXcexrUQ,12133
+auditail/rules.py,sha256=el41GydJj9oT19hYWF-vRj5XE_Gf93GxJa762OxnS5k,2534
+auditail/types.py,sha256=ufDyNJ8kXcyzPPItydVwjFV_sMUd3Hej58Hi7KRTzEY,1325
+auditail-0.2.0.dist-info/licenses/LICENSE,sha256=9x00mTCv_ClV0JKuyfzOwgPP3xtuN9njGmyPxjnJhOI,1065
+auditail-0.2.0.dist-info/METADATA,sha256=5dKcVWQgEr4dzFRIhm50C9Zc7KhV_7qCpY9zAa-DQ8I,3280
+auditail-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+auditail-0.2.0.dist-info/top_level.txt,sha256=s0wgs0OnwRM6cOHBLqEsz-f9n4-h4LSM1zwiR74jN_Q,9
+auditail-0.2.0.dist-info/RECORD,,

auditail-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

auditail-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Auditail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

auditail-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+auditail