Merge branch 'main' into feat/ci-optimization-and-instructions

Author: imran-siddique

notebooks/01_policy_enforcement_101.ipynb

@@ -0,0 +1,204 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ "metadata": {
+  "colab": {
+   "name": "01_policy_enforcement_101.ipynb",
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  }
+ },
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 🛡️ Policy Enforcement 101\n",
+    "**Agent Governance Toolkit — Interactive Demo**\n",
+    "\n",
+    "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/microsoft/agent-governance-toolkit/blob/main/notebooks/01_policy_enforcement_101.ipynb)\n",
+    "\n",
+    "In this notebook you will:\n",
+    "- Define agent capabilities using `CapabilityModel`\n",
+    "- Evaluate actions against a `GovernancePolicy`\n",
+    "- See violations get blocked in real time\n",
+    "- Inspect the audit trail\n",
+    "\n",
+    "> **No API key required** — this demo runs fully offline."
+   ],
+   "id": "intro"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": ["## Step 1 — Install the toolkit"],
+   "id": "install-header"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install agent-governance-toolkit[full] -q"
+   ],
+   "id": "install"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": ["## Step 2 — Define a Governance Policy"],
+   "id": "policy-header"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from agent_os.integrations.base import GovernancePolicy\n",
+    "\n",
+    "policy = GovernancePolicy(\n",
+    "    name=\"demo-policy\",\n",
+    "    blocked_patterns=[\n",
+    "        \"DROP TABLE\",      # dangerous SQL\n",
+    "        \"rm -rf\",          # destructive shell commands\n",
+    "        r\"\\b\\d{3}-\\d{2}-\\d{4}\\b\",  # SSN pattern\n",
+    "    ],\n",
+    "    require_human_approval=False,\n",
+    "    max_tool_calls=5,\n",
+    ")\n",
+    "\n",
+    "print(f\"Policy created: {policy.name}\")\n",
+    "print(f\"Max tool calls allowed: {policy.max_tool_calls}\")\n",
+    "print(f\"Blocked patterns: {policy.blocked_patterns}\")"
+   ],
+   "id": "policy"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": ["## Step 3 — Create a LangChain Governed Agent"],
+   "id": "kernel-header"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from agent_os.integrations import LangChainKernel\n",
+    "\n",
+    "kernel = LangChainKernel(policy=policy)\n",
+    "ctx = kernel.create_context(\"demo-agent\")\n",
+    "audit = []\n",
+    "\n",
+    "print(\"Kernel and context created successfully.\")"
+   ],
+   "id": "kernel"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": ["## Step 4 — Test Policy Violations"],
+   "id": "violations-header"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from datetime import datetime\n",
+    "\n",
+    "test_inputs = [\n",
+    "    (\"DROP TABLE users; SELECT 1\",  \"Dangerous SQL\"),\n",
+    "    (\"Run: rm -rf /var/logs\",        \"Destructive shell command\"),\n",
+    "    (\"My SSN is 123-45-6789\",        \"PII — SSN pattern\"),\n",
+    "    (\"What is the weather in London?\", \"Safe query\"),\n",
+    "]\n",
+    "\n",
+    "print(f\"{'Input':<45} {'Result':<10} Reason\")\n",
+    "print(\"-\" * 80)\n",
+    "\n",
+    "for text, label in test_inputs:\n",
+    "    allowed, reason = kernel.pre_execute(ctx, text)\n",
+    "    status = \"✅ ALLOWED\" if allowed else \"🚫 BLOCKED\"\n",
+    "    print(f\"{label:<45} {status:<10} {reason}\")\n",
+    "    audit.append({\n",
+    "        \"ts\": datetime.now().isoformat(),\n",
+    "        \"label\": label,\n",
+    "        \"status\": \"ALLOWED\" if allowed else \"BLOCKED\",\n",
+    "        \"reason\": reason,\n",
+    "    })"
+   ],
+   "id": "violations"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": ["## Step 5 — Test Call Budget Enforcement"],
+   "id": "budget-header"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(\"Simulating call budget exhaustion...\")\n",
+    "ctx.call_count = policy.max_tool_calls\n",
+    "\n",
+    "allowed, reason = kernel.pre_execute(ctx, \"Summarise the quarterly report\")\n",
+    "print(f\"Status: {'✅ ALLOWED' if allowed else '🚫 BLOCKED'}\")\n",
+    "print(f\"Reason: {reason}\")\n",
+    "\n",
+    "ctx.call_count = 0  # reset"
+   ],
+   "id": "budget"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": ["## Step 6 — View Audit Trail"],
+   "id": "audit-header"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(\"\\n── Audit Trail ──────────────────────────────────────\")\n",
+    "for i, entry in enumerate(audit, 1):\n",
+    "    print(f\"  [{i}] {entry['ts']}\")\n",
+    "    print(f\"       Input:  {entry['label']}\")\n",
+    "    print(f\"       Status: {entry['status']}\")\n",
+    "    print(f\"       Reason: {entry['reason']}\")\n",
+    "    print()\n",
+    "\n",
+    "blocked = sum(1 for e in audit if e['status'] == 'BLOCKED')\n",
+    "allowed = len(audit) - blocked\n",
+    "print(f\"Summary: {allowed} allowed, {blocked} blocked out of {len(audit)} total\")"
+   ],
+   "id": "audit"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## ✅ What You Learned\n",
+    "\n",
+    "- How to define a `GovernancePolicy` with blocked patterns and call budgets\n",
+    "- How the governance layer intercepts agent actions before execution\n",
+    "- How to inspect the audit trail for compliance reporting\n",
+    "\n",
+    "**Next:** Try the [MCP Security Proxy notebook →](./02_mcp_security_proxy.ipynb)"
+   ],
+   "id": "summary"
+  }
+ ]
+}