admina-framework 0.11.0__tar.gz → 0.12.0__tar.gz

{admina_framework-0.11.0/admina_framework.egg-info → admina_framework-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: admina-framework
-Version: 0.11.0
+Version: 0.12.0
 Summary: Admina — governed AI development framework
 Author-email: Stefano Noferi <info@admina.org>
 Maintainer-email: Stefano Noferi <info@admina.org>
@@ -30,7 +30,7 @@ License-File: NOTICE
 Requires-Dist: pyyaml<7,>=6.0
 Requires-Dist: click<9,>=8.1
 Requires-Dist: jinja2<4,>=3.1
-Requires-Dist: cryptography<50,>=41.0
+Requires-Dist: cryptography<51,>=41.0
 Provides-Extra: proxy
 Requires-Dist: fastapi<1,>=0.104; extra == "proxy"
 Requires-Dist: uvicorn[standard]<1,>=0.24; extra == "proxy"
@@ -52,15 +52,15 @@ Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "telemetry"
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.20; extra == "telemetry"
 Requires-Dist: opentelemetry-instrumentation-fastapi<1,>=0.40b0; extra == "telemetry"
 Provides-Extra: rust
-Requires-Dist: admina-core<0.12,>=0.9.3; extra == "rust"
+Requires-Dist: admina-core<0.13,>=0.9.3; extra == "rust"
 Provides-Extra: full
 Requires-Dist: admina-framework[nlp,proxy,telemetry]; extra == "full"
 Provides-Extra: openai
-Requires-Dist: openai<3,>=1.0; extra == "openai"
+Requires-Dist: openai<4,>=1.0; extra == "openai"
 Provides-Extra: ollama
 Requires-Dist: ollama<1,>=0.3; extra == "ollama"
 Provides-Extra: anthropic
-Requires-Dist: anthropic<1,>=0.39; extra == "anthropic"
+Requires-Dist: anthropic<2,>=0.39; extra == "anthropic"
 Provides-Extra: mistral
 Requires-Dist: mistralai<3,>=1.0; extra == "mistral"
 Provides-Extra: gemini
@@ -331,16 +331,23 @@ from admina import GovernedModel, GovernedData, GovernedAgent, ComplianceKit
 
 | Interface | Builtin implementations |
 |-----------|------------------------|
-| Model Adapter | Ollama, OpenAI |
+| Model Adapter | Ollama, OpenAI, Anthropic, Gemini, Mistral, Bedrock, vLLM |
 | Data Connector | ChromaDB, Filesystem |
 | Governance Domain | GuardrailsAI (toxic, jailbreak, bias, PII) |
 | Compliance Template | EU AI Act |
 | Transport Adapter | MCP, HTTP REST |
 | Forensic Store | Filesystem, S3-compatible (boto3 — AWS S3, MinIO, R2, …) |
 | Auth Provider | API Key |
-| PII Engine | spaCy + Regex |
+| PII Engine | spaCy + Regex (default), Microsoft Presidio (`pip install admina-framework[presidio]`, `ADMINA_PII_ENGINE=presidio`) |
 | Alert Channel | Log, Webhook |
 
+Model adapters lazy-import their provider SDK, so install the ones you
+use: `pip install admina-framework[adapters]` for all of them, or a
+single provider (`[openai]`, `[ollama]`, `[anthropic]`, `[mistral]`,
+`[gemini]`, `[bedrock]`). vLLM has no extra of its own — it serves an
+OpenAI-compatible API and subclasses the OpenAI adapter, so install
+`[openai]` for it.
+
 ```bash
 admina plugin list                    # List registered plugins
 admina plugin install ./my-plugin     # Install a custom plugin

{admina_framework-0.11.0 → admina_framework-0.12.0}/README.md

@@ -254,16 +254,23 @@ from admina import GovernedModel, GovernedData, GovernedAgent, ComplianceKit
 
 | Interface | Builtin implementations |
 |-----------|------------------------|
-| Model Adapter | Ollama, OpenAI |
+| Model Adapter | Ollama, OpenAI, Anthropic, Gemini, Mistral, Bedrock, vLLM |
 | Data Connector | ChromaDB, Filesystem |
 | Governance Domain | GuardrailsAI (toxic, jailbreak, bias, PII) |
 | Compliance Template | EU AI Act |
 | Transport Adapter | MCP, HTTP REST |
 | Forensic Store | Filesystem, S3-compatible (boto3 — AWS S3, MinIO, R2, …) |
 | Auth Provider | API Key |
-| PII Engine | spaCy + Regex |
+| PII Engine | spaCy + Regex (default), Microsoft Presidio (`pip install admina-framework[presidio]`, `ADMINA_PII_ENGINE=presidio`) |
 | Alert Channel | Log, Webhook |
 
+Model adapters lazy-import their provider SDK, so install the ones you
+use: `pip install admina-framework[adapters]` for all of them, or a
+single provider (`[openai]`, `[ollama]`, `[anthropic]`, `[mistral]`,
+`[gemini]`, `[bedrock]`). vLLM has no extra of its own — it serves an
+OpenAI-compatible API and subclasses the OpenAI adapter, so install
+`[openai]` for it.
+
 ```bash
 admina plugin list                    # List registered plugins
 admina plugin install ./my-plugin     # Install a custom plugin

{admina_framework-0.11.0 → admina_framework-0.12.0}/admina/__init__.py

@@ -23,7 +23,7 @@ from __future__ import annotations
 
 from admina.sdk import ComplianceKit, GovernedAgent, GovernedData, GovernedModel
 
-__version__ = "0.11.0"
+__version__ = "0.12.0"
 
 __all__ = [
     "__version__",

{admina_framework-0.11.0 → admina_framework-0.12.0}/admina/cli/main.py

@@ -20,6 +20,7 @@ Entry point: ``admina = "cli.main:app"`` in pyproject.toml.
 from __future__ import annotations
 
 import hashlib
+import json
 import logging
 import os
 import shutil
@@ -1485,6 +1486,171 @@ def password_set(new_password: str) -> None:
     click.echo("  Restart services to apply: docker compose up --build -d\n")
 
 
+# ── admina egress commands ───────────────────────────────────
+
+
+@app.group()
+def egress() -> None:
+    """Inspect and manage the egress policy."""
+
+
+@egress.command("suggest-allowlist")
+@click.option(
+    "--since",
+    type=click.IntRange(min=0),
+    default=7,
+    help="Only consider records from the last N days.",
+)
+@click.option(
+    "--forensic-dir",
+    default=None,
+    help=(
+        "Directory holding forensic records (the filesystem store's base_dir). "
+        "Defaults to $FORENSIC_BASE_DIR, then .admina/forensic."
+    ),
+)
+def suggest_allowlist(since: int, forensic_dir: str | None) -> None:
+    """Print a candidate allowlist from destinations seen in observe mode."""
+    # Same source `admina doctor` reads for the filesystem store; the flag
+    # stays an explicit override.
+    base = Path(forensic_dir or os.environ.get("FORENSIC_BASE_DIR") or ".admina/forensic")
+    cutoff = time.time() - since * 86400
+    seen: set[str] = set()
+    for path in sorted(base.rglob("*.json")) if base.is_dir() else []:
+        try:
+            if path.stat().st_mtime < cutoff:
+                continue
+            record = json.loads(path.read_text())
+        except (OSError, ValueError):
+            continue
+        # Handle both wrapped (ForensicBlackBox) and flat (test) record shapes
+        if not isinstance(record, dict):
+            continue
+        event = record.get("event", record)
+        if not isinstance(event, dict):
+            continue
+        check = event.get("checks") or {}
+        if not isinstance(check, dict):
+            continue
+        egress = check.get("egress") or {}
+        if not isinstance(egress, dict):
+            continue
+        destinations = egress.get("destinations") or []
+        if not isinstance(destinations, list):
+            continue
+        for dest in destinations:
+            if isinstance(dest, str) and dest:
+                seen.add(dest)
+
+    if not seen:
+        click.echo(f"No egress observations found in {base} for the last {since} day(s).")
+        click.echo("Run with ADMINA_EGRESS_MODE=observe to collect them.")
+        click.echo(
+            "Observations are read back from forensic records, and FORENSIC_BACKEND "
+            "defaults to 'memory' — set FORENSIC_BACKEND=filesystem and "
+            "FORENSIC_BASE_DIR for anything to be written."
+        )
+        return
+
+    click.echo("# Candidate allowlist from observed traffic.")
+    click.echo("# Review every entry before promoting it: observation records what")
+    click.echo("# happened, not what should be allowed.")
+    click.echo("domains:")
+    click.echo("  agent_security:")
+    click.echo("    egress:")
+    click.echo("      allow:")
+    for dest in sorted(seen):
+        click.echo(f"        - {dest}")
+
+
+def _quarantine_redis(url: str):
+    """Open an async Redis client. Isolated so tests can substitute it."""
+    import redis.asyncio as aioredis
+
+    return aioredis.from_url(url, decode_responses=True)
+
+
+@egress.group()
+def quarantine() -> None:
+    """Inspect and clear quarantined destinations."""
+
+
+@quarantine.command("list")
+@click.option(
+    "--redis-url",
+    default=lambda: os.environ.get("REDIS_URL", "redis://localhost:6379/0"),
+)
+def quarantine_list(redis_url: str) -> None:
+    """Show destinations currently refused for payload-bearing calls."""
+    import asyncio
+    import time
+
+    from admina.domains.agent_security.coordination import QuarantineStore
+
+    async def _run():
+        client = _quarantine_redis(redis_url)
+        try:
+            store = QuarantineStore(client, ttl_seconds=1)
+            return await store.current_raising(time.time())
+        finally:
+            await client.close()
+
+    try:
+        live = sorted(asyncio.run(_run()))
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"Could not read quarantine set: {exc}")
+        raise SystemExit(1)
+
+    if not live:
+        click.echo("No destination is currently quarantined.")
+        return
+    click.echo("Quarantined for writes (reads are unaffected):")
+    for destination in live:
+        click.echo(f"  - {destination}")
+    click.echo("")
+    click.echo(
+        "Write-shaped calls to these are refused only under ADMINA_EGRESS_MODE=enforce; "
+        "under the default observe mode they are recorded and allowed."
+    )
+
+
+@quarantine.command("lift")
+@click.argument("destination")
+@click.option(
+    "--redis-url",
+    default=lambda: os.environ.get("REDIS_URL", "redis://localhost:6379/0"),
+)
+def quarantine_lift(destination: str, redis_url: str) -> None:
+    """Clear one destination's quarantine."""
+    import asyncio
+
+    from admina.domains.agent_security.coordination import QuarantineStore
+
+    # Destinations are stored as the egress analyser normalised them, which
+    # lower-cases every host. An operator reading WIKI.CORP off a dashboard
+    # would otherwise be told it was not quarantined.
+    destination = destination.strip().lower()
+
+    async def _run():
+        client = _quarantine_redis(redis_url)
+        try:
+            store = QuarantineStore(client, ttl_seconds=1)
+            return await store.lift_raising(destination)
+        finally:
+            await client.close()
+
+    try:
+        lifted = asyncio.run(_run())
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"Could not reach quarantine store: {exc}")
+        raise SystemExit(1)
+
+    if lifted:
+        click.echo(f"Lifted quarantine on {destination}.")
+    else:
+        click.echo(f"{destination} was not quarantined.")
+
+
 @app.command()
 @click.option(
     "--output",

{admina_framework-0.11.0 → admina_framework-0.12.0}/admina/core/config.py

@@ -152,6 +152,20 @@ class LoopBreakerConfig:
     max_consecutive: int = 3
 
 
+@dataclass
+class EgressConfig:
+    """Destination-based egress control settings."""
+
+    enabled: bool = True
+    allow: list[str] = field(default_factory=list)
+    read_only_tools: list[str] = field(default_factory=list)
+    # Parsed now, consumed by the coordination detector.
+    coordination_declared: list[str] = field(default_factory=list)
+    fanin_window_seconds: int = 3600
+    fanin_min_agents: int = 5
+    quarantine_ttl_seconds: int = 86400
+
+
 @dataclass
 class AgentSecurityConfig:
     """Agent-security domain."""
@@ -160,6 +174,7 @@ class AgentSecurityConfig:
     proxy: ProxyConfig = field(default_factory=ProxyConfig)
     firewall: FirewallConfig = field(default_factory=FirewallConfig)
     loop_breaker: LoopBreakerConfig = field(default_factory=LoopBreakerConfig)
+    egress: EgressConfig = field(default_factory=EgressConfig)
 
 
 @dataclass
@@ -318,9 +333,16 @@ def _build_from_yaml(data: dict[str, Any]) -> AdminaConfig:
 
     # agent_security
     as_raw = domains.get("agent_security", {})
-    px_raw = as_raw.get("proxy", {})
-    fw_raw = as_raw.get("firewall", {})
-    lb_raw = as_raw.get("loop_breaker", {})
+    # ``or {}``: a section written with nothing under it ("egress:") parses
+    # as None, and the next .get() would raise. For egress that exception is
+    # swallowed by the factory's broad except and downgraded to an empty
+    # allowlist, which under enforce blocks every destination with no sign of
+    # why; for the other three it is an outright crash.
+    px_raw = as_raw.get("proxy") or {}
+    fw_raw = as_raw.get("firewall") or {}
+    lb_raw = as_raw.get("loop_breaker") or {}
+    eg_raw = as_raw.get("egress") or {}
+    eg_fanin = eg_raw.get("fanin", {}) or {}
     agent_sec = AgentSecurityConfig(
         enabled=as_raw.get("enabled", True),
         proxy=ProxyConfig(
@@ -339,6 +361,15 @@ def _build_from_yaml(data: dict[str, Any]) -> AdminaConfig:
             similarity_threshold=lb_raw.get("similarity_threshold", 0.85),
             max_consecutive=lb_raw.get("max_consecutive", 3),
         ),
+        egress=EgressConfig(
+            enabled=eg_raw.get("enabled", True),
+            allow=list(eg_raw.get("allow") or []),
+            read_only_tools=list(eg_raw.get("read_only_tools") or []),
+            coordination_declared=list(eg_raw.get("coordination_declared") or []),
+            fanin_window_seconds=int(eg_fanin.get("window_seconds", 3600)),
+            fanin_min_agents=int(eg_fanin.get("min_agents", 5)),
+            quarantine_ttl_seconds=int(eg_raw.get("quarantine_ttl_seconds", 86400)),
+        ),
     )
 
     # compliance