sentinelgate-core 0.1.0__py3-none-any.whl

sentinelgate/__init__.py

@@ -0,0 +1,55 @@
+# Copyright 2024 SentinelGate Contributors
+# Licensed under the Apache License, Version 2.0
+
+"""
+SentinelGate - Security enforcement layer for agentic AI applications.
+
+Your agent decides. SentinelGate authorizes.
+"""
+
+from __future__ import annotations
+
+from sentinelgate.exceptions import (
+    ApprovalDenied,
+    ApprovalRequired,
+    AuthorizationError,
+    PolicyError,
+    PolicyLoadError,
+    PolicyValidationError,
+    SecurityViolation,
+    SentinelGateError,
+)
+from sentinelgate.gateway import SecurityGateway
+from sentinelgate.types import (
+    DecisionAction,
+    PolicyViolation,
+    RiskLevel,
+    SecurityDecision,
+    SecurityEvent,
+    ToolRequest,
+    TrustLevel,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main entry point
+    "SecurityGateway",
+    # Types
+    "DecisionAction",
+    "PolicyViolation",
+    "RiskLevel",
+    "SecurityDecision",
+    "SecurityEvent",
+    "ToolRequest",
+    "TrustLevel",
+    # Exceptions
+    "ApprovalDenied",
+    "ApprovalRequired",
+    "AuthorizationError",
+    "PolicyError",
+    "PolicyLoadError",
+    "PolicyValidationError",
+    "SecurityViolation",
+    "SentinelGateError",
+]

sentinelgate/approval/__init__.py

@@ -0,0 +1,20 @@
+# Copyright 2024 SentinelGate Contributors
+# Licensed under the Apache License, Version 2.0
+
+"""Human-in-the-loop approval handlers."""
+
+from sentinelgate.approval.handler import (
+    ApprovalHandler,
+    AutoApproveHandler,
+    AutoDenyHandler,
+    CallbackApprovalHandler,
+    ConsoleApprovalHandler,
+)
+
+__all__ = [
+    "ApprovalHandler",
+    "AutoApproveHandler",
+    "AutoDenyHandler",
+    "CallbackApprovalHandler",
+    "ConsoleApprovalHandler",
+]

sentinelgate/approval/handler.py

@@ -0,0 +1,215 @@
+# Copyright 2024 SentinelGate Contributors
+# Licensed under the Apache License, Version 2.0
+
+"""Pluggable human-in-the-loop approval handlers.
+
+Usage:
+    from sentinelgate.approval import ConsoleApprovalHandler, CallbackApprovalHandler
+
+    # Interactive CLI approval
+    handler = ConsoleApprovalHandler()
+
+    # Custom callback approval
+    handler = CallbackApprovalHandler(my_approval_function)
+
+    # Auto-approve for development (logs a warning)
+    handler = AutoApproveHandler()
+
+    # Auto-deny for testing
+    handler = AutoDenyHandler()
+"""
+
+from __future__ import annotations
+
+import sys
+import warnings
+from collections.abc import Callable
+
+from sentinelgate.types import ApprovalResult, SecurityEvent
+
+
+class ApprovalHandler:
+    """Base class for approval handlers.
+
+    Subclass this to implement custom approval workflows
+    (Slack, email, webhook, dashboard, etc.).
+    """
+
+    def request_approval(self, event: SecurityEvent) -> ApprovalResult:
+        """Request human approval for a security event.
+
+        Args:
+            event: The security event requiring approval.
+
+        Returns:
+            An ApprovalResult indicating whether the action was approved.
+        """
+        raise NotImplementedError("Subclasses must implement request_approval()")
+
+    def _format_event_summary(self, event: SecurityEvent) -> str:
+        """Format a security event into a human-readable summary."""
+        lines = [
+            "--- SentinelGate Approval Request ---",
+            f"Agent:    {event.actor}",
+            f"Action:   {event.action}",
+            f"Resource: {event.resource}",
+        ]
+
+        if event.arguments:
+            lines.append("Arguments:")
+            for key, value in event.arguments.items():
+                val_str = str(value)
+                if len(val_str) > 100:
+                    val_str = val_str[:100] + "..."
+                lines.append(f"  {key}: {val_str}")
+
+        if event.decision:
+            lines.append(f"Risk Score: {event.decision.risk_score:.1f}")
+            lines.append(f"Risk Level: {event.decision.risk_level.value}")
+            if event.decision.reason:
+                lines.append(f"Reason: {event.decision.reason}")
+
+        lines.append("-" * 40)
+        return "\n".join(lines)
+
+
+class ConsoleApprovalHandler(ApprovalHandler):
+    """Interactive CLI approval handler.
+
+    Displays the security event details and prompts for
+    approval via stdin.
+    """
+
+    def request_approval(self, event: SecurityEvent) -> ApprovalResult:
+        """Prompt for approval via the console.
+
+        Args:
+            event: The security event requiring approval.
+
+        Returns:
+            An ApprovalResult based on user input.
+        """
+        summary = self._format_event_summary(event)
+        print("\n" + summary, file=sys.stderr)
+
+        try:
+            response = input("Approve this action? [y/N]: ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            print("\nApproval denied (no input).", file=sys.stderr)
+            return ApprovalResult(
+                approved=False,
+                approver="console",
+                reason="No input received",
+            )
+
+        approved = response in ("y", "yes")
+
+        reason = ""
+        if not approved and response not in ("n", "no", ""):
+            reason = response
+
+        return ApprovalResult(
+            approved=approved,
+            approver="console",
+            reason=reason or ("Approved by user" if approved else "Denied by user"),
+        )
+
+
+class CallbackApprovalHandler(ApprovalHandler):
+    """Approval handler that delegates to a callback function.
+
+    The callback receives the SecurityEvent and must return
+    an ApprovalResult or a bool.
+    """
+
+    def __init__(self, callback: Callable[[SecurityEvent], ApprovalResult | bool]) -> None:
+        """Initialize with a callback function.
+
+        Args:
+            callback: A function that takes a SecurityEvent and returns
+                either an ApprovalResult or a bool.
+        """
+        if not callable(callback):
+            raise TypeError("callback must be callable")
+        self._callback = callback
+
+    def request_approval(self, event: SecurityEvent) -> ApprovalResult:
+        """Delegate approval to the callback.
+
+        Args:
+            event: The security event requiring approval.
+
+        Returns:
+            An ApprovalResult.
+        """
+        result = self._callback(event)
+
+        if isinstance(result, ApprovalResult):
+            return result
+
+        if isinstance(result, bool):
+            return ApprovalResult(
+                approved=result,
+                approver="callback",
+                reason="Approved by callback" if result else "Denied by callback",
+            )
+
+        # Try to interpret as truthy/falsy
+        return ApprovalResult(
+            approved=bool(result),
+            approver="callback",
+            reason=f"Callback returned: {type(result).__name__}",
+        )
+
+
+class AutoApproveHandler(ApprovalHandler):
+    """Auto-approve handler for development environments.
+
+    Automatically approves all requests with a warning.
+    Do not use in production.
+    """
+
+    def __init__(self) -> None:
+        warnings.warn(
+            "AutoApproveHandler is enabled. All approval requests will be "
+            "automatically approved. Do not use this in production.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    def request_approval(self, event: SecurityEvent) -> ApprovalResult:
+        """Auto-approve the request.
+
+        Args:
+            event: The security event (ignored).
+
+        Returns:
+            An approved ApprovalResult.
+        """
+        return ApprovalResult(
+            approved=True,
+            approver="auto_approve",
+            reason="Automatically approved (development mode)",
+        )
+
+
+class AutoDenyHandler(ApprovalHandler):
+    """Auto-deny handler for testing environments.
+
+    Automatically denies all approval requests.
+    """
+
+    def request_approval(self, event: SecurityEvent) -> ApprovalResult:
+        """Auto-deny the request.
+
+        Args:
+            event: The security event (ignored).
+
+        Returns:
+            A denied ApprovalResult.
+        """
+        return ApprovalResult(
+            approved=False,
+            approver="auto_deny",
+            reason="Automatically denied (testing mode)",
+        )

sentinelgate/audit/__init__.py

@@ -0,0 +1,9 @@
+# Copyright 2024 SentinelGate Contributors
+# Licensed under the Apache License, Version 2.0
+
+"""Audit and security logging."""
+
+from sentinelgate.audit.exporters import CallbackExporter, ConsoleExporter, JSONFileExporter
+from sentinelgate.audit.logger import AuditLogger
+
+__all__ = ["AuditLogger", "ConsoleExporter", "JSONFileExporter", "CallbackExporter"]

sentinelgate/audit/exporters.py

@@ -0,0 +1,131 @@
+# Copyright 2024 SentinelGate Contributors
+# Licensed under the Apache License, Version 2.0
+
+"""Audit event exporters."""
+
+from __future__ import annotations
+
+import json
+import sys
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import TextIO
+
+from sentinelgate.types import SecurityEvent
+
+
+class BaseExporter:
+    """Base class for audit event exporters."""
+
+    def export(self, event: SecurityEvent) -> None:
+        """Export a security event.
+
+        Args:
+            event: The security event to export.
+        """
+        raise NotImplementedError("Subclasses must implement export()")
+
+
+class ConsoleExporter(BaseExporter):
+    """Exports security events to the console with formatting."""
+
+    # Terminal colors (ANSI codes)
+    COLORS = {
+        "allow": "\033[92m",   # green
+        "deny": "\033[91m",    # red
+        "review": "\033[93m",  # yellow
+        "redact": "\033[94m",  # blue
+        "reset": "\033[0m",
+    }
+
+    def __init__(
+        self,
+        stream: TextIO | None = None,
+        use_color: bool = True,
+        verbose: bool = False,
+    ) -> None:
+        """Initialize the console exporter.
+
+        Args:
+            stream: Output stream. Defaults to stderr.
+            use_color: Whether to use ANSI colors.
+            verbose: Whether to include full event details.
+        """
+        self._stream = stream or sys.stderr
+        self._use_color = use_color and hasattr(self._stream, "isatty") and self._stream.isatty()
+        self._verbose = verbose
+
+    def export(self, event: SecurityEvent) -> None:
+        """Export a security event to the console."""
+        action_str = "UNKNOWN"
+        if event.decision:
+            action_str = event.decision.action.value.upper()
+
+        # Format the line
+        if self._use_color:
+            color = self.COLORS.get(action_str.lower(), self.COLORS["reset"])
+            reset = self.COLORS["reset"]
+        else:
+            color = ""
+            reset = ""
+
+        line = f"[SentinelGate] {color}{action_str.ljust(6)}{reset} | {event.actor} | {event.action} | {event.resource}"
+
+        if event.decision and event.decision.reason:
+            line += f" | {event.decision.reason}"
+
+        print(line, file=self._stream)
+
+        if self._verbose and event.arguments:
+            args_str = json.dumps(event.arguments, default=str)
+            if len(args_str) > 200:
+                args_str = args_str[:200] + "..."
+            print(f"  Arguments: {args_str}", file=self._stream)
+
+
+class JSONFileExporter(BaseExporter):
+    """Exports security events to a JSON Lines file."""
+
+    def __init__(self, filepath: str, flush_every: int = 1) -> None:
+        """Initialize the JSON file exporter.
+
+        Args:
+            filepath: Path to the output file.
+            flush_every: Flush after this many events.
+        """
+        self._filepath = Path(filepath)
+        self._flush_every = flush_every
+        self._count = 0
+        self._lock = threading.Lock()
+
+        # Ensure parent directory exists
+        self._filepath.parent.mkdir(parents=True, exist_ok=True)
+
+    def export(self, event: SecurityEvent) -> None:
+        """Export a security event to the JSON lines file."""
+        with self._lock, open(self._filepath, "a", encoding="utf-8") as f:
+            json_line = json.dumps(event.to_dict(), default=str)
+            f.write(json_line + "\n")
+
+            self._count += 1
+            if self._count % self._flush_every == 0:
+                f.flush()
+
+
+class CallbackExporter(BaseExporter):
+    """Exports security events via a callback function."""
+
+    def __init__(self, callback: Callable[[SecurityEvent], None]) -> None:
+        """Initialize with a callback function.
+
+        Args:
+            callback: Function to call for each event.
+        """
+        if not callable(callback):
+            raise TypeError("callback must be callable")
+        self._callback = callback
+
+    def export(self, event: SecurityEvent) -> None:
+        """Export a security event via the callback."""
+        self._callback(event)

sentinelgate/audit/logger.py

@@ -0,0 +1,156 @@
+# Copyright 2024 SentinelGate Contributors
+# Licensed under the Apache License, Version 2.0
+
+"""Structured audit logger for security events."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import threading
+from typing import Any
+
+from sentinelgate.audit.exporters import BaseExporter
+from sentinelgate.types import SecurityDecision, SecurityEvent
+
+
+class AuditLogger:
+    """Thread-safe structured audit logger.
+
+    Records all security decisions and events for compliance,
+    debugging, and forensic analysis.
+    """
+
+    def __init__(
+        self,
+        exporters: list[BaseExporter] | None = None,
+        max_buffer_size: int = 1000,
+    ) -> None:
+        """Initialize the audit logger.
+
+        Args:
+            exporters: List of exporters for writing events.
+                Defaults to ConsoleExporter if none provided.
+            max_buffer_size: Maximum events to keep in memory.
+        """
+        self._exporters = exporters or []
+        self._buffer: list[SecurityEvent] = []
+        self._max_buffer_size = max_buffer_size
+        self._lock = threading.Lock()
+
+    def log_event(self, event: SecurityEvent) -> None:
+        """Log a security event.
+
+        Args:
+            event: The SecurityEvent to record.
+        """
+        with self._lock:
+            self._buffer.append(event)
+            if len(self._buffer) > self._max_buffer_size:
+                self._buffer.pop(0)
+
+        # Export to all configured exporters
+        for exporter in self._exporters:
+            with contextlib.suppress(Exception):
+                exporter.export(event)
+
+    def log_decision(
+        self,
+        actor: str,
+        action: str,
+        resource: str,
+        decision: SecurityDecision,
+        arguments: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> SecurityEvent:
+        """Log a security decision as an event.
+
+        Args:
+            actor: The agent making the request.
+            action: The action being performed.
+            resource: The resource being accessed.
+            decision: The security decision.
+            arguments: Optional tool arguments.
+            context: Optional additional context.
+
+        Returns:
+            The created SecurityEvent.
+        """
+        event = SecurityEvent(
+            actor=actor,
+            action=action,
+            resource=resource,
+            arguments=arguments or {},
+            decision=decision,
+            context=context or {},
+        )
+
+        self.log_event(event)
+        return event
+
+    def get_events(
+        self,
+        limit: int = 100,
+        actor: str | None = None,
+        action: str | None = None,
+        allowed_only: bool | None = None,
+    ) -> list[SecurityEvent]:
+        """Retrieve logged events with optional filtering.
+
+        Args:
+            limit: Maximum number of events to return.
+            actor: Filter by actor name.
+            action: Filter by action.
+            allowed_only: Filter by decision (True=allowed, False=denied).
+
+        Returns:
+            List of matching SecurityEvent objects.
+        """
+        with self._lock:
+            events = list(self._buffer)
+
+        # Apply filters
+        if actor:
+            events = [e for e in events if e.actor == actor]
+        if action:
+            events = [e for e in events if e.action == action]
+        if allowed_only is not None:
+            events = [
+                e for e in events
+                if e.decision is not None and e.decision.allowed == allowed_only
+            ]
+
+        # Return most recent events
+        return events[-limit:]
+
+    def get_violations(self, limit: int = 100) -> list[SecurityEvent]:
+        """Get events that were denied or had violations.
+
+        Args:
+            limit: Maximum number of events to return.
+
+        Returns:
+            List of denied/violated SecurityEvent objects.
+        """
+        return self.get_events(limit=limit, allowed_only=False)
+
+    def export_json(self, limit: int = 100) -> str:
+        """Export events as a JSON string.
+
+        Args:
+            limit: Maximum number of events to export.
+
+        Returns:
+            JSON string of events.
+        """
+        events = self.get_events(limit=limit)
+        return json.dumps(
+            [e.to_dict() for e in events],
+            indent=2,
+            default=str,
+        )
+
+    def clear(self) -> None:
+        """Clear all buffered events."""
+        with self._lock:
+            self._buffer.clear()

sentinelgate/authorization/__init__.py

@@ -0,0 +1,10 @@
+# Copyright 2024 SentinelGate Contributors
+# Licensed under the Apache License, Version 2.0
+
+"""Tool authorization components."""
+
+from sentinelgate.authorization.argument_validator import ArgumentValidator
+from sentinelgate.authorization.permissions import PermissionResolver
+from sentinelgate.authorization.tool_auth import ToolAuthorizer
+
+__all__ = ["ToolAuthorizer", "ArgumentValidator", "PermissionResolver"]