From ba240b747d51c8d88737187a6bc0eb9f2208cb3c Mon Sep 17 00:00:00 2001 From: Luana Dos Santos Date: Tue, 18 Aug 2026 10:24:26 -0300 Subject: [PATCH 1/4] W-23907611 docs: draft Policy Write documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite exp-governance-policy-library-apply.adoc from a fully commented-out draft into an active topic covering the Policy Write scope (MS2026-08-R2): apply a universal policy template, and edit/delete/enable-disable native policies, plus the in-progress workflow lock and read-only out-of-scope state. Update the Policies-tab section of exp-services-view-details.adoc to note the new native-policy management actions and read-only out-of-scope policies, and cross-link to the apply/manage topic. Content is grounded in the mulesoft-omni-app UI code. Details that could not be verified in code (universal template list + per-gateway native mappings, GA feature flags, enable/disable support matrix, permission role names, and the API Instance page apply entry point) are marked with TODO(W-23907611) comments for PM confirmation before publishing. Gap analysis: Policy Write — Documentation Gap Report (2026-08-18). Co-Authored-By: Claude Opus 4.8 --- .../exp-governance-policy-library-apply.adoc | 184 +++++++++--------- .../ROOT/pages/exp-services-view-details.adoc | 8 +- 2 files changed, 101 insertions(+), 91 deletions(-) diff --git a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc index 9c7017556..3962c947a 100644 --- a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc +++ b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc @@ -1,126 +1,130 @@ -// = Browse the Policy Library -// :keywords: policy library, canonical policies, governance policies, policy catalog += Apply and Manage Policies from the Policy Library +:keywords: policy library, canonical policies, universal policies, governance policies, apply policy, edit policy, delete policy, policy catalog -// // FLAG: Jul 16 publish condition. The read/browse description below (what the Policy Library is and what users can see) is written for the Jul 16 Policy Read GA. However, the Policy Library UI is gated behind a feature flag (W_23173868_CANONICAL_POLICIES_ENABLED, default off) and is not called out as a Jul 16 deliverable in the PRD. Confirm with the PM that the Policy Library is enabled in browse mode for Jul 16 before publishing this topic. The policy-application wizard is Policy Write (GA Aug 13) and is commented out at the end of this file. +// DRAFT: Policy Write (MS2026-08-R2 / Dreamforce). Tracked in W-23907611. +// This topic was previously a commented-out draft for the Policy Read GA. It has been +// rewritten for the Policy Write scope. Sections contain TODO(W-23907611) markers where a +// detail could not be grounded in code and must be confirmed with the PM before publishing. +// Blockers to resolve before removing this DRAFT banner and publishing: +// 1. Confirmed list of the universal policy templates and their per-gateway native mappings +// (APIM-owned; not enumerated in the Omni codebase). +// 2. Which feature flags are ON for GA, per gateway +// (W_23173868_CANONICAL_POLICIES_ENABLED for Kong, +// W_23308031_NONKONG_POLICIES_VIA_APIM_ENABLED for Apigee/Azure). +// 3. The enable/disable support matrix (which gateways expose the toggle at GA). +// 4. Human-readable required permission/role names for policy write actions. +// 5. Whether applying policies from the API Instance page is enabled at GA +// (listed as out of scope for MS2026-08-R2 in the program tracker). -// The Policy Library is a catalog of predefined policies that you can browse from *Governance* > *Governance Strategies* > *Policy Library*. Use it to explore the policies available to your organization and understand what each one enforces before you govern your APIs. +Use the Policy Library to apply a universal policy template to your API instances and to manage the resulting native policies. A universal template expresses a policy once and applies it as the correct vendor-native policy on each supported gateway, so you can enforce consistent controls across MuleSoft, Google Apigee, Kong Gateway, and Azure API Management without authoring a policy per gateway. -// == Browse Policies by Category +// TODO(W-23907611): AWS API Gateway is excluded from the policy write flow for this release +// (deferred to a later release). Confirm the customer-facing framing of the AWS exclusion with the PM. -// The Policy Library displays each available policy as a card that shows the policy name, its category, and a short description of what the policy does. +== Before You Begin -// To find a policy, you can: +Before getting started, make sure you have: -// * Search for a policy by name using the search box. -// * Filter policies by category: -// + -// -- -// ** *Access and Security*: Authentication and authorization policies, including OAuth 2.0, JWT validation, IP filtering, and rate limiting. -// ** *Performance and Cost*: Policies that manage API performance and cost, such as caching, spike arrest, and request throttling. -// ** *Data Privacy and Integrity*: Policies that protect data privacy and ensure data integrity, such as PII masking, data encryption, and payload validation. -// ** *Compliance and Observability*: Policies that enable compliance tracking and observability, such as audit logging, correlation ID injection, and OpenTelemetry tracing. -// -- +* An Anypoint Platform account. +* Any of these permissions: ++ +-- +** API Governance: Governance Administrator +** API Manager: Manage Policies +-- ++ +// TODO(W-23907611): Confirm the exact permission/role names required for apply, edit, delete, +// and enable/disable. The code enforces per-action permissions (create, update, enable, +// disable, delete) fetched per instance, but exposes only permission keys, not role labels. +For more information, see xref:exp-home-start.adoc#permissions[Enhanced Experience Permissions]. -// Policies that apply to any service, including scanned and federated APIs, are marked with a *Universal* badge. +* API instances registered in the portfolio on a supported gateway. -// == See Also +[NOTE] +==== +Policy write actions respect your permissions. If you don't have permission for an action, that action is unavailable and the experience explains that the action isn't permitted. If the platform can't verify your permissions for an instance, the actions remain available and the gateway enforces authorization when you submit the request. +==== -// * xref:exp-governance-create-strategy.adoc[] -// * xref:exp-services-view-details.adoc[] -// * xref:exp-governance-govern-third-party-apis.adoc[] +== Browse the Policy Library -// // FLAG: Aug 13 release (policy write scope). Everything below documents applying policies to API instances (including third-party provider instances) through the Policy Library wizard, which is Policy Write — GA Aug 13. It is out of scope for the Jul 16 Policy Read GA. Uncomment when the Aug 13 write release is documented, and fold these sections into the topic above (add the apply use cases, permissions, and wizard steps). Note: for MuleSoft-native and Kong instances, policy application already ships, but cross-gateway apply as described here aligns with the Aug 13 milestone — confirm scope with the PM before publishing. -// //// -// == When to Use the Policy Library to Apply Policies +The Policy Library is a catalog of predefined policies that you can browse from *Governance* > *Governance Strategies* > *Policy Library*. Each policy appears with its name, category, and a short description of what it enforces. -// Use the Policy Library instead of governance strategies when you want to: +You can filter policies by category: -// * Apply a policy to a specific set of API instances without creating a governance strategy. -// * Add supplemental policies to instances that are already governed by strategies. -// * Apply policies to third-party provider services hosted on platforms such as Akamai. -// * Test policy behavior on a limited scope before a broader rollout. +* *Access & Security* +* *Performance & Cost* +* *Quality of Service* +* *Data Privacy & Integrity* +* *Compliance & Observability* -// For comprehensive, scope-driven governance across multiple services, use xref:exp-governance-create-strategy.adoc[governance strategies] instead. +// TODO(W-23907611): Confirm the shipping list of universal policy templates and the native +// policy each maps to per gateway (for example, an API key template mapping to VerifyAPIKey +// on Apigee and key-auth on Kong). This mapping is served at runtime by API Manager and is +// not defined in the Omni codebase, so it must be confirmed with the PM / API Platform team +// before it is documented as a table. Do not transcribe the mapping from the planning tracker. -// == Before You Begin +== Apply a Policy -// Before getting started, make sure you have: +. Log in and go to *Governance* > *Governance Strategies* > *Policy Library*. +. Select the policy you want to apply. +. Configure the policy parameters. Required and optional fields vary by policy type. +. Select the API instances where you want to apply the policy. +. Review the summary, then apply the policy. -// * An Anypoint Platform account. -// * Any of these permissions: -// + -// -- -// ** API Governance: Governance Administrator -// ** API Manager: Manage Policies -// -- -// + -// For more information, see xref:exp-home-start.adoc#permissions[Enhanced Experience Permissions]. +// TODO(W-23907611): Confirm the exact wizard step labels and the primary action button label +// against the shipped UI before publishing (the apply flow is driven by the governance policy +// wizard). Applying policies directly from an API Instance page is listed as out of scope for +// MS2026-08-R2 — confirm whether that entry point is available at GA before documenting it. -// * API instances registered in the portfolio. For third-party provider services, make sure that the xref:exp-governance-setup-third-party-providers.adoc[provider connection] is established. +When you apply a policy, the platform validates it against your governance configuration and then creates the corresponding native policy on each selected instance's gateway. -// == Open the Policy Library Wizard +[NOTE] +==== +While a policy operation is in progress on an instance, applying policies to that instance is paused and policy actions are unavailable until the operation completes or fails. This prevents conflicting changes while the vendor-native apply workflow runs. +==== -// . Log in and go to *Governance* > *Governance Strategies* > *Policy Library*. -// . Select *Apply Policy* to start the policy application wizard. +== Manage Applied Policies -// The wizard guides you through policy selection, configuration, instance selection, and review. +Manage the native policies on an instance from the *Policies* tab of the instance detail page. The available actions depend on the gateway and on your permissions. For where to find this tab, see xref:exp-services-view-details.adoc[]. -// == Select Policy +=== Edit a Policy -// Browse the available policies and filter by category, then select the policy you want to apply and select *Next*. +For Apigee and Azure API Management native policies that originate from a universal template, select *Edit Configuration* to change the policy's settings. -// == Configure Policy +Editing uses a two-tier experience: -// Enter configuration parameters for your selected policy. Required and optional fields vary by policy type. +* If the policy's configuration schema is available, the policy opens in an editable form. +* If no schema is available, the policy opens in a read-only view of its current configuration. -// Common configuration fields include: +Your changes are saved back to the vendor gateway. -// * *Policy Name*: A descriptive name for this policy application. -// * *Enforcement Mode*: Whether to enforce the policy or monitor violations only (if supported). -// * *Parameters*: Policy-specific settings such as rate limits, authentication providers, or transformation rules. +[NOTE] +==== +Editing Kong gateway-scope policies is not supported. +==== -// Configure the policy parameters according to your requirements and select *Next*. +=== Delete a Policy -// == Select Instances +To remove a native policy from an instance, select the remove action for the policy. A confirmation dialog appears before the policy is removed. Removing a policy detaches it from the instance, and traffic that the policy was filtering is no longer enforced. After you confirm, the policy no longer appears in the instance's policy list. -// Choose the API instances where you want to apply the policy: +// TODO(W-23907611): Confirm the exact remove action/menu label and confirmation button label +// against the shipped UI before publishing. -// . Review the list of available API instances. The list includes instances from Anypoint Platform and connected third-party providers. -// . Use filters to narrow the list by: -// + -// -- -// ** *Provider*: Filter by specific providers (such as Akamai) or Anypoint Platform gateways. -// ** *Service Type*: Filter by service type (such as REST API or GraphQL). -// ** *Tags*: Filter by tags assigned to services. -// -- +=== Enable or Disable a Policy -// . Select one or more instances where you want to apply the policy. -// . Select *Next*. +On gateways that support it, you can enable or disable a policy without removing it. The state change is reflected in the policy list. On gateways that don't support enabling and disabling, the toggle is unavailable. -// == Review and Apply +// TODO(W-23907611): Confirm the enable/disable support matrix (which gateways expose the +// toggle at GA) before publishing. Do not list specific gateways as supported or unsupported +// until engineering confirms the shipping behavior. -// Review the policy application summary: +=== View Policies Outside Your Scope -// * *Policy*: The selected policy and its configuration. -// * *Instances*: The list of instances where the policy is applied. -// * *Expected Outcome*: A summary of what happens when you apply the policy. +Policies that are outside your instance's scope appear in a read-only state. For these policies, edit, delete, and enable/disable actions are not available. -// *Read-Only Mode*: If any selected instances belong to a provider connection with read-only credentials, those instances receive the policy in monitoring mode only. To enable write access, xref:exp-governance-setup-third-party-providers.adoc#update-credentials[update provider credentials]. +== See Also -// Select *Apply* to apply the policy to the selected instances. - -// == Verify Policy Application - -// After applying the policy: - -// . Go to *Portfolio* > *APIs* and open the affected API instance. -// . Review the *Applied Policies* tab to verify the policy appears in the list. -// . Check the *Policy Application Status*: -// + -// -- -// ** *Enabled*: The policy is actively enforced on the gateway. -// ** *Read-Only*: The policy is applied in monitoring mode only (typically due to read-only provider credentials). -// -- - -// If the policy is in read-only mode and you want enforcement, xref:exp-governance-setup-third-party-providers.adoc#update-credentials[update provider credentials] to grant write access. -// //// +* xref:exp-governance-create-strategy.adoc[] +* xref:exp-governance-work-with-strategies.adoc[] +* xref:exp-services-view-details.adoc[] +* xref:exp-governance-govern-third-party-apis.adoc[] diff --git a/modules/ROOT/pages/exp-services-view-details.adoc b/modules/ROOT/pages/exp-services-view-details.adoc index c84043a2f..cf3d8ae88 100644 --- a/modules/ROOT/pages/exp-services-view-details.adoc +++ b/modules/ROOT/pages/exp-services-view-details.adoc @@ -41,7 +41,7 @@ tab can differ by service type and release. For end-to-end portfolio tasks that |Yes |Yes |Yes |Each Model Proxy is exactly one instance so there is no *Instances* tab. |No |*Policies* -|Governance policies attached to the service or its instances (access, data, performance, compliance, and related domains your organization uses). For APIs discovered by scanners, this tab shows read policies from Amazon API Gateway, Google Apigee, Azure API Management, and Kong Gateway. If the instance uses a Kong gateway, the listed policies are gateway-level policies (plugins). Other service-level policies (plugins) can also apply. +|Governance policies attached to the service or its instances (access, data, performance, compliance, and related domains your organization uses). For APIs discovered by scanners, this tab shows read policies from Amazon API Gateway, Google Apigee, Azure API Management, and Kong Gateway. If the instance uses a Kong gateway, the listed policies are gateway-level policies (plugins). Other service-level policies (plugins) can also apply. On supported gateways, you can also manage native policies from this tab. See xref:exp-governance-policy-library-apply.adoc[]. |Yes |Yes |Yes |Yes |No |*Monitoring* @@ -77,6 +77,12 @@ If a provider scanner has policy-read scopes configured, the *Policies* tab show Policy visibility depends on the last successful scanner run, not on a live provider query. If required provider scopes or roles are missing, policy results can be incomplete or unavailable. Policy fields such as status, apply level, and detail can vary by provider. If expected policies are missing, check scanner run status and history in *Providers*. +== Manage Native Policies + +On supported gateways, the *Policies* tab also lets you manage the native policies applied to an instance. Depending on the gateway and your permissions, you can edit, delete, or enable and disable a policy directly from this tab. Policies that are outside your instance's scope appear in a read-only state, without edit, delete, or enable/disable actions. + +For the full apply and management workflow, see xref:exp-governance-policy-library-apply.adoc[]. + == See Also * xref:exp-overview.adoc[] From 46c5e56779f1bd10b663cdfda8e34f1b5cf8d133 Mon Sep 17 00:00:00 2001 From: jenny hajee Date: Tue, 18 Aug 2026 17:10:37 -0500 Subject: [PATCH 2/4] Jenny added updates for the write policies for API gateway scanners --- modules/ROOT/pages/exp-instances-add.adoc | 10 +++- modules/ROOT/pages/exp-overview.adoc | 4 +- modules/ROOT/pages/exp-providers-manage.adoc | 2 + .../exp-scanners-add-from-providers.adoc | 6 ++ modules/ROOT/pages/exp-scanners-manage.adoc | 4 ++ .../exp-scanners-prerequisites-reference.adoc | 60 +++++++++++++++++++ .../ROOT/pages/exp-scanners-view-details.adoc | 5 ++ 7 files changed, 88 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/exp-instances-add.adoc b/modules/ROOT/pages/exp-instances-add.adoc index 8ee7f08a3..b8a3f2986 100644 --- a/modules/ROOT/pages/exp-instances-add.adoc +++ b/modules/ROOT/pages/exp-instances-add.adoc @@ -54,7 +54,15 @@ Field names, required metadata, and available gateway or runtime options depend After creating or updating an instance, you can continue managing the service through related areas of the experience. -* Use the *Policies* tab to review or apply policies to the instance. If the instance uses a Kong gateway, applying a policy targets the gateway level and protects all services in that gateway. +* Use the *Policies* tab to review or apply policies to the instance. ++ +-- +For a managed instance on an Omni Gateway, policies are enforced through the Omni Gateway. + +For an instance discovered on a third-party API gateway (Amazon API Gateway, Azure API Management, Google Apigee, or Kong Gateway), the *Policies* tab applies policies directly to the provider through policy write, with no Omni Gateway in the request path. This requires a scanner configured with write credentials for the provider. If the scanner has read-only credentials, the instance appears as *Read-Only* and policy actions are unavailable. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. + +If the instance uses a Kong gateway, applying a policy targets the gateway level and protects all services in that gateway. +-- * Use the *Monitoring* tab to review metrics and runtime performance when monitoring is available. * Coordinate with platform owners if DNS, certificates, or upstream routing changes must happen outside the product. diff --git a/modules/ROOT/pages/exp-overview.adoc b/modules/ROOT/pages/exp-overview.adoc index a27692f30..f59538d49 100644 --- a/modules/ROOT/pages/exp-overview.adoc +++ b/modules/ROOT/pages/exp-overview.adoc @@ -11,7 +11,7 @@ The enhanced MuleSoft experience supports the full lifecycle of AI-connected int Entity Management:: Register and manage agents, REST and GraphQL APIs, MCP servers, Model proxies, and gateways, including Anypoint Omni Gateway, external gateways, and unmanaged gateways. Each type has a dedicated catalog under *Portfolio*. -Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. Conformance reporting summarizes rule violations and severity so you can close gaps systematically. +Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. For connected third-party API gateways (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), apply, enable, disable, and delete policies directly from Anypoint through policy write, with no Omni Gateway in the request path. Conformance reporting summarizes rule violations and severity so you can close gaps systematically. Cost and Performance Optimization:: Monitor token usage, per-instance signals, and daily cost where the product exposes them. Apply governance strategies and related controls, such as tool mapping and tool sanitization, to reduce spend and risk where the experience supports them. @@ -38,7 +38,7 @@ Under *Portfolio*, open *Agents*, *MCP Servers*, *Model Proxies*, *APIs*, or *Ga In *Portfolio*, open a service detail page from *Agents*, *MCP Servers*, *Model Proxies*, or *APIs*, then open the *Instances* tab to create managed or unmanaged deployments that match your needs. Managed instances on Omni Gateway give stronger governance and monitoring when the new experience exposes them. *Gateways* don't include an *Instances* tab on their detail page. For instance workflows, see xref:exp-instances-add.adoc[]. . Configure policies. + -On a service detail page in *Portfolio*, open the *Policies* tab for the service or one of its instances to apply governance policies that match access control, data privacy, performance, and compliance goals. Use top-level *Governance* for gateway-wide policy work, organization strategies, and cost tools. For governance policy workflows, see xref:exp-governance-work-with-strategies.adoc[]. +On a service detail page in *Portfolio*, open the *Policies* tab for the service or one of its instances to apply governance policies that match access control, data privacy, performance, and compliance goals. For APIs discovered from third-party gateways, applying policies requires a scanner configured with write credentials for the provider; see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. Use top-level *Governance* for gateway-wide policy work, organization strategies, and cost tools. For governance policy workflows, see xref:exp-governance-work-with-strategies.adoc[]. . Review compliance. + In *Portfolio*, open a service detail page from *Agents*, *APIs*, or *MCP Servers*, then open the *Conformance Report* tab to review scores, violations, and warnings and address the findings your governance team prioritizes. For gateways, use top-level *Governance* for the same compliance story at the scope the experience supports. For service-level tabs and conformance context, see xref:exp-services-view-details.adoc[]. diff --git a/modules/ROOT/pages/exp-providers-manage.adoc b/modules/ROOT/pages/exp-providers-manage.adoc index a685cc892..cb632603b 100644 --- a/modules/ROOT/pages/exp-providers-manage.adoc +++ b/modules/ROOT/pages/exp-providers-manage.adoc @@ -100,6 +100,8 @@ When scanning Kong, the enhanced experience discovers gateway-level plugin infor *Akamai API Security* is available only when your administrator has enabled the feature for your organization. When enabled, it appears in the *Not Connected* section of the Providers sidebar. ==== +Of these providers, the API gateway providers Amazon (API Gateway), Google (Apigee), Kong, and Microsoft (Azure API Management) support policy write. APIs discovered from a scanner that has only read credentials appear as *Read-Only*, and policy actions are unavailable until you add write credentials to the scanner. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. + The specific providers available depend on your organization's enabled products and enhanced experience configuration. == See Also diff --git a/modules/ROOT/pages/exp-scanners-add-from-providers.adoc b/modules/ROOT/pages/exp-scanners-add-from-providers.adoc index 1fedbdaef..d38570bcc 100644 --- a/modules/ROOT/pages/exp-scanners-add-from-providers.adoc +++ b/modules/ROOT/pages/exp-scanners-add-from-providers.adoc @@ -38,6 +38,10 @@ Scheduled or on-demand scans pick up releases and configuration drift according + When a scanner is enabled, it can discover and read policies from API configurations. This allows the system to enforce policies on the discovered services. This is especially useful for API-based policies, such as web application firewall (WAF) policies. +* Policy write ++ +For API gateway providers that support policy write (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), a scanner configured with write credentials lets you apply, enable, disable, and delete policies on discovered APIs directly from Anypoint. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. + == Workflow Entry Points for Adding a Scanner The system exposes the same underlying connect-and-configure wizard from more than one place; the label depends on context: @@ -82,6 +86,8 @@ If some environments show no policy binding, select *Check again* to retry the p Regardless of entry point, adding a scanner establishes trust and scope. You specify which provider platform to reach, how the system authenticates, and how you validate connectivity. You also name and schedule the scanner—or configure another trigger—so discovery runs on the cadence your team expects. Saving the configuration activates the scanner for the catalogs and features your administrator enabled. +For API gateway providers that support policy write, supply credentials that include the provider's write scope during setup. Discovery credentials alone enable read-only access: the scanner discovers and reads policies, but the affected APIs appear as *Read-Only* and policy actions are unavailable until you add write credentials. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc[]. + == After the Scanner Runs When the scanner is active, it applies discovery results according to its settings and your organization's rules. You review outcomes on the *Providers* page and on scanner detail pages, and you manage discovered services from the relevant *Portfolio* catalogs. diff --git a/modules/ROOT/pages/exp-scanners-manage.adoc b/modules/ROOT/pages/exp-scanners-manage.adoc index 7398c5f19..f1e6991da 100644 --- a/modules/ROOT/pages/exp-scanners-manage.adoc +++ b/modules/ROOT/pages/exp-scanners-manage.adoc @@ -20,11 +20,15 @@ Re-enable scheduled scanning after a pause. * *Scanner Settings* + Change names, descriptions, credentials, provider scope, or scan-related settings your product exposes, then save, so future runs use the new definition. ++ +For API gateway providers that support policy write, adding write credentials to a read-only scanner enables policy write (apply, enable, disable, and delete) on the scanner's discovered APIs. Read and write credentials are configured separately. For provider-specific write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. * *Delete Scanner* + Remove the scanner from *Providers* when the provider link is no longer authorized or useful. Consider the impact on discovered services in *Portfolio* and on dependent teams before you delete the scanner. + NOTE: When you delete an Akamai API Security scanner, the system attempts to remove the Akamai correlation policy from the scanner's environments. If the removal fails, the correlation policy may remain applied; check *Automated Policies* to verify. Discovered services remain in your portfolio regardless. ++ +NOTE: Deleting a write-enabled API gateway scanner doesn't remove policies that were previously applied to the provider's APIs through policy write. Those policies remain active on the gateway. Anypoint stops tracking them, and you lose the ability to manage them from Anypoint until you reconnect a scanner with write credentials. == See Also diff --git a/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc b/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc index f09f75f74..bbc17f556 100644 --- a/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc +++ b/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc @@ -3,6 +3,8 @@ Scanner prerequisites by provider help you confirm required roles, credentials, and permissions before creating a scanner. Use this reference to prevent connection test failures and incomplete discovery by validating provider-specific access in advance. Each scanner also requires Exchange Administrator permission and the correct business group context. +For API gateway providers that support policy write, discovery credentials aren't enough to apply policies. Supply credentials with the write scope for the gateway, and review the additional write prerequisites in xref:_policy_write_prerequisites[]. Write scopes are noted in the matrix as *Write scope (policy apply)*. + == Before You Begin Before adding any scanner, make sure you have: @@ -141,6 +143,12 @@ a| * *Resource scope (REST APIs):* `arn:aws:apigateway:{region}::/restapis/*` * *Resource scope (HTTP APIs):* `arn:aws:apigateway:{region}::/apis/*` +*Write scope (policy apply):* IAM write permissions for API Gateway, in addition to the read permissions: + +* `apigateway:PUT` +* `apigateway:POST` +* `apigateway:DELETE` + [NOTE] For web application firewall (WAF) policies, the scanner also uses `software.amazon.awssdk:wafv2` and `software.amazon.awssdk:route53`. @@ -154,6 +162,8 @@ a| * *Read role scope:* API Management Service Reader at the API Management resource or resource group scope * *Read OAuth scope:* `https://management.azure.com/.default` +*Write scope (policy apply):* API Management Service Contributor role (ARM) at the API Management resource or resource group scope + | Google Apigee | API a| @@ -163,6 +173,8 @@ a| * *Read role:* Service account with the Viewer role, or an Apigee permission role with equivalent read access +*Write scope (policy apply):* API Admin role (Management API), or an Apigee permission role with equivalent write access + | Kong Gateway | API a| @@ -172,6 +184,8 @@ a| * *Apply read scope:* Admin API read permission required to read policy in target environments +*Write scope (policy apply):* Admin API write permission required to apply, enable, disable, or delete policy in target environments + | Akamai Security | API Security a| @@ -216,6 +230,52 @@ a| |=== +== Policy Write Prerequisites + +Policy write lets you apply, enable, disable, and delete policies on connected third-party gateway APIs directly from Anypoint, with no Anypoint gateway in the request path. Policy write is available for API gateway providers only: Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway. Agent, API Security, and MCP scanners don't support policy write. + +Before you can write policies, confirm these prerequisites in addition to the discovery prerequisites in the matrix: + +* *Write credentials:* Provide credentials that have the write scope for the target gateway. Configure read and write credentials separately in the scanner. Read-only credentials allow discovery only. +* *Write scope:* The write scope covers enabling, disabling, and deleting existing vendor-native policies, and creating and editing universal (canonical) policies, at both the instance and service scope. Creating and editing native vendor policies isn't supported. +* *Provider write permissions:* Grant the provider-specific *Write scope (policy apply)* listed for each API gateway provider in the xref:_scanner_prerequisite_matrix[]. + +The following table summarizes the read and write scopes for each API gateway provider that supports policy write. + +[cols="1,1,1",options="header"] +|=== +| Provider +| Read Scope +| Write Scope + +| Amazon API Gateway +| `apigateway:GET` +| `apigateway:PUT`, `apigateway:POST`, `apigateway:DELETE` + +| Azure API Management +| Reader role (ARM) +| API Management Service Contributor role (ARM) + +| Google Apigee +| Viewer role (Management API) +| API Admin role (Management API) + +| Kong Gateway +| Admin API read +| Admin API write +|=== + +=== Read-Only APIs + +When a scanner has only read credentials for a gateway, its API instances appear as *Read-Only* and policy actions are unavailable. To enable policy write, update the scanner with write credentials by using the credential update link on the API instance. + +=== Tracked Applies and Audit Trail + +Every policy write is tracked and records an applied or failed state alongside the scanner-read configuration. Anypoint also logs each write as compliance evidence, including who made the change, the policy, the target, the vendor, the timestamp, and the result. + +[NOTE] +Anypoint doesn't manage vendor policy lifecycle, versioning, or CI/CD. + == See Also * xref:exp-scanners-add-from-providers.adoc[] diff --git a/modules/ROOT/pages/exp-scanners-view-details.adoc b/modules/ROOT/pages/exp-scanners-view-details.adoc index e1f3b1595..b699c75b5 100644 --- a/modules/ROOT/pages/exp-scanners-view-details.adoc +++ b/modules/ROOT/pages/exp-scanners-view-details.adoc @@ -39,6 +39,8 @@ For import scanners, this tab reflects discovered services imported by scan runs Use *Settings* to review and update scanner configuration values, such as provider connection details, run schedule, and scanner metadata. You can also delete the scanner from this tab. +For API gateway providers that support policy write, the scanner stores read and write credentials separately. Read credentials enable discovery and policy read; write credentials enable policy write (apply, enable, disable, and delete). Use *Settings* to add or update write credentials—for example, to change an API scanner from read-only to write-enabled. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. + == Tab Content by Scanner Type Import scanner:: @@ -47,6 +49,9 @@ Shows imported discovery activity in scanner tabs, including newly discovered se Akamai API Security scanner:: Shows correlation and governance enrichment activity for existing services, including risk and findings signals. +API gateway scanner:: +For providers that support policy write (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), the *Settings* tab additionally supports configuring separate write credentials to enable policy write on discovered APIs. + == See Also * xref:exp-providers-manage.adoc[] From 5024057a14ea3ececea1dfe0f4c7b177dbe81d5d Mon Sep 17 00:00:00 2001 From: jenny hajee Date: Wed, 19 Aug 2026 15:32:59 -0500 Subject: [PATCH 3/4] Amazon out of scope for write policy support in R2 release. Removed those instances --- modules/ROOT/pages/exp-instances-add.adoc | 2 +- modules/ROOT/pages/exp-overview.adoc | 2 +- modules/ROOT/pages/exp-providers-manage.adoc | 2 +- modules/ROOT/pages/exp-scanners-add-from-providers.adoc | 2 +- .../ROOT/pages/exp-scanners-prerequisites-reference.adoc | 8 +++++++- modules/ROOT/pages/exp-scanners-view-details.adoc | 2 +- 6 files changed, 12 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/exp-instances-add.adoc b/modules/ROOT/pages/exp-instances-add.adoc index b8a3f2986..4743ae700 100644 --- a/modules/ROOT/pages/exp-instances-add.adoc +++ b/modules/ROOT/pages/exp-instances-add.adoc @@ -59,7 +59,7 @@ After creating or updating an instance, you can continue managing the service th -- For a managed instance on an Omni Gateway, policies are enforced through the Omni Gateway. -For an instance discovered on a third-party API gateway (Amazon API Gateway, Azure API Management, Google Apigee, or Kong Gateway), the *Policies* tab applies policies directly to the provider through policy write, with no Omni Gateway in the request path. This requires a scanner configured with write credentials for the provider. If the scanner has read-only credentials, the instance appears as *Read-Only* and policy actions are unavailable. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +For an instance discovered on a third-party API gateway (Azure API Management, Google Apigee, or Kong Gateway), the *Policies* tab applies policies directly to the provider through policy write, with no Omni Gateway in the request path. This requires a scanner configured with write credentials for the provider. If the scanner has read-only credentials, the instance appears as *Read-Only* and policy actions are unavailable. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. If the instance uses a Kong gateway, applying a policy targets the gateway level and protects all services in that gateway. -- diff --git a/modules/ROOT/pages/exp-overview.adoc b/modules/ROOT/pages/exp-overview.adoc index f59538d49..ff627267a 100644 --- a/modules/ROOT/pages/exp-overview.adoc +++ b/modules/ROOT/pages/exp-overview.adoc @@ -11,7 +11,7 @@ The enhanced MuleSoft experience supports the full lifecycle of AI-connected int Entity Management:: Register and manage agents, REST and GraphQL APIs, MCP servers, Model proxies, and gateways, including Anypoint Omni Gateway, external gateways, and unmanaged gateways. Each type has a dedicated catalog under *Portfolio*. -Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. For connected third-party API gateways (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), apply, enable, disable, and delete policies directly from Anypoint through policy write, with no Omni Gateway in the request path. Conformance reporting summarizes rule violations and severity so you can close gaps systematically. +Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. For connected third-party API gateways (Azure API Management, Google Apigee, and Kong Gateway), apply, enable, disable, and delete policies directly from Anypoint through policy write, with no Omni Gateway in the request path. Conformance reporting summarizes rule violations and severity so you can close gaps systematically. Cost and Performance Optimization:: Monitor token usage, per-instance signals, and daily cost where the product exposes them. Apply governance strategies and related controls, such as tool mapping and tool sanitization, to reduce spend and risk where the experience supports them. diff --git a/modules/ROOT/pages/exp-providers-manage.adoc b/modules/ROOT/pages/exp-providers-manage.adoc index cb632603b..2ab7de7c4 100644 --- a/modules/ROOT/pages/exp-providers-manage.adoc +++ b/modules/ROOT/pages/exp-providers-manage.adoc @@ -100,7 +100,7 @@ When scanning Kong, the enhanced experience discovers gateway-level plugin infor *Akamai API Security* is available only when your administrator has enabled the feature for your organization. When enabled, it appears in the *Not Connected* section of the Providers sidebar. ==== -Of these providers, the API gateway providers Amazon (API Gateway), Google (Apigee), Kong, and Microsoft (Azure API Management) support policy write. APIs discovered from a scanner that has only read credentials appear as *Read-Only*, and policy actions are unavailable until you add write credentials to the scanner. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +Of these providers, the API gateway providers Google (Apigee), Kong, and Microsoft (Azure API Management) support policy write. APIs discovered from a scanner that has only read credentials appear as *Read-Only*, and policy actions are unavailable until you add write credentials to the scanner. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. The specific providers available depend on your organization's enabled products and enhanced experience configuration. diff --git a/modules/ROOT/pages/exp-scanners-add-from-providers.adoc b/modules/ROOT/pages/exp-scanners-add-from-providers.adoc index d38570bcc..63f5258d2 100644 --- a/modules/ROOT/pages/exp-scanners-add-from-providers.adoc +++ b/modules/ROOT/pages/exp-scanners-add-from-providers.adoc @@ -40,7 +40,7 @@ When a scanner is enabled, it can discover and read policies from API configurat * Policy write + -For API gateway providers that support policy write (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), a scanner configured with write credentials lets you apply, enable, disable, and delete policies on discovered APIs directly from Anypoint. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +For API gateway providers that support policy write (Azure API Management, Google Apigee, and Kong Gateway), a scanner configured with write credentials lets you apply, enable, disable, and delete policies on discovered APIs directly from Anypoint. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. == Workflow Entry Points for Adding a Scanner diff --git a/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc b/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc index bbc17f556..46962a38c 100644 --- a/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc +++ b/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc @@ -143,11 +143,14 @@ a| * *Resource scope (REST APIs):* `arn:aws:apigateway:{region}::/restapis/*` * *Resource scope (HTTP APIs):* `arn:aws:apigateway:{region}::/apis/*` +// TODO: Amazon API Gateway policy write is deferred to a later release. Restore the write scope below when AWS write support ships. +//// *Write scope (policy apply):* IAM write permissions for API Gateway, in addition to the read permissions: * `apigateway:PUT` * `apigateway:POST` * `apigateway:DELETE` +//// [NOTE] For web application firewall (WAF) policies, the scanner also uses `software.amazon.awssdk:wafv2` and `software.amazon.awssdk:route53`. @@ -232,7 +235,7 @@ a| == Policy Write Prerequisites -Policy write lets you apply, enable, disable, and delete policies on connected third-party gateway APIs directly from Anypoint, with no Anypoint gateway in the request path. Policy write is available for API gateway providers only: Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway. Agent, API Security, and MCP scanners don't support policy write. +Policy write lets you apply, enable, disable, and delete policies on connected third-party gateway APIs directly from Anypoint, with no Anypoint gateway in the request path. Policy write is available for API gateway providers only: Azure API Management, Google Apigee, and Kong Gateway. Agent, API Security, and MCP scanners don't support policy write. Before you can write policies, confirm these prerequisites in addition to the discovery prerequisites in the matrix: @@ -248,9 +251,12 @@ The following table summarizes the read and write scopes for each API gateway pr | Read Scope | Write Scope +// TODO: Amazon API Gateway policy write is deferred to a later release. Restore this row when AWS write support ships. +//// | Amazon API Gateway | `apigateway:GET` | `apigateway:PUT`, `apigateway:POST`, `apigateway:DELETE` +//// | Azure API Management | Reader role (ARM) diff --git a/modules/ROOT/pages/exp-scanners-view-details.adoc b/modules/ROOT/pages/exp-scanners-view-details.adoc index b699c75b5..fefd49baf 100644 --- a/modules/ROOT/pages/exp-scanners-view-details.adoc +++ b/modules/ROOT/pages/exp-scanners-view-details.adoc @@ -50,7 +50,7 @@ Akamai API Security scanner:: Shows correlation and governance enrichment activity for existing services, including risk and findings signals. API gateway scanner:: -For providers that support policy write (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), the *Settings* tab additionally supports configuring separate write credentials to enable policy write on discovered APIs. +For providers that support policy write (Azure API Management, Google Apigee, and Kong Gateway), the *Settings* tab additionally supports configuring separate write credentials to enable policy write on discovered APIs. == See Also From 2099afa163b80bb7f825a09d25f0c29feb2f2af5 Mon Sep 17 00:00:00 2001 From: Luana Dos Santos Date: Fri, 21 Aug 2026 14:05:03 -0300 Subject: [PATCH 4/4] W-23907611 docs: document Activity log tab for tracked policy writes Add coverage for the Activity log tab surfaced by the two additional scope PRDs (Policy Write / Unified Policy Catalog) and verified in code (ActivitiesTab.tsx, activitiesTab i18n). Applies are asynchronous and tracked (Apply/Update/Toggle/Remove; Running/Completed/Failed). Cross-linked from the apply flow and the instance Policies tab. Left as DRAFT with a TODO on the feature-flag/external-provider gating and no actor field (not a full audit trail). Co-Authored-By: Claude Opus 4.8 --- .../exp-governance-policy-library-apply.adoc | 24 +++++++++++++++++++ .../ROOT/pages/exp-services-view-details.adoc | 2 ++ 2 files changed, 26 insertions(+) diff --git a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc index 3962c947a..416195cb9 100644 --- a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc +++ b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc @@ -78,6 +78,8 @@ You can filter policies by category: When you apply a policy, the platform validates it against your governance configuration and then creates the corresponding native policy on each selected instance's gateway. +Applying a policy is an asynchronous, tracked operation, not a fire-and-forget action. A message confirms that the operation is running and directs you to the *Activity log* tab to check its status. When you apply a policy to more than one instance, each instance reports its own result, so you can see which instances succeeded and which failed. To review the outcome, see <>. + [NOTE] ==== While a policy operation is in progress on an instance, applying policies to that instance is paused and policy actions are unavailable until the operation completes or fails. This prevents conflicting changes while the vendor-native apply workflow runs. @@ -122,6 +124,28 @@ On gateways that support it, you can enable or disable a policy without removing Policies that are outside your instance's scope appear in a read-only state. For these policies, edit, delete, and enable/disable actions are not available. +[#track-policy-changes] +== Track Policy Changes + +Policy write actions run asynchronously and are tracked, so you can confirm whether a change landed on the gateway instead of assuming it did. Review recent policy operations for an instance on the *Activity log* tab of the instance detail page. + +The *Activity log* tab lists recent policy operations with these columns: + +* *Policy*: The policy the operation applied to. +* *Action*: The operation performed — *Apply*, *Update*, *Toggle*, or *Remove*. +* *Status*: The current state of the operation — *Running*, *Completed*, or *Failed*. + +The tab shows the most recent operations from the last 30 days. If no policy changes have been recorded for the instance in that window, the tab reports that no activity is available. + +Use the *Activity log* tab to confirm that an apply, edit, enable, disable, or delete completed, or to see which operations failed and need to be retried. + +// TODO(W-23907611): The Activity log tab is gated by a feature flag and, per the code, +// currently appears only for external (non-MuleSoft) provider instances. Confirm the GA +// availability (flag state and which provider instances show the tab) with engineering. +// Also confirm the exact column headers and the empty-state wording against the shipped UI. +// Note: the log records policy/action/status/time only — it does NOT record an actor +// ("who"), so do not describe it as a full audit trail. + == See Also * xref:exp-governance-create-strategy.adoc[] diff --git a/modules/ROOT/pages/exp-services-view-details.adoc b/modules/ROOT/pages/exp-services-view-details.adoc index cf3d8ae88..b164d1f21 100644 --- a/modules/ROOT/pages/exp-services-view-details.adoc +++ b/modules/ROOT/pages/exp-services-view-details.adoc @@ -81,6 +81,8 @@ Policy visibility depends on the last successful scanner run, not on a live prov On supported gateways, the *Policies* tab also lets you manage the native policies applied to an instance. Depending on the gateway and your permissions, you can edit, delete, or enable and disable a policy directly from this tab. Policies that are outside your instance's scope appear in a read-only state, without edit, delete, or enable/disable actions. +Policy write actions are tracked. To confirm whether an apply, edit, enable, disable, or delete completed on the gateway, review the *Activity log* tab of the instance detail page. See xref:exp-governance-policy-library-apply.adoc#track-policy-changes[Track Policy Changes]. + For the full apply and management workflow, see xref:exp-governance-policy-library-apply.adoc[]. == See Also