ai-guardian

AI Guardian

Disclaimer: Community-maintained open-source project, not affiliated with, endorsed by, or sponsored by Ollama, IGEL, or any AI-security vendor. Product and trademark names belong to their owners. Source at github.com/AIops-tools/AI-Guardian under the MIT license.

Governed observability + governance for on-endpoint local LLMs (Ollama) — 21 MCP tools, every one wrapped with the bundled @governed_tool harness: a local unified audit log under ~/.ai-guardian/, token/runaway budget guard, undo-token recording, and descriptive risk tiers. It is the complement to IGEL AI Armor: AI Armor governs whether a local model may run; ai-guardian records what it did and gates what leaves in the prompt.

Ollama keeps no queryable prompt history (context is client-supplied each request), so ai-guardian observes on two fronts: passive inventory / state auditing over /api/tags, /api/ps, /api/show, /api/version; and opt-in route-through content governance — a caller sends a prompt through guarded_generate / observe_chat, which scans + policy-gates + records it and only then calls Ollama.

Standalone: the governance harness is bundled in the package (ai_guardian.governance) — no external skill-family dependency. A transparent capture proxy for other clients' traffic is v0.2 roadmap, and IGEL AI Armor interop is doc-level positioning.

What This Skill Does

scan_prompt is pure (no Ollama call). guarded_generate / observe_chat block when the prompt's risk band >= block_threshold (default high) or the model is disallowed; blocked calls never reach Ollama and are recorded as blocked.

Quick Install

uv tool install ai-guardian-aiops
ai-guardian doctor          # works zero-config against a local Ollama
ai-guardian init            # optional: endpoint(s) + optional token + model allowlist

When to Use This Skill

• Inventory local models and spot shadow AI (list_models / anomaly_report): unsanctioned models show allowed:false
• Scan a prompt before sending it (scan_prompt): secrets / PII / source-code / jailbreak → a weighted risk band, no model call
• Stop secrets or PII leaking into a local model (guarded_generate / observe_chat): scan + policy-gate + record, then run only if allowed
• Detect a tampered / re-pulled model (model_provenance): current digest vs its pin → drift
• Enforce which models may run (set_model_allowlist / set_model_denylist) and pin trusted digests (pin_model_digest)
• Inspect VRAM residency (running_models / vram_usage) and audit observed usage (usage_events)

Do NOT use when the target is a GPU inference cluster (multi-node serving) — that is a different tool in the AIops-tools line. Also not for hypervisors, storage appliances, backup products, container clusters, or network devices.

Related Skills — Skill Routing

Common Workflows

1. Find and shut down shadow (unsanctioned) local models

1. ai-guardian doctor → confirm the Ollama endpoint is reachable before you conclude a fleet has "no models" when it really has no connectivity
2. ai-guardian overview → endpoint status, model count, and what is loaded right now
3. ai-guardian model list (MCP: list_models) → every installed model with its allow/deny verdict; anything allowed:false is shadow AI
4. ai-guardian guard anomalies (MCP: anomaly_report) → a one-shot rollup of shadow models + digest drift + high-risk / blocked prompts, so you can tell a single stray pull from a pattern
5. ai-guardian model running / vram_usage → is the shadow model merely installed, or actually loaded and consuming VRAM right now?
6. Tighten policy so it cannot recur: set_model_allowlist(["llama3.*", "qwen*"]) → future unsanctioned models are refused at pull_model. Reversible: the prior list is captured as the undo descriptor
7. Remove the offender: ai-guardian model remove --dry-run, then re-run without --dry-run → high risk, double confirmation, needs AI_GUARDIAN_AUDIT_APPROVED_BY; the undo descriptor records a re-pull
8. Failure branch: if the new allowlist turns out to be too tight and blocks a sanctioned model, ai-guardian undo list → undo apply restores the prior list exactly. If a removal was wrong, replaying the undo re-pulls the model — but the weights come from the registry, so confirm the digest afterwards with workflow 3 rather than assuming it is bit-identical.

2. Stop secrets and PII leaking into a local model

1. ai-guardian guard scan "…text…" (MCP: scan_prompt) → a pure call, no model involved: deterministic findings (secrets / PII / code / jailbreak) plus a weighted risk band. Use it to pre-check content offline before it ever reaches a model
2. ai-guardian guard policy (MCP: policy_view) → confirm which models are permitted and what the current thresholds are
3. Route real calls through the guard: guarded_generate(model, prompt, block_threshold="high") → the guard scans, records to the usage log, and blocks before Ollama if the risk band is >= high or the model is disallowed
4. ai-guardian guard usage (MCP: usage_events(allowed=False)) → review what was caught. The raw prompt is never stored — only its length and redacted findings, so reviewing the log cannot itself leak the secret
5. ai-guardian guard anomalies → confirm the rate of blocked prompts is falling after you educate the user or fix the calling integration
6. Failure branch: route-through is opt-in — anything that calls Ollama directly bypasses the guard entirely. If usage_events is suspiciously empty while running_models shows activity, you are looking at un-routed traffic, not a clean fleet. A transparent capture proxy is a v0.2 roadmap item; until then, treat guard coverage as coverage of what was routed, and say so.

3. Detect tampered or silently re-pulled model weights

1. ai-guardian model list / model_details → read the current digest for the models you sanction
2. pin_model_digest(model, digest) → pin the trusted digest once, while you still trust it. Pinning after a suspected compromise pins the compromise
3. Later (or on a schedule): ai-guardian guard provenance (MCP: model_provenance) → any model whose current digest differs from its pin reports status: DRIFT — re-pulled or tampered weights
4. usage_events around the drift timestamp → was the drifted model used, and for what, before you noticed?
5. Failure branch: DRIFT is a statement about the digest, not about intent — a legitimate upgrade drifts identically to tampering. Investigate before removing: check whether a pull_model appears in the audit trail at ~/.ai-guardian/audit.db. If it does not, treat it as untrusted and remove under workflow 1. Re-pin only once you have re-established what the digest should be.

4. Fleet hygiene review before a rollout

1. ai-guardian overview → the endpoint's current state at a glance
2. ai-guardian model list → the full inventory with allow/deny verdicts
3. ai-guardian guard provenance → every pinned model still matching its digest
4. vram_usage + running_models → what is resident and whether the endpoint has headroom for the model you are about to roll out
5. unload_model → free VRAM from an idle model without removing it (reversible in practice — it reloads on next use)
6. ai-guardian model pull → the pull is checked against the allowlist, so an unsanctioned rollout is refused rather than merely logged
7. ai-guardian guard anomalies → a clean rollup is the exit criterion for the review
8. Failure branch: if pull_model is refused, the model is not on the allowlist — widen the policy deliberately with set_model_allowlist (audited, reversible) rather than working around the guard. If the pull fails on VRAM, unload_model an idle model first; the audit trail records the failed attempt with status=error and no undo token.

Governance & Safety

The skill delivers reads and writes and records them; it does not decide whether a write is permitted. That is your agent's judgement, or the permission of the host and account you run it under (point it at a runtime the account cannot administer, or hand the agent only the scan/observe tools). There is no read-only switch, deny-rules file, or approval gate — content governance (the model allow/deny policy and the guarded_generate block threshold) is a separate, product-level control that stays.

• Audit is the guarantee, and it is not bypassable. Every operation — MCP and CLI alike — is logged to ~/.ai-guardian/audit.db (relocatable via AI_GUARDIAN_AIOPS_HOME): params, result, status, duration, and the risk tier. Observed local-LLM usage lives in a separate ~/.ai-guardian/usage.db.
• AI_GUARDIAN_AUDIT_APPROVED_BY / AI_GUARDIAN_AUDIT_RATIONALE are optional annotations recorded on the audit row (who/why); they are never required and never block.
• Runaway guard — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with AI_GUARDIAN_RUNAWAY_MAX=0.
• remove_model supports --dry-run + double confirmation at the CLI and records an undo (re-pull); allowlist/denylist writes record an undo → the prior list.
• The scanner is deterministic and offline; findings are redacted so a secret is never re-emitted.

References

• references/capabilities.md — full 21-tool + endpoint reference
• references/cli-reference.md — CLI command reference
• references/setup-guide.md — onboarding, optional token, and connectivity