{
  "nbformat": 4,
  "nbformat_minor": 5,
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "version": "3.13.0"
    },
    "blog_metadata": {
      "topic": "If your hosted agents can reach anything, you don’t have governance — you have hope",
      "slug": "if-your-hosted-agents-can-reach-anything-you-don-t-have-gove",
      "generated_by": "LinkedIn Post Generator + Azure OpenAI",
      "generated_at": "2026-09-23T00:42:21.647Z"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# If your hosted agents can reach anything, you don’t have governance — you have hope\n",
        "\n",
        "This notebook turns the blog post into a hands-on validation workflow for agent connectivity governance. The focus is simple: define an explicit allowlist for tools and destinations, test both allowed and denied paths, generate evidence, detect drift, and simulate release gating so governance is based on behavior rather than intent."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "%pip install -q pandas"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "from dataclasses import dataclass, asdict\n",
        "from typing import List, Dict, Any\n",
        "from datetime import datetime\n",
        "import json\n",
        "import os\n",
        "import tempfile\n",
        "import pandas as pd"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Approval flow as executable data\n",
        "\n",
        "The post starts with an approval flow: define the baseline, run a validation harness, attach evidence, then deploy and continuously check for drift. Since Mermaid is not executable Python, this cell represents the same flow as structured data you can inspect and reuse in tests."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "approval_flow = {\n",
        "    \"nodes\": [\n",
        "        \"Developer defines agent\",\n",
        "        \"Approved tools + destinations baseline\",\n",
        "        \"Pre-production validation harness\",\n",
        "        \"Scenario allowed?\",\n",
        "        \"Tool call succeeds\",\n",
        "        \"Tool call blocked\",\n",
        "        \"Evidence report\",\n",
        "        \"Approval record / change review\",\n",
        "        \"Deploy hosted agent\",\n",
        "        \"Continuous drift check\",\n",
        "    ],\n",
        "    \"edges\": [\n",
        "        (\"Developer defines agent\", \"Approved tools + destinations baseline\"),\n",
        "        (\"Approved tools + destinations baseline\", \"Pre-production validation harness\"),\n",
        "        (\"Pre-production validation harness\", \"Scenario allowed?\"),\n",
        "        (\"Scenario allowed?\", \"Tool call succeeds\"),\n",
        "        (\"Scenario allowed?\", \"Tool call blocked\"),\n",
        "        (\"Tool call succeeds\", \"Evidence report\"),\n",
        "        (\"Tool call blocked\", \"Evidence report\"),\n",
        "        (\"Evidence report\", \"Approval record / change review\"),\n",
        "        (\"Approval record / change review\", \"Deploy hosted agent\"),\n",
        "        (\"Deploy hosted agent\", \"Continuous drift check\"),\n",
        "    ]\n",
        "}\n",
        "\n",
        "print(json.dumps(approval_flow, indent=2))"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Define the approved baseline\n",
        "\n",
        "This example creates the explicit governance baseline from the post: approved tools, approved destinations, and a set of scenarios with expected allow or block outcomes. The key idea is deny by default unless a tool and destination are both named."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "# Define approved tools, destinations, and validation scenarios for agent governance\n",
        "from dataclasses import dataclass\n",
        "from typing import List\n",
        "\n",
        "@dataclass\n",
        "class Scenario:\n",
        "    name: str\n",
        "    tool: str\n",
        "    destination: str\n",
        "    should_allow: bool\n",
        "\n",
        "APPROVED_TOOLS = {\"search_docs\", \"ticket_lookup\"}\n",
        "APPROVED_DESTINATIONS = {\"https://docs.contoso.internal\", \"https://tickets.contoso.internal\"}\n",
        "\n",
        "SCENARIOS: List[Scenario] = [\n",
        "    Scenario(\"approved-doc-search\", \"search_docs\", \"https://docs.contoso.internal\", True),\n",
        "    Scenario(\"approved-ticket-lookup\", \"ticket_lookup\", \"https://tickets.contoso.internal\", True),\n",
        "    Scenario(\"blocked-external-web\", \"search_docs\", \"https://example.com\", False),\n",
        "    Scenario(\"blocked-unapproved-tool\", \"shell_exec\", \"https://docs.contoso.internal\", False),\n",
        "]\n",
        "\n",
        "print(\"Approved tools:\", APPROVED_TOOLS)\n",
        "print(\"Approved destinations:\", APPROVED_DESTINATIONS)\n",
        "print(\"Scenarios:\")\n",
        "for s in SCENARIOS:\n",
        "    print(asdict(s))"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Run a pre-production validation harness\n",
        "\n",
        "This harness evaluates each scenario against the approved baseline and emits a JSON evidence report. In a real delivery pipeline, this report should be stored with the approval record so reviewers can see expected versus actual behavior."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "# Run a pre-production validation harness and emit an evidence report for approval records\n",
        "import json\n",
        "from datetime import datetime\n",
        "\n",
        "approved_tools = {\"search_docs\", \"ticket_lookup\"}\n",
        "approved_destinations = {\"https://docs.contoso.internal\", \"https://tickets.contoso.internal\"}\n",
        "scenarios = [\n",
        "    {\"name\": \"approved-doc-search\", \"tool\": \"search_docs\", \"destination\": \"https://docs.contoso.internal\", \"should_allow\": True},\n",
        "    {\"name\": \"blocked-external-web\", \"tool\": \"search_docs\", \"destination\": \"https://example.com\", \"should_allow\": False},\n",
        "    {\"name\": \"blocked-unapproved-tool\", \"tool\": \"shell_exec\", \"destination\": \"https://docs.contoso.internal\", \"should_allow\": False},\n",
        "]\n",
        "\n",
        "results = []\n",
        "for s in scenarios:\n",
        "    allowed = s[\"tool\"] in approved_tools and s[\"destination\"] in approved_destinations\n",
        "    results.append({**s, \"actual_allow\": allowed, \"pass\": allowed == s[\"should_allow\"]})\n",
        "\n",
        "report = {\n",
        "    \"agent_id\": \"agent-preprod-001\",\n",
        "    \"generated_utc\": datetime.utcnow().isoformat() + \"Z\",\n",
        "    \"summary\": {\"total\": len(results), \"passed\": sum(r[\"pass\"] for r in results)},\n",
        "    \"results\": results,\n",
        "}\n",
        "print(json.dumps(report, indent=2))\n",
        "\n",
        "report_df = pd.DataFrame(report[\"results\"])\n",
        "report_df"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Fail the release when governance validation fails\n",
        "\n",
        "A warning is not governance. This example simulates a release gate: if any scenario fails, the release should be marked failed. To keep the notebook running, the code computes the same decision without terminating the kernel."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "# Fail the release if any validation scenario violates the approved governance baseline\n",
        "results = [\n",
        "    {\"name\": \"approved-doc-search\", \"pass\": True},\n",
        "    {\"name\": \"blocked-external-web\", \"pass\": True},\n",
        "    {\"name\": \"blocked-unapproved-tool\", \"pass\": False},\n",
        "]\n",
        "\n",
        "failed = [r[\"name\"] for r in results if not r[\"pass\"]]\n",
        "release_status = \"FAILED\" if failed else \"PASSED\"\n",
        "\n",
        "if failed:\n",
        "    print(\"Validation failed for scenarios:\", \", \".join(failed))\n",
        "else:\n",
        "    print(\"Validation passed: governance evidence is complete.\")\n",
        "\n",
        "print(\"Release status:\", release_status)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Translate infrastructure examples into reviewable Python artifacts\n",
        "\n",
        "The blog includes Bicep snippets for disabling public network access and tagging AI resources with approval metadata. This Python cell captures the same intent as dictionaries so you can validate the important governance properties in a notebook."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "search_resource = {\n",
        "    \"type\": \"Microsoft.Search/searchServices\",\n",
        "    \"apiVersion\": \"2023-11-01\",\n",
        "    \"name\": \"contoso-agent-search\",\n",
        "    \"location\": \"example-region\",\n",
        "    \"sku\": {\"name\": \"basic\"},\n",
        "    \"properties\": {\n",
        "        \"publicNetworkAccess\": \"disabled\",\n",
        "        \"networkRuleSet\": {\"ipRules\": []}\n",
        "    }\n",
        "}\n",
        "\n",
        "ai_resource = {\n",
        "    \"type\": \"Microsoft.CognitiveServices/accounts\",\n",
        "    \"apiVersion\": \"2023-05-01\",\n",
        "    \"name\": \"contoso-agent-host\",\n",
        "    \"location\": \"example-region\",\n",
        "    \"kind\": \"OpenAI\",\n",
        "    \"sku\": {\"name\": \"S0\"},\n",
        "    \"tags\": {\n",
        "        \"approvedTools\": \"search_docs,ticket_lookup\",\n",
        "        \"approvedDestinations\": \"docs.contoso.internal,tickets.contoso.internal\",\n",
        "        \"approvalRecordId\": \"ARB-2026-0142\"\n",
        "    }\n",
        "}\n",
        "\n",
        "print(\"Search resource review:\")\n",
        "print(json.dumps(search_resource, indent=2))\n",
        "print(\"\\nAI resource review:\")\n",
        "print(json.dumps(ai_resource, indent=2))\n",
        "\n",
        "assert search_resource[\"properties\"][\"publicNetworkAccess\"] == \"disabled\"\n",
        "assert \"approvalRecordId\" in ai_resource[\"tags\"]\n",
        "print(\"\\nGovernance checks passed for infrastructure intent.\")"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Export a portable checklist artifact\n",
        "\n",
        "The post uses PowerShell to export the approved tools and destinations into a checklist file. This Python version creates the same kind of portable artifact so security, platform, and application teams can review the same baseline."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "baseline = {\n",
        "    \"AgentId\": \"agent-prod-001\",\n",
        "    \"ApprovedTools\": [\"search_docs\", \"ticket_lookup\"],\n",
        "    \"ApprovedDestinations\": [\"https://docs.contoso.internal\", \"https://tickets.contoso.internal\"],\n",
        "    \"ApprovalRecord\": \"ARB-2026-0142\"\n",
        "}\n",
        "\n",
        "checklist = []\n",
        "for tool in baseline[\"ApprovedTools\"]:\n",
        "    checklist.append({\"Type\": \"Tool\", \"Value\": tool})\n",
        "for destination in baseline[\"ApprovedDestinations\"]:\n",
        "    checklist.append({\"Type\": \"Destination\", \"Value\": destination})\n",
        "\n",
        "checklist_path = os.path.join(tempfile.gettempdir(), \"agent-checklist.json\")\n",
        "with open(checklist_path, \"w\", encoding=\"utf-8\") as f:\n",
        "    json.dump(checklist, f, indent=2)\n",
        "\n",
        "print(\"Checklist written to:\", checklist_path)\n",
        "with open(checklist_path, \"r\", encoding=\"utf-8\") as f:\n",
        "    print(f.read())"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Detect drift after deployment\n",
        "\n",
        "Approved architectures drift over time. This example compares the approved checklist with an observed current configuration and flags unauthorized additions such as a new tool or an external destination."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "with open(checklist_path, \"r\", encoding=\"utf-8\") as f:\n",
        "    baseline_items = json.load(f)\n",
        "\n",
        "current = [\n",
        "    {\"Type\": \"Tool\", \"Value\": \"search_docs\"},\n",
        "    {\"Type\": \"Tool\", \"Value\": \"shell_exec\"},\n",
        "    {\"Type\": \"Destination\", \"Value\": \"https://docs.contoso.internal\"},\n",
        "    {\"Type\": \"Destination\", \"Value\": \"https://example.com\"},\n",
        "]\n",
        "\n",
        "approved = {f\"{item['Type']}:{item['Value']}\" for item in baseline_items}\n",
        "observed = {f\"{item['Type']}:{item['Value']}\" for item in current}\n",
        "\n",
        "unauthorized_additions = sorted(observed - approved)\n",
        "missing_expected_items = sorted(approved - observed)\n",
        "\n",
        "drift_report = {\n",
        "    \"unauthorized_additions\": unauthorized_additions,\n",
        "    \"missing_expected_items\": missing_expected_items,\n",
        "    \"drift_detected\": bool(unauthorized_additions or missing_expected_items)\n",
        "}\n",
        "\n",
        "print(json.dumps(drift_report, indent=2))\n",
        "pd.DataFrame({\n",
        "    \"unauthorized_additions\": pd.Series(unauthorized_additions),\n",
        "    \"missing_expected_items\": pd.Series(missing_expected_items)\n",
        "})"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Release discipline as executable sequence data\n",
        "\n",
        "The second Mermaid diagram in the post shows the release sequence from baseline definition through approval or rejection. This Python representation makes the same sequence explicit and reviewable."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "release_sequence = [\n",
        "    {\"from\": \"Developer\", \"to\": \"Approved Baseline\", \"action\": \"Define approved tools/destinations\"},\n",
        "    {\"from\": \"Developer\", \"to\": \"Validation Harness\", \"action\": \"Submit allowed + denied scenarios\"},\n",
        "    {\"from\": \"Validation Harness\", \"to\": \"Hosted Agent\", \"action\": \"Execute tool-call tests\"},\n",
        "    {\"from\": \"Hosted Agent\", \"to\": \"Validation Harness\", \"action\": \"Return Allow/Block outcomes\"},\n",
        "    {\"from\": \"Validation Harness\", \"to\": \"Approval Record\", \"action\": \"Attach evidence report\"},\n",
        "    {\"from\": \"Approval Record\", \"to\": \"Developer\", \"action\": \"Approve or reject deployment\"},\n",
        "]\n",
        "\n",
        "print(json.dumps(release_sequence, indent=2))\n",
        "pd.DataFrame(release_sequence)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Run the four failure-mode tests from the post\n",
        "\n",
        "The blog recommends testing more than the happy path. This cell simulates four high-value tests: unapproved destination, prompt-injected tool redirection, overbroad data request, and external-call spike containment."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "approved_tools = {\"search_docs\", \"ticket_lookup\"}\n",
        "approved_destinations = {\"https://docs.contoso.internal\", \"https://tickets.contoso.internal\"}\n",
        "allowed_data_scopes = {\"public_docs\", \"ticket_metadata\"}\n",
        "max_external_calls = 3\n",
        "\n",
        "failure_mode_tests = [\n",
        "    {\n",
        "        \"name\": \"unapproved_destination\",\n",
        "        \"tool\": \"search_docs\",\n",
        "        \"destination\": \"https://evil.example\",\n",
        "        \"requested_scope\": \"public_docs\",\n",
        "        \"external_calls\": 1,\n",
        "        \"expected\": \"block\"\n",
        "    },\n",
        "    {\n",
        "        \"name\": \"prompt_injection_tool_redirect\",\n",
        "        \"tool\": \"shell_exec\",\n",
        "        \"destination\": \"https://docs.contoso.internal\",\n",
        "        \"requested_scope\": \"public_docs\",\n",
        "        \"external_calls\": 1,\n",
        "        \"expected\": \"block\"\n",
        "    },\n",
        "    {\n",
        "        \"name\": \"overbroad_data_request\",\n",
        "        \"tool\": \"ticket_lookup\",\n",
        "        \"destination\": \"https://tickets.contoso.internal\",\n",
        "        \"requested_scope\": \"all_customer_records\",\n",
        "        \"external_calls\": 1,\n",
        "        \"expected\": \"block\"\n",
        "    },\n",
        "    {\n",
        "        \"name\": \"external_call_spike\",\n",
        "        \"tool\": \"search_docs\",\n",
        "        \"destination\": \"https://docs.contoso.internal\",\n",
        "        \"requested_scope\": \"public_docs\",\n",
        "        \"external_calls\": 10,\n",
        "        \"expected\": \"block\"\n",
        "    },\n",
        "]\n",
        "\n",
        "def evaluate_test(test: Dict[str, Any]) -> Dict[str, Any]:\n",
        "    tool_ok = test[\"tool\"] in approved_tools\n",
        "    destination_ok = test[\"destination\"] in approved_destinations\n",
        "    scope_ok = test[\"requested_scope\"] in allowed_data_scopes\n",
        "    rate_ok = test[\"external_calls\"] <= max_external_calls\n",
        "    actual = \"allow\" if all([tool_ok, destination_ok, scope_ok, rate_ok]) else \"block\"\n",
        "    return {\n",
        "        **test,\n",
        "        \"actual\": actual,\n",
        "        \"pass\": actual == test[\"expected\"],\n",
        "        \"reasons\": {\n",
        "            \"tool_ok\": tool_ok,\n",
        "            \"destination_ok\": destination_ok,\n",
        "            \"scope_ok\": scope_ok,\n",
        "            \"rate_ok\": rate_ok,\n",
        "        }\n",
        "    }\n",
        "\n",
        "failure_results = [evaluate_test(t) for t in failure_mode_tests]\n",
        "print(json.dumps(failure_results, indent=2))\n",
        "pd.DataFrame([{k: v for k, v in r.items() if k != \"reasons\"} for r in failure_results])"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Simulate a kill switch test\n",
        "\n",
        "The post argues that a kill switch is only real if it has been tested. This example simulates revoking a credential and disabling a route, then verifies that the agent fails safely and produces an auditable event."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "agent_runtime_state = {\n",
        "    \"credential_active\": False,\n",
        "    \"route_enabled\": False,\n",
        "    \"tool\": \"search_docs\",\n",
        "    \"destination\": \"https://docs.contoso.internal\"\n",
        "}\n",
        "\n",
        "def simulate_agent_call(state: Dict[str, Any]) -> Dict[str, Any]:\n",
        "    if not state[\"credential_active\"]:\n",
        "        return {\n",
        "            \"status\": \"failed_safe\",\n",
        "            \"reason\": \"credential_revoked\",\n",
        "            \"logged\": True,\n",
        "            \"on_call_actionable\": True\n",
        "        }\n",
        "    if not state[\"route_enabled\"]:\n",
        "        return {\n",
        "            \"status\": \"failed_safe\",\n",
        "            \"reason\": \"route_disabled\",\n",
        "            \"logged\": True,\n",
        "            \"on_call_actionable\": True\n",
        "        }\n",
        "    return {\n",
        "        \"status\": \"allowed\",\n",
        "        \"reason\": \"all_controls_present\",\n",
        "        \"logged\": True,\n",
        "        \"on_call_actionable\": True\n",
        "    }\n",
        "\n",
        "kill_switch_result = simulate_agent_call(agent_runtime_state)\n",
        "print(json.dumps(kill_switch_result, indent=2))"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Score your current governance maturity\n",
        "\n",
        "The post ends with a simple 1-to-5 rating. This cell provides a lightweight scoring model based on whether key controls are present and tested."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "maturity_controls = {\n",
        "    \"named_destinations\": True,\n",
        "    \"named_tools\": True,\n",
        "    \"deny_by_default\": True,\n",
        "    \"validation_harness\": True,\n",
        "    \"evidence_report\": True,\n",
        "    \"release_gate\": True,\n",
        "    \"drift_detection\": True,\n",
        "    \"kill_switch_tested\": True,\n",
        "    \"scoped_identity\": False,\n",
        "    \"write_action_controls\": False,\n",
        "}\n",
        "\n",
        "score = sum(maturity_controls.values())\n",
        "max_score = len(maturity_controls)\n",
        "normalized = score / max_score\n",
        "\n",
        "if normalized <= 0.2:\n",
        "    rating = 1\n",
        "elif normalized <= 0.4:\n",
        "    rating = 2\n",
        "elif normalized <= 0.6:\n",
        "    rating = 3\n",
        "elif normalized <= 0.8:\n",
        "    rating = 4\n",
        "else:\n",
        "    rating = 5\n",
        "\n",
        "print(\"Control coverage:\", f\"{score}/{max_score}\")\n",
        "print(\"Governance maturity rating (1-5):\", rating)\n",
        "pd.DataFrame(list(maturity_controls.items()), columns=[\"control\", \"implemented\"])"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Summary\n",
        "\n",
        "This notebook converted the article into a practical governance validation flow: define an explicit baseline, test allowed and denied scenarios, generate evidence, gate releases, represent infrastructure intent, export a checklist, detect drift, and test failure modes including kill switches.\n",
        "\n",
        "## Next Steps\n",
        "\n",
        "1. Replace the sample tools and destinations with your real agent inventory.\n",
        "2. Connect the validation harness to your CI/CD pipeline so failed governance checks block release.\n",
        "3. Store evidence reports and approval record IDs with deployments.\n",
        "4. Add live checks for identity scope, data classification, and write-capable tool authorization.\n",
        "5. Schedule recurring drift detection and reapproval when tools, destinations, permissions, or data flows change."
      ]
    }
  ]
}