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:
@@ -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,
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user