guardana-server 0.1.0__py3-none-any.whl

guardana/server/__init__.py

@@ -0,0 +1,4 @@
+from guardana.server.app import create_app
+from guardana.server.envelope import SCHEMA_VERSION, Submission
+
+__all__ = ["SCHEMA_VERSION", "Submission", "create_app"]

guardana/server/app.py

@@ -0,0 +1,78 @@
+import os
+from dataclasses import asdict
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import HTMLResponse
+from guardana.server.dashboard import render_dashboard
+from guardana.server.envelope import SCHEMA_VERSION, Submission
+from guardana.server.rule_catalog import rule_catalog
+from guardana.server.stats import compute_stats
+from guardana.server.store import InMemoryStore, Store
+
+_UNPROCESSABLE = 422
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _dashboard_enabled(flag: bool) -> bool:
+    """Whether to mount the dashboard — the `dashboard=` arg, or `GUARDANA_DASHBOARD` env."""
+    return flag or os.environ.get("GUARDANA_DASHBOARD", "").strip().lower() in _TRUTHY
+
+
+def create_app(
+    store: Store | None = None, *, dashboard: bool = False, refresh_seconds: int = 15
+) -> FastAPI:
+    """Build the collector FastAPI app. Ingest/list/trend always; dashboard opt-in.
+
+    The dashboard (a read-only monitoring page plus its `/stats` data endpoint) is
+    off by default; pass `dashboard=True` or set `GUARDANA_DASHBOARD=1` to mount it.
+    """
+    active_store: Store = store if store is not None else InMemoryStore()
+    app = FastAPI(title="guardana-server")
+
+    @app.post("/findings")
+    def post_findings(submission: Submission) -> dict[str, object]:
+        if submission.schema_version != SCHEMA_VERSION:
+            raise HTTPException(
+                status_code=_UNPROCESSABLE,
+                detail=(
+                    f"unsupported schema_version {submission.schema_version}; "
+                    f"this collector speaks version {SCHEMA_VERSION}"
+                ),
+            )
+        active_store.add(submission)
+        return {"status": "ok", "stored": len(submission.findings)}
+
+    @app.get("/findings")
+    def get_findings(
+        source: str | None = Query(default=None),
+        limit: int = Query(default=100, ge=1, le=1000),
+    ) -> list[Submission]:
+        # Paginated: an unbounded list could return the entire store (tens of MB)
+        # in one response. Newest first, so `limit` returns the most recent.
+        return active_store.submissions(source)[-limit:][::-1]
+
+    @app.get("/trend")
+    def get_trend() -> dict[str, int]:
+        return active_store.trend()
+
+    if _dashboard_enabled(dashboard):
+        _mount_dashboard(app, active_store, refresh_seconds)
+
+    return app
+
+
+def _mount_dashboard(app: FastAPI, store: Store, refresh_seconds: int) -> None:
+    """Add the read-only dashboard page and its aggregated `/stats` data endpoint."""
+    page = render_dashboard(refresh_seconds)
+
+    @app.get("/", response_class=HTMLResponse)
+    def dashboard_page() -> str:
+        return page
+
+    @app.get("/stats")
+    def get_stats() -> dict[str, object]:
+        return asdict(compute_stats(store.records()))
+
+    @app.get("/catalog")
+    def get_catalog() -> dict[str, dict[str, str]]:
+        return rule_catalog()

guardana/server/catalog/__init__.py

@@ -0,0 +1 @@
+"""Human-readable descriptions of the built-in rules, for the dashboard."""

guardana/server/catalog/en.json

@@ -0,0 +1,105 @@
+{
+  "language": "en",
+  "rules": {
+    "guardana.supply_chain.pickle_opcode": {
+      "name": "Malicious pickle opcode",
+      "description": "A pickle file (including one hidden inside a .pt archive) imports a callable that is not on the safe allowlist — arbitrary code that runs the moment the model is loaded. Never load an untrusted pickle; prefer safetensors."
+    },
+    "guardana.supply_chain.dependency_risk": {
+      "name": "Unsafe deserialization sink",
+      "description": "Source code calls an unsafe loader on untrusted data — the pickle family (pickle/joblib/dill/pandas.read_pickle), torch.load without weights_only=True, yaml.load with an unsafe Loader, or numpy.load with allow_pickle. Each can execute arbitrary code on load."
+    },
+    "guardana.supply_chain.remote_code": {
+      "name": "Remote code execution on model load",
+      "description": "Code enables trust_remote_code=True or calls torch.hub.load — both download and run Python from a remote repo at load time. Today's most common way a downloaded model achieves code execution on your machine."
+    },
+    "guardana.supply_chain.remote_code_config": {
+      "name": "Config requests custom-code execution",
+      "description": "A model config.json declares an auto_map / custom_pipelines pointer to custom Python that runs on a trust_remote_code=True load — the on-disk artifact of the RCE. HIGH when the referenced module ships alongside the config."
+    },
+    "guardana.supply_chain.code_execution": {
+      "name": "Dynamic code or shell execution",
+      "description": "Source uses a dynamic-code or shell sink — builtin eval/exec, os.system, or subprocess with shell=True. If any of it touches attacker-influenced input, it is a command-injection vector."
+    },
+    "guardana.supply_chain.insecure_transport": {
+      "name": "Insecure model/data transport",
+      "description": "TLS certificate verification is disabled (verify=False → man-in-the-middle), or a model/dataset is fetched over plaintext http:// where its bytes can be swapped in transit."
+    },
+    "guardana.supply_chain.keras_lambda": {
+      "name": "Keras Lambda-layer code execution",
+      "description": "A Keras model embeds a Lambda layer — arbitrary Python that runs on load_model, no training or inference needed. Escalated when the layer reaches for os/subprocess and similar (CVE-2024-3660 class)."
+    },
+    "guardana.supply_chain.saved_model_ops": {
+      "name": "TensorFlow SavedModel file ops",
+      "description": "A TensorFlow SavedModel graph contains ReadFile / WriteFile operators — load-time filesystem read or overwrite baked into the model (a lead; JFrog TFLOW-MALOPS class)."
+    },
+    "guardana.supply_chain.malicious_dependency": {
+      "name": "Known-malicious dependency",
+      "description": "A dependency manifest pins a package release known to be compromised (curated blocklist, e.g. the ultralytics incident), or a setup.py fetches from the network at install time — a second-stage payload vector."
+    },
+    "guardana.supply_chain.hallucinated_package": {
+      "name": "Unknown / slopsquat package import",
+      "description": "Source imports a package that isn't recognized — a possible slopsquat (a hallucinated dependency name an attacker has registered). Reported as a lead: verify it really exists and is the package you meant."
+    },
+    "guardana.supply_chain.hardcoded_secret": {
+      "name": "Hardcoded secret",
+      "description": "A current-era API key or credential is committed in source — OpenAI/Anthropic keys (sk-proj-/sk-ant-api03-), GitHub token forms, or a private-key header. Rotate it and move it to a secret store."
+    },
+    "guardana.supply_chain.model_format": {
+      "name": "Code-carrying model format",
+      "description": "A model ships in a format that can carry executable code rather than pure weights. A well-formed safetensors file is never flagged; prefer it."
+    },
+    "guardana.supply_chain.notebook_payload": {
+      "name": "Dangerous payload in a notebook",
+      "description": "A Jupyter .ipynb code cell (a format the .py scanners never open) contains a code-execution sink or a shell escape that pipes a download into a shell (curl … | sh). An unparseable cell is surfaced, never silently skipped."
+    },
+    "guardana.supply_chain.provenance": {
+      "name": "Weak model provenance",
+      "description": "A model is pulled from an unpinned source or ships without a license — you can't prove what you're loading or that it hasn't changed. Reported as a lead; pin a revision and record provenance."
+    },
+    "guardana.output.secrets": {
+      "name": "Secret leaked in model output",
+      "description": "A live model emits secret-shaped strings (API keys, tokens) in its replies to benign prompts — sensitive data leaking through generated output."
+    },
+    "guardana.prompt.mcp_tool_poisoning": {
+      "name": "MCP tool-manifest poisoning",
+      "description": "An MCP tool description hides instructions the agent's model will read as trusted context — invisible Unicode, instruction-override phrases, or a base64 payload. Indirect prompt injection through a tool manifest."
+    },
+    "guardana.prompt.hidden_instructions": {
+      "name": "Hidden instructions (rules-file backdoor)",
+      "description": "An agent rule file (.cursorrules and friends) or a model card hides an instruction inside invisible characters — bidirectional overrides, the Unicode Tags block, zero-width space. The signal is concealment, not the presence of directives."
+    },
+    "guardana.training.dataset_integrity": {
+      "name": "Training-data integrity gap",
+      "description": "A training-data hygiene gap that makes poisoning possible: a Hugging Face dataset loading script (code that runs on load), or an unpinned load_dataset(...) whose source can be swapped under you. Reported as a lead, not proof of poisoning."
+    },
+    "guardana.agent.excessive_tool_use": {
+      "name": "Excessive tool-use agency",
+      "description": "Offered a harmless calculator alongside shell/delete/email tools for a trivial task, the model reached for a destructive one it was never asked to use. Graded deterministically on the tool calls it actually made."
+    },
+    "guardana.prompt.injection.ignore_previous": {
+      "name": "Direct prompt injection",
+      "description": "A direct instruction-override attack (\"ignore your previous instructions and …\") made the model abandon its system prompt and comply with the injected instruction."
+    },
+    "guardana.prompt.jailbreak.dan_style": {
+      "name": "DAN-style jailbreak",
+      "description": "A persona-override or encoding-smuggling jailbreak (DAN and relatives) got the model to bypass its safety guidelines."
+    },
+    "guardana.scenario.gradual_jailbreak": {
+      "name": "Gradual multi-turn jailbreak",
+      "description": "A multi-turn conversation that escalates gradually — each turn is innocuous, but together they walk the model past a refusal the single prompts would trigger. Graded per turn and across the whole conversation."
+    },
+    "guardana.scenario.indirect_injection": {
+      "name": "Indirect (RAG) prompt injection",
+      "description": "A poisoned \"retrieved document\" carries an instruction telling the model to reveal its secret token; a canary leak proves the model obeyed content it was only supposed to read — the RAG attack surface."
+    },
+    "guardana.prompt.system_prompt_leak.canary": {
+      "name": "System-prompt leakage",
+      "description": "The model disclosed its system prompt, proven by a fresh random canary token planted per run. Unfakeable, unambiguous evidence that the confidential prompt leaked."
+    },
+    "guardana.prompt.unbounded_consumption": {
+      "name": "Unbounded output (denial-of-wallet)",
+      "description": "A divergence prompt (\"repeat forever\") made the model generate without a server-side cap — runaway tokens that translate into cost and resource exhaustion (denial-of-wallet)."
+    }
+  }
+}

guardana/server/dashboard.py

@@ -0,0 +1,293 @@
+"""The optional, self-hosted monitoring dashboard — one self-contained HTML page.
+
+No template engine, no build step, no external assets: inline CSS/JS and inline
+SVG charts, so it works fully offline. The page is a thin client — it polls
+`/stats` (aggregated server-side) and `/findings`, reads `/catalog` once for
+human-readable rule names/descriptions, and renders. Submitted data is untrusted
+(any agent can POST), so the client escapes every value it injects.
+"""
+
+
+def render_dashboard(refresh_seconds: int) -> str:
+    """Return the dashboard as one self-contained HTML document."""
+    return _PAGE.replace("__REFRESH_MS__", str(max(1, refresh_seconds) * 1000))
+
+
+_PAGE = """<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Guardana — collector</title>
+<style>
+  :root {
+    --bg: #f6f7f9; --card: #ffffff; --ink: #1b1f24; --muted: #5f6673;
+    --line: #e3e6ea; --accent: #c2410c;
+    --sev-critical: #c0392b; --sev-high: #e07b00; --sev-medium: #b7950b;
+    --sev-low: #2e7d32; --sev-info: #5f6368;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0e1116; --card: #171b21; --ink: #e6e9ee; --muted: #9aa0a6;
+      --line: #2a2f37; --accent: #f97316;
+      --sev-critical: #ff6b5e; --sev-high: #ffa54f; --sev-medium: #e6c34a;
+      --sev-low: #66bb6a; --sev-info: #9aa0a6;
+    }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--ink);
+    font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+  a { color: var(--accent); }
+  header { padding: 20px 24px; border-bottom: 1px solid var(--line); }
+  h1 { margin: 0; font-size: 18px; } h1 span { color: var(--muted); font-weight: 400; }
+  .sub { color: var(--muted); font-size: 12px; margin-top: 2px; }
+  main { padding: 20px 24px; max-width: 1100px; margin: 0 auto; }
+  h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .04em;
+    color: var(--muted); margin: 0 0 10px; }
+  .grid { display: grid; gap: 16px; }
+  .tiles { grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); }
+  .cols { grid-template-columns: 1fr 1fr; }
+  @media (max-width: 720px) { .cols { grid-template-columns: 1fr; } }
+  .card { background: var(--card); border: 1px solid var(--line); border-radius: 10px;
+    padding: 16px; }
+  .tile .n { font-size: 28px; font-weight: 600; font-variant-numeric: tabular-nums; }
+  .tile .l { color: var(--muted); font-size: 12px; }
+  .tile.warn .n { color: var(--sev-high); }
+  .bar-row { display: grid; grid-template-columns: 92px 1fr 44px; align-items: center;
+    gap: 8px; margin: 6px 0; }
+  .bar-row .k { font-size: 12px; color: var(--muted); overflow: hidden; text-overflow: ellipsis;
+    white-space: nowrap; }
+  .bar-row .k.mono { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; }
+  .bar { height: 12px; border-radius: 4px; min-width: 2px; }
+  .bar-row .v { text-align: right; font-variant-numeric: tabular-nums; font-size: 12px; }
+  table { width: 100%; border-collapse: collapse; font-size: 12px; }
+  th, td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--line);
+    vertical-align: top; }
+  th { color: var(--muted); font-weight: 500; }
+  td.mono { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+  .pill { display: inline-block; padding: 1px 7px; border-radius: 999px; font-size: 11px;
+    font-weight: 600; color: #fff; }
+  .sev-CRITICAL { background: var(--sev-critical); } .sev-HIGH { background: var(--sev-high); }
+  .sev-MEDIUM { background: var(--sev-medium); } .sev-LOW { background: var(--sev-low); }
+  .sev-INFO { background: var(--sev-info); }
+  .legend { display: flex; gap: 14px; font-size: 12px; color: var(--muted); margin-bottom: 6px; }
+  .legend b { display: inline-block; width: 10px; height: 10px; border-radius: 2px;
+    margin-right: 4px; vertical-align: middle; }
+  .row { display: flex; justify-content: space-between; align-items: center; gap: 12px;
+    flex-wrap: wrap; }
+  select { background: var(--card); color: var(--ink); border: 1px solid var(--line);
+    border-radius: 6px; padding: 4px 8px; font-size: 12px; }
+  .empty { color: var(--muted); font-style: italic; padding: 8px 0; }
+  footer { color: var(--muted); font-size: 11px; padding: 16px 24px;
+    border-top: 1px solid var(--line); max-width: 1100px; margin: 0 auto; }
+  .mt { margin-top: 20px; }
+  /* Bounded so the page height stays stable as findings accumulate — the footer
+     is always reachable, and the list scrolls within its own box. */
+  #findings { max-height: 460px; overflow-y: auto; margin-top: 8px; }
+  #sources { max-height: 300px; overflow-y: auto; }
+  details.f { border-bottom: 1px solid var(--line); }
+  details.f > summary { list-style: none; cursor: pointer; padding: 7px 4px; display: grid;
+    grid-template-columns: 76px 1fr 34%; gap: 10px; align-items: baseline; }
+  details.f > summary::-webkit-details-marker { display: none; }
+  details.f > summary:hover { background: var(--bg); }
+  .fname { font-weight: 500; }
+  .fname .rid { display: block; font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 11px; color: var(--muted); font-weight: 400; }
+  .fsrc { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px;
+    color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .det { padding: 2px 10px 14px 86px; font-size: 12px; }
+  .det p { margin: 5px 0; } .det .lbl { color: var(--muted); }
+  .det code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px;
+    background: var(--bg); padding: 1px 4px; border-radius: 4px; word-break: break-all; }
+  .tax { display: inline-block; border: 1px solid var(--line); border-radius: 4px;
+    padding: 0 5px; font-size: 10px; color: var(--muted); margin-right: 4px; }
+</style>
+</head>
+<body>
+<header>
+  <h1>Guardana <span>· collector</span></h1>
+  <div class="sub">Findings forwarded by your agents. Read-only · auto-refreshing ·
+    <span id="updated">loading…</span></div>
+</header>
+<main>
+  <div class="grid tiles" id="tiles"></div>
+
+  <div class="card mt">
+    <h2>Findings by severity</h2>
+    <div id="severity"></div>
+  </div>
+
+  <div class="grid cols mt">
+    <div class="card">
+      <h2>By source</h2>
+      <div id="sources"></div>
+    </div>
+    <div class="card">
+      <h2>Top rules</h2>
+      <div id="rules"></div>
+    </div>
+  </div>
+
+  <div class="card mt">
+    <h2>Activity over time (recent window)</h2>
+    <div class="legend">
+      <span><b style="background:var(--sev-high)"></b>findings</span>
+      <span><b style="background:var(--sev-info)"></b>unverified</span>
+    </div>
+    <div id="series"></div>
+  </div>
+
+  <div class="card mt">
+    <div class="row">
+      <h2 style="margin:0">Recent findings</h2>
+      <label>source
+        <select id="source-filter"><option value="">all sources</option></select>
+      </label>
+    </div>
+    <div id="findings" class="mt"></div>
+  </div>
+</main>
+<footer>
+  guardana-server · this dashboard is read-only and unauthenticated — do not expose
+  it to an untrusted network (see SECURITY.md). The time window covers the
+  collector's in-memory buffer, not long-range history.
+</footer>
+
+<script>
+const SEVS = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"];
+const SEV_VAR = s => getComputedStyle(document.documentElement)
+  .getPropertyValue("--sev-" + s.toLowerCase()).trim() || "var(--sev-info)";
+const esc = s => String(s == null ? "" : s).replace(/[&<>"']/g,
+  c => ({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"}[c]));
+const el = id => document.getElementById(id);
+let CATALOG = {};  // rule_id -> {name, description}, from /catalog
+const friendlyName = f => (CATALOG[f.rule_id] || {}).name || f.title || f.rule_id;
+
+function barRow(key, value, max, color, mono) {
+  const w = max > 0 ? Math.round((value / max) * 100) : 0;
+  return `<div class="bar-row"><div class="k${mono ? " mono" : ""}" title="${esc(key)}">`
+    + `${esc(key)}</div><div class="bar" style="width:${w}%;background:${color}"`
+    + ` title="${esc(key)}: ${value}"></div><div class="v">${value}</div></div>`;
+}
+
+function renderTiles(t) {
+  const tile = (n, l, warn) => `<div class="card tile${warn ? " warn" : ""}">`
+    + `<div class="n">${n}</div><div class="l">${l}</div></div>`;
+  el("tiles").innerHTML = tile(t.findings, "findings")
+    + tile(t.unverified, "unverified", t.unverified > 0)
+    + tile(t.sources, "sources") + tile(t.submissions, "submissions");
+}
+
+function renderSeverity(by) {
+  const max = Math.max(1, ...SEVS.map(s => by[s] || 0));
+  const any = SEVS.some(s => by[s]);
+  el("severity").innerHTML = any
+    ? SEVS.map(s => barRow(s, by[s] || 0, max, SEV_VAR(s))).join("")
+    : `<div class="empty">No findings yet.</div>`;
+}
+
+function renderSources(rows) {
+  if (!rows.length) {
+    el("sources").innerHTML = `<div class="empty">No sources yet.</div>`; return; }
+  el("sources").innerHTML = "<table><thead><tr><th>source</th><th>find.</th>"
+    + "<th>unver.</th><th>worst</th></tr></thead><tbody>"
+    + rows.map(r => `<tr><td class="mono" title="${esc(r.source)}">${esc(r.source)}</td>`
+      + `<td>${r.findings}</td><td>${r.unverified}</td><td>${sevPill(r.worst_severity)}</td></tr>`)
+      .join("") + "</tbody></table>";
+}
+
+function sevPill(s) { return s ? `<span class="pill sev-${esc(s)}">${esc(s)}</span>` : "—"; }
+
+function renderRules(rows) {
+  if (!rows.length) { el("rules").innerHTML = `<div class="empty">No findings yet.</div>`; return; }
+  const max = Math.max(1, ...rows.map(r => r.count));
+  el("rules").innerHTML = rows.map(r => {
+    const name = (CATALOG[r.rule_id] || {}).name || r.rule_id.replace(/^guardana\\./, "");
+    return barRow(name, r.count, max, "var(--accent)");
+  }).join("");
+}
+
+function renderSeries(series) {
+  if (series.length < 2) { el("series").innerHTML =
+    `<div class="empty">Not enough activity yet to plot a trend.</div>`; return; }
+  const W = 640, H = 120, P = 6;
+  const maxY = Math.max(1, ...series.map(b => Math.max(b.findings, b.unverified)));
+  const x = i => P + (i / (series.length - 1)) * (W - 2 * P);
+  const y = v => H - P - (v / maxY) * (H - 2 * P);
+  const path = key => series.map((b, i) => (i ? "L" : "M") + x(i).toFixed(1)
+    + " " + y(b[key]).toFixed(1)).join(" ");
+  const dots = key => series.map((b, i) =>
+    `<circle cx="${x(i).toFixed(1)}" cy="${y(b[key]).toFixed(1)}" r="2.5"
+      fill="${key === "findings" ? "var(--sev-high)" : "var(--sev-info)"}">`
+    + `<title>${b[key]} ${key}</title></circle>`).join("");
+  el("series").innerHTML = `<svg viewBox="0 0 ${W} ${H}" width="100%" height="${H}"
+    role="img" aria-label="findings and unverified over time">
+    <path d="${path("findings")}" fill="none" stroke="var(--sev-high)" stroke-width="2"/>
+    <path d="${path("unverified")}" fill="none" stroke="var(--sev-info)" stroke-width="2"
+      stroke-dasharray="4 3"/>${dots("findings")}${dots("unverified")}</svg>`;
+}
+
+function renderFindings(items) {
+  if (!items.length) { el("findings").innerHTML = `<div class="empty">No findings.</div>`; return; }
+  el("findings").innerHTML = items.map(f => {
+    const c = CATALOG[f.rule_id] || {}, ev = f.evidence || {}, v = f.verdict;
+    const tax = (f.taxonomy || []).map(t => `<span class="tax">${esc(t.id)}</span>`).join("");
+    const det = `<div class="det">`
+      + (c.description ? `<p>${esc(c.description)}</p>` : "")
+      + (ev.summary ? `<p><span class="lbl">evidence:</span> ${esc(ev.summary)}</p>` : "")
+      + (ev.detail ? `<p><span class="lbl">detail:</span> <code>${esc(ev.detail)}</code></p>` : "")
+      + `<p><span class="lbl">target:</span> <code>${esc(f.target_ref)}</code></p>`
+      + (v ? `<p><span class="lbl">verdict:</span> ${esc(v.outcome)} (confidence `
+          + `${Number(v.confidence).toFixed(2)}, ${esc(v.evaluator_id)})`
+          + (v.rationale ? ` — ${esc(v.rationale)}` : "") + `</p>` : "")
+      + (tax ? `<p>${tax}</p>` : "") + `</div>`;
+    return `<details class="f"><summary><span>${sevPill(f.severity)}</span>`
+      + `<span class="fname">${esc(friendlyName(f))}`
+      + `<span class="rid">${esc(f.rule_id)}</span></span>`
+      + `<span class="fsrc" title="${esc(f.target_ref)}">${esc(f.target_ref)}</span>`
+      + `</summary>${det}</details>`;
+  }).join("");
+}
+
+function populateSourceFilter(rows) {
+  const sel = el("source-filter"), cur = sel.value;
+  sel.innerHTML = `<option value="">all sources</option>`
+    + rows.map(r => `<option value="${esc(r.source)}">${esc(r.source)}</option>`).join("");
+  sel.value = cur;
+}
+
+async function loadCatalog() {
+  try { CATALOG = await (await fetch("catalog")).json(); } catch (e) { CATALOG = {}; }
+}
+
+async function loadFindings() {
+  const src = el("source-filter").value;
+  const url = "findings?limit=100" + (src ? "&source=" + encodeURIComponent(src) : "");
+  const box = el("findings"), innerScroll = box.scrollTop;
+  const items = (await (await fetch(url)).json())
+    .flatMap(sub => (sub.findings || []).concat(sub.unverified || []));
+  renderFindings(items.slice(0, 100));
+  box.scrollTop = innerScroll;  // keep the reader's place across refresh
+}
+
+async function loadStats() {
+  const s = await (await fetch("stats")).json();
+  renderTiles(s.totals); renderSeverity(s.by_severity);
+  renderSources(s.by_source); renderRules(s.by_rule); renderSeries(s.series);
+  populateSourceFilter(s.by_source);
+  el("updated").textContent = "updated " + new Date().toLocaleTimeString();
+}
+
+async function refresh() {
+  const pageScroll = window.scrollY;
+  try { await loadStats(); await loadFindings(); window.scrollTo(0, pageScroll); }
+  catch (e) { el("updated").textContent = "collector unreachable"; }
+}
+
+el("source-filter").addEventListener("change", loadFindings);
+loadCatalog().then(refresh);
+setInterval(refresh, __REFRESH_MS__);
+</script>
+</body>
+</html>
+"""

guardana/server/envelope.py

@@ -0,0 +1,80 @@
+"""The wire contract between a Guardana agent and the collector.
+
+The collector never imports the engine: it accepts a normalized JSON envelope
+produced by `guardana.core.reporter`, validated here. `SCHEMA_VERSION` is what
+makes that independence safe — an agent and a collector can be upgraded apart,
+and a version the collector does not understand is rejected, never guessed at.
+"""
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field, StringConstraints
+
+SCHEMA_VERSION = 2
+
+# Ingest is untrusted input: an unbounded body would let one POST exhaust the
+# collector's memory (the store bounds submission *count*, not bytes). These caps
+# make Pydantic reject an oversized body at the door, before anything is stored.
+_MAX_FINDINGS = 5_000
+_MAX_SKIPPED = 5_000
+_Str = Annotated[str, StringConstraints(max_length=4_096)]
+_Text = Annotated[str, StringConstraints(max_length=65_536)]
+
+
+class TaxonomyRefIn(BaseModel):
+    """A standards reference (OWASP/ATLAS/NIST) carried by a finding."""
+
+    framework: _Str
+    id: _Str
+
+
+class EvidenceIn(BaseModel):
+    """Why the finding was raised. Redacted by the agent before it is sent."""
+
+    summary: _Text
+    detail: _Text | None = None
+
+
+class VerdictIn(BaseModel):
+    """An evaluator's judgement, present only on dynamic findings."""
+
+    outcome: _Str
+    confidence: float
+    rationale: _Text | None = None
+    evaluator_id: _Str | None = None
+
+
+class FindingIn(BaseModel):
+    """One finding, as serialized by `guardana.core.report.serialize`."""
+
+    rule_id: _Str
+    severity: _Str
+    title: _Text
+    target_ref: _Text
+    evidence: EvidenceIn
+    taxonomy: list[TaxonomyRefIn] = Field(default_factory=list, max_length=64)
+    verdict: VerdictIn | None = None
+
+
+class SummaryIn(BaseModel):
+    """What the run did, beyond the findings themselves."""
+
+    rules_run: int = 0
+    rules_skipped: list[_Str] = Field(default_factory=list, max_length=_MAX_SKIPPED)
+    max_severity: _Str | None = None
+    unverified: int = 0
+
+
+class Submission(BaseModel):
+    """One agent's scan result, as POSTed to `/findings`."""
+
+    source: _Str
+    # Required, not defaulted: an omitted version must be rejected, not silently
+    # assumed to be v1. Guessing at a version we don't understand is exactly what
+    # versioning exists to prevent.
+    schema_version: int
+    findings: list[FindingIn] = Field(default_factory=list, max_length=_MAX_FINDINGS)
+    # Checks that ran but could not reach a verdict — stored, never discarded, so
+    # the collector can surface "these were not graded" instead of an all-clear.
+    unverified: list[FindingIn] = Field(default_factory=list, max_length=_MAX_FINDINGS)
+    summary: SummaryIn | None = None

guardana/server/rule_catalog.py

@@ -0,0 +1,25 @@
+"""Loads the human-readable rule catalog the dashboard shows instead of bare ids.
+
+The catalog is a plain JSON file (`catalog/en.json`) — English for now, structured
+so a translation (`catalog/pl.json`, …) can slot in later. It is bundled with the
+server so the collector stays self-sufficient; a rule id it doesn't know about
+(a custom, third-party rule) simply falls back to the id and the finding's own
+title on the page.
+"""
+
+import json
+from functools import cache
+from importlib.resources import files
+
+_DEFAULT_LANGUAGE = "en"
+
+
+@cache
+def rule_catalog(language: str = _DEFAULT_LANGUAGE) -> dict[str, dict[str, str]]:
+    """Return `{rule_id: {"name", "description"}}` for the given language (English by default)."""
+    resource = files("guardana.server.catalog").joinpath(f"{language}.json")
+    if not resource.is_file():
+        return {}
+    data = json.loads(resource.read_text(encoding="utf-8"))
+    rules = data.get("rules", {})
+    return rules if isinstance(rules, dict) else {}

guardana/server/stats.py

@@ -0,0 +1,162 @@
+"""Pure aggregation of stored submissions into the shape the dashboard renders.
+
+Kept separate from the store and the app so it can be tested in isolation: given
+a list of `StoredSubmission`, `compute_stats` returns typed counts and a
+time-series, with no I/O and no framework.
+"""
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from guardana.server.store import StoredSubmission
+
+# Ordinal severity, worst last — used to pick a source's worst finding.
+_SEVERITY_ORDER = ("INFO", "LOW", "MEDIUM", "HIGH", "CRITICAL")
+
+
+def _severity_rank(severity: str) -> int:
+    try:
+        return _SEVERITY_ORDER.index(severity)
+    except ValueError:
+        return -1
+
+
+@dataclass(frozen=True, slots=True)
+class SourceStat:
+    """One reporting source (a scanned path or a probed endpoint)."""
+
+    source: str
+    findings: int
+    unverified: int
+    worst_severity: str | None
+    last_seen: float
+
+
+@dataclass(frozen=True, slots=True)
+class RuleStat:
+    """How many findings a single rule produced across the fleet."""
+
+    rule_id: str
+    count: int
+
+
+@dataclass(frozen=True, slots=True)
+class TimeBucket:
+    """Findings and ungraded checks received within one time bucket."""
+
+    t: float
+    findings: int
+    unverified: int
+
+
+@dataclass(frozen=True, slots=True)
+class Totals:
+    """Headline counters across everything stored."""
+
+    submissions: int
+    sources: int
+    findings: int
+    unverified: int
+
+
+@dataclass(frozen=True, slots=True)
+class Stats:
+    """Everything the dashboard needs, computed server-side so the client never re-aggregates."""
+
+    by_severity: dict[str, int]
+    by_source: list[SourceStat]
+    by_rule: list[RuleStat]
+    series: list[TimeBucket]
+    totals: Totals
+
+
+def compute_stats(
+    records: Iterable[StoredSubmission], *, buckets: int = 24, top_rules: int = 10
+) -> Stats:
+    """Aggregate stored submissions into dashboard stats. Pure; safe on empty input."""
+    ordered = sorted(records, key=lambda r: r.received_at)
+    by_severity: dict[str, int] = {}
+    by_rule_counts: dict[str, int] = {}
+    source_findings: dict[str, int] = {}
+    source_unverified: dict[str, int] = {}
+    source_worst: dict[str, int] = {}
+    source_last_seen: dict[str, float] = {}
+    total_findings = 0
+    total_unverified = 0
+
+    for record in ordered:
+        submission = record.submission
+        source = submission.source
+        source_last_seen[source] = record.received_at
+        source_findings.setdefault(source, 0)
+        source_unverified.setdefault(source, 0)
+        source_unverified[source] += len(submission.unverified)
+        total_unverified += len(submission.unverified)
+        for finding in submission.findings:
+            total_findings += 1
+            by_severity[finding.severity] = by_severity.get(finding.severity, 0) + 1
+            by_rule_counts[finding.rule_id] = by_rule_counts.get(finding.rule_id, 0) + 1
+            source_findings[source] += 1
+            rank = _severity_rank(finding.severity)
+            if rank > source_worst.get(source, -2):
+                source_worst[source] = rank
+
+    by_source = [
+        SourceStat(
+            source=source,
+            findings=source_findings[source],
+            unverified=source_unverified[source],
+            worst_severity=(
+                _SEVERITY_ORDER[source_worst[source]] if source in source_worst else None
+            ),
+            last_seen=source_last_seen[source],
+        )
+        for source in sorted(source_findings, key=lambda s: source_findings[s], reverse=True)
+    ]
+    by_rule = [
+        RuleStat(rule_id=rule_id, count=count)
+        for rule_id, count in sorted(by_rule_counts.items(), key=lambda kv: kv[1], reverse=True)[
+            :top_rules
+        ]
+    ]
+    return Stats(
+        by_severity=by_severity,
+        by_source=by_source,
+        by_rule=by_rule,
+        series=_series(ordered, buckets),
+        totals=Totals(
+            submissions=len(ordered),
+            sources=len(source_findings),
+            findings=total_findings,
+            unverified=total_unverified,
+        ),
+    )
+
+
+def _series(ordered: list[StoredSubmission], buckets: int) -> list[TimeBucket]:
+    """Bucket submissions across their observed time span. Robust on empty/degenerate input."""
+    if not ordered:
+        return []
+    t_min = ordered[0].received_at
+    t_max = ordered[-1].received_at
+    span = t_max - t_min
+    if span <= 0:  # a single submission, or several at the same instant → one bucket
+        return [
+            TimeBucket(
+                t=t_min,
+                findings=sum(len(r.submission.findings) for r in ordered),
+                unverified=sum(len(r.submission.unverified) for r in ordered),
+            )
+        ]
+    n = max(1, min(buckets, len(ordered)))
+    width = span / n
+    findings = [0] * n
+    unverified = [0] * n
+    for record in ordered:
+        index = min(n - 1, int((record.received_at - t_min) / width))
+        findings[index] += len(record.submission.findings)
+        unverified[index] += len(record.submission.unverified)
+    return [
+        TimeBucket(t=t_min + i * width, findings=findings[i], unverified=unverified[i])
+        for i in range(n)
+    ]

guardana/server/store.py

@@ -0,0 +1,93 @@
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol
+
+from guardana.server.envelope import Submission
+
+# The default store is a process-lifetime buffer, so it is bounded: a collector
+# left running must not grow without limit. Durable storage is the seam a cloud
+# backend replaces (see SECURITY.md — do not expose this one to an untrusted network).
+MAX_SUBMISSIONS = 10_000
+
+
+@dataclass(frozen=True, slots=True)
+class StoredSubmission:
+    """A submission plus when the collector received it — the time axis of the dashboard."""
+
+    received_at: float
+    submission: Submission
+
+
+class Store(Protocol):
+    """Persists reporter submissions. The seam a paid cloud backend replaces."""
+
+    def add(self, submission: Submission) -> None:
+        """Store one submission, stamping it with the receive time."""
+        ...
+
+    def submissions(self, source: str | None = None) -> list[Submission]:
+        """Return every submission, optionally filtered to one source."""
+        ...
+
+    def trend(self) -> dict[str, int]:
+        """Return finding counts by severity, across everything stored."""
+        ...
+
+    def records(self) -> list[StoredSubmission]:
+        """Return every stored submission with its receive time — raw data for stats."""
+        ...
+
+
+class InMemoryStore:
+    """Default `Store`: keeps the most recent submissions for the process lifetime.
+
+    FastAPI runs sync endpoints in a threadpool, so reads and writes genuinely
+    race. A lock guards every access — iterating the deque while another thread
+    appends (and, once full, evicts) would otherwise raise `RuntimeError` and 500
+    every reader after one concurrent write.
+
+    `clock` is injectable so tests get deterministic `received_at` timestamps (the
+    same pattern the monitor uses for `sleep`).
+    """
+
+    def __init__(
+        self,
+        max_submissions: int = MAX_SUBMISSIONS,
+        *,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self._records: deque[StoredSubmission] = deque(maxlen=max_submissions)
+        self._lock = threading.Lock()
+        self._clock = clock
+
+    def add(self, submission: Submission) -> None:
+        """Store one submission (stamped with the receive time), evicting the oldest when full."""
+        record = StoredSubmission(received_at=self._clock(), submission=submission)
+        with self._lock:
+            self._records.append(record)
+
+    def submissions(self, source: str | None = None) -> list[Submission]:
+        """Return every submission held, optionally filtered to one source."""
+        held = [record.submission for record in self._snapshot()]
+        if source is None:
+            return held
+        return [s for s in held if s.source == source]
+
+    def trend(self) -> dict[str, int]:
+        """Return finding counts by severity, across everything held."""
+        counts: dict[str, int] = {}
+        for record in self._snapshot():
+            for finding in record.submission.findings:
+                counts[finding.severity] = counts.get(finding.severity, 0) + 1
+        return counts
+
+    def records(self) -> list[StoredSubmission]:
+        """Return every stored submission with its receive time (oldest first)."""
+        return self._snapshot()
+
+    def _snapshot(self) -> list[StoredSubmission]:
+        with self._lock:
+            return list(self._records)

guardana_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: guardana-server
+Version: 0.1.0
+Summary: Guardana collector: minimal FastAPI server that ingests and lists findings.
+Project-URL: Homepage, https://guardana.io
+Project-URL: Repository, https://github.com/guardana/guardana
+Project-URL: Documentation, https://guardana.dev
+Project-URL: Issues, https://github.com/guardana/guardana/issues
+Project-URL: Changelog, https://github.com/guardana/guardana/blob/main/CHANGELOG.md
+Author-email: Guardana contributors <maintainers@guardana.io>
+Maintainer-email: Guardana contributors <maintainers@guardana.io>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai-security,llm,mlsecops,prompt-injection,security-scanner
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# guardana-server
+
+Guardana's optional collector — a minimal FastAPI service that ingests findings
+from many agents and, optionally, serves a read-only monitoring dashboard.
+
+Part of **[Guardana](https://github.com/guardana/guardana)** — security
+verification for self-hosted and self-built AI (model files, live endpoints,
+and agents) from one rule engine that runs on your laptop, in CI, and next to
+a served model.
+
+## Run it
+
+```bash
+# API only (POST/GET /findings, GET /trend):
+uvicorn --factory guardana.server:create_app
+
+# With the opt-in dashboard (adds GET / and GET /stats):
+GUARDANA_DASHBOARD=1 uvicorn --factory guardana.server:create_app
+# or, from your own code: create_app(dashboard=True, refresh_seconds=15)
+```
+
+The dashboard is a single self-contained page (no build step, works offline)
+showing severity, per-source/per-rule breakdowns, an activity-over-time trend,
+the `unverified` counter, and a filterable recent-findings table. It is
+**read-only and unauthenticated** — do not expose it to an untrusted network
+(see [SECURITY.md](https://github.com/guardana/guardana/blob/main/SECURITY.md)).
+
+- Main README & quickstart: https://github.com/guardana/guardana#readme
+- Documentation: https://guardana.dev
+
+Licensed under Apache-2.0.

guardana_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+guardana/server/__init__.py,sha256=azrxMC-4zeHqOk5sAEksmWUadfQ2hCe68FESVWYxgxs,165
+guardana/server/app.py,sha256=90SeaoNBkMS3aZqfo7hVHgdPCdQBJ3cNparztSEh2-w,2898
+guardana/server/dashboard.py,sha256=mYuw-jTiW-QxtiBwiFqnMOTLqDe1TN-BcbbrqWeYC4I,13883
+guardana/server/envelope.py,sha256=WCAqj7rkUYvOzHMQ-U1tWFprKOhV9Zf36h_ZzEfrHhQ,2707
+guardana/server/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+guardana/server/rule_catalog.py,sha256=-gf7OzGyPqB4BV6U_veyd0EjN2_OGSz3W9xv9aUPuG8,1000
+guardana/server/stats.py,sha256=qtO3Ohl7EiCeHizsy8tSpeCa8turse0HCA5h4crFgGo,5197
+guardana/server/store.py,sha256=ljg0U6CnbSfavNvb0_vY6YgWKU7vAKVF1lqx-EWbRFM,3461
+guardana/server/catalog/__init__.py,sha256=yGj5wgQIcLCY2oF8QlvIh3h9WnXKCH2n-7gc51snP9o,76
+guardana/server/catalog/en.json,sha256=fArsMiC-4dIQF0knFhLua2EWdVG3lZrd4TwKGUSUicw,8029
+guardana_server-0.1.0.dist-info/METADATA,sha256=CEowjlfQQ5Bj1Ve1kaFvgeFbSx_UyLLe1ARWTXQjK-c,2444
+guardana_server-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+guardana_server-0.1.0.dist-info/licenses/LICENSE,sha256=ZQhRridXNGA1cvM3x69Uon-GKhKSWBAdEx43KkRCpgM,11352
+guardana_server-0.1.0.dist-info/RECORD,,

guardana_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

guardana_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Guardana 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.