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

@@ -34,6 +34,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 = {
"assignments": ["microsoft.authorization/policyassignments"],
@@ -50,14 +53,45 @@ AZURE_PILLARS = {"cost": "cost", "security": "security", "highavailability": "re
"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"])
@@ -97,7 +131,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()
@@ -109,6 +143,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", [])
@@ -156,7 +192,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}?"):

View File

@@ -58,6 +58,8 @@ def _gcp_client():
async def _gcp_token() -> str:
connection = get_connection()
if connection.get("access_token"):
return str(connection["access_token"])
key = hashlib.sha256(json.dumps(connection, sort_keys=True).encode()).hexdigest()
cached = GCP_TOKENS.get(key)
now = time.time()
@@ -75,10 +77,32 @@ async def _gcp_token() -> str:
return token
def _gcp_quota_project() -> str:
"""The project Google bills a user credential's calls to: the connection's quota_project, else a projects/<id>
scope root. Recommender and Developer Knowledge refuse a user token without one; Cloud Asset doesn't need it."""
connection = get_connection()
if connection.get("quota_project"):
return str(connection["quota_project"])
kind, _, identifier = str(connection.get("scope_root", "")).strip("/").partition("/")
return identifier if kind == "projects" else ""
# The APIs that need a quota project for a user credential. Sent only to these, so Cloud Asset keeps working for a
# caller who lacks serviceusage.services.use on the quota project.
GCP_QUOTA_APIS = ("https://recommender.googleapis.com/",) # a literal: the builder refuses computed module-level values
async def _gcp_auth(quota: bool) -> Dict[str, str]:
headers = {"Authorization": f"Bearer {await _gcp_token()}"}
project = _gcp_quota_project() if quota else ""
if project:
headers["x-goog-user-project"] = project
return headers
async def _gcp_get(url: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
token = await _gcp_token()
response = await _with_backoff(
lambda: _gcp_client().get(url, params=params, headers={"Authorization": f"Bearer {token}"}))
headers = await _gcp_auth(url.startswith(GCP_QUOTA_APIS))
response = await _with_backoff(lambda: _gcp_client().get(url, params=params, headers=headers))
response.raise_for_status()
return response.json()

View File

@@ -1,9 +1,8 @@
# cloud-knowledge: calls each hyperscaler's hosted knowledge server over MCP. A query is only ever built from the
# fixed lists below, so a customer's name or resource can't reach a third party.
# Well-Architected guidance: calls each hyperscaler's hosted knowledge server over MCP. Inlined into the
# azure-discovery and gcp-discovery servers (cloud-knowledge, which also used it, was retired on 2026-11-04). A query is only ever built from the fixed lists below, so a
# customer's name or resource can't reach a third party. boto3 is imported only for AWS, so the other servers don't
# need it.
import asyncio
import boto3
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
KNOWLEDGE_SERVERS = {
"azure": {"url": "https://learn.microsoft.com/api/mcp", "tool": "microsoft_docs_search",
@@ -36,15 +35,23 @@ def _knowledge_message(response) -> Dict[str, Any]:
async def _knowledge_post(provider: str, connection: Dict[str, Any], body: Dict[str, Any],
session: Optional[str] = None):
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 provider == "gcp":
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()
@@ -58,17 +65,18 @@ async def _knowledge_post(provider: str, connection: Dict[str, Any], body: Dict[
return response
async def _knowledge_session(provider: str, connection: Dict[str, Any]) -> Optional[str]:
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": "cloud-knowledge", "version": "0.1.0"}}})
"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) -> List[Dict[str, Any]]:
session = session or await _knowledge_session(provider, connection)
response = await _knowledge_post(provider, connection, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session)
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", [])
@@ -82,15 +90,16 @@ def _knowledge_argument(tool: Dict[str, Any]) -> str:
return "query"
async def _knowledge_search(provider: str, connection: Dict[str, Any], query: str) -> List[Dict[str, Any]]:
session = await _knowledge_session(provider, connection)
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)}
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)
"params": {"name": name, "arguments": {_knowledge_argument(tools[name]): query}}}, session, auth)
message = _knowledge_message(response)
results = []
for part in message.get("result", {}).get("content", []):
@@ -106,3 +115,20 @@ async def _knowledge_search(provider: str, connection: Dict[str, Any], query: st
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)}}

View File

@@ -17,7 +17,6 @@ CONNECTIONS = {
"aws-discovery": {"access_key_id": "a", "secret_access_key": "b", "role_arn": "arn:aws:iam::111111111111:role/r",
"external_id": "e", "regions": "eu-west-2"},
"gcp-discovery": {"scope_root": "projects/p1", "service_account_json": "{}"},
"cloud-knowledge": {"google_api_key": "k"},
}
@@ -114,8 +113,6 @@ def test_evidence_changes_with_the_content():
def test_tools_refuse_a_forged_page_token():
if SERVER_DIR.name == "cloud-knowledge":
pytest.skip("this server has no paged tools")
prefix = SERVER_DIR.name.split("-")[0]
token = server.mcp_connection.bind(CONNECTIONS[SERVER_DIR.name])
try:

View File

@@ -0,0 +1,104 @@
"""`<provider>_search_well_architected`, for every discovery server that offers it. Run with SERVER_DIR set, as
test_contract.py is; a server without the tool skips. Moved from the retired cloud-knowledge server on 2026-11-04."""
import asyncio
import json
import os
import sys
from pathlib import Path
import httpx
import pytest
SERVER_DIR = Path(__file__).resolve().parents[1] / os.environ["SERVER_DIR"]
sys.path.insert(0, str(SERVER_DIR))
import mcp_connection # noqa: E402
import server # noqa: E402
PROVIDER = SERVER_DIR.name.split("-")[0]
TOOL = f"{PROVIDER}_search_well_architected"
VENDOR_TOOL = {"azure": "microsoft_docs_search", "gcp": "search_documents", "aws": "aws___search_documentation"}
CONNECTIONS = {"azure": {"tenant_id": "t", "client_id": "c", "client_secret": "s", "scope_root": "subscriptions/sub-1"},
"gcp": {"scope_root": "projects/p1", "access_token": "tok"}}
if not hasattr(server, TOOL):
pytest.skip(f"{SERVER_DIR.name} has no {TOOL}", allow_module_level=True)
class Vendor:
def __init__(self, tool=VENDOR_TOOL[PROVIDER], argument="query"):
self.tool, self.argument, self.sent, self.headers = tool, argument, [], []
def __call__(self, request):
body = json.loads(request.content)
self.sent.append(body)
self.headers.append(dict(request.headers))
if body["method"] == "initialize":
return httpx.Response(200, headers={"mcp-session-id": "s1"}, json={"result": {}})
if body["method"] == "tools/list":
return httpx.Response(200, json={"result": {"tools": [{"name": self.tool, "inputSchema": {
"required": [self.argument], "properties": {self.argument: {"type": "string"}}}}]}})
text = json.dumps({"results": [{"title": "Reliability", "contentUrl": "https://example.test/r", "content": "Guidance"}]})
payload = json.dumps({"result": {"content": [{"type": "text", "text": text}]}})
return httpx.Response(200, headers={"content-type": "text/event-stream"}, text=f"event: message\ndata: {payload}\n\n")
def call(arguments, vendor):
async def run():
client = httpx.AsyncClient(transport=httpx.MockTransport(vendor))
original = server.get_upstream_client
server.get_upstream_client = lambda kind, build: client
bound = mcp_connection.bind(CONNECTIONS[PROVIDER])
try:
return await getattr(server, TOOL)(arguments)
finally:
mcp_connection.unbind(bound)
server.get_upstream_client = original
await client.aclose()
return asyncio.run(run())
GOOD = {"pillar": "reliability", "topic": "landing zone"}
def test_search_returns_cited_guidance():
data = call(GOOD, Vendor())["data"]
assert data["provider"] == PROVIDER
assert data["results"][0]["url"] == "https://example.test/r" and data["evidence_ref"].startswith("sha256:")
def test_query_is_built_only_from_fixed_lists():
vendor = Vendor()
call({**GOOD, "customer": "Meridian Retail", "extra": "pos-db-01"}, vendor)
sent = json.dumps(vendor.sent)
assert f"{server.KNOWLEDGE_SERVERS[PROVIDER]['framework']} reliability landing zone" in sent
assert "Meridian" not in sent and "pos-db-01" not in sent
def test_free_text_topic_never_leaves():
vendor = Vendor()
result = call({**GOOD, "topic": "Meridian Retail pos-db-01 outage"}, vendor)
assert result["success"] is False and not vendor.sent
def test_unknown_pillar_is_refused():
vendor = Vendor()
assert call({**GOOD, "pillar": "x"}, vendor)["success"] is False and not vendor.sent
def test_the_vendors_argument_name_is_read_from_the_tool():
vendor = Vendor(argument="search_phrase")
call(GOOD, vendor)
assert "search_phrase" in vendor.sent[-1]["params"]["arguments"]
def test_a_vendor_dropping_its_tool_is_a_clean_failure():
assert call(GOOD, Vendor("something_else"))["success"] is False
def test_gcp_search_bills_the_connections_project():
if PROVIDER != "gcp":
pytest.skip("GCP only")
vendor = Vendor()
call(GOOD, vendor)
assert all(h.get("authorization") == "Bearer tok" and h.get("x-goog-user-project") == "p1" for h in vendor.headers)

View File

@@ -21,6 +21,9 @@ SECRET_KEYS = (
"appsettings", "env", "envvars", "environmentvariables", "variables", "password", "adminpassword", "secret",
"secretvalue", "sastoken", "accesskey", "primarykey", "secondarykey", "privatekey", "kubeconfig", "credentials",
)
# A single value under one of these keys is a tag or label (env=dev), not a secret: only a list or map under it (a
# container's environment variables) is redacted.
SCALAR_SAFE_KEYS = ("env",)
# Values under these keys name a person, or may. A principal of unknown type counts as a person.
PERSON_KEYS = (
"createdby", "lastmodifiedby", "updatedby", "creator", "owner", "owneremail", "contact", "contactemail", "email",
@@ -54,10 +57,14 @@ def _anonymise_member(value: str) -> str:
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]"
@@ -67,7 +74,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)):