# Implementation plan: Azure, AWS and Google Cloud discovery MCP servers | | | |---|---| | Date | 2026-10-30 | | Status | Built to simulated-cloud tests. See [Build status](#build-status-2026-10-30) | | Update 2026-11-04 | `cloud-knowledge` is retired. Guidance is a tool on `azure-discovery` and `gcp-discovery`, on the customer's connection (D9). Sections below that describe `cloud-knowledge` are history | | Scope | Three read-only MCP servers that collect metadata from a customer's cloud estate for CP1 Discovery (ALZ-F01), one folder each under `mcp-servers/` | | Reference for Azure | [Azure MCP Server](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/README.md) | | Platform code read | `modernization-platform` @ `c89aedcb9` | ## Build status (2026-10-30) | Item | State | |---|---| | `azure-discovery`, `aws-discovery`, `gcp-discovery`, `cloud-knowledge` | **Built.** Rendered by the platform's builder; contract, provider and template conformance tests pass against simulated clouds | | `search_well_architected` on Azure | **Tested live** against the Microsoft Learn MCP Server | | Shared skills | **Written,** not published to the catalog. No owner agreed | | Tested on a real cloud | **Azure: yes, directly (2026-10-30),** on one dev subscription, bypassing the gateway and vault. AWS and Google Cloud: no sandbox yet (D7) | | Throttling | Rule 8 is built on all servers. On Azure, 42 rapid calls all succeeded, with 2 throttle events handled | | Credential path through the vault | **Blocked:** the [Vault Service isn't deployed](platform-issues/vault-service-not-deployed/report-2026-10-30.md) | | Image build | **Built on the public `python:3.13.16`,** with `mcp-servers/_common/Dockerfile.python`, because the platform's hardened base image needs a JFrog login. Each starts and answers `/health` as user 1000. Pushed to ACR. Replace with the rendered Dockerfile when the base is available | | Deployed | **Yes (2026-10-30),** to `mcp-servers` on `crucible-kab-dev-aks`, on the public Python images (`azure-discovery` 0.1.2; the others 0.1.1). Outbound access to all three clouds' APIs confirmed from the pods; a live Azure search works from the cluster | | Registered in KAB | **Yes (2026-10-30),** in tenant `CP1 Agentic Landing Zone` (gateway tenant `cp1-agentic-landing-zone`). The gateway discovered 14 tools on each discovery server and 3 on `cloud-knowledge` | | Connected to agents | **No** | Changes from this plan made during the build: - Tools aren't in server folders by hand: code lives in `mcp-servers/_common/`, and a definition's `shared_code`, `extra_requirements` and `verify_tool` drive the render. - `verify_connection` is reserved by the platform, so each server has a `_check_connection` tool that the render connects to it. - Azure uses REST through the template's `httpx`, with Resource Graph for every read, so the query scope is the boundary. AWS uses boto3, and Google uses `google-auth` with Cloud Asset Inventory. - `search_well_architected` takes a topic from a **fixed list**, rather than filtering free text. Customer detail can't enter a query at all. ## 1. Summary The purpose of these servers is to **discover a customer's cloud estate: what servers, workloads, Kubernetes clusters, networks and subnets exist, how they connect, and which organisational and resource policies govern them.** They also give agents each hyperscaler's Well-Architected guidance, so that later workflows can compare the estate against it. We build three servers on KAB's MCP server template: `azure-discovery`, `aws-discovery` and `gcp-discovery`. For Azure, this replicates the read-only, metadata-level part of the Azure MCP Server that serves discovery. The AWS and Google Cloud servers offer the same tools, so the agents can treat all three alike. **Why build, rather than deploy the vendors' servers.** KAB runs one server for many customers. The gateway fetches each customer's credential from the Vault Service and sends it with every call. The template enforces this, and `docs/TENANCY.md` names a server that reads its own environment as the failure to look for, because it "holds one customer's access for every tenant". The vendor servers don't fit that model as far as their documentation shows: | Vendor server | How it authenticates | Fit | |---|---|---| | Azure MCP Server | Azure Identity at process level (`az login`, or `EnvironmentCredential` variables in Docker). Its README doesn't describe per-request credentials. | One customer per process | | AWS API MCP Server | Local package. Its PyPI page says the HTTP mode is not designed for multi-tenant use. AWS now points users to the hosted AWS MCP Server. | One customer per process | | AWS MCP Server (hosted) | SigV4, with named profiles for multi-account use | Hosted by AWS. Per-customer use from KAB is unproven. | | Google `gcloud-mcp` and remote servers | Runs under the active `gcloud` account. The Cloud Asset Inventory remote server is in preview. | One account per process, or preview | The vendor servers also carry far more than Discovery may use: write operations such as ARM deployments, and data-plane reads such as Key Vault secrets and Cosmos DB documents. Story ALZ-DSC-02 requires read-only, metadata-level discovery, so we'd be filtering them down anyway. The alternative is in [D1](#3-decisions-needed): run one vendor process per customer behind a thin adapter. ## 2. Target design ### Repository layout Each server follows the existing `alz-discovery-sample` convention: a definition file beside a rendered folder. ``` mcp-servers/ ├── alz-discovery-sample.server.yaml unchanged; still used for evals ├── alz-discovery-sample/ ├── _common/ helpers inlined into each server at render time │ ├── tool_support.py scope check, paging, redaction, evidence_ref │ └── test_contract.py the contract all three servers must pass ├── azure-discovery.server.yaml port 8111 ├── azure-discovery/ │ ├── requirements.extra.txt the SDKs this server adds to the template's list │ └── tests/ ├── aws-discovery.server.yaml port 8112 ├── aws-discovery/ ├── gcp-discovery.server.yaml port 8113 ├── gcp-discovery/ ├── cloud-knowledge.server.yaml port 8114, if D9 chooses it └── cloud-knowledge/ ``` The rendered image contains only the template's files, so `_common/` is inlined by `scripts/render_mcp_server.py` rather than imported. The builder has no field for extra packages, so the same script appends `requirements.extra.txt`. The definition stays the source of truth, and a server folder is never edited by hand. ### How a call flows ``` workflow run ──X-Project-ID──> agent ──X-Project-Id + agent key──> MCP gateway │ fetches the credential │ (tenant, project, server) ▼ cloud API <── short-lived token ── -discovery params._meta["com.kyndryl.mcp/connection"] ``` - **Customer access uses the platform as it stands.** Each engagement is a KAB project. A customer's credential is stored as an `mcp` secret for that project and server, through the Credentials page, whose form is built from the server's declared connection fields. The page can test it through `verify_connection`. - **A discovery server never has a tenant-wide credential.** The gateway would use it for every project without its own, which is one customer's access serving others. - **The credential never enters model context.** It travels in `_meta`, not in `arguments`. - **The server holds nothing between calls.** No customer token or data is kept beyond the request. Any token cache is keyed by connection and held in memory only. - **`REQUIRE_VAULT_CONNECTION` stays `true`,** so a call without a credential is refused. - **Each server sets `verify_tool`,** so a stored credential can be tested from KAB. The code passes the project id at each of these hops, but this has never been exercised end to end. Phase 0 proves it. ### Tools Every tool name carries the provider prefix. The runtime refuses an agent that declares the same tool name from two servers (`tools.py`: "declared from two servers"), so three servers can't all expose `get_resource_metadata`. The table shows the suffix. **Core discovery tools (v1):** | Discovers | Tool suffix | Azure | AWS | Google Cloud | |---|---|---|---|---| | Connection works | `verify_connection` | Token, then list subscriptions | `sts:GetCallerIdentity` | Token, then read the scope root | | Estate structure | `list_accounts` | Management groups, subscriptions, resource groups | Organizations accounts and OUs | Organisation, folders, projects | | Everything, by type | `list_resources` | Resource Graph | Resource Explorer or Config | Cloud Asset `searchAllResources` | | Targeted questions | `query_resources` | Resource Graph KQL | Config advanced query | Cloud Asset `queryAssets` | | One resource in detail | `get_resource_metadata` | ARM | Config or service `Describe*` | Cloud Asset `batchGetAssets` | | **Servers** | `list_servers` | VMs, scale sets, disks | EC2, Auto Scaling, EBS | Compute Engine, instance groups, disks | | **Workloads** | `list_workloads` | App Service, Functions, Container Apps, Container Instances | Lambda, ECS, Elastic Beanstalk, App Runner | Cloud Run, Cloud Functions, App Engine | | **Kubernetes clusters** | `list_kubernetes_clusters` | AKS: version, node pools, networking | EKS: version, node groups, networking | GKE: version, node pools, networking | | **Networks and subnets** | `get_network_topology` | VNets, subnets, peerings, route tables, NSGs, gateways, load balancers, private endpoints | VPCs, subnets, Transit Gateway, route tables, security groups, load balancers | VPCs, subnets, peering, routes, firewall rules, load balancers | | Databases and storage | `list_data_stores` | SQL, Cosmos DB, storage accounts | RDS, DynamoDB, S3 | Cloud SQL, Firestore, Cloud Storage | | **Organisational policies** | `list_organization_policies` | Azure Policy definitions, initiatives, assignments, exemptions and compliance state | SCPs, RCPs, tag and backup policies, Config rule compliance | Organization Policy constraints, IAM deny policies, VPC Service Controls | | **Resource policies** | `list_resource_policies` | Key Vault access policies, storage network rules, resource locks | S3 bucket, KMS key, Lambda, SQS and SNS policies; IAM role trust policies | IAM policies on resources, through Cloud Asset `searchAllIamPolicies` | | **Well-Architected findings** | `list_recommendations` | Azure Advisor, which groups recommendations by category | Trusted Advisor, plus the customer's own Well-Architected Tool reviews | Recommender | Kubernetes discovery stops at the cloud control plane in v1: clusters, versions, node pools and networking. What runs inside a cluster needs Kubernetes API access to each cluster, which is a separate customer permission. See [D8](#3-decisions-needed). **Later, once discovery works:** | Tool suffix | Why it can wait | |---|---| | `get_network_metrics` | Needed for ALZ-DSC-07's bottleneck analysis, but not to detect what exists | | `list_identity_assignments` | Who holds which role. Closer to Assessment | | `get_retail_price` | A Business Case input | ### Policy collection Policy tools return the policy as the provider records it, plus where it applies and what it covers. They don't judge whether a policy is good; that's for Assessment. | Field | Meaning | |---|---| | `policy_id`, `name`, `type` | The provider's identity for the policy | | `layer` | `organisation` or `resource` | | `attached_to`, `inherited_from` | The scope it applies at, and where it came from | | `effect` | Deny, audit, allow and so on, as the provider states it | | `document` | The policy text, redacted | | `compliance` | Compliant and non-compliant counts, where the provider reports them | - **Volume:** resource policies can run to one per bucket, key or function, so `list_resource_policies` pages by resource type. - **Personal data:** policy documents name users, and Google IAM members are often personal email addresses. These are anonymised by rule 5. - **AWS organisation policies:** these can only be read from the management account or a delegated administrator, so a customer must grant that access specifically. ### Well-Architected integration There are two separate needs, and they use different sources. | | Estate findings | Guidance | |---|---|---| | Question | What do the provider's own checks say about **this customer's estate?** | What does the framework **recommend?** | | Tool | `list_recommendations`, on each discovery server | `search_well_architected` and shared skills | | Credential | The customer's, from the vault | **Kyndryl's**, or none. Never the customer's | | Contains customer data | Yes | No, and must stay that way | **Findings.** Each finding keeps the provider's own category or pillar, and gains a `pillar` field mapped to a common list. The frameworks' pillars differ between providers, so the mapping is a table in `_common/`. AWS Well-Architected Tool reviews are read only if the customer already has them: `wellarchitected:GetLensReview` is a Read action, but creating a review is a write and is out of scope. **Guidance.** Each provider has a hosted knowledge server: | Provider | Server | Access | Status to confirm | |---|---|---|---| | Azure | Microsoft Learn MCP Server, `https://learn.microsoft.com/api/mcp` | No authentication, no charge. Tools: `microsoft_docs_search`, `microsoft_docs_fetch`, `microsoft_code_sample_search` | Coverage of Well-Architected pages | | AWS | AWS MCP Server, which AWS now recommends over the AWS Knowledge MCP Server | IAM, signed with SigV4 or OAuth. Needs a Kyndryl AWS identity | Whether it covers Well-Architected content | | Google Cloud | Developer Knowledge MCP server, `https://developerknowledge.googleapis.com/mcp` | API key. Corpus includes `docs.cloud.google.com`; announced in preview in February 2026 | Current status, and coverage of the framework | We wrap these rather than register them directly. The gateway registers a server by calling KAB's own `/.well-known/mcp-auth` and `/messages` endpoints, which a vendor's hosted server doesn't offer. Phase 0 confirms this. **What the platform review found (D9, under review).** - **One server gets one credential per call.** The gateway sends the project's `mcp` credential, and only falls back to the tenant's if the project has none (`vault/client.py`, `connection_for`). A discovery server carrying a customer's credential can't also receive a Kyndryl one, so **`search_well_architected` can't stay on the discovery servers** if its credential is to live in the vault. - **The vault has no platform-wide secret,** only project and tenant. A Kyndryl key in the vault must be stored once per tenant. - **The catalog knowledge base isn't reachable by agents.** It's a global, curated corpus with a review and publish flow, but it's admin-only with "deliberately no read path for ordinary users", and it serves the catalog chat. I found no agent-facing retrieval route. - **Shared skills are the platform's way to give agents guidance.** They're versioned (`name@X.Y.Z`), pinned by a lock file, and recorded in the trail. Sub-agents can't load them, but the orchestrator and individual agents can. | Option | How it works | Credentials | Platform changes | Drawback | |---|---|---|---|---| | A. Separate `cloud-knowledge` server | A fourth server wrapping the three vendors, with its own tenant-wide `mcp` credential | Vault, stored once per tenant | None | One more server; a key per tenant | | B. Shared skills | Well-Architected guidance curated into versioned skills, one per provider | None, and nothing leaves the platform | None | Goes stale; needs an owner; check content licensing | | C. Knowledge base | Well-Architected documents ingested into the curated corpus | None | A new agent read path | Needs a platform change | | D. Server's own environment | Keep the tool on the discovery servers, with a Kubernetes Secret | Outside the vault, against this review's aim | None | Doesn't use the platform's credential handling | **Recommendation: A and B together.** B gives every agent the same reviewed baseline with no network call and no credential. A answers specific questions from current documents, with its credentials in the vault. `search_well_architected` then moves off the discovery servers, which keep only customer access. **The workflow that uses it.** The stories put Well-Architected in Target Architecture (ALZ-F05: pillar trade-offs, and AC3 on conflicting pillars), not Discovery. Discovery collects the findings. F01's agents don't declare `search_well_architected`, and F05 wires it in when that Feature is built ([D10](#3-decisions-needed)). ### How this compares with the Azure MCP Server | Its area | Our treatment | |---|---| | Subscriptions, resource groups, Resource Graph, compute | Replicated, read-only, in v1 | | Policy, Advisor | Replicated, read-only, in v1 | | RBAC, retail pricing | Replicated read-only later | | Monitor metrics | Later, for network metrics | | Storage, SQL, Cosmos DB | **Control-plane metadata only.** No blobs, rows or documents | | Key Vault | Vaults appear as resources with metadata. **Secret, key and certificate values are never read** | | Log Analytics queries, tracing | **Left out of v1.** Results can contain customer data | | ARM deployments, Advisor dismissals, custom log ingestion | **Left out.** These write | | Azure Quick Review compliance scanning | Left out of v1. It needs the `azqr` binary, and belongs to Assessment rather than Discovery | | Network | **We add this.** The README lists no network area beyond CDN, and networks and subnets are core to discovery | | Kubernetes | **We add this.** The README's tool areas as reviewed don't cover AKS discovery, so confirm against the current tool list in phase 2 | ### Rules every tool follows Each rule is in `_common/tool_support.py` and is tested by `_common/test_contract.py`. 1. **Read-only.** The code only uses list, get and describe calls, and the customer's role enforces the same limit. A tool filter alone isn't a security boundary. 2. **Inside the connection's boundary.** A request outside the configured management group, organisation or folder is refused, whatever the model asked for. 3. **Bounded output.** Every list is paged, with a default page size and a byte ceiling, and each response includes a continuation token. Traced hand-offs show the model's context is the real limit (see [the artifacts report](platform-issues/artifacts-step-within-a-run/report-2026-10-29.md)). 4. **Inside the time limit.** The runtime gives each MCP call 120 seconds (`MCP_TIMEOUT_S`). Long collections return a partial page rather than time out. 5. **Redaction and anonymisation.** Known secret-bearing fields are dropped: VM user data, custom script settings, function app settings, connection strings, environment variables. People are anonymised in every tool's output, not only policies: - A human principal becomes its kind alone, such as `[user]` or `[group]`. No name, email or hash is kept. A hash isn't anonymous, because it can be matched back and still links one person across records. - A principal whose type can't be determined is treated as human. - Email addresses in tags, descriptions and other free text are replaced with `[email]`. - Non-human identities, such as roles and service accounts, stay, because Discovery needs them to show what can reach what. 6. **Evidence.** Each response has `provider`, `evidence_ref` and a collection timestamp, matching the story's contract. 7. **Data, not instructions.** Tags and descriptions are customer-controlled text and are returned as data. The eval suite includes a planted injection in a tag. 8. **Throttling.** Provider rate limits are honoured with backoff, and `get_budgets` limits apply. 9. **No payloads in logs.** Logs carry tool, outcome, duration and resource count only. 10. **No customer data in knowledge queries.** On the knowledge server, `search_well_architected` accepts a pillar and a topic from a fixed format. Customer names, resource names and ids are refused, because the query leaves for a third-party service. ### Customer access | | Azure | AWS | Google Cloud | |---|---|---|---| | What the customer sets up | App registration with a federated credential or client secret | IAM role with a trust policy and external id | Service account with Workload Identity Federation or a key | | Read-only roles (v1) | Reader at management group | `SecurityAudit` and `ViewOnlyAccess`, in the management or delegated administrator account for organisation policies; `wellarchitected` read actions | Cloud Asset Viewer, Browser, Compute Network Viewer, Organization Policy Viewer, Recommender viewer roles | | Connection fields | `tenant_id`, `client_id`, `client_secret`, `scope_root`, `cloud` | `role_arn`, `external_id`, `regions`, broker credential | `scope_root`, `service_account`, `credential_config` | Exact role lists are confirmed in each server's phase, tested against a real sandbox, and published as a customer onboarding guide. `cloud` covers Azure's sovereign clouds, which the Azure MCP Server also supports. ## 3. Decisions needed | # | Decision | Recommendation | Why | |---|---|---|---| | D1 | Build on the template, or run vendor servers per customer? | **Build on the template** | One shared server with per-call credentials is how the gateway works. Per-customer vendor processes mean a deployment for every customer, and we'd still have to filter their tools. | | D2 | How does a scope entry identify a cloud resource? | **Add `provider` and `resource_ref` to scope entries, and add `resource_ref` to the tool** | The story's tool takes only `scope_entry_id`, but a stateless server can't resolve that. It needs an ADR in both patterns. | | D3 | Who owns scope data in production? | **Build a real `alz-scope` as separate work** | It's still sample data, along with the other eight logical servers. Until it exists, a customer's scope has no source. See risk R1. | | D4 | How do we authenticate to customers? | **Start with vault-stored read-only credentials; move to federation** | Stored credentials work today. Federation removes long-lived customer secrets, but needs the AKS OIDC issuer exposed and a design for customer trust. | | D5 | What does AWS's first hop use? | **Decide with D4** | Assuming a customer role needs a Kyndryl AWS identity first, either a broker access key or OIDC federation from AKS. | | D6 | Is `query_resources` in v1? | **Yes, with scope and size limits** | It's the most useful Azure MCP capability for discovery, and the underlying APIs are read-only. The model writes the query, so it needs the boundary check. | | D7 | Are there sandboxes for all three clouds? | **We need one per provider, with an organisation-level structure** | Management group and organisation behaviour can't be tested in a single account. | | D8 | Does discovery look inside Kubernetes clusters (namespaces, deployments, images)? | **Not in v1.** Add it as a later phase | It needs read access granted on each cluster, and private clusters may be unreachable from KAB. | | D9 | Where does Kyndryl's own access to AWS and Google knowledge live? | **Decided 2026-11-04: nowhere separate.** Guidance is a tool on each provider's discovery server, on the customer's connection, and `cloud-knowledge` is retired. Options were in [Well-Architected integration](#well-architected-integration) | The platform review showed it can't sit on the discovery servers' vault credential. | | D10 | Should Discovery use Well-Architected guidance, or only Target Architecture? | **Decided: Target Architecture.** Discovery collects findings only. **Superseded 2026-11-03** by ALZ-F01 ADR 0014: Discovery runs a Well-Architected review | Agreed 2026-10-30. | | D11 | Are people's names and emails in collected data kept? | **Decided: no, they are anonymised. Finishing this is deferred** | Agreed 2026-10-30, and deferred the same day. See [Later work](#later-work). | ## 4. Delivery plan Azure goes first because it's the reference and the cluster already runs there. AWS and Google Cloud reuse what it proves. ### Phase 0: Prove the path Use a small server with one tool that echoes which connection fields arrived, never their values. 1. Clear the MCP gateway registration blocker ([platform issue](platform-issues/mcp-gateway-default-tenant/report-2026-10-29.md)). The servers are saved as global entries. 2. Store a test credential in the Vault Service for one project and server. 3. Call the tool from a real workflow run, and confirm the connection reaches the server with the right tenant and project. 4. Confirm outbound access from the `mcp-servers` namespace to the three providers' APIs. 5. Build an image that adds an SDK on top of the template, and confirm `constraints.txt` doesn't conflict. 6. Confirm that the builder's checks accept third-party imports in `ai_implementation`. 7. Confirm that a stored project credential is the one used, and that a project without one is refused. 8. Confirm that a vendor's hosted server can't be registered directly with the gateway. **Done when:** a workflow step gets a vault credential to a server, and an SDK-based image builds. ### Phase 1: Shared foundation 1. Extend `scripts/render_mcp_server.py` to inline `_common/` and append `requirements.extra.txt`. 2. Write `_common/tool_support.py` and `_common/test_contract.py`. 3. Add the servers to `deploy/crucible-kab-dev.yaml`, and add their tests to `.gitea/workflows/check.yml`. 4. Record the accepted decisions as ADRs. **Done when:** an empty server renders, passes the template's conformance test and passes the contract test. ### Phase 2: `azure-discovery` 1. Implement authentication and `verify_connection`, then `list_accounts`. 2. Implement `list_resources`, `query_resources` and `get_resource_metadata`. 3. Implement `list_servers`, `list_workloads`, `list_kubernetes_clusters`, `get_network_topology` and `list_data_stores`. 4. Implement `list_organization_policies`, `list_resource_policies` and `list_recommendations`. 5. Test against recorded responses, then against the Azure sandbox. 6. Record the minimum role list and write the onboarding guide. 7. Deploy, and register in KAB. **Done when:** the contract test passes, a read-only sandbox identity can run every tool, the same tools refuse out-of-boundary requests, and a write attempt is impossible with the documented role. ### Phase 3: `aws-discovery` Repeat phase 2, using boto3 and `moto` for offline tests. Multi-account collection through Organizations and `AssumeRole` is the main new work, along with resource policies, which each come from a different service. ### Phase 4: `gcp-discovery` Repeat phase 2 using the Google client libraries. The work here is folder- and organisation-level scope through Cloud Asset Inventory, including `searchAllIamPolicies`. ### Phase 4a: Well-Architected guidance Depends on D9. 1. Build the `cloud-knowledge` server with `search_well_architected`, starting with the Microsoft Learn MCP Server, which needs no credential. 2. Curate and publish the shared skills, and agree who keeps them current. 3. Test rule 10 with planted customer names. **Done when:** an agent gets cited guidance for a pillar and topic from each provider, and no customer detail appears in an outbound query. ### Phase 5: Connect the agents The two patterns stay separate, so each gets its own change and ADR. | Pattern | Change | |---|---| | Sub-agents | Add the three servers to `mcp:` in the orchestrator. The collect skill calls the provider's tool for each cloud scope entry. Policy records are stored in the run workspace. | | Individual agents | Add them to the scan executor and network agents, with prompt changes. Policies need an owner: a new story and agent, or an extension to an existing one. The critic's checks cover cloud findings too. | 1. Bump the agent versions, rebuild, and re-import both workflows. 2. Add eval cases using a sandbox estate, including the planted injection and an out-of-scope request. 3. Run Discovery end to end on one sandbox per provider, then on a mixed estate. A declared server that isn't offered stops the agent's tools from loading. Every agent that declares these servers therefore needs all three registered and healthy, including for a customer on one cloud. Credentials are only needed when a tool is called. **Done when:** a Discovery run produces findings from all three clouds, the critic reports coverage, and each finding has evidence. ### Phase 6: Production readiness 1. Security review, covering the customer credential lifecycle and rotation. 2. Customer-facing documents: required roles, what is and isn't collected, and how to revoke access. 3. Load testing on a large estate, and tuning of page sizes. 4. Move to federation if D4 is accepted. ## 5. Testing | Level | What it proves | Runs in | |---|---|---| | Template conformance | MCP protocol, auth and the connection contract | CI | | Shared contract test | The rules in section 2, for each server | CI | | Unit tests on recorded responses | Mapping, paging and redaction | CI | | Sandbox integration | Real permissions and real API behaviour | By hand, then scheduled | | Agent evals | The model uses the tools correctly | Against the deployed agent | No customer data is used in tests. Recorded responses come from sandboxes only. ## 6. Risks | # | Risk | Impact | Mitigation | |---|---|---|---| | R1 | **The other Discovery servers are still sample data:** `alz-scope`, `alz-cmdb`, `alz-inventory`, `alz-evidence` and others | These three servers alone don't deliver a live customer run | D3. Agree which of them are real for the first customer | | R2 | The MCP registration 500 stays open | Nothing can be registered | Phase 0, using "All tenants" or the tenant mapping | | R3 | Project id or credential doesn't reach the server in a real run | Customer access doesn't work, or a tenant-wide credential is used instead. `TENANCY.md` says a call with no project finds no credential, but `vault/client.py` falls back to the tenant's | Phase 0 tests this before any tool work; never store a tenant-wide credential on a discovery server | | R4 | A large estate overflows the model's context | Failed steps, especially the critics | Paging, byte limits, summaries from `list_*` tools | | R5 | Customer secrets in the vault are a high-value target | A leak exposes several customers' metadata | Read-only roles, external ids, rotation, then federation | | R6 | Every key in a tenant can request any of that tenant's projects' credentials (`TENANCY.md`) | Weak separation between engagements in one tenant | Treat as accepted-for-now, and raise it with the platform team before real customers | | R7 | Sensitive values appear in metadata | Client data reaches model and artifacts | Redaction list, tests, `OBSERVABILITY_CAPTURE_CONTENT: false` | | R8 | SDK versions conflict with the template's pins, or inflate the image | Build failures | Phase 0 spike; use the narrowest SDK packages | | R9 | The vendor servers change quickly | Our capability table goes stale | Review the reference at each release; it's a guide, not a dependency | | R10 | A knowledge query carries customer detail to a third party | Customer data leaves the platform | Rule 10: fixed query format, tested with planted names | | R11 | Policy documents hold personal data and reveal the customer's security posture | Sensitive content in model context and artifacts | Rule 5, tested with planted names, and treating the output as customer-confidential. Names inside free text other than emails can still slip through | | R12 | Hosted knowledge servers are new, and change or are in preview | Guidance tool breaks while discovery works | Isolated in one tool per server; failure returns an error, never blocks collection | ## Later work **Anonymisation (deferred 2026-10-30).** The code built so far stays in place: rule 5 still runs on every reply, with its tests. Not done, and not to be relied on until it is: - Names in tags, descriptions and other free text, other than under known fields such as `owner`. - A check of real collected data for names and for secret fields. The Azure test only counted email addresses and `objectId` values. - Confirmation of the approach against customer data agreements. **Until this is done, don't run discovery on a customer's estate.** ## 7. What isn't covered - Writing to a customer's cloud, in any phase. - Reading customer data: blobs, rows, documents, secrets, log contents. - On-premises discovery, which stays with `alz-estate`. - Agents beyond ALZ-F01. Assessment can reuse these servers later. - What runs inside a Kubernetes cluster, in v1 (D8). - Creating or scoring Well-Architected reviews. The servers read findings; judging the estate against the framework belongs to Assessment and Target Architecture.