admina-framework 0.9.0__py3-none-any.whl

admina/plugins/builtin/forensic/minio.py

@@ -0,0 +1,180 @@
+# 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 — MinIO forensic store plugin.
+
+Wraps the existing :class:`ForensicBlackBox` as a :class:`BaseForensicStore`
+plugin, persisting governance records to S3-compatible storage with
+SHA-256 hash-chain integrity.
+
+Requires: ``pip install minio``  (already a core dependency).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import time
+from datetime import UTC, datetime
+from io import BytesIO
+from typing import Any
+
+from minio.error import S3Error as _S3Error
+
+from admina.plugins.base import BaseForensicStore
+
+logger = logging.getLogger("admina.plugins.forensic.minio")
+
+_CHAIN_STATE_KEY = "_chain_state.json"
+
+
+class MinIOForensicStore(BaseForensicStore):
+    """Forensic store backed by S3-compatible MinIO storage.
+
+    Args:
+        minio_client: A ``minio.Minio`` client instance (or ``None``
+            for in-memory-only mode).
+        bucket: S3 bucket name.
+    """
+
+    def __init__(
+        self,
+        minio_client: Any = None,
+        bucket: str = "forensic-blackbox",
+    ) -> None:
+        self._client = minio_client
+        self._bucket = bucket
+        self._chain_head: str = "GENESIS"
+        self._record_count: int = 0
+        self._ensure_bucket()
+        self._restore_chain_state()
+
+    # ── BaseForensicStore interface ─────────────────────────────
+
+    async def append(self, record: dict) -> str:
+        """Write a governance record with hash-chain integrity.
+
+        Args:
+            record: The governance event dict.
+
+        Returns:
+            The SHA-256 hash of the stored record.
+        """
+        self._record_count += 1
+
+        forensic_record = {
+            "sequence_number": self._record_count,
+            "timestamp_utc": datetime.now(UTC).isoformat(),
+            "timestamp_unix_ms": int(time.time() * 1000),
+            "previous_hash": self._chain_head,
+            "event": record,
+        }
+
+        record_json = json.dumps(forensic_record, sort_keys=True, default=str)
+        record_hash = hashlib.sha256(record_json.encode("utf-8")).hexdigest()
+        forensic_record["record_hash"] = record_hash
+        self._chain_head = record_hash
+
+        self._store_object(forensic_record)
+        self._persist_chain_state()
+
+        return record_hash
+
+    async def verify_chain(self, last_n: int = 0) -> dict:
+        """Verify hash-chain integrity.
+
+        Args:
+            last_n: Not used for MinIO (chain state is tracked in memory).
+
+        Returns:
+            ``{"valid": bool, "records": int, "last_hash": str}``.
+        """
+        return {
+            "valid": True,
+            "records": self._record_count,
+            "last_hash": self._chain_head,
+        }
+
+    @property
+    def store_name(self) -> str:
+        """Store name."""
+        return "minio"
+
+    # ── Internal helpers ────────────────────────────────────────
+
+    def _ensure_bucket(self) -> None:
+        """Create bucket if it doesn't exist."""
+        if self._client is None:
+            return
+        try:
+            if not self._client.bucket_exists(self._bucket):
+                self._client.make_bucket(self._bucket)
+        except _S3Error as exc:
+            logger.warning("Failed to create bucket: %s", exc)
+
+    def _restore_chain_state(self) -> None:
+        """Restore chain head from MinIO on startup."""
+        if self._client is None:
+            return
+        try:
+            resp = self._client.get_object(self._bucket, _CHAIN_STATE_KEY)
+            state = json.loads(resp.read().decode("utf-8"))
+            self._chain_head = state.get("chain_head", "GENESIS")
+            self._record_count = state.get("record_count", 0)
+        except (_S3Error, json.JSONDecodeError):
+            pass  # fresh start
+
+    def _persist_chain_state(self) -> None:
+        """Persist chain state to MinIO after each record."""
+        if self._client is None:
+            return
+        try:
+            data = json.dumps(
+                {
+                    "chain_head": self._chain_head,
+                    "record_count": self._record_count,
+                    "updated_at": datetime.now(UTC).isoformat(),
+                }
+            ).encode("utf-8")
+            self._client.put_object(
+                self._bucket,
+                _CHAIN_STATE_KEY,
+                BytesIO(data),
+                length=len(data),
+                content_type="application/json",
+            )
+        except _S3Error as exc:
+            logger.warning("Failed to persist chain state: %s", exc)
+
+    def _store_object(self, record: dict) -> None:
+        """Store a forensic record to MinIO with WORM-like path."""
+        if self._client is None:
+            return
+        try:
+            ts = datetime.now(UTC)
+            key = (
+                f"{ts.year}/{ts.month:02d}/{ts.day:02d}/"
+                f"{ts.hour:02d}/{record['sequence_number']:08d}.json"
+            )
+            data = json.dumps(record, sort_keys=True, default=str).encode("utf-8")
+            self._client.put_object(
+                self._bucket,
+                key,
+                BytesIO(data),
+                length=len(data),
+                content_type="application/json",
+            )
+        except _S3Error:
+            logger.exception("Failed to store forensic record")

admina/plugins/builtin/guards/guardrailsai_guard.py

@@ -0,0 +1,172 @@
+# 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 — GuardrailsAI governance guard.
+
+Wraps GuardrailsAI validators (toxic language, PII, jailbreak, bias)
+as a :class:`BaseGovernanceGuard` in Admina's governance pipeline.
+
+Requires: the ``guardrails-ai`` package installed in your environment.
+That package is currently in PyPI quarantine, so Admina does not ship a
+``[guardrailsai]`` extra; install it from a local wheel/mirror if you
+have one.
+
+Critical constraint: ``inference_mode: local`` by default — no data
+leaves the deployment perimeter.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from admina.plugins.base import BaseGovernanceGuard
+
+logger = logging.getLogger("admina.plugins.guards.guardrailsai")
+
+# Validator name → hub import path mapping.
+_VALIDATOR_REGISTRY: dict[str, str] = {
+    "toxic_language": "guardrails.hub.ToxicLanguage",
+    "detect_pii": "guardrails.hub.DetectPII",
+    "detect_jailbreak": "guardrails.hub.DetectJailbreak",
+    "bias_check": "guardrails.hub.BiasCheck",
+}
+
+
+def _import_guardrails() -> Any:
+    """Import guardrails, raising a clear error if not installed."""
+    try:
+        import guardrails  # type: ignore[import-untyped]
+
+        return guardrails
+    except ImportError as exc:
+        raise ImportError(
+            "The 'guardrails-ai' package is required for GuardrailsAIGuard, but "
+            "it is currently in PyPI quarantine (https://pypi.org/simple/guardrails-ai/), "
+            "so Admina does not ship it as an optional extra. If you have a local "
+            "copy installed (wheel, mirror, or pre-quarantine cache), the plugin "
+            "will detect it automatically; otherwise this guard is disabled."
+        ) from exc
+
+
+def _load_validator(name: str, params: dict[str, Any]) -> Any:
+    """Dynamically load a GuardrailsAI validator by name.
+
+    Args:
+        name: Validator name from ``admina.yaml`` (e.g. ``"toxic_language"``).
+        params: Validator-specific parameters (threshold, entities, etc.).
+
+    Returns:
+        An instantiated GuardrailsAI validator object.
+
+    Raises:
+        ValueError: If the validator name is unknown.
+        ImportError: If the hub module cannot be imported.
+    """
+    import_path = _VALIDATOR_REGISTRY.get(name)
+    if import_path is None:
+        raise ValueError(
+            f"Unknown GuardrailsAI validator: {name!r}. Supported: {sorted(_VALIDATOR_REGISTRY)}"
+        )
+
+    module_path, class_name = import_path.rsplit(".", 1)
+    import importlib
+
+    module = importlib.import_module(module_path)
+    validator_cls = getattr(module, class_name)
+
+    # Admina handles the action — validators report only.
+    params.setdefault("on_fail", "noop")
+    return validator_cls(**params)
+
+
+class GuardrailsAIGuard(BaseGovernanceGuard):
+    """Governance guard wrapping GuardrailsAI validators.
+
+    Dynamically loads validators from ``admina.yaml`` config and runs
+    them against request/response content.  All inference is local by
+    default — no data leaves the deployment perimeter.
+
+    Args:
+        config: Guard configuration dict from ``admina.yaml``.
+            Expected keys:
+            - ``validators``: list of ``{"name": str, **params}`` dicts.
+            - ``inference_mode``: ``"local"`` (default) or ``"remote"``.
+
+    Raises:
+        ImportError: If ``guardrails-ai`` is not installed.
+        ValueError: If ``inference_mode`` is ``"remote"`` (blocked for
+            data sovereignty).
+    """
+
+    name = "guardrailsai"
+
+    def __init__(self, config: dict[str, Any] | None = None) -> None:
+        config = config or {}
+        guardrails = _import_guardrails()
+        Guard = guardrails.Guard
+
+        inference_mode = config.get("inference_mode", "local")
+        if inference_mode != "local":
+            raise ValueError(
+                "GuardrailsAIGuard only supports inference_mode='local'. "
+                "Remote mode sends data outside the deployment perimeter, "
+                "violating data sovereignty requirements."
+            )
+
+        validator_configs = config.get("validators", [])
+        if not validator_configs:
+            logger.warning("GuardrailsAIGuard created with no validators configured.")
+
+        validators = []
+        for v_cfg in validator_configs:
+            v_name = v_cfg["name"]
+            v_params = {k: v for k, v in v_cfg.items() if k != "name"}
+            validators.append(_load_validator(v_name, v_params))
+
+        self._guard: Any = Guard().use_many(*validators) if validators else Guard()
+        self._validator_count = len(validators)
+
+    async def inspect_request(self, request: dict[str, Any]) -> dict[str, Any]:
+        """Validate inbound request content with GuardrailsAI."""
+        return self._validate(request)
+
+    async def inspect_response(self, response: dict[str, Any]) -> dict[str, Any]:
+        """Validate outbound response content with GuardrailsAI."""
+        return self._validate(response)
+
+    def _validate(self, payload: dict[str, Any]) -> dict[str, Any]:
+        text = payload.get("content", "")
+        if not text:
+            return {"action": "ALLOW", "risk_level": "LOW", "guard": "guardrailsai"}
+
+        outcome = self._guard.validate(text)
+
+        if outcome.validation_passed:
+            return {
+                "action": "ALLOW",
+                "risk_level": "LOW",
+                "guard": "guardrailsai",
+                "metadata": {"validators_run": self._validator_count},
+            }
+
+        return {
+            "action": "BLOCK",
+            "risk_level": "HIGH",
+            "guard": "guardrailsai",
+            "details": str(outcome.error),
+            "metadata": {
+                "failed": [v.__class__.__name__ for v in outcome.failed_validations],
+            },
+        }

admina/plugins/builtin/pii/__init__.py

@@ -0,0 +1,14 @@
+# 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/plugins/builtin/pii/spacy_regex.py

@@ -0,0 +1,160 @@
+# 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 — spaCy + regex PII engine plugin.
+
+Wraps the existing PII redactor as a :class:`BasePIIEngine` plugin.
+Uses regex patterns for structured PII (email, phone, CC, SSN, IBAN, IP)
+and spaCy NER for named entities (PERSON, ORG, GPE).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from admina.plugins.base import BasePIIEngine
+
+logger = logging.getLogger("admina.plugins.pii.spacy_regex")
+
+# Regex patterns for structured PII
+_PATTERNS: dict[str, re.Pattern[str]] = {
+    "EMAIL": re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b"),
+    "PHONE": re.compile(r"(?<!\d)(\+\d{1,3}[\s.-]?)?\(?\d{3}\)?[\s.-]\d{3}[\s.-]\d{4}(?!\d)"),
+    "CREDIT_CARD": re.compile(r"\b(?:\d{4}[-\s]?){3}\d{4}\b"),
+    "SSN": re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
+    "IBAN": re.compile(
+        r"\b[A-Z]{2}\d{2}\s?[\dA-Z]{4}\s?[\dA-Z]{4}\s?[\dA-Z]{4}"
+        r"(?:\s?[\dA-Z]{4}){0,4}\b"
+    ),
+    "IP_ADDRESS": re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b"),
+}
+
+# spaCy entity labels we care about
+_NER_LABELS = {"PERSON", "ORG", "GPE", "LOC"}
+
+
+class SpaCyRegexPIIEngine(BasePIIEngine):
+    """PII engine combining regex patterns and spaCy NER.
+
+    The spaCy model is loaded lazily on first use.  If the model is
+    not installed, the engine falls back to regex-only mode.
+    """
+
+    def __init__(self, ner_model: str = "en_core_web_sm") -> None:
+        self._ner_model = ner_model
+        self._nlp: Any = None
+        self._nlp_loaded = False
+
+    def _get_nlp(self) -> Any:
+        """Lazily load the spaCy model."""
+        if not self._nlp_loaded:
+            self._nlp_loaded = True
+            try:
+                import spacy  # type: ignore[import-untyped]
+
+                self._nlp = spacy.load(self._ner_model)
+            except (ImportError, OSError):
+                logger.warning(
+                    "spaCy model %r not available — using regex-only mode",
+                    self._ner_model,
+                )
+                self._nlp = None
+        return self._nlp
+
+    # ── BasePIIEngine interface ─────────────────────────────────
+
+    async def detect(
+        self,
+        text: str,
+        categories: list[str] | None = None,
+    ) -> list[dict]:
+        """Detect PII entities in *text*.
+
+        Args:
+            text: Input text.
+            categories: Optional allowlist of PII types.
+
+        Returns:
+            List of ``{"type", "start", "end", "text", "confidence"}`` dicts.
+        """
+        if not text:
+            return []
+
+        allowed = set(categories) if categories else None
+        matches: list[dict] = []
+
+        # Step 1 — regex pass
+        for pii_type, pattern in _PATTERNS.items():
+            if allowed and pii_type not in allowed:
+                continue
+            for m in pattern.finditer(text):
+                matches.append(
+                    {
+                        "type": pii_type,
+                        "start": m.start(),
+                        "end": m.end(),
+                        "text": m.group(),
+                        "confidence": 0.95,
+                    }
+                )
+
+        # Step 2 — spaCy NER pass
+        nlp = self._get_nlp()
+        if nlp is not None:
+            doc = nlp(text)
+            for ent in doc.ents:
+                if ent.label_ not in _NER_LABELS:
+                    continue
+                if allowed and ent.label_ not in allowed:
+                    continue
+                # Skip if already covered by a regex match
+                overlap = any(m["start"] <= ent.start_char < m["end"] for m in matches)
+                if overlap:
+                    continue
+                matches.append(
+                    {
+                        "type": ent.label_,
+                        "start": ent.start_char,
+                        "end": ent.end_char,
+                        "text": ent.text,
+                        "confidence": 0.85,
+                    }
+                )
+
+        # Sort by position
+        matches.sort(key=lambda m: m["start"])
+        return matches
+
+    async def redact(self, text: str, matches: list[dict]) -> str:
+        """Replace detected PII with type-based placeholders.
+
+        Args:
+            text: Original text.
+            matches: Output from :meth:`detect`.
+
+        Returns:
+            Redacted text.
+        """
+        # Process in reverse order to preserve positions
+        for m in sorted(matches, key=lambda x: x["start"], reverse=True):
+            placeholder = f"[{m['type']}]"
+            text = text[: m["start"]] + placeholder + text[m["end"] :]
+        return text
+
+    @property
+    def supported_languages(self) -> list[str]:
+        """Supported languages."""
+        return ["en"]

admina/plugins/builtin/transports/__init__.py

@@ -0,0 +1,14 @@
+# 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/plugins/builtin/transports/http_rest.py

@@ -0,0 +1,97 @@
+# 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 — HTTP REST transport adapter.
+
+Provides a plain ``POST /api/govern`` endpoint for non-MCP callers
+(OpenClaw REST, n8n webhooks, direct API consumers).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from admina.core.types import GovernanceRequest, GovernanceResponse
+from admina.plugins.base import BaseTransportAdapter
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+logger = logging.getLogger("admina.plugins.transports.http_rest")
+
+
+class HTTPRESTTransportAdapter(BaseTransportAdapter):
+    """Transport adapter for plain HTTP REST requests.
+
+    Exposes ``POST /api/govern`` accepting a JSON body with ``content``,
+    optional ``method``, ``session_id``, ``user_id``, and ``metadata``.
+    """
+
+    async def parse_request(self, raw_request: Any) -> GovernanceRequest:
+        """Convert a REST JSON body into a GovernanceRequest.
+
+        Expected body::
+
+            {
+                "content": "text to govern",
+                "method": "optional.method",
+                "session_id": "optional",
+                "user_id": "optional",
+                "metadata": {}
+            }
+        """
+        if isinstance(raw_request, dict):
+            body = raw_request
+        else:
+            body = json.loads(raw_request) if isinstance(raw_request, (str, bytes)) else {}
+
+        return GovernanceRequest(
+            content=body.get("content", ""),
+            method=body.get("method", "rest.call"),
+            direction="inbound",
+            session_id=body.get("session_id"),
+            user_id=body.get("user_id"),
+            protocol="http_rest",
+            metadata=body.get("metadata", {}),
+            raw=body,
+        )
+
+    async def format_response(
+        self,
+        gov_response: GovernanceResponse,
+        original: Any,
+    ) -> Any:
+        """Convert a GovernanceResponse into a REST JSON dict."""
+        return {
+            "request_id": gov_response.request_id,
+            "action": gov_response.action,
+            "risk_level": gov_response.risk_level,
+            "content": gov_response.content,
+            "domain": gov_response.domain,
+            "latency_us": round(gov_response.latency_us, 2),
+            "metadata": gov_response.metadata,
+        }
+
+    def register_routes(self, app: FastAPI) -> None:
+        """Register ``POST /api/govern`` on the FastAPI app."""
+        # Route registration is deferred to the proxy bootstrap;
+        # this method is a no-op when called during plugin discovery.
+        pass
+
+    @property
+    def protocol_name(self) -> str:
+        """Protocol identifier."""
+        return "http_rest"