Platform scripts, MCP servers, deployment and docs for the KAB runs

- Scripts to run workflows from a YAML context or run inputs (kab_run_workflow.py, with
  --input name=@file), store per-project discovery connections, bootstrap agent MCP keys,
  refresh the KAB token, publish reports and build estate snapshots.
- Hyperscaler discovery servers extended in place; cloud-knowledge folded into them.
- deploy/crucible-kab-dev.yaml: the Discovery package agent and the Assessment agents.
- Platform issue write-ups and current-wiring notes under docs/platform-issues/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-05 22:13:25 +00:00
parent c14a94f33b
commit f659564208
71 changed files with 2818 additions and 2821 deletions

View File

@@ -4,7 +4,7 @@
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
Version: 0.1.6
Template: mcp-server-template 1.1.0
Features:
@@ -82,8 +82,11 @@ CONNECTION_SCHEMA = {'type': 'object',
'format': 'password'},
'scope_root': {'type': 'string',
'title': 'Scope root',
'description': 'What may be read: managementGroups/<id> '
'or subscriptions/<id>.'},
'description': 'What may be read: '
'managementGroups/<id>, '
'subscriptions/<id>, or one resource '
'group, '
'subscriptions/<id>/resourceGroups/<name>.'},
'cloud': {'type': 'string',
'title': 'Cloud',
'description': 'public, usgov or china. Default public.'}},
@@ -120,7 +123,7 @@ class Config:
# 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')
SERVER_VERSION = os.getenv("MCP_SERVER_VERSION", '0.1.6')
# 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")
@@ -513,10 +516,11 @@ TOOLS_REGISTRY = [
},
{
"name": 'azure_list_data_stores',
"description": 'List SQL, Cosmos DB or storage account metadata. Never rows, documents or blobs.',
"description": 'List SQL, Cosmos DB, storage account, PostgreSQL, MySQL or Redis metadata. Never rows, documents or blobs.',
"inputSchema": {'type': 'object',
'properties': {'kind': {'type': 'string',
'description': 'One of: sql, cosmos_db, storage_accounts.'},
'description': 'One of: sql, cosmos_db, storage_accounts, '
'postgresql, mysql, redis.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
@@ -567,6 +571,18 @@ TOOLS_REGISTRY = [
'reply.'}},
'required': []}
},
{
"name": 'azure_search_well_architected',
"description": "Search the Azure Well-Architected Framework's guidance by pillar and topic. Both come from fixed lists, so no customer detail leaves the platform. Microsoft Learn is public, so no credential is used.",
"inputSchema": {'type': 'object',
'properties': {'pillar': {'type': 'string',
'description': 'reliability, security, cost, operations, '
'performance or sustainability.'},
'topic': {'type': 'string',
'description': 'One of the fixed topics; an invalid value '
'lists them.'}},
'required': ['pillar', 'topic']}
},
{
"name": 'verify_connection',
"description": (
@@ -623,6 +639,8 @@ SECRET_KEYS = (
"secretvalue", "sastoken", "accesskey", "primarykey", "secondarykey", "privatekey", "kubeconfig", "credentials",
)
SCALAR_SAFE_KEYS = ("env",)
PERSON_KEYS = (
"createdby", "lastmodifiedby", "updatedby", "creator", "owner", "owneremail", "contact", "contactemail", "email",
"objectid", "principalid", "principalname", "userprincipalname",
@@ -654,10 +672,13 @@ def _anonymise_member(value: str) -> str:
return PRINCIPAL_KINDS[kind]
return _clean_text(value)
def _scalar(value) -> bool:
return value is None or isinstance(value, (str, bool, int, float))
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:
if lowered in SECRET_KEYS and not (lowered in SCALAR_SAFE_KEYS and _scalar(value)):
return "[redacted]"
if lowered in PERSON_KEYS:
return "[user]"
@@ -667,7 +688,7 @@ def _scrub(value, key: str = ""):
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:
elif name in cleaned and tag in SECRET_KEYS and not (tag in SCALAR_SAFE_KEYS and _scalar(cleaned[name])):
cleaned[name] = "[redacted]"
return cleaned
if isinstance(value, (list, tuple)):
@@ -812,6 +833,9 @@ AZURE_DATA = {
"sql": ["microsoft.sql/servers", "microsoft.sql/servers/databases"],
"cosmos_db": ["microsoft.documentdb/databaseaccounts"],
"storage_accounts": ["microsoft.storage/storageaccounts"],
"postgresql": ["microsoft.dbforpostgresql/flexibleservers", "microsoft.dbforpostgresql/servers"],
"mysql": ["microsoft.dbformysql/flexibleservers", "microsoft.dbformysql/servers"],
"redis": ["microsoft.cache/redis", "microsoft.cache/redisenterprise"],
}
AZURE_ORG_POLICIES = {
@@ -830,13 +854,41 @@ AZURE_RESOURCE_POLICIES = {
AZURE_PILLARS = {"cost": "cost", "security": "security", "highavailability": "reliability",
"performance": "performance", "operationalexcellence": "operations"}
AZURE_RESOURCE_GROUP = r"[-\w.()]{1,90}"
def _azure_root(connection: Dict[str, Any]) -> tuple:
"""(managementGroups or subscriptions, its id, the resource group or None) from the connection's scope root."""
parts = str(connection.get("scope_root", "")).strip("/").split("/")
if len(parts) == 2 and parts[0] in ("managementGroups", "subscriptions") and parts[1]:
return parts[0], parts[1], None
if (len(parts) == 4 and parts[0] == "subscriptions" and parts[1] and parts[2].lower() == "resourcegroups"
and re.fullmatch(AZURE_RESOURCE_GROUP, parts[3]) and not parts[3].endswith(".")):
return "subscriptions", parts[1], parts[3]
raise ValueError("scope_root must be managementGroups/<id>, subscriptions/<id> or "
"subscriptions/<id>/resourceGroups/<name>")
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>")
kind, identifier, _ = _azure_root(connection)
return {kind: [identifier]}
def _azure_scoped_query(query: str, connection: Dict[str, Any]) -> str:
"""The query narrowed to the connection's resource group, when its scope root names one.
Resource Graph scopes by subscription or management group only, so a resource group is a filter placed straight
after the table. Rows outside any resource group (the subscription itself, subscription-wide policy assignments
and Advisor findings) still apply to the group, so they stay. A join, union or lookup could read a second table
without the filter, so a resource-group scope refuses them.
"""
_, _, group = _azure_root(connection)
if group is None:
return query
if re.search(r"\b(join|union|lookup)\b", query, re.IGNORECASE):
raise PermissionError("a resource-group scope allows no join, union or lookup")
table, bar, rest = query.partition("|")
narrowed = f"{table.strip()} | where isempty(resourceGroup) or resourceGroup =~ '{group}'"
return f"{narrowed} |{rest}" if bar else narrowed
def _azure_endpoints(connection: Dict[str, Any]) -> Dict[str, str]:
return AZURE_CLOUDS.get(str(connection.get("cloud") or "public"), AZURE_CLOUDS["public"])
@@ -873,7 +925,7 @@ async def _azure_graph(query: str, top: int, skip_token: Optional[str] = None) -
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)}))
json={"query": _azure_scoped_query(query, connection), "options": options, **_azure_scope(connection)}))
response.raise_for_status()
return response.json()
@@ -884,6 +936,8 @@ async def _azure_page(tool: str, arguments: Dict[str, Any], query: str, finish=N
return _refuse("invalid_page_token", "page_token isn't one this server issued")
try:
body = await _azure_graph(query, _page_size(arguments), upstream)
except PermissionError as error:
return _refuse("outside_scope", str(error))
except Exception as error:
return _upstream_failed("azure", error)
items = [finish(i) for i in body.get("data", [])] if finish else body.get("data", [])
@@ -926,7 +980,9 @@ async def _azure_locks(tool: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
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"
group = _azure_root(connection)[2]
within = f"/resourceGroups/{group}" if group else ""
base = f"{_azure_endpoints(connection)['arm']}/subscriptions/{subscription}{within}/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}?"):
@@ -940,11 +996,139 @@ async def _azure_locks(tool: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
return _page_result("azure", tool, arguments, body.get("value", []), upstream, body.get("nextLink"), skip,
{"subscription_id": subscription, "kind": "resource_locks"})
KNOWLEDGE_SERVERS = {
"azure": {"url": "https://learn.microsoft.com/api/mcp", "tool": "microsoft_docs_search",
"framework": "Azure Well-Architected Framework"},
"aws": {"url": "https://aws-mcp.eu-west-1.api.aws/mcp", "tool": "aws___search_documentation",
"framework": "AWS Well-Architected Framework"},
"gcp": {"url": "https://developerknowledge.googleapis.com/mcp", "tool": "search_documents",
"framework": "Google Cloud Well-Architected Framework"},
}
KNOWLEDGE_PILLARS = ("reliability", "security", "cost", "operations", "performance", "sustainability")
KNOWLEDGE_TOPICS = (
"landing zone", "resource organization", "identity and access", "network segmentation", "hybrid connectivity",
"encryption", "logging and monitoring", "backup and recovery", "disaster recovery", "high availability",
"scaling", "kubernetes", "containers", "virtual machines", "databases", "storage", "serverless", "governance",
"policy enforcement", "tagging", "cost allocation", "migration", "incident response", "patching",
)
KNOWLEDGE_MAX_TEXT = 4000
def _knowledge_client():
return get_upstream_client("knowledge", lambda c: httpx.AsyncClient(timeout=60, follow_redirects=False))
def _knowledge_message(response) -> Dict[str, Any]:
"""The JSON-RPC reply, whether it came back as JSON or as a server-sent event."""
if "text/event-stream" in response.headers.get("content-type", ""):
lines = [line[5:].strip() for line in response.text.splitlines() if line.startswith("data:")]
return json.loads(lines[-1]) if lines else {}
return response.json()
async def _knowledge_post(provider: str, connection: Dict[str, Any], body: Dict[str, Any],
session: Optional[str] = None, auth: Optional[Dict[str, str]] = None):
"""auth: headers a discovery server supplies from its own connection (gcp-discovery's OAuth token), used in
place of the stored API key."""
url = KNOWLEDGE_SERVERS[provider]["url"]
headers = {"Accept": "application/json, text/event-stream", "Content-Type": "application/json"}
if session:
headers["Mcp-Session-Id"] = session
if auth:
headers.update(auth)
elif provider == "gcp":
headers["X-Goog-Api-Key"] = connection.get("google_api_key", "")
content = json.dumps(body)
if provider == "aws":
import boto3
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
def sign():
credentials = boto3.Session(aws_access_key_id=connection.get("aws_access_key_id"),
aws_secret_access_key=connection.get("aws_secret_access_key")).get_credentials()
request = AWSRequest(method="POST", url=url, data=content, headers=headers)
SigV4Auth(credentials, "aws-mcp", "eu-west-1").add_auth(request)
return dict(request.headers)
headers = await asyncio.to_thread(sign)
response = await _with_backoff(lambda: _knowledge_client().post(url, content=content, headers=headers))
response.raise_for_status()
return response
async def _knowledge_session(provider: str, connection: Dict[str, Any], auth: Optional[Dict[str, str]] = None) -> Optional[str]:
response = await _knowledge_post(provider, connection, {
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {"protocolVersion": "2025-06-18", "capabilities": {},
"clientInfo": {"name": "kab-cp1-discovery", "version": "0.1.0"}}}, auth=auth)
return response.headers.get("mcp-session-id")
async def _knowledge_tools(provider: str, connection: Dict[str, Any], session: Optional[str] = None,
auth: Optional[Dict[str, str]] = None) -> List[Dict[str, Any]]:
session = session or await _knowledge_session(provider, connection, auth)
response = await _knowledge_post(provider, connection, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session, auth)
return _knowledge_message(response).get("result", {}).get("tools", [])
def _knowledge_argument(tool: Dict[str, Any]) -> str:
"""The search tool's query argument. Vendors name it differently and may change it, so it's read from the tool."""
schema = tool.get("inputSchema", {})
properties = schema.get("properties", {})
for name in list(schema.get("required", [])) + list(properties):
if properties.get(name, {}).get("type") == "string":
return name
return "query"
async def _knowledge_search(provider: str, connection: Dict[str, Any], query: str,
auth: Optional[Dict[str, str]] = None) -> List[Dict[str, Any]]:
session = await _knowledge_session(provider, connection, auth)
name = KNOWLEDGE_SERVERS[provider]["tool"]
tools = {t.get("name"): t for t in await _knowledge_tools(provider, connection, session, auth)}
if name not in tools:
raise LookupError(f"{provider} no longer offers {name}")
response = await _knowledge_post(provider, connection, {
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": {"name": name, "arguments": {_knowledge_argument(tools[name]): query}}}, session, auth)
message = _knowledge_message(response)
results = []
for part in message.get("result", {}).get("content", []):
if part.get("type") != "text":
continue
try:
parsed = json.loads(part["text"])
except ValueError:
parsed = {"content": part["text"]}
found = parsed.get("results", parsed) if isinstance(parsed, dict) else parsed
for item in found if isinstance(found, list) else [found]:
if isinstance(item, dict):
results.append({"title": item.get("title"), "url": item.get("contentUrl") or item.get("url"),
"text": str(item.get("content") or item.get("text") or "")[:KNOWLEDGE_MAX_TEXT]})
return results
async def _knowledge_tool(provider: str, tool: str, arguments: Dict[str, Any], connection: Dict[str, Any],
auth: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
"""One provider's `<provider>_search_well_architected` tool: fixed pillar and topic in, guidance excerpts out."""
pillar, topic = arguments.get("pillar"), arguments.get("topic")
if pillar not in KNOWLEDGE_PILLARS:
return _refuse("invalid_argument", "pillar must be one of: " + ", ".join(KNOWLEDGE_PILLARS))
if topic not in KNOWLEDGE_TOPICS:
return _refuse("invalid_argument", "topic must be one of: " + ", ".join(KNOWLEDGE_TOPICS))
query = f"{KNOWLEDGE_SERVERS[provider]['framework']} {pillar} {topic}"
try:
results = await _knowledge_search(provider, connection, query, auth)
except Exception as error:
return _upstream_failed(provider, error)
return {"success": True, "data": {"provider": provider, "pillar": pillar, "topic": topic, "results": results,
"collected_at": _collected_at(), "evidence_ref": _evidence_ref(tool, arguments, results)}}
async def azure_check_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
try:
body = await _azure_graph("ResourceContainers | summarize count()", 1)
group = _azure_root(get_connection())[2]
query = "ResourceContainers | where type =~ 'microsoft.resources/subscriptions/resourcegroups' | summarize count()" if group else "ResourceContainers | summarize count()"
body = await _azure_graph(query, 1)
except Exception as error:
return {"ok": False, "message": _upstream_failed("azure", error)["error"]["message"]}
if group and not any(int(v or 0) for row in body.get("data", []) for v in row.values()):
return {"ok": False, "message": "Signed in, but the resource group in the scope root was not found or is not readable."}
return {"ok": True, "message": "Signed in and read the scope root."}
async def azure_list_accounts(arguments: Dict[str, Any]) -> Dict[str, Any]:
@@ -1005,6 +1189,9 @@ 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 azure_search_well_architected(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _knowledge_tool("azure", "azure_search_well_architected", arguments, {}, None)
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()
@@ -1032,6 +1219,7 @@ TOOL_FUNCTIONS = {
'azure_list_organization_policies': azure_list_organization_policies,
'azure_list_resource_policies': azure_list_resource_policies,
'azure_list_recommendations': azure_list_recommendations,
'azure_search_well_architected': azure_search_well_architected,
'verify_connection': verify_connection,
}