Some checks failed
check agents / check (push) Failing after 12s
azure-discovery, aws-discovery and gcp-discovery collect read-only metadata on servers, workloads, Kubernetes clusters, networks, data stores, policies and provider recommendations. Credentials arrive per call from the vault. Replies are paged, scrubbed of secrets and anonymised, and throttled calls back off. cloud-knowledge searches each provider's Well-Architected guidance from fixed lists only, so no customer detail can leave the platform. Adds shared skills, the render and test tooling, a public Python Dockerfile until the hardened base image is reachable, the customer access guide, the implementation plan and the Vault Service platform issue. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1334 lines
60 KiB
Python
1334 lines
60 KiB
Python
"""Azure Discovery
|
|
===============
|
|
|
|
Read-only discovery of a customer's Azure estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Advisor findings - through Azure Resource Graph.
|
|
|
|
Generated by Agent Builder Platform - MCP Server Builder
|
|
Version: 0.1.2
|
|
Template: mcp-server-template 1.1.0
|
|
|
|
Features:
|
|
- JSON-RPC 2.0 over HTTP (MCP standard)
|
|
- Bearer token authentication
|
|
- Health check endpoint
|
|
- Structured logging (JSON, one object per line)
|
|
|
|
Environment Variables:
|
|
- MCP_REGISTRATION_API_KEY: Authentication key for Gateway registration (required)
|
|
- MCP_SERVER_PORT: Server port (default: 8111)
|
|
- MCP_SERVER_NAME: Display name for the server
|
|
- LOG_LEVEL: Logging level (default: INFO)
|
|
- LOG_FORMAT: json (default) or console
|
|
"""
|
|
|
|
import os
|
|
import re
|
|
import sys
|
|
import json
|
|
import inspect
|
|
import time
|
|
import traceback
|
|
import asyncio
|
|
import logging
|
|
import secrets
|
|
from typing import Dict, Any, List, Optional, Union # noqa: F401
|
|
from collections import OrderedDict
|
|
from contextlib import asynccontextmanager
|
|
from datetime import datetime, timezone
|
|
|
|
import structlog
|
|
from fastapi import FastAPI, HTTPException, Depends, Request
|
|
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
|
|
from pydantic import BaseModel, Field, StrictInt, StrictStr
|
|
|
|
import mcp_connection
|
|
|
|
# Additional imports from tool implementations
|
|
import base64
|
|
import hashlib
|
|
import httpx
|
|
|
|
TEMPLATE_VERSION = '1.1.0'
|
|
|
|
# What this server needs to reach its upstream, advertised to the gateway on initialize (None: nothing)
|
|
CONNECTION_SCHEMA = {'type': 'object',
|
|
'title': 'Azure Discovery',
|
|
'description': "Read-only discovery of a customer's Azure estate - servers, "
|
|
'workloads, Kubernetes clusters, networks, data stores, policies and '
|
|
'Advisor findings - through Azure Resource Graph.',
|
|
'properties': {'tenant_id': {'type': 'string',
|
|
'title': 'Tenant ID',
|
|
'description': "The customer's Microsoft Entra tenant "
|
|
'id.'},
|
|
'client_id': {'type': 'string',
|
|
'title': 'Client ID',
|
|
'description': 'The application (client) id of the '
|
|
'read-only app registration.'},
|
|
'client_secret': {'type': 'string',
|
|
'title': 'Client secret',
|
|
'description': "The app registration's client "
|
|
'secret.',
|
|
'writeOnly': True,
|
|
'format': 'password'},
|
|
'access_token': {'type': 'string',
|
|
'title': 'Access token',
|
|
'description': 'For a short trial only, instead of '
|
|
'the three fields above. A token from '
|
|
'az account get-access-token. It '
|
|
'expires within about an hour and '
|
|
"carries that person's own Azure "
|
|
'permissions.',
|
|
'writeOnly': True,
|
|
'format': 'password'},
|
|
'scope_root': {'type': 'string',
|
|
'title': 'Scope root',
|
|
'description': 'What may be read: managementGroups/<id> '
|
|
'or subscriptions/<id>.'},
|
|
'cloud': {'type': 'string',
|
|
'title': 'Cloud',
|
|
'description': 'public, usgov or china. Default public.'}},
|
|
'required': ['scope_root'],
|
|
'additionalProperties': False}
|
|
VERIFY_TOOL = 'verify_connection'
|
|
|
|
# ============================================
|
|
# Configuration
|
|
# ============================================
|
|
|
|
def _load_env_file() -> None:
|
|
"""Read the `.env` next to this file, so `cp .env.example .env` and `python server.py` work.
|
|
|
|
Variables that are already set win, so a container's or a pipeline's settings are never overridden.
|
|
The image does not contain a `.env`, so this does nothing there.
|
|
"""
|
|
path = globals().get("__file__")
|
|
if not path:
|
|
return
|
|
try:
|
|
from dotenv import load_dotenv
|
|
except ImportError:
|
|
return
|
|
load_dotenv(os.path.join(os.path.dirname(os.path.abspath(path)), ".env"))
|
|
|
|
|
|
_load_env_file()
|
|
|
|
|
|
class Config:
|
|
"""Server configuration from environment variables"""
|
|
|
|
# Server Identity
|
|
SERVER_ID = os.getenv("MCP_SERVER_ID", 'azure-discovery')
|
|
SERVER_NAME = os.getenv("MCP_SERVER_NAME", 'Azure Discovery')
|
|
SERVER_VERSION = os.getenv("MCP_SERVER_VERSION", '0.1.2')
|
|
# MCP_SERVER_PORT, or SERVER_PORT as the ConfigMaps in the tools repo name it
|
|
SERVER_PORT = int(os.getenv("MCP_SERVER_PORT") or os.getenv("SERVER_PORT") or "8111")
|
|
|
|
# Authentication (REQUIRED for MCP Gateway registration)
|
|
# Generate secure key: openssl rand -hex 32
|
|
MCP_REGISTRATION_API_KEY = os.getenv("MCP_REGISTRATION_API_KEY", "").strip()
|
|
# The placeholder from .env.example is not a key: a server started with it unchanged has no key.
|
|
if MCP_REGISTRATION_API_KEY.startswith("<"):
|
|
MCP_REGISTRATION_API_KEY = ""
|
|
|
|
# Feature Flags
|
|
REQUIRE_AUTH = os.getenv("REQUIRE_AUTH", "true").lower() == "true"
|
|
# Applies when CONNECTION_SCHEMA is set: refuse a call that arrives without the tenant's connection
|
|
# instead of falling back to this server's own environment. Set to false only for local runs.
|
|
REQUIRE_VAULT_CONNECTION = os.getenv("REQUIRE_VAULT_CONNECTION", "true").lower() == "true"
|
|
|
|
# Logging: LOG_FORMAT is "json" (one object per line, for log stores) or "console" (for reading by eye)
|
|
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
|
|
LOG_FORMAT = os.getenv("LOG_FORMAT", "json").lower()
|
|
|
|
config = Config()
|
|
|
|
# ============================================
|
|
# Logging Configuration
|
|
# ============================================
|
|
|
|
def sanitize_log(value: Any, max_length: int = 200) -> str:
|
|
"""Make a caller-supplied value safe to log: one line, no control characters, bounded."""
|
|
if not isinstance(value, str):
|
|
value = str(value)
|
|
# Written with .replace() because that is the pattern CodeQL recognises as a
|
|
# barrier for py/log-injection (CWE-117).
|
|
value = value.replace("\n", "").replace("\r", "")
|
|
return re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]", "", value)[:max_length]
|
|
|
|
|
|
def _add_server_identity(_logger, _method, event_dict):
|
|
event_dict.setdefault("server_id", config.SERVER_ID)
|
|
event_dict.setdefault("server_name", config.SERVER_NAME)
|
|
event_dict.setdefault("server_version", config.SERVER_VERSION)
|
|
return event_dict
|
|
|
|
|
|
_LEADING_KEYS = (
|
|
"timestamp", "level", "event", "logger", "server_id", "server_name", "server_version",
|
|
"request_id", "method", "tool",
|
|
)
|
|
|
|
|
|
def _scrub_secrets(_logger, _method, event_dict):
|
|
"""The last step before a line is written: no credential reaches the log, whoever logged it."""
|
|
return mcp_connection.scrub(event_dict)
|
|
|
|
|
|
def _lead_with_common_keys(_logger, _method, event_dict):
|
|
"""Every line starts with the same fields in the same order; the event's own follow."""
|
|
lead = {key: event_dict.pop(key) for key in _LEADING_KEYS if key in event_dict}
|
|
lead.update(event_dict)
|
|
return lead
|
|
|
|
|
|
def configure_logging() -> None:
|
|
"""Send every log line, ours and the libraries', to stdout in one format."""
|
|
level = getattr(logging, config.LOG_LEVEL, logging.INFO)
|
|
shared = [
|
|
structlog.contextvars.merge_contextvars,
|
|
structlog.stdlib.add_logger_name,
|
|
structlog.stdlib.add_log_level,
|
|
structlog.processors.TimeStamper(fmt="iso", utc=True),
|
|
_add_server_identity,
|
|
]
|
|
renderer = (
|
|
structlog.dev.ConsoleRenderer(colors=False)
|
|
if config.LOG_FORMAT == "console"
|
|
else structlog.processors.JSONRenderer()
|
|
)
|
|
structlog.configure(
|
|
processors=shared + [
|
|
structlog.stdlib.PositionalArgumentsFormatter(),
|
|
structlog.processors.StackInfoRenderer(),
|
|
structlog.processors.format_exc_info,
|
|
structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
|
|
],
|
|
logger_factory=structlog.stdlib.LoggerFactory(),
|
|
wrapper_class=structlog.stdlib.BoundLogger,
|
|
cache_logger_on_first_use=True,
|
|
)
|
|
handler = logging.StreamHandler(sys.stdout)
|
|
handler.mcp_server_handler = True
|
|
handler.setFormatter(structlog.stdlib.ProcessorFormatter(
|
|
foreign_pre_chain=shared,
|
|
processors=[
|
|
structlog.stdlib.ProcessorFormatter.remove_processors_meta,
|
|
structlog.processors.format_exc_info,
|
|
_lead_with_common_keys,
|
|
_scrub_secrets,
|
|
renderer,
|
|
],
|
|
))
|
|
root = logging.getLogger()
|
|
root.handlers = [h for h in root.handlers if not getattr(h, "mcp_server_handler", False)] + [handler]
|
|
root.setLevel(level)
|
|
# httpx logs every request URL at INFO, and an upstream URL often carries a key: keep those lines for DEBUG
|
|
for name in ("httpx", "httpcore"):
|
|
logging.getLogger(name).setLevel(level if level <= logging.DEBUG else logging.WARNING)
|
|
# uvicorn installs its own handlers; route them through ours so every line has the same shape
|
|
for name in ("uvicorn", "uvicorn.error", "uvicorn.access"):
|
|
uvicorn_logger = logging.getLogger(name)
|
|
uvicorn_logger.handlers.clear()
|
|
uvicorn_logger.propagate = True
|
|
|
|
|
|
configure_logging()
|
|
logger = structlog.get_logger(__name__)
|
|
|
|
# ============================================
|
|
# Per-request connection
|
|
# ============================================
|
|
|
|
CONNECTION_METHODS = ("tools/call", "resources/read", "prompts/get")
|
|
|
|
|
|
def get_connection() -> Dict[str, Any]:
|
|
"""The connection fields the gateway sent with this request; empty when it sent none."""
|
|
return dict(mcp_connection.active() or {})
|
|
|
|
|
|
_client_cache: "OrderedDict[str, Any]" = OrderedDict()
|
|
_CLIENT_CACHE_MAX = 32
|
|
|
|
|
|
def get_upstream_client(kind, build):
|
|
"""The upstream client of type `kind` for this request's connection.
|
|
|
|
`build(connection)` runs once per distinct (kind, connection), so two tools that talk to different
|
|
upstreams with the same tenant connection each get their own client.
|
|
"""
|
|
if not isinstance(kind, str) or not kind:
|
|
raise TypeError("get_upstream_client needs a client kind, for example get_upstream_client('jira', build)")
|
|
key = f"{kind}:{mcp_connection.fingerprint(mcp_connection.active())}"
|
|
client = _client_cache.get(key)
|
|
if client is None:
|
|
client = build(get_connection())
|
|
_client_cache[key] = client
|
|
while len(_client_cache) > _CLIENT_CACHE_MAX:
|
|
_close_client(_client_cache.popitem(last=False)[1])
|
|
else:
|
|
_client_cache.move_to_end(key)
|
|
return client
|
|
|
|
|
|
_closing_tasks: set = set()
|
|
|
|
|
|
def _close_client(client) -> None:
|
|
"""Release the connections of a client that left the cache (an httpx client holds a pool of sockets).
|
|
|
|
Closes with `aclose()`, `close()` or `dispose()` (an httpx client, most clients, a SQLAlchemy engine); a client
|
|
with none of them is left to the garbage collector. A failure to close is logged and never reaches the
|
|
request that happened to evict it.
|
|
"""
|
|
close = getattr(client, "aclose", None) or getattr(client, "close", None) or getattr(client, "dispose", None)
|
|
if close is None:
|
|
return
|
|
try:
|
|
result = close()
|
|
if inspect.isawaitable(result):
|
|
try:
|
|
task = asyncio.get_running_loop().create_task(result)
|
|
except RuntimeError: # no loop to run it on
|
|
result.close()
|
|
return
|
|
_closing_tasks.add(task) # a task nobody refers to can be collected before it finishes
|
|
task.add_done_callback(_closing_tasks.discard)
|
|
except Exception as error:
|
|
logger.warning("client_close_failed", error_type=type(error).__name__, error=sanitize_log(error))
|
|
|
|
|
|
async def _close_all_clients() -> None:
|
|
"""On shutdown: close every cached client and wait for the closes already under way."""
|
|
while _client_cache:
|
|
_close_client(_client_cache.popitem(last=False)[1])
|
|
if _closing_tasks:
|
|
await asyncio.gather(*list(_closing_tasks), return_exceptions=True)
|
|
|
|
|
|
def check_connection(profile: Optional[Dict[str, Any]]) -> None:
|
|
"""Refuse a call with no connection (unless the environment may be used) or with an incomplete one."""
|
|
if not profile:
|
|
if config.REQUIRE_VAULT_CONNECTION:
|
|
raise ValueError(
|
|
"No connection was sent with this request: no credential is stored for this tenant. "
|
|
"Store one under Credentials, or set REQUIRE_VAULT_CONNECTION=false to use this "
|
|
"server's own environment."
|
|
)
|
|
return
|
|
missing = mcp_connection.missing_fields(profile, CONNECTION_SCHEMA)
|
|
if missing:
|
|
raise ValueError("The connection sent with this request is missing: " + ", ".join(missing))
|
|
|
|
|
|
def render_prompt(template: str, values: Dict[str, Any]) -> str:
|
|
"""Fill {{name}} markers in a prompt template; a marker with no value is left as written."""
|
|
return re.sub(
|
|
r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}",
|
|
lambda m: str(values[m.group(1)]) if m.group(1) in values else m.group(0),
|
|
template,
|
|
)
|
|
|
|
# ============================================
|
|
# Authentication
|
|
# ============================================
|
|
|
|
security = HTTPBearer(auto_error=False)
|
|
|
|
async def verify_mcp_registration_key(
|
|
credentials: Optional[HTTPAuthorizationCredentials] = Depends(security)
|
|
) -> bool:
|
|
"""
|
|
Verify MCP registration API key for /messages endpoint.
|
|
|
|
This is the industry-standard Bearer token authentication pattern.
|
|
"""
|
|
# Skip auth if disabled (for testing only!)
|
|
if not config.REQUIRE_AUTH:
|
|
logger.warning("auth_disabled", detail="testing mode only")
|
|
return True
|
|
|
|
if not credentials:
|
|
logger.warning("auth_missing_credentials")
|
|
raise HTTPException(
|
|
status_code=401,
|
|
detail="Missing authentication credentials. Include 'Authorization: Bearer <token>' header.",
|
|
headers={"WWW-Authenticate": "Bearer"}
|
|
)
|
|
|
|
provided_key = credentials.credentials
|
|
expected_key = config.MCP_REGISTRATION_API_KEY
|
|
|
|
if not expected_key:
|
|
logger.error("auth_key_not_configured")
|
|
raise HTTPException(
|
|
status_code=500,
|
|
detail="Server authentication not configured"
|
|
)
|
|
|
|
if not secrets.compare_digest(provided_key.encode("utf-8"), expected_key.encode("utf-8")):
|
|
logger.warning("auth_invalid_key")
|
|
raise HTTPException(
|
|
status_code=401,
|
|
detail="Invalid authentication credentials",
|
|
headers={"WWW-Authenticate": "Bearer"}
|
|
)
|
|
|
|
return True
|
|
|
|
# ============================================
|
|
# MCP Protocol Models
|
|
# ============================================
|
|
|
|
class MCPRequest(BaseModel):
|
|
"""JSON-RPC 2.0 request (MCP standard)"""
|
|
jsonrpc: str = "2.0"
|
|
id: Union[StrictStr, StrictInt] # JSON-RPC allows a string or a number; the reply echoes it unchanged
|
|
method: str
|
|
params: Dict[str, Any] = Field(default_factory=dict)
|
|
|
|
class MCPResponse(BaseModel):
|
|
"""JSON-RPC 2.0 response (MCP standard)"""
|
|
jsonrpc: str = "2.0"
|
|
id: Union[StrictStr, StrictInt]
|
|
result: Optional[Dict[str, Any]] = None
|
|
error: Optional[Dict[str, Any]] = None
|
|
|
|
# ============================================
|
|
# Tool Definitions
|
|
# ============================================
|
|
|
|
TOOLS_REGISTRY = [
|
|
{
|
|
"name": 'azure_check_connection',
|
|
"description": 'Test the stored connection: sign in and read the scope root. Returns no customer data.',
|
|
"inputSchema": {'type': 'object', 'properties': {}, 'required': []}
|
|
},
|
|
{
|
|
"name": 'azure_list_accounts',
|
|
"description": 'List the estate structure: management groups, subscriptions and resource groups.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: subscriptions, management_groups, '
|
|
'resource_groups.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'azure_list_resources',
|
|
"description": 'List every resource in scope, or one resource type, with id, type, location and tags.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'resource_type': {'type': 'string',
|
|
'description': 'Optional ARM type, such as '
|
|
'microsoft.compute/virtualmachines.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'azure_query_resources',
|
|
"description": "Run a read-only Azure Resource Graph KQL query over the connection's scope. Secrets and people are removed from the results.",
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'query': {'type': 'string',
|
|
'description': 'KQL starting with a Resource Graph table.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': ['query']}
|
|
},
|
|
{
|
|
"name": 'azure_get_resource_metadata',
|
|
"description": "Read-only provider metadata for one resource inside the connection's scope.",
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'resource_id': {'type': 'string',
|
|
'description': 'The full ARM resource id.'},
|
|
'scope_entry_id': {'type': 'string',
|
|
'description': 'The scope entry this answers, '
|
|
'echoed in the reply.'}},
|
|
'required': ['resource_id']}
|
|
},
|
|
{
|
|
"name": 'azure_list_servers',
|
|
"description": 'List virtual machines, scale sets or managed disks.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: virtual_machines, scale_sets, disks.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'azure_list_workloads',
|
|
"description": 'List App Service, Container Apps or Container Instances workloads.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: app_service, container_apps, '
|
|
'container_instances.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'azure_list_kubernetes_clusters',
|
|
"description": 'List AKS clusters with version, node pools and networking. Stops at the cloud control plane.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'azure_get_network_topology',
|
|
"description": 'List virtual networks with their subnets and peerings, or route tables, NSGs, gateways, load balancers, private endpoints or public IPs.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: virtual_networks, route_tables, '
|
|
'network_security_groups, gateways, '
|
|
'load_balancers, private_endpoints, '
|
|
'public_ips.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'azure_list_data_stores',
|
|
"description": 'List SQL, Cosmos DB or storage account metadata. Never rows, documents or blobs.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: sql, cosmos_db, storage_accounts.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'azure_list_organization_policies',
|
|
"description": 'List Azure Policy assignments, definitions, initiatives, exemptions or compliance states.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: assignments, definitions, '
|
|
'initiatives, exemptions, compliance.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'azure_list_resource_policies',
|
|
"description": 'List Key Vault access policies (never secret values), storage network rules or resource locks. Principals are anonymised.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'subscription_id': {'type': 'string',
|
|
'description': 'For resource_locks. Needed when '
|
|
'the scope root is a management '
|
|
'group.'},
|
|
'kind': {'type': 'string',
|
|
'description': 'One of: key_vault_access, '
|
|
'storage_network_rules, resource_locks.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'azure_list_recommendations',
|
|
"description": 'List Azure Advisor recommendations, each with a common Well-Architected pillar.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'verify_connection',
|
|
"description": (
|
|
"Check that the connection sent with this request works against the upstream, and say who it "
|
|
"authenticated as. Makes no change."
|
|
),
|
|
"inputSchema": {'type': 'object', 'properties': {}, 'required': []}
|
|
}
|
|
]
|
|
|
|
# ============================================
|
|
# Resource Definitions
|
|
# ============================================
|
|
|
|
RESOURCES_REGISTRY = []
|
|
|
|
# ============================================
|
|
# Prompt Definitions
|
|
# ============================================
|
|
|
|
PROMPT_TEMPLATES = {}
|
|
|
|
PROMPTS_REGISTRY = [
|
|
{
|
|
"name": name,
|
|
"description": prompt["description"],
|
|
"arguments": [
|
|
{"name": a["name"], "description": a["description"], "required": a["required"]}
|
|
for a in prompt["arguments"]
|
|
],
|
|
}
|
|
for name, prompt in PROMPT_TEMPLATES.items()
|
|
]
|
|
|
|
# ============================================
|
|
# Tool Implementations
|
|
# ============================================
|
|
|
|
DEFAULT_PAGE_SIZE = 50
|
|
|
|
MAX_PAGE_SIZE = 200
|
|
|
|
MAX_RESPONSE_BYTES = 200000
|
|
|
|
RETRY_ATTEMPTS = 5
|
|
|
|
RETRY_MAX_WAIT_SECONDS = 20
|
|
|
|
RETRY_BUDGET_SECONDS = 60
|
|
|
|
SECRET_KEYS = (
|
|
"userdata", "customdata", "customscript", "protectedsettings", "connectionstring", "connectionstrings",
|
|
"appsettings", "env", "envvars", "environmentvariables", "variables", "password", "adminpassword", "secret",
|
|
"secretvalue", "sastoken", "accesskey", "primarykey", "secondarykey", "privatekey", "kubeconfig", "credentials",
|
|
)
|
|
|
|
PERSON_KEYS = (
|
|
"createdby", "lastmodifiedby", "updatedby", "creator", "owner", "owneremail", "contact", "contactemail", "email",
|
|
"objectid", "principalid", "principalname", "userprincipalname",
|
|
)
|
|
|
|
PRINCIPAL_KINDS = {"user": "[user]", "group": "[group]", "domain": "[domain]", "principal": "[user]",
|
|
"principalSet": "[group]", "deleted": "[user]"}
|
|
|
|
NON_PERSON_EMAIL_DOMAINS = ("gserviceaccount.com",)
|
|
|
|
def _clean_text(text: str) -> str:
|
|
"""Anonymise people inside a string: emails, AWS IAM users, and session names, which are often emails."""
|
|
def email(match):
|
|
return match.group(0) if match.group(0).lower().endswith(NON_PERSON_EMAIL_DOMAINS) else "[email]"
|
|
|
|
text = re.sub(r"arn:aws[a-z-]*:iam::\d{12}:user/[^\s\"',]+", "[user]", text)
|
|
text = re.sub(r"(arn:aws[a-z-]*:sts::\d{12}:assumed-role/[^/\s\"',]+)/[^\s\"',]+", r"\1/[session]", text)
|
|
# Bounded, and skipped without an @: an unbounded pattern takes minutes on one long string.
|
|
if "@" not in text:
|
|
return text
|
|
return re.sub(r"[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,255}\.[A-Za-z]{2,24}", email, text)
|
|
|
|
def _anonymise_member(value: str) -> str:
|
|
"""One IAM member, such as user:a@b.example. Service accounts stay: Discovery shows what can reach what."""
|
|
kind = value.split(":", 1)[0]
|
|
if ":" in value and kind == "serviceAccount":
|
|
return value
|
|
if ":" in value and kind in PRINCIPAL_KINDS:
|
|
return PRINCIPAL_KINDS[kind]
|
|
return _clean_text(value)
|
|
|
|
def _scrub(value, key: str = ""):
|
|
"""Drop secrets and anonymise people, however deep. Every tool's reply passes through here."""
|
|
lowered = key.lower().replace("_", "").replace("-", "")
|
|
if lowered in SECRET_KEYS:
|
|
return "[redacted]"
|
|
if lowered in PERSON_KEYS:
|
|
return "[user]"
|
|
if isinstance(value, dict):
|
|
tag = str(value.get("Key", value.get("key", ""))).lower().replace("_", "").replace("-", "")
|
|
cleaned = {k: _scrub(v, str(k)) for k, v in value.items()}
|
|
for name in ("Value", "value"):
|
|
if name in cleaned and tag in PERSON_KEYS:
|
|
cleaned[name] = "[user]"
|
|
elif name in cleaned and tag in SECRET_KEYS:
|
|
cleaned[name] = "[redacted]"
|
|
return cleaned
|
|
if isinstance(value, (list, tuple)):
|
|
return [_scrub(v, "members" if lowered == "members" else "") for v in value]
|
|
if isinstance(value, str):
|
|
return _anonymise_member(value) if lowered == "members" else _clean_text(value)
|
|
if value is None or isinstance(value, (bool, int, float)):
|
|
return value
|
|
return str(value)
|
|
|
|
def _retry_delay(response, attempt: int) -> float:
|
|
"""How long the provider asked us to wait: Retry-After, or Resource Graph's hh:mm:ss quota reset."""
|
|
reset = response.headers.get("x-ms-user-quota-resets-after", "")
|
|
if reset.count(":") == 2:
|
|
hours, minutes, seconds = reset.split(":")
|
|
return int(hours) * 3600 + int(minutes) * 60 + float(seconds)
|
|
try:
|
|
return float(response.headers.get("retry-after", ""))
|
|
except ValueError:
|
|
return float(2 ** attempt)
|
|
|
|
async def _with_backoff(send):
|
|
"""Send, waiting when the provider throttles. The waits stay well inside the 120-second limit on an MCP call."""
|
|
waited = 0.0
|
|
response = await send()
|
|
for attempt in range(RETRY_ATTEMPTS):
|
|
if response.status_code not in (429, 503):
|
|
return response
|
|
delay = min(_retry_delay(response, attempt), RETRY_MAX_WAIT_SECONDS)
|
|
if waited + delay > RETRY_BUDGET_SECONDS:
|
|
return response
|
|
logger.info("upstream_throttled", status=response.status_code, wait_seconds=delay)
|
|
await asyncio.sleep(delay)
|
|
waited += delay
|
|
response = await send()
|
|
return response
|
|
|
|
def _page_size(arguments: Dict[str, Any]) -> int:
|
|
try:
|
|
size = int(arguments.get("page_size") or DEFAULT_PAGE_SIZE)
|
|
except (TypeError, ValueError):
|
|
return DEFAULT_PAGE_SIZE
|
|
return max(1, min(size, MAX_PAGE_SIZE))
|
|
|
|
def _read_page(arguments: Dict[str, Any]):
|
|
"""(upstream token, items of that upstream page already returned)."""
|
|
token = arguments.get("page_token")
|
|
if not token:
|
|
return None, 0
|
|
state = json.loads(base64.urlsafe_b64decode(str(token).encode()).decode())
|
|
return state["u"], int(state["s"])
|
|
|
|
def _write_page(upstream, skip: int) -> str:
|
|
return base64.urlsafe_b64encode(json.dumps({"u": upstream, "s": skip}).encode()).decode()
|
|
|
|
def _evidence_ref(tool: str, arguments: Dict[str, Any], payload) -> str:
|
|
asked = {k: v for k, v in arguments.items() if k != "page_token"}
|
|
blob = json.dumps([tool, asked, payload], sort_keys=True, default=str)
|
|
return "sha256:" + hashlib.sha256(blob.encode()).hexdigest()
|
|
|
|
def _collected_at() -> str:
|
|
return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
|
|
|
|
def _refuse(code: str, message: str) -> Dict[str, Any]:
|
|
return {"success": False, "error": {"code": code, "message": message}}
|
|
|
|
def _upstream_failed(provider: str, error: Exception) -> Dict[str, Any]:
|
|
"""Name the failure and never its text: an upstream error can quote a request or an identity."""
|
|
status = getattr(getattr(error, "response", None), "status_code", None)
|
|
code = getattr(error, "response", None)
|
|
if isinstance(code, dict):
|
|
status = code.get("Error", {}).get("Code")
|
|
logger.warning("upstream_call_failed", provider=provider, error_type=type(error).__name__, status=status)
|
|
detail = f" ({status})" if status else ""
|
|
return _refuse("upstream_failed", f"{provider} refused or failed the call: {type(error).__name__}{detail}")
|
|
|
|
def _page_result(provider: str, tool: str, arguments: Dict[str, Any], items: List[Any], used, upstream_next,
|
|
skip: int = 0, extra: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
"""One page of scrubbed items, cut at MAX_RESPONSE_BYTES; the token resumes exactly where the cut fell."""
|
|
remaining = [_scrub(item) for item in items[skip:]]
|
|
kept, size = [], 0
|
|
for item in remaining:
|
|
size += len(json.dumps(item, default=str))
|
|
if kept and size > MAX_RESPONSE_BYTES:
|
|
break
|
|
kept.append(item)
|
|
if len(kept) < len(remaining):
|
|
next_token = _write_page(used, skip + len(kept))
|
|
else:
|
|
next_token = _write_page(upstream_next, 0) if upstream_next else None
|
|
data = {"provider": provider, "items": kept, "count": len(kept), "next_page_token": next_token,
|
|
"collected_at": _collected_at(), "evidence_ref": _evidence_ref(tool, arguments, kept)}
|
|
data.update(extra or {})
|
|
return {"success": True, "data": data}
|
|
|
|
def _one_result(provider: str, tool: str, arguments: Dict[str, Any], metadata: Any) -> Dict[str, Any]:
|
|
clean = _scrub(metadata)
|
|
return {"success": True, "data": {"provider": provider, "metadata": clean, "collected_at": _collected_at(),
|
|
"evidence_ref": _evidence_ref(tool, arguments, clean)}}
|
|
|
|
AZURE_CLOUDS = {
|
|
"public": {"login": "https://login.microsoftonline.com", "arm": "https://management.azure.com"},
|
|
"usgov": {"login": "https://login.microsoftonline.us", "arm": "https://management.usgovcloudapi.net"},
|
|
"china": {"login": "https://login.chinacloudapi.cn", "arm": "https://management.chinacloudapi.cn"},
|
|
}
|
|
|
|
AZURE_GRAPH_VERSION = "2022-10-01"
|
|
|
|
AZURE_LOCKS_VERSION = "2020-05-01"
|
|
|
|
AZURE_TABLES = ("resources", "resourcecontainers", "policyresources", "advisorresources", "networkresources")
|
|
|
|
AZURE_TOKENS = {}
|
|
|
|
AZURE_SERVERS = {
|
|
"virtual_machines": ["microsoft.compute/virtualmachines"],
|
|
"scale_sets": ["microsoft.compute/virtualmachinescalesets"],
|
|
"disks": ["microsoft.compute/disks"],
|
|
}
|
|
|
|
AZURE_WORKLOADS = {
|
|
"app_service": ["microsoft.web/sites", "microsoft.web/serverfarms"],
|
|
"container_apps": ["microsoft.app/containerapps", "microsoft.app/managedenvironments"],
|
|
"container_instances": ["microsoft.containerinstance/containergroups"],
|
|
}
|
|
|
|
AZURE_KUBERNETES = {"clusters": ["microsoft.containerservice/managedclusters"]}
|
|
|
|
AZURE_NETWORK = {
|
|
"virtual_networks": ["microsoft.network/virtualnetworks"],
|
|
"route_tables": ["microsoft.network/routetables"],
|
|
"network_security_groups": ["microsoft.network/networksecuritygroups"],
|
|
"gateways": ["microsoft.network/virtualnetworkgateways", "microsoft.network/expressroutecircuits",
|
|
"microsoft.network/natgateways", "microsoft.network/azurefirewalls",
|
|
"microsoft.network/applicationgateways"],
|
|
"load_balancers": ["microsoft.network/loadbalancers"],
|
|
"private_endpoints": ["microsoft.network/privateendpoints"],
|
|
"public_ips": ["microsoft.network/publicipaddresses"],
|
|
}
|
|
|
|
AZURE_DATA = {
|
|
"sql": ["microsoft.sql/servers", "microsoft.sql/servers/databases"],
|
|
"cosmos_db": ["microsoft.documentdb/databaseaccounts"],
|
|
"storage_accounts": ["microsoft.storage/storageaccounts"],
|
|
}
|
|
|
|
AZURE_ORG_POLICIES = {
|
|
"assignments": ["microsoft.authorization/policyassignments"],
|
|
"definitions": ["microsoft.authorization/policydefinitions"],
|
|
"initiatives": ["microsoft.authorization/policysetdefinitions"],
|
|
"exemptions": ["microsoft.authorization/policyexemptions"],
|
|
"compliance": ["microsoft.policyinsights/policystates"],
|
|
}
|
|
|
|
AZURE_RESOURCE_POLICIES = {
|
|
"key_vault_access": ["microsoft.keyvault/vaults"],
|
|
"storage_network_rules": ["microsoft.storage/storageaccounts"],
|
|
}
|
|
|
|
AZURE_PILLARS = {"cost": "cost", "security": "security", "highavailability": "reliability",
|
|
"performance": "performance", "operationalexcellence": "operations"}
|
|
|
|
def _azure_scope(connection: Dict[str, Any]) -> Dict[str, List[str]]:
|
|
"""The query scope: the connection's root, and nothing the caller can widen."""
|
|
kind, _, identifier = str(connection.get("scope_root", "")).strip("/").partition("/")
|
|
if not identifier or "/" in identifier or kind not in ("managementGroups", "subscriptions"):
|
|
raise ValueError("scope_root must be managementGroups/<id> or subscriptions/<id>")
|
|
return {kind: [identifier]}
|
|
|
|
def _azure_endpoints(connection: Dict[str, Any]) -> Dict[str, str]:
|
|
return AZURE_CLOUDS.get(str(connection.get("cloud") or "public"), AZURE_CLOUDS["public"])
|
|
|
|
def _azure_client():
|
|
return get_upstream_client("azure", lambda c: httpx.AsyncClient(timeout=100))
|
|
|
|
async def _azure_token(connection: Dict[str, Any]) -> str:
|
|
"""A token for Resource Graph: the short-lived one stored for a trial, or one signed in with the app registration."""
|
|
if connection.get("access_token"):
|
|
return str(connection["access_token"])
|
|
if not all(connection.get(f) for f in ("tenant_id", "client_id", "client_secret")):
|
|
raise ValueError("the connection needs access_token, or tenant_id, client_id and client_secret")
|
|
key = hashlib.sha256(json.dumps(connection, sort_keys=True).encode()).hexdigest()
|
|
cached = AZURE_TOKENS.get(key)
|
|
now = time.time()
|
|
if cached and cached[1] > now + 60:
|
|
return cached[0]
|
|
endpoints = _azure_endpoints(connection)
|
|
response = await _azure_client().post(
|
|
f"{endpoints['login']}/{connection['tenant_id']}/oauth2/v2.0/token",
|
|
data={"grant_type": "client_credentials", "client_id": connection["client_id"],
|
|
"client_secret": connection["client_secret"], "scope": f"{endpoints['arm']}/.default"})
|
|
response.raise_for_status()
|
|
body = response.json()
|
|
AZURE_TOKENS[key] = (body["access_token"], now + int(body.get("expires_in", 3600)))
|
|
return body["access_token"]
|
|
|
|
async def _azure_graph(query: str, top: int, skip_token: Optional[str] = None) -> Dict[str, Any]:
|
|
connection = get_connection()
|
|
options = {"$top": top, "resultFormat": "objectArray"}
|
|
if skip_token:
|
|
options["$skipToken"] = skip_token
|
|
token = await _azure_token(connection)
|
|
response = await _with_backoff(lambda: _azure_client().post(
|
|
f"{_azure_endpoints(connection)['arm']}/providers/Microsoft.ResourceGraph/resources",
|
|
params={"api-version": AZURE_GRAPH_VERSION}, headers={"Authorization": f"Bearer {token}"},
|
|
json={"query": query, "options": options, **_azure_scope(connection)}))
|
|
response.raise_for_status()
|
|
return response.json()
|
|
|
|
async def _azure_page(tool: str, arguments: Dict[str, Any], query: str, finish=None) -> Dict[str, Any]:
|
|
try:
|
|
upstream, skip = _read_page(arguments)
|
|
except (ValueError, KeyError, TypeError):
|
|
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
|
try:
|
|
body = await _azure_graph(query, _page_size(arguments), upstream)
|
|
except Exception as error:
|
|
return _upstream_failed("azure", error)
|
|
items = [finish(i) for i in body.get("data", [])] if finish else body.get("data", [])
|
|
return _page_result("azure", tool, arguments, items, upstream, body.get("$skipToken"), skip)
|
|
|
|
def _azure_type_query(table: str, types: List[str]) -> str:
|
|
listed = ", ".join(f"'{t}'" for t in types)
|
|
return f"{table} | where type in~ ({listed}) | order by id asc"
|
|
|
|
async def _azure_kind(tool: str, arguments: Dict[str, Any], kinds: Dict[str, List[str]], table: str = "Resources",
|
|
default: Optional[str] = None, finish=None) -> Dict[str, Any]:
|
|
kind = arguments.get("kind") or default or next(iter(kinds))
|
|
if kind not in kinds:
|
|
return _refuse("unknown_kind", "kind must be one of: " + ", ".join(kinds))
|
|
return await _azure_page(tool, arguments, _azure_type_query(table, kinds[kind]), finish)
|
|
|
|
def _azure_recommendation(item: Dict[str, Any]) -> Dict[str, Any]:
|
|
category = str(item.get("properties", {}).get("category", ""))
|
|
return {**item, "pillar": AZURE_PILLARS.get(category.lower(), "other"), "provider_category": category}
|
|
|
|
async def _azure_lock_subscription(arguments: Dict[str, Any]):
|
|
"""The subscription to read locks from, or None. Resource Graph, under the connection's scope, sets the boundary."""
|
|
kind, identifiers = next(iter(_azure_scope(get_connection()).items()))
|
|
wanted = arguments.get("subscription_id")
|
|
if kind == "subscriptions":
|
|
return identifiers[0] if wanted in (None, identifiers[0]) else None
|
|
if not wanted or not re.fullmatch(r"[A-Za-z0-9\-]+", str(wanted)):
|
|
return None
|
|
query = f"ResourceContainers | where type =~ 'microsoft.resources/subscriptions' and subscriptionId =~ '{wanted}'"
|
|
return wanted if (await _azure_graph(query, 1)).get("data") else None
|
|
|
|
async def _azure_locks(tool: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
"""Resource locks, from ARM: Resource Graph doesn't hold them, and answers 0 whether or not any exist."""
|
|
try:
|
|
upstream, skip = _read_page(arguments)
|
|
except (ValueError, KeyError, TypeError):
|
|
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
|
connection = get_connection()
|
|
try:
|
|
subscription = await _azure_lock_subscription(arguments)
|
|
if not subscription:
|
|
return _refuse("outside_scope", "subscription_id must name a subscription under this connection's scope")
|
|
base = f"{_azure_endpoints(connection)['arm']}/subscriptions/{subscription}/providers/Microsoft.Authorization/locks"
|
|
# A page token carries ARM's next link, and the bearer token goes wherever it points, so it must stay here.
|
|
url = upstream or f"{base}?api-version={AZURE_LOCKS_VERSION}"
|
|
if not url.startswith(f"{base}?"):
|
|
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
|
token = await _azure_token(connection)
|
|
response = await _with_backoff(lambda: _azure_client().get(url, headers={"Authorization": f"Bearer {token}"}))
|
|
response.raise_for_status()
|
|
body = response.json()
|
|
except Exception as error:
|
|
return _upstream_failed("azure", error)
|
|
return _page_result("azure", tool, arguments, body.get("value", []), upstream, body.get("nextLink"), skip,
|
|
{"subscription_id": subscription, "kind": "resource_locks"})
|
|
|
|
async def azure_check_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
try:
|
|
body = await _azure_graph("ResourceContainers | summarize count()", 1)
|
|
except Exception as error:
|
|
return {"ok": False, "message": _upstream_failed("azure", error)["error"]["message"]}
|
|
return {"ok": True, "message": "Signed in and read the scope root."}
|
|
|
|
async def azure_list_accounts(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
kinds = {"subscriptions": ["microsoft.resources/subscriptions"], "management_groups": ["microsoft.management/managementgroups"], "resource_groups": ["microsoft.resources/subscriptions/resourcegroups"]}
|
|
return await _azure_kind("azure_list_accounts", arguments, kinds, "ResourceContainers", "subscriptions")
|
|
|
|
async def azure_list_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
kind = arguments.get("resource_type")
|
|
if kind and not re.fullmatch(r"[A-Za-z0-9./]+", str(kind)):
|
|
return _refuse("invalid_argument", "resource_type must be an ARM type")
|
|
where = f" | where type =~ '{kind}'" if kind else ""
|
|
return await _azure_page("azure_list_resources", arguments, f"Resources{where} | project id, name, type, location, resourceGroup, subscriptionId, tags | order by id asc")
|
|
|
|
async def azure_query_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
query = str(arguments.get("query") or "").strip()
|
|
if not query or len(query) > 4000:
|
|
return _refuse("invalid_argument", "query is required, up to 4000 characters")
|
|
if query.split("|")[0].strip().lower() not in AZURE_TABLES:
|
|
return _refuse("invalid_argument", "query must start with one of: " + ", ".join(AZURE_TABLES))
|
|
return await _azure_page("azure_query_resources", arguments, query)
|
|
|
|
async def azure_get_resource_metadata(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
resource_id = str(arguments.get("resource_id") or "")
|
|
if not re.fullmatch(r"/subscriptions/[A-Za-z0-9\-]+(/[A-Za-z0-9._()\-]+)+", resource_id):
|
|
return _refuse("invalid_argument", "resource_id must be a full ARM resource id")
|
|
try:
|
|
body = await _azure_graph(f"Resources | where id =~ '{resource_id}'", 1)
|
|
except Exception as error:
|
|
return _upstream_failed("azure", error)
|
|
if not body.get("data"):
|
|
return _refuse("outside_scope", "no such resource inside this connection's scope")
|
|
return _one_result("azure", "azure_get_resource_metadata", arguments, body["data"][0])
|
|
|
|
async def azure_list_servers(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _azure_kind("azure_list_servers", arguments, AZURE_SERVERS)
|
|
|
|
async def azure_list_workloads(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _azure_kind("azure_list_workloads", arguments, AZURE_WORKLOADS)
|
|
|
|
async def azure_list_kubernetes_clusters(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _azure_kind("azure_list_kubernetes_clusters", arguments, AZURE_KUBERNETES)
|
|
|
|
async def azure_get_network_topology(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _azure_kind("azure_get_network_topology", arguments, AZURE_NETWORK)
|
|
|
|
async def azure_list_data_stores(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _azure_kind("azure_list_data_stores", arguments, AZURE_DATA)
|
|
|
|
async def azure_list_organization_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _azure_kind("azure_list_organization_policies", arguments, AZURE_ORG_POLICIES, "PolicyResources", "assignments")
|
|
|
|
async def azure_list_resource_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
if arguments.get("kind") == "resource_locks":
|
|
return await _azure_locks("azure_list_resource_policies", arguments)
|
|
return await _azure_kind("azure_list_resource_policies", arguments, AZURE_RESOURCE_POLICIES)
|
|
|
|
async def azure_list_recommendations(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
query = "AdvisorResources | where type =~ 'microsoft.advisor/recommendations' | order by id asc"
|
|
return await _azure_page("azure_list_recommendations", arguments, query, _azure_recommendation)
|
|
|
|
async def verify_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
"""Check that the connection sent with this request works against the upstream. Makes no change."""
|
|
connection = get_connection()
|
|
if not connection:
|
|
return {"ok": False, "message": "No connection was sent with this request."}
|
|
missing = mcp_connection.missing_fields(connection, CONNECTION_SCHEMA)
|
|
if missing:
|
|
return {"ok": False, "message": "The connection is missing: " + ", ".join(missing)}
|
|
|
|
return await azure_check_connection(arguments)
|
|
|
|
|
|
# Tool function registry
|
|
TOOL_FUNCTIONS = {
|
|
'azure_check_connection': azure_check_connection,
|
|
'azure_list_accounts': azure_list_accounts,
|
|
'azure_list_resources': azure_list_resources,
|
|
'azure_query_resources': azure_query_resources,
|
|
'azure_get_resource_metadata': azure_get_resource_metadata,
|
|
'azure_list_servers': azure_list_servers,
|
|
'azure_list_workloads': azure_list_workloads,
|
|
'azure_list_kubernetes_clusters': azure_list_kubernetes_clusters,
|
|
'azure_get_network_topology': azure_get_network_topology,
|
|
'azure_list_data_stores': azure_list_data_stores,
|
|
'azure_list_organization_policies': azure_list_organization_policies,
|
|
'azure_list_resource_policies': azure_list_resource_policies,
|
|
'azure_list_recommendations': azure_list_recommendations,
|
|
'verify_connection': verify_connection,
|
|
}
|
|
|
|
# ============================================
|
|
# Resource Implementations
|
|
# ============================================
|
|
|
|
|
|
# Resource read handlers by uri
|
|
RESOURCE_HANDLERS = {
|
|
|
|
}
|
|
|
|
# ============================================
|
|
# FastAPI Application
|
|
# ============================================
|
|
|
|
@asynccontextmanager
|
|
async def lifespan(app: FastAPI):
|
|
"""Application lifespan manager"""
|
|
logger.info(
|
|
"server_starting",
|
|
port=config.SERVER_PORT,
|
|
auth_required=config.REQUIRE_AUTH,
|
|
tools=len(TOOLS_REGISTRY),
|
|
resources=len(RESOURCES_REGISTRY),
|
|
prompts=len(PROMPTS_REGISTRY),
|
|
template_version=TEMPLATE_VERSION,
|
|
)
|
|
|
|
# Validate configuration
|
|
if config.REQUIRE_AUTH and not config.MCP_REGISTRATION_API_KEY:
|
|
logger.error(
|
|
"registration_key_not_set",
|
|
hint="Set MCP_REGISTRATION_API_KEY before starting the server",
|
|
)
|
|
|
|
yield
|
|
|
|
await _close_all_clients()
|
|
logger.info("server_stopping")
|
|
|
|
app = FastAPI(
|
|
title=config.SERVER_NAME,
|
|
version=config.SERVER_VERSION,
|
|
description="Read-only discovery of a customer's Azure estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Advisor findings - through Azure Resource Graph.",
|
|
lifespan=lifespan
|
|
)
|
|
|
|
|
|
# FastAPI's default answer to an invalid request repeats it, and the request can carry the tenant's connection
|
|
mcp_connection.install_invalid_request_handler(
|
|
app, lambda fields: logger.warning("invalid_request", fields=sanitize_log(fields))
|
|
)
|
|
|
|
# ============================================
|
|
# Health Check Endpoint
|
|
# ============================================
|
|
|
|
@app.get("/health")
|
|
async def health_check():
|
|
"""
|
|
Health check endpoint (no authentication required).
|
|
|
|
Used by:
|
|
- MCP Gateway health monitoring
|
|
- Kubernetes liveness/readiness probes
|
|
- Load balancers
|
|
"""
|
|
# Answers without a key, so it says only what a probe needs: not how authentication is set up
|
|
return {
|
|
"status": "healthy" if config.MCP_REGISTRATION_API_KEY else "degraded",
|
|
"server_id": config.SERVER_ID,
|
|
"server_name": config.SERVER_NAME,
|
|
"version": config.SERVER_VERSION,
|
|
"timestamp": datetime.now(timezone.utc).isoformat(),
|
|
}
|
|
|
|
# ============================================
|
|
# MCP Authentication Info Endpoint
|
|
# ============================================
|
|
|
|
@app.get("/.well-known/mcp-auth")
|
|
async def mcp_auth_info():
|
|
"""
|
|
MCP Authentication Information Endpoint (PUBLIC - no auth required).
|
|
|
|
Exposes authentication requirements for Gateway registration.
|
|
"""
|
|
return {
|
|
"auth_required": config.REQUIRE_AUTH,
|
|
"auth_type": "bearer",
|
|
"description": "Include 'Authorization: Bearer <MCP_REGISTRATION_API_KEY>' header",
|
|
"env_var": "MCP_REGISTRATION_API_KEY"
|
|
}
|
|
|
|
# ============================================
|
|
# MCP Protocol /messages Endpoint
|
|
# ============================================
|
|
|
|
class _MethodNotFound(Exception):
|
|
"""The JSON-RPC method is not one this server answers."""
|
|
|
|
|
|
async def dispatch_mcp_request(request: MCPRequest) -> MCPResponse:
|
|
"""Run one JSON-RPC request; every outcome, errors included, is an MCPResponse."""
|
|
# The tenant's connection, bound for this request only so tools reach the right account
|
|
connection_token = mcp_connection.bind(mcp_connection.from_params(request.params))
|
|
try:
|
|
if CONNECTION_SCHEMA is not None and request.method in CONNECTION_METHODS:
|
|
check_connection(mcp_connection.active())
|
|
|
|
if request.method == "initialize":
|
|
result = {
|
|
"protocolVersion": "1.0.0",
|
|
"serverInfo": {
|
|
"name": config.SERVER_NAME,
|
|
"version": config.SERVER_VERSION,
|
|
"server_id": config.SERVER_ID
|
|
},
|
|
"capabilities": {
|
|
"tools": True,
|
|
"resources": False,
|
|
"prompts": False
|
|
},
|
|
"authentication": {
|
|
"type": "bearer",
|
|
"description": "Requires MCP_REGISTRATION_API_KEY in Authorization header"
|
|
}
|
|
}
|
|
if CONNECTION_SCHEMA is not None:
|
|
result["_meta"] = mcp_connection.schema_meta(CONNECTION_SCHEMA, verify_tool=VERIFY_TOOL)
|
|
return MCPResponse(id=request.id, result=result)
|
|
|
|
elif request.method == "tools/list":
|
|
return MCPResponse(id=request.id, result={"tools": TOOLS_REGISTRY})
|
|
|
|
elif request.method == "tools/call":
|
|
tool_name = request.params.get("name")
|
|
arguments = request.params.get("arguments")
|
|
if arguments is None:
|
|
arguments = {}
|
|
|
|
if not tool_name:
|
|
raise ValueError("Missing 'name' in params")
|
|
if not isinstance(tool_name, str):
|
|
raise ValueError("'name' must be a string")
|
|
if not isinstance(arguments, dict):
|
|
raise ValueError("'arguments' must be an object")
|
|
|
|
structlog.contextvars.bind_contextvars(tool=sanitize_log(tool_name))
|
|
tool_func = TOOL_FUNCTIONS.get(tool_name)
|
|
if not tool_func:
|
|
raise ValueError(f"Unknown tool: {tool_name}")
|
|
|
|
result = await tool_func(arguments)
|
|
if isinstance(result, dict) and result.get("success") is False and isinstance(result.get("error"), str):
|
|
# A failed call's message often quotes the upstream URL, which may carry a key
|
|
result = {**result, "error": mcp_connection.scrub(result["error"])}
|
|
|
|
reply = {
|
|
"content": [
|
|
{
|
|
"type": "text",
|
|
"text": json.dumps(result) if isinstance(result, dict) else str(result)
|
|
}
|
|
]
|
|
}
|
|
if isinstance(result, dict) and result.get("success") is False:
|
|
# A tool that reports failure is an error to the caller too (MCP: isError), not a normal result
|
|
reply["isError"] = True
|
|
return MCPResponse(id=request.id, result=reply)
|
|
|
|
elif request.method == "resources/list":
|
|
return MCPResponse(id=request.id, result={"resources": RESOURCES_REGISTRY})
|
|
|
|
elif request.method == "resources/read":
|
|
uri = request.params.get("uri")
|
|
if not uri:
|
|
raise ValueError("Missing 'uri' in params")
|
|
structlog.contextvars.bind_contextvars(resource=sanitize_log(uri))
|
|
handler = RESOURCE_HANDLERS.get(uri)
|
|
if not handler:
|
|
raise ValueError(f"Unknown resource: {uri}")
|
|
content = await handler(uri)
|
|
mime_type = next((r["mimeType"] for r in RESOURCES_REGISTRY if r["uri"] == uri), "text/plain")
|
|
text = content if isinstance(content, str) else json.dumps(content)
|
|
return MCPResponse(id=request.id, result={
|
|
"contents": [{"uri": uri, "mimeType": mime_type, "text": text}]
|
|
})
|
|
|
|
elif request.method == "prompts/list":
|
|
return MCPResponse(id=request.id, result={"prompts": PROMPTS_REGISTRY})
|
|
|
|
elif request.method == "prompts/get":
|
|
prompt_name = request.params.get("name")
|
|
prompt = PROMPT_TEMPLATES.get(prompt_name) if isinstance(prompt_name, str) else None
|
|
if prompt is None:
|
|
raise ValueError(f"Unknown prompt: {prompt_name}")
|
|
structlog.contextvars.bind_contextvars(prompt=sanitize_log(prompt_name))
|
|
supplied = request.params.get("arguments") or {}
|
|
values = {a["name"]: a["default"] for a in prompt["arguments"] if a["default"] is not None}
|
|
values.update(supplied)
|
|
missing = [a["name"] for a in prompt["arguments"] if a["required"] and a["name"] not in values]
|
|
if missing:
|
|
raise ValueError("Missing prompt argument(s): " + ", ".join(missing))
|
|
return MCPResponse(id=request.id, result={
|
|
"description": prompt["description"],
|
|
"messages": [{
|
|
"role": "user",
|
|
"content": {"type": "text", "text": render_prompt(prompt["template"], values)},
|
|
}],
|
|
})
|
|
|
|
else:
|
|
raise _MethodNotFound(f"Unknown method: {request.method}")
|
|
|
|
except _MethodNotFound as e:
|
|
logger.warning("mcp_method_not_found", error=sanitize_log(mcp_connection.redact(e)))
|
|
return MCPResponse(id=request.id, error={"code": -32601, "message": mcp_connection.redact(e)})
|
|
except NotImplementedError as e:
|
|
message = mcp_connection.redact(e)
|
|
logger.warning("tool_not_implemented", error=sanitize_log(message))
|
|
return MCPResponse(id=request.id, error={"code": -32601, "message": message})
|
|
except ValueError as e:
|
|
message = mcp_connection.redact(e)
|
|
logger.warning("mcp_client_error", error=sanitize_log(message))
|
|
return MCPResponse(id=request.id, error={"code": -32602, "message": message})
|
|
except Exception as e:
|
|
# The message of an unexpected error is not shown to the caller and is redacted before it is logged;
|
|
# a tool may have put the connection's credential in it.
|
|
logger.error(
|
|
"mcp_unexpected_error",
|
|
error_type=type(e).__name__,
|
|
error=sanitize_log(mcp_connection.redact(e)),
|
|
traceback=sanitize_log(mcp_connection.redact(traceback.format_exc())),
|
|
)
|
|
return MCPResponse(id=request.id, error={"code": -32603, "message": "Internal server error"})
|
|
finally:
|
|
mcp_connection.unbind(connection_token)
|
|
|
|
|
|
@app.post("/messages")
|
|
async def handle_mcp_message(
|
|
request: MCPRequest,
|
|
http_request: Request,
|
|
authenticated: bool = Depends(verify_mcp_registration_key)
|
|
) -> MCPResponse:
|
|
"""
|
|
MCP protocol message handler (JSON-RPC 2.0 over HTTP).
|
|
|
|
This is the STANDARD MCP endpoint for Gateway integration.
|
|
Requires Bearer token authentication (MCP_REGISTRATION_API_KEY).
|
|
|
|
Supported Methods:
|
|
- initialize: Protocol handshake and capability exchange
|
|
- tools/list: Discover available tools
|
|
- tools/call: Execute a specific tool
|
|
- resources/list: List available resources
|
|
- prompts/list: List available prompts
|
|
"""
|
|
started = time.monotonic()
|
|
structlog.contextvars.clear_contextvars()
|
|
structlog.contextvars.bind_contextvars(
|
|
request_id=sanitize_log(http_request.headers.get("x-request-id") or str(request.id)),
|
|
method=sanitize_log(request.method),
|
|
)
|
|
try:
|
|
response = await dispatch_mcp_request(request)
|
|
completed = {}
|
|
if CONNECTION_SCHEMA is not None and request.method in CONNECTION_METHODS:
|
|
# Which connection served the call: a short id, never the credential
|
|
completed["connection"] = mcp_connection.fingerprint(mcp_connection.from_params(request.params))
|
|
logger.info(
|
|
"mcp_request_completed",
|
|
outcome="error" if response.error else ("tool_error" if (response.result or {}).get("isError") else "ok"),
|
|
error_code=(response.error or {}).get("code"),
|
|
duration_ms=round((time.monotonic() - started) * 1000, 1),
|
|
**completed,
|
|
)
|
|
return response
|
|
finally:
|
|
structlog.contextvars.clear_contextvars()
|
|
|
|
# ============================================
|
|
# Entry Point
|
|
# ============================================
|
|
|
|
if __name__ == "__main__":
|
|
import uvicorn
|
|
uvicorn.run(
|
|
"server:app",
|
|
host="0.0.0.0",
|
|
port=config.SERVER_PORT,
|
|
log_level=logging.getLevelName(getattr(logging, config.LOG_LEVEL, logging.INFO)).lower(),
|
|
log_config=None, # configure_logging() owns the format
|
|
access_log=True,
|
|
reload=False # Set to True for development
|
|
)
|