admina-framework 0.9.0__py3-none-any.whl

admina/proxy/api/integration.py

@@ -0,0 +1,153 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""External integration REST endpoints.
+
+Provides a simpler REST interface for non-MCP callers:
+  POST /api/v1/validate  — validate an action payload
+  POST /api/v1/audit     — log an action result to forensic black box
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+
+logger = logging.getLogger("admina.api.integration")
+
+
+def create_integration_endpoints(
+    *,
+    get_firewall: Any,
+    get_pii_scanner: Any,
+    get_loop_breaker: Any,
+    get_forensic_box: Any,
+) -> APIRouter:
+    """Create a new APIRouter with integration endpoints.
+
+    A fresh router is created on each call for test isolation.
+
+    Args:
+        get_firewall: Callable returning the firewall checker.
+        get_pii_scanner: Callable returning the PII redactor.
+        get_loop_breaker: Callable returning the loop breaker.
+        get_forensic_box: Callable returning ForensicBlackBox | None.
+
+    Returns:
+        The configured APIRouter.
+    """
+    router = APIRouter(prefix="/api/v1", tags=["integration"])
+
+    @router.post("/validate")
+    async def validate_action(body: dict) -> dict[str, Any]:
+        """Validate an action payload through the governance pipeline.
+
+        Expects JSON body with at least ``content`` (str).  Optional:
+        ``session_id``, ``method``.
+
+        Returns ``action`` (ALLOW / BLOCK / MODIFY), ``risk_level``,
+        and per-domain ``checks``.
+        """
+        content = body.get("content", "")
+        if not content:
+            raise HTTPException(status_code=400, detail="'content' field is required")
+
+        session_id = body.get("session_id", "rest-" + uuid.uuid4().hex[:8])
+
+        start = time.perf_counter()
+        action = "ALLOW"
+        risk_level = "LOW"
+        checks: dict[str, Any] = {}
+
+        # Loop breaker
+        lb = get_loop_breaker()
+        lb_result = lb.check(session_id, content)
+        checks["loop_breaker"] = lb_result
+        if lb_result.get("is_loop"):
+            action = "BLOCK"
+            risk_level = "HIGH"
+
+        # Firewall
+        if action == "ALLOW":
+            fw = get_firewall()
+            fw_result = fw.check(content)
+            checks["firewall"] = fw_result
+            if fw_result.get("is_injection"):
+                action = "BLOCK"
+                risk_level = fw_result.get("risk_level", "HIGH")
+
+        # PII redaction
+        redacted_content = content
+        pii = get_pii_scanner()
+        pii_result = pii.redact(content)
+        checks["pii_redaction"] = {
+            "count": pii_result["count"],
+            "entities": pii_result["entities"],
+        }
+        if pii_result["count"] > 0:
+            redacted_content = pii_result["redacted_text"]
+            if action == "ALLOW":
+                action = "MODIFY"
+
+        latency_ms = round((time.perf_counter() - start) * 1000, 2)
+
+        return {
+            "action": action,
+            "risk_level": risk_level,
+            "checks": checks,
+            "redacted_content": redacted_content if action == "MODIFY" else None,
+            "latency_ms": latency_ms,
+        }
+
+    @router.post("/audit")
+    async def audit_action(body: dict) -> dict[str, Any]:
+        """Log an action result to the forensic black box.
+
+        Expects JSON body with ``event`` (dict) containing the
+        action details to record.
+
+        Returns forensic record metadata (sequence number, hash).
+        """
+        event_data = body.get("event")
+        if not event_data or not isinstance(event_data, dict):
+            raise HTTPException(
+                status_code=400,
+                detail="'event' field is required and must be a dict",
+            )
+
+        fbox = get_forensic_box()
+        if fbox is None:
+            return {
+                "recorded": False,
+                "error": "Forensic black box not available (MinIO not connected)",
+            }
+
+        event_data.setdefault("event_id", str(uuid.uuid4()))
+        event_data.setdefault("timestamp", datetime.now(UTC).isoformat())
+        event_data.setdefault("source", "api_v1_audit")
+
+        record = fbox.record(event_data)
+        return {
+            "recorded": True,
+            "sequence_number": record["sequence_number"],
+            "record_hash": record["record_hash"],
+            "previous_hash": record["previous_hash"],
+        }
+
+    return router

admina/proxy/config.py

@@ -0,0 +1,214 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Admina — Configuration & Data Models
+"""
+
+import warnings
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from admina.core.types import EventType, GovernanceAction, RiskLevel
+
+
+# ── Environment Config ──────────────────────────────────────
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # Storage
+    REDIS_URL: str = "redis://localhost:6379/0"
+    CLICKHOUSE_HOST: str = "localhost"
+    CLICKHOUSE_PORT: int = 8123
+    CLICKHOUSE_DB: str = "admina"
+    CLICKHOUSE_PASSWORD: str = ""
+    MINIO_ENDPOINT: str = "localhost:9000"
+    MINIO_ACCESS_KEY: str = "admina"
+    MINIO_SECRET_KEY: str = ""
+    MINIO_BUCKET: str = "forensic-blackbox"
+    MINIO_SECURE: bool = False
+
+    # Forensic blackbox backend selection.
+    #   "memory" (default): in-memory ledger, hashed and chained but
+    #               LOST ON RESTART. Default so the proxy never writes
+    #               files unbidden. Switch to "filesystem" or "s3" for
+    #               persistence — that's an explicit operator decision.
+    #   "filesystem": local JSON files with SHA-256 chained hashes, no
+    #               external service required. Path: FORENSIC_BASE_DIR
+    #               (must be set explicitly to opt in).
+    #   "s3":       generic S3-compatible via boto3 — works with AWS S3,
+    #               Cloudflare R2, Backblaze B2, SeaweedFS, Garage,
+    #               Ceph RGW, etc. Recommended replacement for "minio"
+    #               since the MinIO Python SDK has been archived.
+    #               Configure via FORENSIC_S3_* env vars.
+    #   "minio":    legacy MinIO SDK. Kept for backward compatibility,
+    #               will be removed in a future release.
+    FORENSIC_BACKEND: str = "memory"
+    # Empty by default — when FORENSIC_BACKEND="filesystem" the operator
+    # MUST set this. Bare-metal / k8s typical: /var/lib/admina/forensic
+    # mounted as a persistent volume.
+    FORENSIC_BASE_DIR: str = ""
+    # Generic S3 settings (used when FORENSIC_BACKEND="s3"). All
+    # standard boto3 / AWS env vars (AWS_ACCESS_KEY_ID, etc.) are also
+    # honoured if the FORENSIC_S3_* equivalents are empty.
+    FORENSIC_S3_ENDPOINT: str = ""  # e.g. http://seaweedfs:8333
+    FORENSIC_S3_REGION: str = "us-east-1"
+    FORENSIC_S3_ACCESS_KEY: str = ""
+    FORENSIC_S3_SECRET_KEY: str = ""
+    FORENSIC_S3_BUCKET: str = "forensic-blackbox"
+    # Object Lock — when "true", every forensic record written to S3 is
+    # locked in COMPLIANCE mode for FORENSIC_S3_LOCK_DAYS days. The bucket
+    # MUST have been created with ObjectLockEnabledForBucket=true (set
+    # FORENSIC_S3_LOCK_AUTO_BUCKET=true to do this automatically the
+    # first time the proxy starts and the bucket does not exist).
+    # WORM = Write Once Read Many — required for many compliance regimes
+    # (eIDAS, EU AI Act forensic evidence, FINRA, HIPAA).
+    FORENSIC_S3_LOCK: bool = False
+    FORENSIC_S3_LOCK_DAYS: int = 365 * 7  # default: 7 years
+    FORENSIC_S3_LOCK_AUTO_BUCKET: bool = False
+    # Retry / backoff for transient S3 failures (network blip, throttling).
+    FORENSIC_S3_MAX_RETRIES: int = 5
+    FORENSIC_S3_BASE_DELAY_S: float = 0.2
+
+    # Telemetry
+    OTEL_ENDPOINT: str = "http://localhost:4317"
+
+    # Proxy
+    UPSTREAM_MCP_URL: str = "http://localhost:9000"
+    LOG_LEVEL: str = "INFO"
+    CORS_ORIGINS: str = "http://localhost:3000,http://localhost:8080"
+
+    # Auth — set a strong random key in production: openssl rand -hex 32
+    # If empty, auth is disabled (local development only).
+    ADMINA_API_KEY: str = ""
+    ALLOW_UNAUTHENTICATED: bool = False
+
+    # Rate limiting (per session, requires Redis)
+    RATE_LIMIT_MAX_REQUESTS: int = 100  # requests per window
+    RATE_LIMIT_WINDOW_SECONDS: int = 60  # window in seconds
+    RATE_LIMIT_IP_MULTIPLIER: int = 5  # IP limit = session limit * this
+
+    # Governance mode — controls how the pipeline reacts to detections.
+    #   "enforce" (default, recommended for production): block flagged
+    #              requests, redact PII, raise alerts.
+    #   "observe": never block. Run the full pipeline, log every decision
+    #              with what would have happened, and let traffic through
+    #              unchanged. Ideal for the first 1-2 weeks of a new
+    #              deployment to tune thresholds without breaking users.
+    #   "dry-run": same as observe but additionally tag the response so
+    #              downstream tools know the request was analysed.
+    # Restrictive default — opt out explicitly via ADMINA_GOVERNANCE_MODE=observe.
+    GOVERNANCE_MODE: str = "enforce"
+
+    # Governance thresholds
+    LOOP_WINDOW_SIZE: int = 10
+    LOOP_SIMILARITY_THRESHOLD: float = 0.85
+    LOOP_MAX_CONSECUTIVE: int = 3
+    INJECTION_FAST_PATH_ENABLED: bool = True
+    INJECTION_DEEP_PATH_ENABLED: bool = True
+    PII_REDACTION_ENABLED: bool = True
+    MAX_REQUEST_TOKENS: int = 100000
+
+    @field_validator("GOVERNANCE_MODE")
+    @classmethod
+    def validate_governance_mode(cls, v: str) -> str:
+        v = v.lower().strip()
+        if v not in {"enforce", "observe", "dry-run", "dry_run"}:
+            raise ValueError(
+                f"GOVERNANCE_MODE must be one of: enforce | observe | dry-run (got {v!r})"
+            )
+        return "dry-run" if v == "dry_run" else v
+
+    @field_validator("FORENSIC_BACKEND")
+    @classmethod
+    def validate_forensic_backend(cls, v: str) -> str:
+        v = v.lower().strip()
+        if v not in {"memory", "filesystem", "s3", "minio"}:
+            raise ValueError(
+                f"FORENSIC_BACKEND must be 'memory' | 'filesystem' | 's3' | 'minio' (got {v!r})"
+            )
+        return v
+
+    @field_validator("CORS_ORIGINS")
+    @classmethod
+    def warn_wildcard_cors(cls, v: str) -> str:
+        origins = [o.strip() for o in v.split(",")]
+        if "*" in origins:
+            warnings.warn(
+                "CORS_ORIGINS contains '*' — this allows any domain to make "
+                "cross-origin requests to the proxy. Use specific origins in production.",
+                stacklevel=2,
+            )
+        return v
+
+    @field_validator("ADMINA_API_KEY")
+    @classmethod
+    def warn_short_api_key(cls, v: str) -> str:
+        if v and len(v) < 16:
+            warnings.warn(
+                "ADMINA_API_KEY is shorter than 16 characters — use a stronger key in production",
+                stacklevel=2,
+            )
+        return v
+
+    @field_validator("MINIO_SECRET_KEY")
+    @classmethod
+    def warn_empty_minio_secret(cls, v: str) -> str:
+        if not v:
+            warnings.warn(
+                "MINIO_SECRET_KEY is not set — forensic storage will fail. Set it in .env.",
+                stacklevel=2,
+            )
+        return v
+
+
+settings = Settings()
+
+
+# ── MCP Protocol Models ─────────────────────────────────────
+class MCPRequest(BaseModel):
+    jsonrpc: str = "2.0"
+    id: int | str | None = None
+    method: str
+    params: dict[str, Any] | None = None
+
+
+class MCPResponse(BaseModel):
+    jsonrpc: str = "2.0"
+    id: int | str | None = None
+    result: Any | None = None
+    error: dict[str, Any] | None = None
+
+
+# ── Governance Event ─────────────────────────────────────────
+class GovernanceEvent(BaseModel):
+    event_id: str
+    timestamp: str
+    event_type: EventType
+    agent_id: str = "unknown"
+    session_id: str = "unknown"
+    method: str = ""
+    tool_name: str = ""
+    action: GovernanceAction = GovernanceAction.ALLOW
+    risk_level: RiskLevel = RiskLevel.LOW
+    details: dict[str, Any] = Field(default_factory=dict)
+    latency_ms: float = 0.0
+    request_hash: str = ""
+    response_hash: str = ""

admina/proxy/engine_bridge.py

@@ -0,0 +1,306 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Admina — Hybrid Engine Bridge
+Auto-detects Rust engine, falls back to pure Python.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC
+from typing import Any, Protocol
+
+logger = logging.getLogger("admina.engine")
+
+# ── Detect Rust engine ──────────────────────────────────────
+ENGINE = "python"
+_rust_available = False
+
+try:
+    import admina_core
+
+    _rust_available = True
+    ENGINE = "rust"
+    _info = admina_core.engine_info()
+    logger.info(
+        "[RUST] Rust engine loaded: v%s — modules: %s", admina_core.version(), _info["modules"]
+    )
+except ImportError:
+    logger.info(
+        "[PYTHON] Rust engine not found, using pure Python (install admina-core for 10-100x speedup)"
+    )
+
+
+# ── Firewall Bridge ─────────────────────────────────────────
+def _load_firewall_yaml_overrides() -> tuple[list, list]:
+    """Read agent_security.firewall.{custom_patterns,disabled_categories}
+    from admina.yaml if present. Falls back to no overrides on any error.
+    Each custom pattern in YAML is `{regex, category, risk_level}`.
+    """
+    extras: list = []
+    disabled: list = []
+    try:
+        from admina.core.config import load_config
+        from admina.core.types import RiskLevel
+
+        cfg = load_config()
+        fw_cfg = (
+            cfg.raw.get("domains", {}).get("agent_security", {}).get("firewall", {})
+            if hasattr(cfg, "raw") and isinstance(cfg.raw, dict)
+            else {}
+        )
+        disabled = list(fw_cfg.get("disabled_categories") or [])
+        for entry in fw_cfg.get("custom_patterns") or []:
+            try:
+                extras.append(
+                    (
+                        entry["regex"],
+                        entry.get("category", "user_custom"),
+                        RiskLevel(entry.get("risk_level", "medium").lower()),
+                    )
+                )
+            except (KeyError, ValueError, TypeError) as exc:
+                logger.warning("Skipping malformed custom_pattern %r: %s", entry, exc)
+    except (ImportError, AttributeError, OSError):
+        pass
+    return extras, disabled
+
+
+class _PythonFirewallBridge:
+    """Wraps the existing Python InjectionFirewall with a compatible interface."""
+
+    def __init__(self):
+        from admina.domains.agent_security.firewall import InjectionFirewall
+
+        extras, disabled = _load_firewall_yaml_overrides()
+        if extras or disabled:
+            logger.info(
+                "Loaded %d custom firewall pattern(s); disabled: %s",
+                len(extras),
+                disabled or "(none)",
+            )
+        self._impl = InjectionFirewall(
+            extra_patterns=extras or None,
+            disabled_categories=disabled or None,
+        )
+
+    def check(self, text: str) -> dict:
+        return self._impl.check(text)
+
+    def get_stats(self) -> dict:
+        stats = self._impl.get_stats()
+        stats["engine"] = "python"
+        return stats
+
+
+class _RustFirewallBridge:
+    """Wraps Rust RustFirewall, returns dicts for compatibility."""
+
+    def __init__(self):
+        self._impl = admina_core.RustFirewall()
+
+    def check(self, text: str) -> dict:
+        result = self._impl.check(text)
+        return {
+            "is_injection": result.is_injection,
+            "risk_level": result.risk_level,
+            "matched_patterns": result.matched_patterns,
+            "heuristic_score": result.heuristic_score,
+            "heuristic_signals": result.heuristic_signals,
+        }
+
+    def get_stats(self) -> dict:
+        return self._impl.get_stats()
+
+
+# ── PII Scanner Bridge ──────────────────────────────────────
+class _PythonPiiBridge:
+    def __init__(self):
+        from admina.domains.data_sovereignty.pii import PIIRedactor
+
+        self._impl = PIIRedactor()
+
+    def redact(self, text: str) -> dict:
+        return self._impl.redact(text)
+
+    def get_stats(self) -> dict:
+        stats = self._impl.get_stats()
+        stats["engine"] = "python"
+        return stats
+
+
+class _RustPiiBridge:
+    def __init__(self):
+        self._impl = admina_core.RustPiiScanner()
+
+    def redact(self, text: str) -> dict:
+        result = self._impl.redact(text)
+        return {
+            "redacted_text": result.redacted_text,
+            "count": result.count,
+            "categories": result.categories,
+            "entities": [{"type": cat, "method": "rust_regex"} for cat in result.categories],
+        }
+
+    def get_stats(self) -> dict:
+        return self._impl.get_stats()
+
+
+# ── Loop Breaker Bridge ─────────────────────────────────────
+class _PythonLoopBridge:
+    def __init__(self, **kwargs):
+        from admina.domains.agent_security.loop_breaker import LoopBreaker
+
+        self._impl = LoopBreaker(**kwargs)
+
+    def check(self, session_id: str, content: str) -> dict:
+        return self._impl.check(session_id, content)
+
+    def get_stats(self) -> dict:
+        stats = self._impl.get_stats()
+        stats["engine"] = "python"
+        return stats
+
+
+class _RustLoopBridge:
+    def __init__(self, window_size=10, similarity_threshold=0.85, max_consecutive=3, **kwargs):
+        self._impl = admina_core.RustLoopBreaker(
+            window_size=window_size,
+            similarity_threshold=similarity_threshold,
+            max_consecutive=max_consecutive,
+        )
+
+    def check(self, session_id: str, content: str) -> dict:
+        return self._impl.check(session_id, content)
+
+    def get_stats(self) -> dict:
+        return self._impl.get_stats()
+
+
+# ── Hash Chain Bridge ────────────────────────────────────────
+class _PythonHashChainBridge:
+    def __init__(self):
+        # Minimal Python fallback
+        self._prev = "genesis"
+        self._seq = 0
+        self._total = 0
+
+    def record(self, event_id: str, data: str) -> dict:
+        import hashlib
+        from datetime import datetime
+
+        self._seq += 1
+        self._total += 1
+        now = datetime.now(UTC)
+        hash_input = f"{self._seq}:{self._prev}:{event_id}:{data}:{int(now.timestamp() * 1000)}"
+        h = hashlib.sha256(hash_input.encode()).hexdigest()
+        prev = self._prev
+        self._prev = h
+        return {
+            "hash": h,
+            "previous_hash": prev,
+            "sequence": self._seq,
+            "event_id": event_id,
+            "timestamp_iso": now.isoformat(),
+            "timestamp_ms": int(now.timestamp() * 1000),
+            "engine": "python",
+        }
+
+    def get_stats(self) -> dict:
+        return {"total_records": self._total, "current_sequence": self._seq, "engine": "python"}
+
+
+class _RustHashChainBridge:
+    def __init__(self):
+        self._impl = admina_core.RustHashChain()
+
+    def record(self, event_id: str, data: str) -> dict:
+        return self._impl.record(event_id, data)
+
+    def verify_chain(self, chain: list) -> dict[str, Any]:
+        return self._impl.verify_chain(chain)
+
+    def get_stats(self) -> dict:
+        return self._impl.get_stats()
+
+
+# ── Bridge Protocols ────────────────────────────────────────
+
+
+class FirewallBridge(Protocol):
+    """Protocol for firewall bridge implementations."""
+
+    def check(self, text: str) -> dict[str, Any]: ...
+    def get_stats(self) -> dict[str, Any]: ...
+
+
+class PIIBridge(Protocol):
+    """Protocol for PII scanner bridge implementations."""
+
+    def redact(self, text: str) -> dict[str, Any]: ...
+    def get_stats(self) -> dict[str, Any]: ...
+
+
+class LoopBreakerBridge(Protocol):
+    """Protocol for loop breaker bridge implementations."""
+
+    def check(self, session_id: str, content: str) -> dict[str, Any]: ...
+    def get_stats(self) -> dict[str, Any]: ...
+
+
+class HashChainBridge(Protocol):
+    """Protocol for hash chain bridge implementations."""
+
+    def record(self, event_id: str, data: str) -> dict[str, Any]: ...
+    def get_stats(self) -> dict[str, Any]: ...
+
+
+# ── Factory Functions ────────────────────────────────────────
+def get_firewall() -> FirewallBridge:
+    """Get the best available firewall engine."""
+    if _rust_available:
+        return _RustFirewallBridge()
+    return _PythonFirewallBridge()
+
+
+def get_pii_scanner() -> PIIBridge:
+    """Get the best available PII scanner."""
+    if _rust_available:
+        return _RustPiiBridge()
+    return _PythonPiiBridge()
+
+
+def get_loop_breaker(**kwargs: Any) -> LoopBreakerBridge:
+    """Get the best available loop breaker."""
+    if _rust_available:
+        return _RustLoopBridge(**kwargs)
+    return _PythonLoopBridge(**kwargs)
+
+
+def get_hash_chain() -> HashChainBridge:
+    """Get the best available hash chain."""
+    if _rust_available:
+        return _RustHashChainBridge()
+    return _PythonHashChainBridge()
+
+
+def engine_status() -> dict[str, Any]:
+    """Get engine status for diagnostics."""
+    return {
+        "engine": ENGINE,
+        "rust_available": _rust_available,
+        "rust_version": admina_core.version() if _rust_available else None,
+    }