admina-framework 0.11.1__tar.gz → 0.12.1__tar.gz

{admina_framework-0.11.1/admina_framework.egg-info → admina_framework-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: admina-framework
-Version: 0.11.1
+Version: 0.12.1
 Summary: Admina — governed AI development framework
 Author-email: Stefano Noferi <info@admina.org>
 Maintainer-email: Stefano Noferi <info@admina.org>
@@ -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
@@ -382,6 +382,10 @@ Real-time governance dashboard on port 3000:
 
 API backend: `GET /api/dashboard/score`, `/feed`, `/compliance`, `/sovereignty`, `/infra`, `/models`
 
+In `admina dev` local mode the dashboard asks for the API key (`admina password show`)
+and keeps a short-lived browser session that only the read-only dashboard API accepts.
+Set `ADMINA_DASHBOARD_ENABLED=false` to stop serving the bundled dashboard.
+
 ## Configuration
 
 Admina uses `admina.yaml` as the primary config file (with `.env` fallback for backward compatibility):

{admina_framework-0.11.1 → admina_framework-0.12.1}/README.md

@@ -305,6 +305,10 @@ Real-time governance dashboard on port 3000:
 
 API backend: `GET /api/dashboard/score`, `/feed`, `/compliance`, `/sovereignty`, `/infra`, `/models`
 
+In `admina dev` local mode the dashboard asks for the API key (`admina password show`)
+and keeps a short-lived browser session that only the read-only dashboard API accepts.
+Set `ADMINA_DASHBOARD_ENABLED=false` to stop serving the bundled dashboard.
+
 ## Configuration
 
 Admina uses `admina.yaml` as the primary config file (with `.env` fallback for backward compatibility):

{admina_framework-0.11.1 → admina_framework-0.12.1}/admina/__init__.py

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

{admina_framework-0.11.1 → admina_framework-0.12.1}/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
@@ -642,6 +643,7 @@ def _run_local(
                 click.echo(f"    http://{ip}:{port}  ({label})")
         else:
             click.echo(f"  Ready → http://{display_host}:{port}")
+        click.echo("  Dashboard sign-in: the API key (show it with `admina password show`)")
         if not no_browser:
             webbrowser.open(f"http://{display_host}:{port}")
     else:
@@ -1485,6 +1487,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.1 → admina_framework-0.12.1}/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

{admina_framework-0.11.1 → admina_framework-0.12.1}/admina/dashboard/static/index.html

@@ -330,6 +330,33 @@
   .link-card:hover { border-color: var(--teal); }
   .link-card .lc-label { font-size: 11px; text-transform: uppercase; color: var(--muted); margin-bottom: 6px; }
   .link-card .lc-title { font-size: 14px; font-weight: 600; }
+
+  /* ── Sign-in ─────────────────────────────────────────── */
+  .signin {
+    position: fixed; inset: 0; z-index: 300; background: var(--bg);
+    display: flex; align-items: center; justify-content: center; padding: 24px;
+  }
+  .signin-card {
+    width: 100%; max-width: 420px; background: var(--surface);
+    border: 1px solid var(--border2); border-radius: 12px; padding: 28px;
+  }
+  .signin-card .logo { display: flex; align-items: center; gap: 10px; font-size: 18px; font-weight: 700; margin-bottom: 16px; }
+  .signin-card .logo img { width: 32px; height: 32px; object-fit: contain; }
+  .signin-card .logo .accent { color: var(--teal); }
+  .signin-card p { font-size: 13px; color: var(--muted); line-height: 1.6; margin-bottom: 16px; }
+  .signin-card code { font-family: var(--mono); font-size: 12px; color: var(--text); }
+  .signin-card label { display: block; font-size: 12px; text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted); margin-bottom: 6px; }
+  .signin-card input {
+    width: 100%; padding: 9px 12px; border-radius: 6px; border: 1px solid var(--border2);
+    background: var(--surface2); color: var(--text); font-family: var(--mono); font-size: 13px;
+  }
+  .signin-card input:focus { outline: none; border-color: var(--teal); }
+  .signin-card button {
+    margin-top: 14px; width: 100%; padding: 9px 12px; border-radius: 6px; cursor: pointer;
+    background: var(--teal-dark); color: #fff; border: 1px solid var(--teal); font-size: 14px; font-weight: 600;
+  }
+  .signin-card button:disabled { opacity: 0.6; cursor: default; }
+  .signin-card .error { margin-top: 12px; font-size: 13px; color: var(--red); }
 </style>
 </head>
 <body>
@@ -339,6 +366,25 @@
      ════════════════════════════════════════════════════════ -->
 <div x-data="dashboard()" x-init="init()">
 
+  <!-- Sign-in: the API key is exchanged for a short-lived browser session -->
+  <div class="signin" x-show="needsLogin" x-cloak>
+    <form class="signin-card" @submit.prevent="login()">
+      <div class="logo">
+        <img src="heimdall.png" alt="">
+        <span><span class="accent">Admina</span> Governance Dashboard</span>
+      </div>
+      <p>
+        Sign in with this instance's API key. In an <code>admina dev</code> project,
+        run <code>admina password show</code> to display it.
+      </p>
+      <label for="admina-api-key">API key</label>
+      <input id="admina-api-key" type="password" x-model="loginKey" x-ref="loginKey"
+             autocomplete="off" autocapitalize="off" spellcheck="false" required>
+      <button type="submit" :disabled="loginBusy || !loginKey">Sign in</button>
+      <div class="error" x-show="loginError" x-text="loginError" role="alert"></div>
+    </form>
+  </div>
+
   <!-- Top Bar -->
   <div class="topbar">
     <div class="logo">
@@ -349,6 +395,9 @@
       <span class="ts" x-text="lastUpdate"></span>
       <div class="sep"></div>
       <button class="refresh-btn" @click="refresh()">Refresh</button>
+      <template x-if="sessionActive">
+        <button class="refresh-btn" @click="logout()">Sign out</button>
+      </template>
       <div class="sep"></div>
       <div class="status">
         <div class="dot" :style="{ background: healthy ? 'var(--green)' : 'var(--red)' }"></div>
@@ -807,7 +856,9 @@
  * Admina Governance Dashboard — Alpine.js application.
  *
  * Reads from the Phase 3.1 API endpoints. Does NOT write.
- * All API calls go through the nginx reverse proxy (/api/*).
+ * All API calls go to /api/* on the same origin: the proxy itself in
+ * `admina dev` local mode (browser session after sign-in), or the nginx
+ * reverse proxy of the Docker stack (which adds the API key).
  */
 function dashboard() {
   return {
@@ -824,6 +875,12 @@ function dashboard() {
     modelData: {},
     oisg: {},
     showAssessmentHelp: false,
+    needsLogin: false,
+    sessionActive: false,
+    loginKey: '',
+    loginError: '',
+    loginBusy: false,
+    _started: false,
     _ws: null,
     _feedId: 0,
     _refreshTimer: null,
@@ -920,17 +977,96 @@ function dashboard() {
 
     // ── Init ───────────────────────────────────────────
     async init() {
-      await this.refresh();
+      if (await this.checkSession()) this.start();
+    },
+
+    start() {
+      // Alpine calls init() both automatically and via x-init: start once.
+      if (this._started) return;
+      this._started = true;
+      this.refresh();
       this.connectWebSocket();
       // Auto-refresh every 10s
       this._refreshTimer = setInterval(() => this.refresh(), 10000);
     },
 
+    // ── Session ────────────────────────────────────────
+    // Serving this page never signs the browser in. The API key is exchanged
+    // once for a short-lived HttpOnly session cookie that only the read-only
+    // dashboard API accepts. Behind the Docker nginx the proxy already
+    // receives the key, so no sign-in is needed there.
+    async checkSession() {
+      try {
+        const r = await fetch('/api/dashboard/session', { cache: 'no-store' });
+        if (r.status === 401) { this.showLogin(''); return false; }
+        if (r.ok) this.sessionActive = !!(await r.json()).session;
+      } catch (e) { /* network error: start anyway and show Disconnected */ }
+      return true;
+    },
+
+    async login() {
+      if (!this.loginKey) return;
+      this.loginBusy = true;
+      this.loginError = '';
+      try {
+        const r = await fetch('/api/dashboard/session', {
+          method: 'POST',
+          headers: { 'X-API-Key': this.loginKey },
+          cache: 'no-store',
+        });
+        if (r.ok) {
+          this.loginKey = '';
+          this.needsLogin = false;
+          this.sessionActive = true;
+          this.start();
+        } else if (r.status === 401) {
+          this.loginError = 'Invalid API key.';
+        } else {
+          let detail = '';
+          try { detail = (await r.json()).detail || ''; } catch (e) { /* not JSON */ }
+          this.loginError = detail || `Sign-in failed (HTTP ${r.status}).`;
+        }
+      } catch (e) {
+        this.loginError = 'Admina is not reachable.';
+      } finally {
+        this.loginBusy = false;
+      }
+    },
+
+    async logout() {
+      try { await fetch('/api/dashboard/session', { method: 'DELETE', cache: 'no-store' }); }
+      catch (e) { /* cookie expires on its own */ }
+      this.showLogin('');
+    },
+
+    showLogin(message) {
+      clearInterval(this._refreshTimer);
+      this._refreshTimer = null;
+      this._started = false;
+      if (this._ws) {
+        const ws = this._ws;
+        this._ws = null;
+        ws.onclose = null;
+        ws.close();
+      }
+      this.wsConnected = false;
+      this.sessionActive = false;
+      this.feedEvents = [];
+      this.loginError = message;
+      this.needsLogin = true;
+      this.$nextTick(() => this.$refs.loginKey && this.$refs.loginKey.focus());
+    },
+
     // ── Fetch all data ─────────────────────────────────
     async refresh() {
       // allSettled so one failing endpoint never blanks the whole dashboard.
       const okJson = async (url) => {
         const r = await fetch(url);
+        if (r.status === 401) {
+          const err = new Error(`${url} -> 401`);
+          err.unauthorized = true;
+          throw err;
+        }
         if (!r.ok) throw new Error(`${url} -> ${r.status}`);
         return r.json();
       };
@@ -944,6 +1080,10 @@ function dashboard() {
         okJson('/api/dashboard/models'),
         okJson('/api/dashboard/oisg'),
       ]);
+      if (results.some(r => r.status === 'rejected' && r.reason && r.reason.unauthorized)) {
+        this.showLogin('Your session has expired. Sign in again.');
+        return;
+      }
       const [scoreRes, compRes, sovRes, statsRes, feedRes, infraRes, modelsRes, oisgRes] =
         results.map(r => r.status === 'fulfilled' ? r.value : null);
 
@@ -998,8 +1138,9 @@ function dashboard() {
 
         this._ws.onclose = () => {
           this.wsConnected = false;
+          if (this.needsLogin) return;
           console.log('[Admina] WebSocket disconnected, reconnecting in 3s...');
-          setTimeout(() => this.connectWebSocket(), 3000);
+          setTimeout(() => { if (!this.needsLogin) this.connectWebSocket(); }, 3000);
         };
 
         this._ws.onerror = () => {
@@ -1007,7 +1148,7 @@ function dashboard() {
         };
       } catch (e) {
         this.wsConnected = false;
-        setTimeout(() => this.connectWebSocket(), 5000);
+        setTimeout(() => { if (!this.needsLogin) this.connectWebSocket(); }, 5000);
       }
     },